Claude Code

Claude Code 使用 Anthropic Messages API。AIOHub 接入 Claude Code 时，ANTHROPIC_BASE_URL 填网关根地址，Claude Code 会自行追加 /v1/messages。

前置条件

已安装 Claude Code（需要 Node.js 18+）
已创建 AIOHub API 令牌
API 令牌的分组包含 Claude / Anthropic-compatible 模型
账户有充足余额

配置方法

方法一：环境变量（推荐）

在终端中设置环境变量后启动 Claude Code：

export ANTHROPIC_BASE_URL="https://api.aiohub.org"
export ANTHROPIC_AUTH_TOKEN="sk-你的API令牌"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"
claude

ANTHROPIC_BASE_URL 不要加 /v1。ANTHROPIC_AUTH_TOKEN 填完整的 sk- API 令牌值，不要手动加 Bearer ；Claude Code 会通过 Authorization Bearer 鉴权发送。

方法二：写入 Shell 配置文件

将环境变量添加到 Shell 启动配置中，每次打开终端自动生效：

macOS / Linux (zsh)
macOS / Linux (bash)
Windows PowerShell

# 编辑 ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.aiohub.org"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的API令牌"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.zshrc
source ~/.zshrc

# 编辑 ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.aiohub.org"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的API令牌"' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL="claude-sonnet-4-20250514"' >> ~/.bashrc
source ~/.bashrc

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.aiohub.org", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的API令牌", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-20250514", "User")

设置后重启终端生效。

方法三：别名

创建一个命令别名，在需要时快速启动：

# 添加到 ~/.zshrc 或 ~/.bashrc
alias mycc="ANTHROPIC_BASE_URL=https://api.aiohub.org ANTHROPIC_AUTH_TOKEN=sk-你的API令牌 ANTHROPIC_MODEL=claude-sonnet-4-20250514 claude"

之后运行 mycc 即可启动使用 AIOHub 的 Claude Code。

方法四：settings.json

在 Claude Code 的 settings.json 中配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
  }
}

用户级配置位于 ~/.claude/settings.json。项目私有配置可放在 .claude/settings.local.json，不要提交真实 API 令牌。

可选：1 小时 prompt caching

Claude API 的 prompt caching 默认 TTL 是 5 分钟。如果你经常在 Claude Code 中恢复长会话、处理大仓库上下文，或在 5 分钟后仍会复用同一段长前缀，可以在 ~/.claude/settings.json 的 env 中加入 ENABLE_PROMPT_CACHING_1H，请求使用 1 小时 TTL：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}

1 小时 TTL 适合会反复复用长上下文的会话。Anthropic 的计费规则中，1 小时 cache write 按基础输入 token 价格的 2 倍计费，cache read 按较低价格计费；如果你总是在 5 分钟内继续会话，默认缓存通常已经够用。

可选：关闭 attribution header

Claude Code 默认会在系统提示词开头插入一段动态的 attribution header（包含客户端版本、prompt 指纹等），每次请求都会变化。通过网关转发时，这段变化的前缀会导致网关侧 KV cache 失效，拖慢推理速度。在 ~/.claude/settings.json 的 env 中设置 CLAUDE_CODE_ATTRIBUTION_HEADER 为 "0" 可以省略这段动态内容，提升 prompt cache 命中率：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

此设置仅影响网关/代理侧的缓存行为，Anthropic 官方 API 的 prompt caching 不受影响。如果你直连 Anthropic API 而非通过网关，无需设置此项。

验证配置

启动 Claude Code 后，发送一条消息。如果正常回复，说明配置成功。先确认 Claude Code 命令可用：

claude --version

也可以检查环境变量是否正确设置：

macOS / Linux
Windows PowerShell

test "$ANTHROPIC_BASE_URL" = "https://api.aiohub.org" && echo "base url ok"
test -n "$ANTHROPIC_AUTH_TOKEN" && echo "api key configured"
test -n "$ANTHROPIC_MODEL" && echo "model configured"

if ($Env:ANTHROPIC_BASE_URL -eq "https://api.aiohub.org") { "base url ok" }
if ($Env:ANTHROPIC_AUTH_TOKEN) { "api key configured" }
if ($Env:ANTHROPIC_MODEL) { "model configured" }

常用调试命令

在 Claude Code 会话内可以用这些命令定位客户端状态：

命令	用途
`/status`	查看当前会话状态
`/context`	查看上下文 Token 用量
`/clear`	清空当前会话后重新开始
`/model`	查看或切换模型

协议说明

Claude Code 会向网关发送 Anthropic Messages 请求，常见路径是 POST /v1/messages。因此 Base URL 必须是 https://api.aiohub.org，而不是 https://api.aiohub.org/v1。如果你用 curl 手动验证，需要自己写完整路径和 Anthropic 版本头：

curl https://api.aiohub.org/v1/messages \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "Hello from AIOHub"}]
  }'

常见问题

启动时反复弹出登录界面

检查当前 shell 是否真的带上 ANTHROPIC_AUTH_TOKEN。如果同时设置了 ANTHROPIC_API_KEY，Claude Code 可能按 API key 模式处理；AIOHub 推荐使用 ANTHROPIC_AUTH_TOKEN。如果你把配置写入 settings.json，可以加上 apiKeyHelper：

{
  "apiKeyHelper": "echo 'sk-你的API令牌'",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aiohub.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌",
    "ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
  }
}

404 或 API Connect Error

确认 ANTHROPIC_BASE_URL 没有 /v1。如果填成 https://api.aiohub.org/v1，Claude Code 可能请求到 /v1/v1/messages。

400 错误

使用 /clear 清空会话后重试，并确认所选模型存在于你的 API 令牌的分组中。若错误与 Claude Code 实验特性有关，可以在启动环境中加入 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 后重试。

上下文过大或会话变慢

使用 /context 查看上下文分布。必要时新建会话、清空会话，或减少自动压缩前的长历史内容。

余额不足错误

前往钱包管理查看余额并充值。

选择客户端

AI 编程工具

OpenAI 兼容应用

图片客户端

聊天客户端

前置条件

配置方法

方法一：环境变量（推荐）

方法二：写入 Shell 配置文件

方法三：别名

方法四：settings.json

可选：1 小时 prompt caching

可选：关闭 attribution header

验证配置

常用调试命令

协议说明

常见问题

官方参考

​前置条件

​配置方法

​方法一：环境变量（推荐）

​方法二：写入 Shell 配置文件

​方法三：别名

​方法四：settings.json

​可选：1 小时 prompt caching

​可选：关闭 attribution header

​验证配置

​常用调试命令

​协议说明

​常见问题

​官方参考

前置条件

配置方法

方法一：环境变量（推荐）

方法二：写入 Shell 配置文件

方法三：别名

方法四：settings.json

可选：1 小时 prompt caching

可选：关闭 attribution header

验证配置

常用调试命令

协议说明

常见问题

官方参考