Claude Code

TIP

用 skill 自动配置

安装 ModelFold skill 后，可以直接对 Agent 说“把 Claude Code 配置成使用 ModelFold”，由它按本页步骤完成配置；也可以照本页手动配置。

npx skills add https://ai.modelfold.online/

Claude Code 说的是 Anthropic Messages 协议,ModelFold 的 Claude 模型正是按这个协议提供的。Claude Code 通过 ANTHROPIC_BASE_URL 和一个凭据变量连过来。

重要规则

1. 通过 GET https://ai.modelfold.online/anthropic/v1/models 发现模型,不要凭记忆或训练数据写模型名。 这个接口给出的才是 Claude Code 真正能跑的那份列表。
2. 用 Authorization: Bearer 认证。 ModelFold 的所有接口都靠这一个请求头携带 API key,列模型接口也一样。名字就叫 apikey 的请求头会被 401 拒掉。Claude Code 从 ANTHROPIC_AUTH_TOKEN 读这个头,并自己加上 Bearer 前缀,所以变量里放原始 key。ANTHROPIC_API_KEY 会作为 X-Api-Key 发出,ModelFold 也接受(原始 key 即可),但推荐用 ANTHROPIC_AUTH_TOKEN。
3. ANTHROPIC_BASE_URL 要写成 https://ai.modelfold.online/anthropic。 Claude Code 会自己往后面拼 /v1/messages。列模型和发请求共用这一前缀:GET /anthropic/v1/models 和 POST /anthropic/v1/messages。

列出可用模型

curl -s -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  https://ai.modelfold.online/anthropic/v1/models |
  jq -r '.data[] | [.id, .display_name, (.max_input_tokens | tostring),
                    (.max_tokens | tostring)] | @tsv'

Windows(PowerShell)下用 curl.exe 发同样的请求:

curl.exe -s -H "Authorization: Bearer $env:MODELFOLD_API_KEY" `
  https://ai.modelfold.online/anthropic/v1/models | jq -r '.data[].id'

响应是 Anthropic 兼容的形状。.data[] 就是列表:id 是 Claude Code 发出去的模型名,display_name、max_input_tokens、max_tokens 说明这个模型接受什么。type 和 created_at 是样板字段。若 has_more 为 true,把 after_id 设成 last_id 再请求下一页。

这些 id 和 Anthropic 官方的一致。用户要指定模型时再把 id 列出来。每次都重新跑这个列表,不要复用之前的答案——模型集合会变。

写配置

Claude Code 用环境变量接收 base URL、凭据和模型:

export ANTHROPIC_BASE_URL=https://ai.modelfold.online/anthropic
export ANTHROPIC_AUTH_TOKEN=$MODELFOLD_API_KEY

ANTHROPIC_BASE_URL 是发请求的根路径,Claude Code 会自己往后面拼 /v1/messages,所以这里配的是 https://ai.modelfold.online/anthropic,不是完整的请求 URL https://ai.modelfold.online/anthropic/v1/messages。

ANTHROPIC_AUTH_TOKEN 存放密钥。Claude Code 把它作为 Authorization: Bearer 发出去。不要在值里再写 Bearer ——那样会变成 Bearer Bearer …。

另一个凭据变量是 ANTHROPIC_API_KEY,作为 X-Api-Key 发出,值必须是 Bearer 加上 key。

ModelFold 用的 id 和 Anthropic 官方一致,所以 Claude Code 内置的 sonnet、opus、haiku、fable 别名不用重映射就能用。只有要指定某个模型时,才把 ANTHROPIC_MODEL 设成列表里的 id,或用 --model / /model 切换。settings 文件里的 model 键只在 ANTHROPIC_MODEL 未设置时生效。

同样的变量可以写进 settings 文件的 env:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.modelfold.online/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "…"
  }
}

同一个变量在 shell 和 settings 文件里都设了时,以 settings 文件为准。不要把凭据写进项目级 .claude/settings.json——那个文件会进仓库。用用户级文件或 .claude/settings.local.json。

macOS 与 Linux

用户级文件是 ~/.claude/settings.json。在启动 claude 的同一个 shell 里导出这些变量,或者写进 shell profile:

export ANTHROPIC_BASE_URL=https://ai.modelfold.online/anthropic
export ANTHROPIC_AUTH_TOKEN=$MODELFOLD_API_KEY

Windows(PowerShell)

文件是 %USERPROFILE%\.claude\settings.json,内容完全一致。

$env:ANTHROPIC_BASE_URL = "https://ai.modelfold.online/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = $env:MODELFOLD_API_KEY
setx ANTHROPIC_BASE_URL "https://ai.modelfold.online/anthropic"
setx ANTHROPIC_AUTH_TOKEN "$env:MODELFOLD_API_KEY"

setx 对此后新开的窗口生效。想立刻用上,同时设 $env:。

确认配置生效

在设好这些变量的 shell 里启动 claude,运行 /status。Status 页应显示 Anthropic base URL 为 https://ai.modelfold.online/anthropic,以及一行点名 ANTHROPIC_AUTH_TOKEN 的鉴权信息(若用的是 ANTHROPIC_API_KEY,则点那个名字)。然后发一条消息。

若弹出 Anthropic 账号登录,说明变量没有进到这个进程。彻底退出终端,从已导出变量的 shell 里重新打开。

claude --debug 会打印 Claude Code 实际发出的请求。

常见坑

1. 名字就叫 apikey 的请求头。 ModelFold 会返回 401。把原始 key 放进 ANTHROPIC_AUTH_TOKEN(推荐)或 ANTHROPIC_API_KEY。
2. 把完整请求 URL 写进 ANTHROPIC_BASE_URL。 Claude Code 自己会拼 /v1/messages,所以值以 /v1 或 /v1/messages 结尾会拼成 /v1/v1/messages。
3. 报 model not found。 Claude Code 要的 id 这个接口没有。运行 /model,从列表里挑一个。
4. 凭据写进了项目级 .claude/settings.json。 那个文件会进仓库。用用户级文件或 .claude/settings.local.json。
5. 在 ANTHROPIC_AUTH_TOKEN 里写了 Bearer 。 Claude Code 自己会加前缀,请求头会变成 Bearer Bearer …。
6. setx 不影响当前窗口。 它对此后新开的窗口生效。想立刻用上,同时设 $env:。
7. PowerShell 的 curl。 它是 Invoke-WebRequest 的别名,不接受这些参数。用 curl.exe。
8. 弹出 Anthropic 账号登录。 这个进程里变量是空的。关掉所有终端,包括编辑器里的,从已导出变量的 shell 里重开。

要用不是本协议的 listing 里的模型,见「安装 modelfold-chat-agents」页的「协议不一致时」一节。