Claude Code 国内使用教程：终端和 VS Code 插件配置完整流程

最近 AI 编程工具越来越多除了 Cursor、Codex 以外Claude Code 也是很多开发者在关注的一个 AI 编程工具。Claude Code 的使用方式和普通聊天工具不太一样它更适合直接在项目目录中运行结合当前项目上下文帮助我们完成代码分析、Bug 修复、页面生成、功能开发、代码重构等任务。但是很多国内普通用户第一次使用 Claude Code 时容易卡在几个地方Claude Code 怎么下载安装API Key 从哪里获取Base URL 应该怎么填国内网络环境下怎么更方便使用settings.json 文件放在哪里怎么配置自定义 API怎么在 VS Code 插件里配置为什么会出现 401 Unauthorized为什么会出现 404为什么配置好了还是不能用这篇文章就整理一份 Claude Code 国内使用教程重点讲清楚如何通过settings.json配置 API Key 和 Base URL让 Claude Code 可以更方便地接入多模型 API 平台。本文以「TransAI API 平台」为例演示。平台地址https://transitai.chat/Claude Code 配置里使用的 Base URLhttps://transitai.chat一、Claude Code 是什么Claude Code 可以理解成一个面向开发者的 AI 编程助手。它不是普通的网页聊天工具而是更偏向开发者工作流可以在本地项目目录中运行读取项目上下文并根据自然语言指令帮助我们分析和修改代码。常见使用场景包括1. 分析项目结构 2. 阅读和解释代码 3. 生成前端页面 4. 修改 Bug 5. 重构代码 6. 编写接口逻辑 7. 生成测试用例 8. 辅助代码审查 9. 生成 README 或技术文档 10. 根据需求修改已有项目比如你可以在项目目录中输入claude 帮我分析这个项目的目录结构并告诉我前端入口文件在哪里也可以让它生成页面claude 帮我写一个 React 登录页面包含手机号、验证码和登录按钮还可以让它辅助排查问题claude 帮我检查这个接口为什么会返回 500并给出可能原因对于经常做项目开发的人来说Claude Code 的优势是可以结合项目上下文不只是单纯回答问题。二、为什么国内用户适合使用自定义 API 方案很多国内用户不是不会用 Claude Code而是卡在账号、Key、网络环境、充值、模型配置这些环节。常见问题包括官方 API Key 获取不方便 网络环境不稳定 不知道 Base URL 怎么填 不知道 settings.json 放在哪里 多个模型平台来回切换很麻烦 想先测试但不想一开始就充值很多 使用 Codex、Cursor、Dify 时还要重复配置所以对国内普通用户来说更简单的方式是使用一个支持 Claude Code 接入的多模型 API 平台。这种方式通常只需要准备两个核心参数1. API Key 2. Base URL然后把它们写进 Claude Code 的settings.json配置文件里就可以开始使用。本文使用的 TransAI API 平台可以用于 Claude Code、Codex、Cursor、Dify、Open WebUI、Cherry Studio 等工具接入。平台地址https://transitai.chat/它的主要特点是1. 注册后可以生成 API Key 2. 可以统一管理余额和消耗 3. 支持多个模型接入 4. 适合国内普通用户测试使用 5. 不需要复杂环境配置好 Key 和 Base URL 即可使用 6. 同一个 Key 后续还能用于 Codex、Cursor、Dify 等工具三、Claude Code 官方地址Claude Code 官方文档地址https://code.claude.com/docs/Claude Code 环境变量说明https://code.claude.com/docs/en/env-varsClaude Code 设置说明https://code.claude.com/docs/en/settings如果你想查看最新安装方式、环境变量、配置说明和更新记录可以优先看官方文档。四、安装 Claude CodeClaude Code 可以通过 npm 安装。在安装之前建议先确认电脑已经安装 Node.js 和 npm。查看 Node.js 版本node -v查看 npm 版本npm -v如果可以正常输出版本号说明 Node.js 环境已经安装好。五、使用 npm 安装 Claude Code如果你已经安装了 Node.js 和 npm可以通过 npm 安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后查看版本claude --version如果可以正常显示版本号说明安装成功。也可以直接运行claude如果能进入 Claude Code 交互界面说明基础安装没有问题。六、Windows 用户安装建议Windows 用户如果直接安装不顺可以先确认几个点1. Node.js 是否已经安装 2. npm 是否可以正常使用 3. npm 全局安装目录是否加入 PATH 4. PowerShell 或终端是否重新打开如果安装完成后提示claude 不是内部或外部命令可能是 npm 全局安装目录没有加入系统环境变量 PATH。可以查看 npm 全局路径npm config get prefix然后把对应目录加入系统 PATH。如果你经常做开发也可以考虑使用 WSL 环境安装 Node.js 和 Claude Code后续运行终端工具会更接近 Linux / macOS 环境。七、注册 TransAI 并创建 API Key打开平台地址https://transitai.chat/注册并登录账号。进入用户后台后找到类似下面的功能入口API Key 管理 令牌管理 余额 充值 模型列表 调用记录 用户中心进入 API Key 管理页面点击创建新的 API Key。创建后会得到类似下面格式的密钥sk-xxxxxxxxxxxxxxxxxxxxxxxx这个 Key 后面要写入 Claude Code 的settings.json配置文件中。注意1. API Key 不要公开给别人 2. 不要把真实 Key 发到文章、评论区或群里 3. 如果 Key 泄露建议立即删除旧 Key重新创建新 Key 4. 文章里展示时可以用 sk-xxxxxxxx 代替八、确认 Claude Code 使用的 Base URL本文使用的 Claude Code 配置方式里Base URL 填写https://transitai.chat这里要注意不同工具的 Base URL 规则可能不一样。有些工具需要填写https://transitai.chat/v1但本文 Claude Code 示例中使用的是https://transitai.chat如果 Base URL 填错可能会出现404 接口路径错误 请求失败 无法连接模型服务所以建议按照本文配置方式填写。九、配置 API Key手动创建 settings.jsonClaude Code 可以通过配置文件统一管理环境变量。这种方式比每次在终端里手动输入环境变量更方便适合普通用户长期使用。配置文件路径一般是~/.claude/settings.jsonWindows 用户对应路径一般是C:\Users\你的用户名\.claude\settings.json安装完后一般.claude文件夹是存在的十、创建 .claude 配置目录macOS / Linux打开终端执行mkdir -p ~/.claude然后创建或编辑settings.jsonnano ~/.claude/settings.json如果你习惯使用 VS Code也可以执行code ~/.claude/settings.jsonWindowsWindows 用户可以在资源管理器地址栏输入%USERPROFILE%然后在用户目录下新建一个文件夹.claude再在.claude文件夹里新建文件settings.json最终路径类似C:\Users\你的用户名\.claude\settings.json十一、写入 settings.json 配置在settings.json中写入下面内容{ env: { ANTHROPIC_BASE_URL: https://transitai.chat, ANTHROPIC_AUTH_TOKEN: sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1, CLAUDE_CODE_ATTRIBUTION_HEADER: 0 } }把里面的sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX替换成你在 TransAI 后台创建的真实 API Key。平台地址https://transitai.chat/Base URLhttps://transitai.chat十二、配置字段说明1. ANTHROPIC_BASE_URLANTHROPIC_BASE_URL: https://transitai.chat这个字段表示 Claude Code 请求模型服务时使用的接口地址。本文使用https://transitai.chat注意这里不要随便改成其他地址。有些工具可能需要/v1但本文 Claude Code 配置里使用的是https://transitai.chat如果 Base URL 填错可能会出现404 接口路径错误 请求失败 无法连接模型服务2. ANTHROPIC_AUTH_TOKENANTHROPIC_AUTH_TOKEN: sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX这个字段就是 API Key。在 TransAI 后台创建 API Key 后把完整 Key 填到这里。注意1. API Key 不要公开给别人 2. 不要把真实 Key 发到文章、截图、评论区或群里 3. 如果 Key 泄露建议立即删除旧 Key重新创建新 Key 4. 写文章时可以用 sk-XXXXXXXXXXXXXXXX 代替3. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1这个字段用于关闭一些非必要流量。普通用户可以直接保留不需要额外修改。4. CLAUDE_CODE_ATTRIBUTION_HEADERCLAUDE_CODE_ATTRIBUTION_HEADER: 0这个字段用于关闭 attribution header。普通用户同样可以直接保留。十三、保存配置后启动 Claude Code保存settings.json后重新打开终端。然后进入一个测试目录mkdir claude-code-test cd claude-code-test启动 Claude Codeclaude进入后先输入一个简单问题请用一句话回复我Claude Code 已经可以正常工作。如果能正常返回说明 API Key 和 Base URL 基本配置成功。十四、新手测试建议第一次使用时不建议直接进入真实项目让 Claude Code 改代码。建议先测试简单任务帮我创建一个简单的 HTML 页面包含标题、输入框和按钮。如果能正常生成内容再进入真实项目cd my-project claude进入真实项目后建议先让它分析不要直接修改先不要修改代码请分析当前项目结构并告诉我这个项目主要使用了哪些技术栈。确认它能正确理解项目后再让它进行具体修改。例如请帮我找到项目的前端入口文件和路由配置文件。或者请分析登录页面相关代码但先不要修改只给出修改建议。确认分析准确后再让它修改请在不影响现有功能的前提下帮我优化登录页面的表单布局。这种方式比一上来直接修改真实项目更稳。十五、VS Code 插件方式配置 Claude Code除了在终端里直接使用 Claude Code也可以通过 VS Code 插件的方式使用。这种方式更适合习惯在编辑器里写代码的用户。很多人不喜欢一直在命令行里切换目录、输入命令如果你平时主要使用 VS Code 开发那么可以直接安装 Claude Code 相关插件然后在 VS Code 里配置 API Key、Base URL 和模型名称。这种方式的好处是1. 不用频繁切换终端窗口 2. 可以直接结合当前项目代码使用 3. 对新手更友好 4. 配置项更直观 5. 适合前端、后端、全栈开发者日常使用1. 在 VS Code 中安装 Claude Code 插件打开 VS Code进入插件市场。快捷键Ctrl Shift X或者点击左侧扩展图标。在搜索框中搜索Claude Code找到对应插件后点击安装。安装完成后通常可以在 VS Code 侧边栏、命令面板或者插件设置中看到 Claude Code 相关入口。2. 打开插件配置页面安装完成后可以通过下面方式打开配置VS Code 设置 - 扩展 - Claude Code或者使用快捷键打开命令面板Ctrl Shift P然后搜索Claude Code找到相关配置入口。不同版本插件的界面可能略有不同但核心配置一般都离不开这几个参数API Key Base URL Model3. 配置 API KeyAPI Key 使用 TransAI 后台创建的 Key。格式一般类似sk-xxxxxxxxxxxxxxxxxxxxxxxx把它填到插件的 API Key 配置项中。注意不要把真实 API Key 发到文章、截图、评论区或群里 如果 Key 泄露建议立即删除旧 Key重新创建新 Key4. 配置 Base URL本文使用的 Base URL 是https://transitai.chat如果插件里有 Base URL、API Base URL、Endpoint、Custom API URL 这类配置项就填写https://transitai.chat注意不同工具对 Base URL 的要求可能不完全一样。有些工具可能需要https://transitai.chat/v1但本文 Claude Code 配置示例中使用的是https://transitai.chat如果配置后出现 404 或接口路径错误可以优先检查 Base URL 是否和插件要求一致。5. 配置模型名称模型名称要以平台后台实际展示为准。如果插件需要填写模型名称就去 TransAI 后台查看当前可用模型复制完整模型名。不要自己随便改成claude claude-sonnet sonnet Claude Code模型名称不一致容易出现model not found或者4046. VS Code 插件配置示例如果插件支持自定义配置可以参考下面几个字段API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx Base URL: https://transitai.chat Model: 以平台后台实际展示为准有些插件可能字段名不同比如Anthropic API Key Anthropic Base URL Custom API Endpoint Model Name不管字段名怎么变化本质上都是配置这三项API Key Base URL Model7. 在 VS Code 中测试是否配置成功配置完成后打开一个项目目录。建议先不要直接让插件修改真实代码可以先问一个简单问题请用一句话回复我Claude Code 已经可以正常工作。如果插件能正常返回说明 API Key、Base URL 和模型配置基本没问题。然后再测试项目分析先不要修改代码请分析当前项目结构并告诉我这个项目主要使用了哪些技术栈。如果它能结合当前项目进行分析就说明已经可以在 VS Code 中正常使用。8. VS Code 插件方式适合哪些用户如果你是下面这些情况比较适合使用 VS Code 插件方式1. 平时主要在 VS Code 里写代码 2. 不想一直在终端里输入 claude 3. 想直接在编辑器里分析当前文件 4. 想结合项目目录让 AI 辅助开发 5. 想让普通用户更容易上手如果你更喜欢命令行工作流也可以继续使用终端方式claude两种方式没有绝对好坏主要看自己的使用习惯。9. VS Code 插件常见问题插件没有反应可能原因API Key 没填 Base URL 填错 模型名称不正确 插件没有保存配置 网络请求失败建议先检查 API Key、Base URL、Model 三个配置。401 Unauthorized一般是 API Key 问题。重点检查Key 是否复制完整 Key 前后是否有空格 Key 是否已经删除 Key 是否填到了正确位置model not found一般是模型名称错误。进入 TransAI 后台查看模型列表复制完整模型名称不要自己猜。404 或接口路径错误一般是 Base URL 问题。本文示例使用https://transitai.chat如果插件要求 OpenAI-compatible/v1格式也可以尝试https://transitai.chat/v1具体以插件说明和实际返回结果为准。终端能用VS Code 插件不能用这种情况一般说明 Claude Code 终端配置和 VS Code 插件配置不是同一套。终端方式可能读取的是~/.claude/settings.json而 VS Code 插件可能读取的是插件自己的设置。所以如果终端能用但插件不能用要单独检查 VS Code 插件里的 API Key、Base URL 和 Model 配置。十六、常见报错和解决方法1. 401 Unauthorized这个通常是 API Key 问题。重点检查settings.json里的字段ANTHROPIC_AUTH_TOKEN: sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX常见原因API Key 填错 API Key 复制不完整 Key 前后有空格 Key 已经被删除或禁用 settings.json 没有保存成功 settings.json 路径放错解决方法进入 TransAI 后台重新复制 API Key确认完整粘贴到~/.claude/settings.jsonWindows 路径一般是C:\Users\你的用户名\.claude\settings.json修改后关闭 Claude Code重新打开终端再运行。2. 404 或接口路径错误这个通常是 Base URL 配置问题。检查settings.json里的字段ANTHROPIC_BASE_URL: https://transitai.chat本文使用的是https://transitai.chat不要手动乱改。如果配置成错误地址就可能出现 404、接口路径错误、请求失败等问题。3. 配置不生效常见原因settings.json 路径放错 文件名写成了 setting.json JSON 格式错误 少了逗号或引号 修改后没有重启 Claude Code VS Code 插件读取的是插件自己的配置不是 settings.json建议确认文件路径~/.claude/settings.json确认 JSON 格式正确{ env: { ANTHROPIC_BASE_URL: https://transitai.chat, ANTHROPIC_AUTH_TOKEN: sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1, CLAUDE_CODE_ATTRIBUTION_HEADER: 0 } }保存后重新启动 Claude Code。4. model not found如果出现model not found一般是工具默认模型或当前平台模型权限的问题。可以先检查平台后台支持的模型列表。如果平台没有开启对应模型或者当前账号没有权限就可能出现这个错误。5. 请求很慢Claude Code 在分析真实项目时可能会读取较多上下文。请求慢可能有这些原因项目太大 上下文太长 模型响应较慢 网络延迟 当前任务太复杂 上游模型繁忙建议先用测试目录跑简单任务确认基础配置没问题后再进入真实项目。6. 余额不足如果提示余额不足说明账号没有可用额度或者测试额度已经用完。可以进入 TransAI 后台查看余额和调用记录。新手第一次测试不建议一上来就让 Claude Code 分析大型项目可以先让它回复一句话或生成一个简单页面。十七、新手推荐测试流程如果你是第一次使用 Claude Code建议按下面流程来第一步安装 Claude Code 第二步注册 TransAI 第三步创建 API Key 第四步创建 ~/.claude/settings.json 第五步写入 ANTHROPIC_BASE_URL 第六步写入 ANTHROPIC_AUTH_TOKEN 第七步保存 settings.json 第八步运行 claude 第九步先问一句简单问题 第十步新建测试目录让它生成简单页面 第十一步进入真实项目让它先分析不要直接修改 第十二步如果不想用终端也可以安装 VS Code 插件在插件里配置 API Key、Base URL 和模型名称 第十三步确认分析准确后再让它修改代码这种方式最稳。不要一开始就让它直接改大型项目否则一旦出错不好判断是配置问题、模型问题还是项目上下文太复杂。如果你平时主要用 VS Code 写代码也可以优先选择 VS Code 插件方式。它的核心配置同样是API Key Base URL Model只要这三项填写正确就可以在编辑器里直接使用 Claude Code 辅助分析项目、生成页面、修改 Bug 和重构代码。十八、Claude Code 适合哪些场景Claude Code 比较适合这些开发场景1. 分析已有项目结构 2. 快速理解陌生代码 3. 生成页面或组件 4. 修改简单 Bug 5. 重构函数或组件 6. 生成接口调用代码 7. 编写 README 8. 辅助写测试用例 9. 根据报错分析原因 10. 辅助完成重复性代码任务例如帮我分析这个项目使用了哪些技术栈帮我找到用户登录逻辑在哪个文件里帮我给当前项目补一个充值记录页面帮我把这个 Vue2 页面改成 Vue3 写法帮我检查为什么这个接口返回 500帮我优化移动端页面布局十九、国内普通用户使用建议如果你只是普通用户或者刚开始接触 AI 编程工具不建议一开始就折腾很多模型和复杂配置。推荐先这样做1. 使用本文配置跑通 Claude Code 2. 先用一个测试项目验证 3. 确认能正常回复后再进入真实项目 4. 先让 Claude Code 分析不要直接修改 5. 熟悉后再让它生成代码或改 Bug如果你是新手第一次不要让它直接改真实项目。建议先问先不要修改代码请告诉我你准备怎么改。确认方案没问题后再让它执行修改。二十、总结Claude Code 国内使用的核心其实就是几件事1. 安装 Claude Code 2. 获取 API Key 3. 创建 settings.json 4. 配置 ANTHROPIC_BASE_URL 5. 配置 ANTHROPIC_AUTH_TOKEN 6. 直接用 Claude Code 做真实任务测试 7. 如果不想用终端可以使用 VS Code 插件方式本文使用的 TransAI API 平台https://transitai.chat/Claude Code 配置中的 Base URLhttps://transitai.chat完整settings.json配置示例{ env: { ANTHROPIC_BASE_URL: https://transitai.chat, ANTHROPIC_AUTH_TOKEN: sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1, CLAUDE_CODE_ATTRIBUTION_HEADER: 0 } }对于国内普通用户来说这种方式比较方便注册平台、生成 API Key、复制配置、运行 Claude Code就可以开始测试。如果你后续还使用 Codex、Cursor、Dify、Open WebUI、Cherry Studio 等工具也可以继续复用同一个平台的 API Key统一管理模型、余额和调用记录。