从零到一：本地安装 Claude Code + 自定义 API 接口全配置指南（附国内踩坑实录）TaoToken 实践

1. 本地安装 Claude Code 到底难在哪国内开发者的真实场景Claude Code 是 Anthropic 官方推出的终端 AI 编程助手能读整个代码库、跨文件改代码、跑命令、提 PR本质上是住在你终端里的 AI 程序员。它支持 macOS、Linux、WindowsWSL2 或 Git Bash原生安装方式不依赖 Node.js。对国内开发者来说安装本身十分钟能搞定真正卡人的是后面那一步——把默认的官方端点换成自定义 API 接口让请求走一个能稳定连通的地址。我见过太多人卡在同一类问题上curl手动测接口明明通一跑claude就报ERR_BAD_REQUEST然后直接退出环境变量在交互式终端里echo有值切到 VS Code 终端就空了settings.json里写了apiBaseUrl结果被完全无视。这些不是玄学是 Claude Code 的启动检查逻辑、shell 加载顺序、配置字段命名三件事叠在一起造成的。这篇面向的是想在国内网络环境下把 Claude Code 跑起来、并且接入自定义 API 接口的开发者。我会按装好 → 配好 → 验证通 → 排错的顺序走一遍重点放在配置片段和逐条验证命令上每一步都给可复制的内容。你跟着做完应该能拿到一个能正常对话的最小闭环。适合谁有终端基础、想用 Claude Code 但被网络和鉴权卡住的个人开发者以及需要给团队统一配置 API 端点的技术负责人。先说清楚一个前提Claude Code 通过ANTHROPIC_BASE_URL支持自定义端点这个端点必须兼容 Anthropic Messages API 格式也就是要能正确处理/v1/messages请求并且转发anthropic-version和anthropic-beta请求头。这是后面所有配置能生效的基础选服务时先确认这一点能省掉一大半排错时间。2. TaoToken 前置准备拿到 Base URL 和 Key 的正确姿势在动手改配置之前先把两样东西准备好一个兼容 Anthropic Messages API 的 Base URL和一个对应的 API Key。我用的是 TaoToken 作为自定义接口端点它的 API 地址是https://taotoken.net/api注意这个地址后面不加任何路径后缀Claude Code 会自己在后面拼/v1/messages。第一步登录控制台创建 Key。打开https://taotoken.net/console在 API Keys 页面新建一个密钥复制出来先存到安全的地方。这个 Key 就是后面ANTHROPIC_API_KEY要填的值。创建时建议给它起个能认出来的名字比如claude-code-local方便以后在列表里区分。第二步确认你要用的模型 ID。Claude Code 默认会挑最新模型但自定义端点下最好显式指定避免请求发出去对方不认识模型名。常见的写法是claude-sonnet-4-6这类具体以你控制台里模型列表显示的为准。这个值后面会填到ANTHROPIC_MODEL里。第三步先别急着配 Claude Code用curl单独验证一下这个端点和 Key 能不能通。这一步非常关键能把接口本身有问题和Claude Code 配置有问题彻底分开。命令如下curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: 你的API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-6, max_tokens: 100, messages: [{role: user, content: Hi}] }如果返回一段正常的 JSON里面有content字段和模型回复说明端点和 Key 都没问题可以进入下一步。如果这里就报 401那是 Key 的问题报 404多半是路径拼错了报 400检查model字段是不是对方不认识的模型名。把这一步跑通后面 Claude Code 里再出问题排查范围就小很多。关于 Key 的存放我的建议是不要直接写死在命令历史里。可以先export到当前会话测试确认没问题后再写进 shell 配置文件。TaoToken 的接入文档在https://taotoken.net/doc里面有各语言的调用示例遇到请求头或参数不确定的时候可以对照看。3. 可复制配置settings.json 与 shell 环境变量全片段配置 Claude Code 的自定义接口有两条路环境变量和settings.json。两者都能用但优先级和生效范围不一样我建议主力用环境变量settings.json作为补充。先讲清楚一个高频坑settings.json里直接写apiBaseUrl和apiKey是无效的Claude Code 不认这两个字段名。API 地址只能通过ANTHROPIC_BASE_URL设置Key 只能通过ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN设置。先看全局配置文件~/.claude/settings.json的正确写法。注意地址写在env对象里作为环境变量注入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-6, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 }, model: sonnet, permissions: { allow: [ Bash(npm run *), Bash(git *) ] } }这里CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设成1是为了关掉启动时的非必要连通性检查国内环境下这个检查经常直接导致进程退出。permissions.allow是白名单把常用的git、npm run放进去省得每次都要确认。再看 shell 环境变量方案写进~/.bashrc或~/.zshrc# Claude Code 自定义 API 配置 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的API_KEY export ANTHROPIC_MODELclaude-sonnet-4-6 export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1如果你用的是 WSL2这里有个必须注意的细节Ubuntu 默认的.bashrc开头有一段非交互式 shell 直接return的逻辑如果你把export写在文件末尾VS Code 终端这类非交互式 shell 根本执行不到。正确做法是把这几行放到文件开头在case $- in那段之前# ~/.bashrc 文件最开头 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的API_KEY export ANTHROPIC_MODELclaude-sonnet-4-6 export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1 # 下面才是系统默认内容 case $- in *i*) ;; *) return;; esac同时建议在~/.profile末尾也补一份覆盖 login shell 场景。三件套记牢Base URL 填https://taotoken.net/apiKey 填控制台创建的密钥Model ID 填claude-sonnet-4-6。这三个值在环境变量和settings.json里要保持一致别一个地方写 A 另一个地方写 B。配置优先级从高到低是组织管理配置 命令行参数 项目本地.claude/settings.local.json 项目共享.claude/settings.json 用户全局~/.claude/settings.json。如果你发现改了全局配置不生效先检查项目目录下是不是有更高优先级的配置文件在覆盖。4. 验证请求从 claude --version 到 /status 的完整链路配置写完不代表生效得一层层验证。我习惯按命令存在 → 环境变量可见 → 接口连通 → Claude Code 内部状态这个顺序查每一步都有明确的成功标志。第一步确认 Claude Code 装好了claude --version能打印出版本号就说明命令在 PATH 里。如果报command not found多半是安装目录~/.local/bin没进 PATH补一句export PATH$HOME/.local/bin:$PATH再source一下。第二步确认环境变量在所有 shell 模式下都能读到。这一步是很多人忽略的交互式终端有值不代表子进程有值bash -ic echo $ANTHROPIC_BASE_URL bash -c echo $ANTHROPIC_API_KEY bash -l -c echo $ANTHROPIC_MODEL三条命令都要有输出而且值要一致。哪条空了就回去检查对应的配置文件位置。WSL2 用户如果改了配置还是读不到在 Windows 端跑一次wsl --shutdown彻底重启 WSL 实例再重开终端。第三步用curl再确认一次接口连通前面第 2 节已经跑过这里可以跳过但如果中间改过 Key 就重跑一遍。第四步启动 Claude Code 并查看内部状态cd your-project claude进入交互界面后输入/status会显示当前使用的模型、账户信息、API 端点等。重点看端点是不是你配的https://taotoken.net/api模型是不是claude-sonnet-4-6。如果这里显示的端点还是官方地址说明环境变量没被 Claude Code 读到回到第二步排查。第五步发一条真实请求验证闭环。在 Claude Code 里直接输入一句简单的话比如让它解释当前目录下某个文件的作用。能正常流式返回内容就说明从本地到自定义接口的整条链路通了。如果卡住不动或者报错看下一节的排查清单。补充一个非交互式验证方式适合写脚本或 CI 场景claude -p 用一句话说明这个项目是做什么的-p参数是单次任务模式跑完就退出输出直接打到终端。这个方式能快速验证配置在非交互环境下是否也生效。5. 本篇常见错排查401、local proxy failed、reading choices 逐条拆配置过程中最常见的报错就那么几个我把它们和对应的动作列出来你对着自己的报错找。报 401 UnauthorizedKey 不对或没被正确读取。先echo $ANTHROPIC_API_KEY确认值非空再确认这个 Key 在控制台里是启用状态。如果 Key 里带了空格或换行export时会被截断重新复制一遍。还有一种情况是同时设了ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN后者会覆盖前者检查是不是设了多余的AUTH_TOKEN。报 local proxy failed 或连接被拒这类通常是本地网络层的问题。先确认ANTHROPIC_BASE_URL末尾没有多余的斜杠https://taotoken.net/api/和https://taotoken.net/api在某些实现下行为不同统一用不带斜杠的写法。再确认没有残留的HTTPS_PROXY环境变量指向一个已经关掉的本地端口echo $HTTPS_PROXY看一下有的话unset掉。报 reading choices 或解析响应失败说明请求发出去了但返回的内容不是预期的 JSON 结构。多半是端点不兼容 Anthropic Messages API 格式或者模型名写错了。用第 2 节的curl命令单独测一次看返回体长什么样。如果返回的是 HTML 错误页说明请求打到了错误的路径。启动直接退出报 ERR_BAD_REQUEST 且提到 api.anthropic.com这是最典型的坑。Claude Code 启动时会硬编码请求官方地址做连通性检查跟你设的ANTHROPIC_BASE_URL无关。解决要两步一是设CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1二是把 Key 指纹写进批准列表。指纹取 Key 的最后 20 个字符echo -n 你的API_KEY | tail -c 20然后手动创建~/.claude/.config.json{ customApiKeyResponses: { approved: [你的key最后20个字符] } }这是个先有鸡还是先有蛋的问题——Claude Code 要先批准你的 Key 才能跳过检查但正常流程又因为检查失败走不到批准那一步所以只能手动建这个文件。报 OAuth 相关错误或反复要求登录说明 Claude Code 还在走账号登录流程没切到 API Key 模式。确认ANTHROPIC_API_KEY已设置且非空然后重新启动claude。如果之前登录过账号可以先/logout登出再重启让它读环境变量。VS Code 终端里配置不生效回到第 3 节的.bashrc非交互式return问题把export挪到文件开头。改完记得完全关闭 VS Code 再重开光开新终端窗口不够。多个安装版本冲突which -a claude看一下有几个路径。如果同时有原生安装和 npm 全局安装建议只留原生版npm uninstall -g anthropic-ai/claude-code删掉 npm 版避免版本打架。6. 长期编码与 Agent 场景把配置沉淀成可复用方案最小闭环跑通之后如果你打算长期用 Claude Code 做日常编码有几个地方值得再优化一下能明显减少重复劳动。第一把配置按项目隔离。全局~/.claude/settings.json放通用的 Base URL 和 Key项目目录下的.claude/settings.json放这个项目特有的模型选择和权限白名单。这样换项目时不用改全局配置团队协作时项目配置还能跟着仓库走。注意.claude/settings.local.json是个人本地配置别提交到 git。第二用apiKeyHelper做动态 Key。如果你的 Key 需要定期轮换或者从密钥管理工具读取可以配一个脚本{ apiKeyHelper: /path/to/get-key.sh }脚本里从你的密钥管理工具取值输出即可Claude Code 默认每 5 分钟或遇到 401 时刷新一次。刷新间隔可以用CLAUDE_CODE_API_KEY_HELPER_TTL_MS调整。第三模型分级使用。日常改代码用 Sonnet 级别就够复杂推理再切 Opus简单任务用 Haiku 省额度。可以在settings.json里分别指定{ env: { ANTHROPIC_DEFAULT_SONNET_MODEL: claude-sonnet-4-6, ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-4-6, ANTHROPIC_DEFAULT_HAIKU_MODEL: claude-haiku-3-5-20241022 } }运行时用/model sonnet或/model opus切换不用重启。第四如果你要跑 Agent 类长任务建议单独规划额度。Coding Plan 这类方案在https://taotoken.net/coding-plan有说明适合需要持续、大量调用的场景比按次计费更可控。模型对话入口在https://taotoken.net/models想先试试不同模型效果可以从这里进。最后提醒一句自定义接口的稳定性直接决定 Claude Code 的体验。选端点时优先确认它兼容 Anthropic Messages API、支持流式响应、正确转发anthropic-version和anthropic-beta头。这三点满足了剩下的就是配置细节。配置改完记得用bash -ic、bash -c、bash -l -c三种模式各验一遍环境变量再启动claude跑/status确认端点最后发一条真实请求收尾。这套流程走下来基本不会再被环境问题反复折腾。