# Claude Code

Anthropic 的终端编程助手,擅长理解需求、规划与改写代码。本页带你从安装到接上 Clomio。Claude Code 接网关时走 **Anthropic Messages API**:客户端把请求发到 `ANTHROPIC_BASE_URL + /v1/messages`,不是 OpenAI `/v1/responses`。

> 关键点: `ANTHROPIC_BASE_URL` 只填域名根地址,不要带 `/v1`。例如填 `https://api.clomio.ai`,不要填 `https://api.clomio.ai/v1`。

---

## 一、安装 Claude Code

### 方式 A:镜像一键安装(推荐,无需 Node.js)

从 `help.clomio.ai` 镜像直连下载独立二进制,国内直连、不依赖 Node。

```bash
curl -fsSL https://help.clomio.ai/claude/install.sh | bash
```

Windows PowerShell:

```powershell
irm https://help.clomio.ai/claude/install.ps1 | iex
```

### 方式 B:npm 全局安装

需要先装好 [Node.js 环境](#/nodejs)。

```bash
npm install -g @anthropic-ai/claude-code
```

macOS / Linux 遇权限问题加 `sudo`。

### 验证与更新

```bash
claude --version
claude doctor
claude update
```

输出版本号即安装成功。`claude update` 会自行检查并更新到最新版;镜像安装也可以按当前系统重跑 `install.sh` 或 `install.ps1`,npm 安装也可以 `npm install -g @anthropic-ai/claude-code@latest`。

---

## 二、获取密钥

在控制台 [api.clomio.ai](https://api.clomio.ai) 创建一个可用于 Claude Code 的 API Key。建议选择 **Claude/Anthropic 平台分组**；如果使用 OpenAI 平台分组，只有该分组明确开放 `/v1/messages` 兼容能力时才适合 Claude Code，否则会被网关拒绝。

注意两类常见限制:

- **未分组 Key**：生产使用不建议空分组；如果 Key 未绑定分组，常见表现是 403 或 key 未分配分组提示。
- **Claude Code only 分组**：这类分组只适合真实 Claude Code 客户端；非 Claude Code 请求可能会被拒绝。

详见 [创建 API 密钥](#/api-key)。

---

## 三、接上 Clomio

Claude Code 通过 `ANTHROPIC_BASE_URL` 指向网关,通过凭据变量带上你的 key。

| 设置项 | 推荐值 | 说明 |
|--------|--------|------|
| `ANTHROPIC_BASE_URL` | `https://api.clomio.ai` | 只填根地址,不带 `/v1` |
| `ANTHROPIC_AUTH_TOKEN` | 你的 Clomio 密钥 | 发送为 `Authorization: Bearer ...`,Clomio 推荐用这个 |
| `ANTHROPIC_API_KEY` | 仅在网关要求 `x-api-key` 时使用 | 发送为 `x-api-key: ...`,不要和 `ANTHROPIC_AUTH_TOKEN` 混用 |

> 地址可换成另外两条线路(`https://sub.qazwc.com` 或 `https://crs.qazwc.com`),国内通常更稳。见 [网关线路](#/gateway-lines)。

### 方式 A:写入配置文件(推荐,重启不丢)

把下面内容写进 `~/.claude/settings.json`(Windows 为 `%USERPROFILE%\.claude\settings.json`):

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.clomio.ai",
    "ANTHROPIC_AUTH_TOKEN": "你的密钥",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

如果是项目专用密钥,放在 `<项目>/.claude/settings.local.json`,并确认该文件已加入 `.gitignore`。

如果“改了配置但仍走旧地址/旧 key”,不要只看一个文件。按这个顺序查实际来源:

```bash
# Claude Code 会话里先看 /status,确认 base URL 与凭据来源
claude
# 进入后输入: /status
# 如果发现仍在用旧 claude.ai 登录或旧网关,可先 /logout 再重新启动

# 退出后在同一个终端查环境与配置文件
env | grep -E 'ANTHROPIC|CLAUDE'
cat ~/.claude/settings.json
cat .claude/settings.local.json 2>/dev/null
```

用户级、项目级、本地 `settings.local.json`、企业托管设置、shell `export`、CC Switch 写入都可能参与最终环境。最终以 `/status` 显示的 Anthropic base URL、Auth token/API key 来源为准。

### 方式 B:环境变量

**临时(仅当前终端):**

```bash
export ANTHROPIC_BASE_URL="https://api.clomio.ai"
export ANTHROPIC_AUTH_TOKEN="你的密钥"
```

**永久(macOS / zsh):**

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.clomio.ai"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的密钥"' >> ~/.zshrc
source ~/.zshrc
```

**永久(Windows / PowerShell):**

```powershell
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.clomio.ai", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "你的密钥", "User")
```

### 方式 C:CC Switch 图形化

[CC Switch](https://github.com/farion1231/cc-switch) 是一个开源的供应商切换工具。安装后新增一个「自定义」供应商,请求地址填 `https://api.clomio.ai`、API Key 填你的密钥,启用即可。确认它最终写入的是根地址,不要额外拼 `/v1`。

### Base URL 写错 `/v1` 的典型症状

Claude Code 官方网关变量是 `ANTHROPIC_BASE_URL`,客户端会在这个值后面自己拼 `/v1/messages`。如果误写成 `https://api.clomio.ai/v1`,实际请求会变成 `/v1/v1/messages`,常见表现是 404、`Cannot POST /v1/v1/messages`、`/status` 里 base URL 带着 `/v1`,或 curl 手测根本打不到 `msg_` 响应。修正后重开终端/重启 Claude Code,再运行 `/status` 确认。

快速自检:

```bash
printf '%s
' "$ANTHROPIC_BASE_URL"
# 正确: https://api.clomio.ai
# 错误: https://api.clomio.ai/v1
```

若怀疑旧 shell 或脚本污染,先清掉再只设置本次要用的两项:

```bash
unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.clomio.ai"
export ANTHROPIC_AUTH_TOKEN="你的密钥"
```

如果 `/status` 仍显示旧登录方式,在 Claude Code 内执行 `/logout`,退出后重新打开终端再启动。`ANTHROPIC_AUTH_TOKEN` 会走 `Authorization: Bearer ...`;`ANTHROPIC_API_KEY` 会走 `x-api-key: ...`。Clomio 常规网关 Key 推荐只保留 `ANTHROPIC_AUTH_TOKEN`,不要两种凭据长期同时存在。

---

## 四、先用 curl 验证网关

在打开 Claude Code 前先测一次 Anthropic Messages API。成功能把网络、base URL、key、分组问题先排掉。

```bash
curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages"   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-4-6","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'
```

看到 `id` 以 `msg_` 开头、并有 `content` 字段,说明网关可达且鉴权通过。若你的网关/工具要求 `ANTHROPIC_API_KEY`,把请求头换成:

```bash
-H "x-api-key: $ANTHROPIC_API_KEY"
```

---

## 五、开始使用

进入任意项目目录,运行:

```bash
claude
```

第一次有初始化引导,一路回车用默认即可。进去后输入:

```text
你现在用的是什么模型? 请只回答模型名。
```

再运行 `/status`,确认能看到 `Anthropic base URL: https://api.clomio.ai` 以及 `Auth token` 或 `API key` 来源。

---

## 常见问题

**`claude` 提示命令找不到?** npm 全局目录可能没在 `PATH` 里,或需重开终端。见 [故障排查](#/troubleshooting)。

**报 401 / 鉴权失败?** 先确认 `ANTHROPIC_BASE_URL` 没带 `/v1`;再确认使用的是 `ANTHROPIC_AUTH_TOKEN` 还是 `ANTHROPIC_API_KEY`。Clomio 常规 key 推荐放 `ANTHROPIC_AUTH_TOKEN`,对应 `Authorization: Bearer`。

**`/status` 显示的凭据不是你刚设置的?** 先 `env | grep ANTHROPIC`,再查 `~/.claude/settings.json`、项目 `.claude/settings.local.json` 和 CC Switch 写入项。必要时 `/logout` 清旧登录,并只保留 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`。

**报 403 且提示 key 未分组?** 去控制台把 API Key 绑定到可用分组；生产环境不建议使用未分组 Key。

**报 `This group does not allow /v1/messages dispatch`?** 你的 Key 绑定到了 OpenAI 平台分组,但该分组未开放 Claude Code 所需的 `/v1/messages` 兼容能力。换 Claude/Anthropic 分组,或使用已开放 Messages 兼容能力的 OpenAI 分组。

**Claude Code 主路径是哪条?** Claude Code 主对话是 `POST /v1/messages`;`POST /v1/messages/count_tokens` 只是 token 估算。Codex/OpenAI 的 `POST /v1/responses` 不要写成 Claude Code 主路径。

**`count_tokens` 404?** Claude Code 会请求 `/v1/messages/count_tokens` 做上下文估算。sub2api 对 OpenAI/Grok 分组会返回 404;对不支持 count_tokens 的上游也会返回 404 让客户端本地估算。只要 `/v1/messages` 正常,通常不影响主对话。

**MCP 工具很多但 tool search 不工作?** 官方 Claude Code 在自定义 `ANTHROPIC_BASE_URL` 下默认会关闭 MCP tool search。若你的网关能透传 `tool_reference` beta 块,可设置 `ENABLE_TOOL_SEARCH=true`;否则保持默认或设 `ENABLE_TOOL_SEARCH=false/auto` 更稳。见 [Claude Code 进阶](#/claude-advanced)。

**卡顿或偶发不可用?** 去控制台给密钥换一个分组/节点,或换 [网关线路](#/gateway-lines) 后重试。

**GitHub Action/CI 里接网关不生效?** 先确认 action/runner 版本是否支持传入 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 或等价环境变量。社区里有 claude-code-action 通过 LLM Gateway 的讨论,不同版本支持面可能不同;把它当作版本排查项,不要假定所有 action 都会读取你本机的 `~/.claude/settings.json`。如果主对话走了网关,但评论分类、安全指导、advisor 或 VS Code 扩展仍直连官方/报 403,优先升级相关组件并检查该路径是否转发了同一组 env。

---

## 官方/社区经验来源

- [Anthropic: Other LLM gateways](https://docs.anthropic.com/en/docs/claude-code/llm-gateway):网关要暴露 Anthropic-format endpoint,且只设置 `ANTHROPIC_BASE_URL` 不等于替换登录凭据。
- [Anthropic: Settings](https://docs.anthropic.com/en/docs/claude-code/settings):用户/项目/本地/托管设置的层级与 `/status` 校验方式。
- [Anthropic: Corporate proxy](https://docs.anthropic.com/en/docs/claude-code/corporate-proxy):企业代理与 LLM Gateway 可以同时存在,代理变量会影响所有出站请求。
- [claude-code-action LLM Gateway discussion](https://github.com/anthropics/claude-code-action/discussions/272):CI/Action 接网关时优先核对 action 版本和 env 传递,作为版本相关排查项。
- [claude-code-action issue #1418](https://github.com/anthropics/claude-code-action/issues/1418):某些 action 辅助路径曾出现硬编码官方 URL 的版本相关问题;若只有部分 CI 步骤绕过网关,先升级并查该 issue 类似症状。
- [Claude Code issue #9010](https://github.com/anthropics/claude-code/issues/9010):VS Code 扩展曾有不继承自定义 LLM Gateway 配置的报告;CLI 正常而扩展异常时,按扩展版本/设置来源排查。
- [@rauchg 的 Vercel AI Gateway 示例](https://x.com/rauchg/status/2007556249437778419):公开社区经验也采用 `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` 的网关接法;迁移到 Clomio 时仍按本文的“不带 `/v1` 根地址”规则。
- [MLflow Gateway + Claude Code 公开示例](https://x.com/MLflow/status/2057915356950172076):把 Claude Code 指向 Anthropic-format gateway/proxy;若 CLI 正常但辅助路径异常,继续按 env 继承与版本差异排查。