Agent

Claude Code 接入 DeepSeek API

settings.json 最小配置、模型档位映射、多套配置切换与常见报错排查

Claude Code 默认要登录 Anthropic 官方账号；换成自己的 API 只需要两个变量：ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。本文以 DeepSeek 为例（撰写时版本：Claude Code 2.1.178，模型 deepseek-v4-pro[1m] / deepseek-flash）。

配置来源与请求链路

一、最小配置

配置文件位置：

系统路径
Linux / macOS / WSL~/.claude/settings.json
WindowsC:\Users\<用户名>\.claude\settings.json

把下面这段抄进 settings.json（BASE_URL、TOKEN、模型名换成自己的）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的key",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]"
  },
  "model": "haiku",
  "includeCoAuthoredBy": false
}

字段含义：

字段作用
ANTHROPIC_BASE_URL请求发到哪：官方、兼容端点或中转站
ANTHROPIC_AUTH_TOKEN鉴权 token（服务商给的 sk-...）
ANTHROPIC_MODEL默认模型名
ANTHROPIC_DEFAULT_*_MODEL把 Claude Code 的档位映射到服务商的模型
model默认用哪一档：haiku / sonnet / opus
includeCoAuthoredBy提交信息里是否带 Claude 署名，一般关掉

二、模型档位映射

Claude Code 内部按档位（不是具体模型名）发请求，2.x 共四档：

档位环境变量用途
fableANTHROPIC_DEFAULT_FABLE_MODEL新增档位
haikuANTHROPIC_DEFAULT_HAIKU_MODEL后台小任务、快速响应
sonnetANTHROPIC_DEFAULT_SONNET_MODEL日常主力
opusANTHROPIC_DEFAULT_OPUS_MODEL复杂任务

不映射也能启动，但服务商不认识 claude-* 这类模型名就会报错。DeepSeek 只有两个模型，本机这样映射：

opus   → deepseek-v4-pro[1m]     # 复杂任务用 pro
sonnet → deepseek-flash
haiku  → deepseek-flash          # 小任务用便宜的 flash

模型名实测：

名称结果
deepseek-flash / deepseek-v4-pro✅ 官方 ID
deepseek-v4-pro[1m]✅ 1M 上下文变体，服务商不支持时去掉后缀
deepseek-v4-flash✅ 旧别名，仍可用
deepseek-v4.1-flash❌ 400，不是有效模型名

官方列表可自查：curl -H "Authorization: Bearer $KEY" https://api.deepseek.com/models。

老配置里常见的 ANTHROPIC_SMALL_FAST_MODEL 等价于 haiku 档。

三、配置来源与优先级

三个地方都能改，优先级从高到低：

  1. --settings <file-or-json>：只对当前这条命令生效
  2. ~/.claude/settings.json 的 env 段：最常用，一次配好
  3. Shell 环境变量：export ANTHROPIC_BASE_URL=...，适合临时测试

实测：shell 里给错的 BASE_URL，settings.json 的 env 仍然覆盖。

--setting-sources user,project,local 可以控制加载哪些来源。

四、多套配置切换

需要对比不同服务商时，把配置存成不同文件名，切换时用 --settings 指定：

settings.json 配置与多套配置切换

ls ~/.claude/settings.json*
# settings.json  settings.json.bak  settings.json.relay-a  settings.json.relay-b

claude --settings ~/.claude/settings.json.relay-a   # 这次用它跑

要固定切换就做成别名：

# ~/.bashrc
alias claude-d='claude --settings ~/.claude/settings.json'               # 默认：DeepSeek
alias claude-a='claude --settings ~/.claude/settings.json.relay-a'       # 备用线路
配置BASE_URLopus / haiku 映射
默认（DeepSeek）https://api.deepseek.com/anthropicdeepseek-v4-pro[1m] / deepseek-flash
中转 Ahttps://中转站域名claude-opus-4-8 / claude-haiku-4-5
中转 Bhttps://另一个中转站claude-opus-4-8 / gpt-5.5

五、Windows 端

同样放 %USERPROFILE%\.claude\settings.json，结构完全一致。环境变量写法不同：

# 临时（当前窗口）
$env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的key"

# 永久（写入用户环境变量，重开终端生效）
setx ANTHROPIC_BASE_URL "https://api.deepseek.com/anthropic"
setx ANTHROPIC_AUTH_TOKEN "sk-你的key"

六、验证

claude -p "只回复 ok"     # 返回 ok 就通了

交互模式里用 /status 查看当前生效的 BASE_URL 和模型。

七、常见报错

现象原因解法
401 UnauthorizedTOKEN 错、过期或没配重新生成并更新 ANTHROPIC_AUTH_TOKEN
400 / model not found模型名不在服务商列表用 /models 接口核对；DeepSeek 只有 deepseek-v4-pro / deepseek-flash
404 / invalid pathBASE_URL 少了路径兼容端点通常有固定路径（DeepSeek 是 /anthropic），按服务商文档填全
缓存相关报错中转不支持 prompt caching设 DISABLE_PROMPT_CACHING=1
网关要求额外 header中转鉴权方式不同ANTHROPIC_CUSTOM_HEADERS，如 "x-api-key: xxx"
请求发去了奇怪的地方代理环境变量劫持检查 HTTP_PROXY / HTTPS_PROXY，必要时 unset
配了 env 仍走官方交互模式里 /login 登录过官方账号settings.json 的 env 优先级更高；必要时 /logout 清除登录态

八、安全

  • key 只放本机：不要提交进仓库，也不要用共享 settings.json 的方式「同步配置」
  • 文件权限：chmod 600 ~/.claude/settings.json
  • 权限白名单放 settings.local.json：本机就是这么分的——settings.json 放 provider 配置，settings.local.json 放工具权限

小结

  1. 切 API = 改 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN，写进 ~/.claude/settings.json 的 env 段
  2. 服务商不认 claude-* 模型名时，用 ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL 做映射
  3. 模型名以服务商 /models 列表为准，不要凭记忆写
  4. 多套配置存成不同文件，claude --settings xxx.json 临时切换
  5. key 不进仓库，文件权限 600
© 2026 BINGBlog