1. 为什么 Claude Code 首次配置总卡在 settings.json
Claude Code 是 Anthropic 推出的终端编码助手，能直接在命令行里读写项目文件、跑测试、改 bug，适合已经装好 Node/npm 的开发者。但很多人第一次跑claude时，要么卡在登录跳转，要么报ANTHROPIC_BASE_URL未设置，要么 Key 写进去了却一直 401。问题基本都出在两个地方：~/.claude/settings.json的骨架没写对，以及环境变量注入的时机不对。
我自己第一次配的时候，把 Key 直接塞进 shell 的export，结果新开一个终端窗口就失效，排查了半小时才发现 Claude Code 读的是它自己的配置文件，不是系统环境变量。这篇手册就按「先确认 Node 环境 → 装 CLI → 写 settings.json → 注入环境变量 → 验证连通」的顺序走一遍，目标是一次跑通统一 Key/API 通道，后面换模型、换项目都不用再折腾。
适合谁看：已经装过 Node 18+ 和 npm、想在终端里用 Claude Code 写代码的人；如果你还没装 Node，先去官网装 LTS 版本再回来。下面所有命令都在 macOS/Linux 的 zsh 或 bash 下验证过，Windows 用 PowerShell 也能对应操作，路径换成C:\Users\你的用户名\.claude\settings.json即可。
2. 前置确认：Node/npm 版本与 TaoToken 通道准备
2.1 先确认 Node 和 npm 版本
Claude Code 对 Node 版本有硬性要求，低于 18 会直接报错退出。先跑这两条：
node -v npm -v正常输出类似v20.11.1和10.2.4。只要 Node 主版本 ≥ 18 就没问题。如果显示command not found，说明 Node 没装或没进 PATH，先解决这个再往下走。npm 版本一般跟着 Node 走，不用单独升级。
2.2 准备 TaoToken 的 Key 和 API 通道
TaoToken 提供统一的 Key/API 通道，Claude Code、Codex、Gemini CLI 这些工具可以共用一套接入方式，不用每个工具单独申请。你需要先去控制台拿一个 API Key，再确认接入地址。
拿 Key 的入口在控制台，创建后复制那串sk-开头的字符串，注意只显示一次，丢了就重新建一个。接入文档里有各工具的配置示例，Claude Code 对应的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两个字段。
注意：Key 属于敏感凭证，不要提交到 Git 仓库，也不要在截图里露出完整字符串。settings.json 建议放在用户目录下，不要放进项目目录。
3. 可复制配置：安装 CLI 与写 settings.json
3.1 全局安装 Claude Code CLI
用 npm 全局安装，命令很简单：
npm i -g @anthropic-ai/claude-code@latest装完验证一下：
claude --version能打印版本号就说明 CLI 装好了。如果你同时想用 Codex 或 Gemini CLI，可以一并装：
npm i -g @openai/codex@latest npm i -g @google/gemini-cli@latest这三个工具都能走 TaoToken 的统一通道，配置思路一致，只是环境变量名不同。
3.2 创建 settings.json 骨架
Claude Code 读取的配置文件在用户目录下的.claude/settings.json。先建目录再建文件：
mkdir -p ~/.claude vim ~/.claude/settings.json写入下面这段骨架，把ANTHROPIC_AUTH_TOKEN换成你自己的 Key：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } }这里有两个关键点。第一，ANTHROPIC_BASE_URL填 TaoToken 的 API 地址https://taotoken.net/api，不要带末尾斜杠，也不要写成官网首页地址，否则请求会打到错误的路由。第二，ANTHROPIC_AUTH_TOKEN就是控制台拿到的 Key，字段名必须完全一致，写成ANTHROPIC_API_KEY是不生效的。
3.3 环境变量注入的两种方式
settings.json 里的env字段是 Claude Code 启动时自己注入的，优先级高于 shell 环境变量。但有些场景你希望临时切换 Key，比如测试不同项目，这时可以在 shell 里覆盖：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的Key"写进~/.zshrc或~/.bashrc就能持久化。两种方式的关系是：settings.json 是项目无关的默认值，shell 变量是会话级覆盖。实测下来，建议把 Key 放 settings.json，把 BASE_URL 也放进去，shell 里只留一个空的环境变量占位，避免两处冲突。
| 配置项 | 位置 | 作用 | 优先级 |
|---|---|---|---|
| ANTHROPIC_BASE_URL | settings.json env | 指定 API 通道地址 | 高 |
| ANTHROPIC_AUTH_TOKEN | settings.json env | 身份凭证 | 高 |
| ANTHROPIC_BASE_URL | shell export | 会话级覆盖 | 低 |
| ANTHROPIC_AUTH_TOKEN | shell export | 会话级覆盖 | 低 |
4. 验证请求：跑通第一次对话与连通性检查
4.1 用 claude 命令做连通性验证
配置写完后，直接在终端跑：
claude第一次启动会进入交互界面。如果配置正确，你会看到欢迎信息和模型名称，直接输入一句「你好，帮我看看当前目录有哪些文件」就能得到回复。如果报401 Unauthorized，说明 Key 不对或没生效；如果报Connection error，多半是 BASE_URL 写错了。
想不进入交互界面快速验证，可以用管道传一句话：
echo "回复 ok 两个字" | claude -p-p是 print 模式，只输出结果不进入对话。正常会返回类似ok的内容，说明整条链路通了。
4.2 检查配置是否被正确读取
如果验证失败，先确认 Claude Code 读到了哪个配置文件：
cat ~/.claude/settings.json确认 JSON 格式合法，可以用python -m json.tool校验：
python -m json.tool ~/.claude/settings.json格式错误会直接报行号，比如多了一个逗号或少了引号。JSON 不允许注释和尾随逗号，这是新手最容易踩的坑。
4.3 用 curl 直接测 API 通道
想排除 CLI 本身的干扰，可以直接用 curl 打一次接口：
curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'返回 JSON 里带content字段就说明通道正常。这一步能快速区分是 Key/通道问题还是 CLI 配置问题。
5. 本篇常见错排查：401、404 与配置不生效
5.1 报 401 Unauthorized
最常见的原因是 Key 复制时带了空格，或者把sk-前缀漏了。重新从控制台复制一次，粘贴到 settings.json 后保存。另一个原因是字段名写错，必须是ANTHROPIC_AUTH_TOKEN，不是ANTHROPIC_API_KEY，也不是AUTH_TOKEN。改完记得重启终端，Claude Code 只在启动时读一次配置。
5.2 报 404 或路由错误
检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net或https://taotoken.net/api/。正确值是https://taotoken.net/api，不带末尾斜杠。带斜杠会导致拼接出//v1/messages这种双斜杠路径，部分网关会返回 404。
5.3 配置改了但不生效
Claude Code 的配置读取顺序是：项目目录下的.claude/settings.json> 用户目录下的~/.claude/settings.json> shell 环境变量。如果你在项目里也建了一个 settings.json，它会覆盖用户级的。排查时先看当前目录有没有.claude文件夹：
ls -la .claude 2>/dev/null有的话检查里面的配置，或者临时改名排除干扰。
5.4 npm 全局安装权限报错
在 macOS/Linux 上跑npm i -g报EACCES，说明全局目录没权限。不要用sudo npm i -g，会把文件属主搞乱。正确做法是改 npm 全局目录到用户空间：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH把最后一行写进~/.zshrc，重开终端再装一次。
6. 后续接入与统一通道的延伸用法
配置跑通后，Claude Code 就能正常在终端里干活了。如果你还想把 Codex、Gemini CLI 也接到同一套通道，思路是一样的：找到各自的配置文件，把 BASE_URL 指向 TaoToken 的 API 地址，把 Key 填进对应的凭证字段。这样一套 Key 管三个工具，切换成本很低。
长期在终端里做编码和 Agent 任务的话，可以关注 Coding Plan 这类按周期计费的方案，比按量付费更适合高频使用。需要看模型列表或临时对话验证，用模型对话页面就行。接入过程中遇到报错，先去 API Keys 页面确认 Key 状态，再对照接入文档检查字段名和地址。
最后留一个实用习惯：把~/.claude/settings.json备份一份到密码管理器里，换电脑时直接粘贴，省得重新配。Key 轮换时只改这一个文件，所有走该配置的会话下次启动自动生效。
