# Claude Code 配置详解

Claude Code 的行为由 `settings.json`、环境变量和登录凭据共同决定。本页解释接入 Clomio 最常用的字段。你不需要全配,挑需要的加即可。

---

## 配置文件在哪、谁优先

`settings.json` 会从多个位置读取并合并,常见优先级从低到高:

| 位置 | 作用域 | 说明 |
|------|--------|------|
| `~/.claude/settings.json` | 用户级 | 你的个人默认,所有项目生效 |
| `<项目>/.claude/settings.json` | 项目级 | 该项目专属,可随仓库共享,不要放密钥 |
| `<项目>/.claude/settings.local.json` | 本地 | 个人本地覆盖,放密钥用这个,记得加进 `.gitignore` |
| 托管设置(企业) | 最高 | 企业策略强制,用户/项目都改不了 |

> 用 `/config` 命令可在界面里查看和改设置;新版也支持 `/config verbose=true` 这类单项修改。实际生效的 base URL 和凭据来源请用 `/status` 看。

---

### 设置与 shell 环境谁覆盖谁

官方配置层级里,托管设置最高,然后是命令行、本地、项目、用户设置;权限规则会合并,普通标量设置按高优先级覆盖低优先级。`settings.json` 的 `env` 会注入 Claude Code 会话和它启动的子进程,但你从某个 shell 直接启动 `claude` 时,本机 shell 里已有的 `ANTHROPIC_*` 也会参与最终环境。排障时不要只看文件,要同时看当前进程环境和 `/status`。

建议顺序:

1. 团队共享值放 `<项目>/.claude/settings.json`,不要放密钥。
2. 个人密钥放 `<项目>/.claude/settings.local.json` 或用户级 `~/.claude/settings.json`。
3. 临时排障用 shell `export`,结束后 `unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY` 避免覆盖文件配置。
4. 最终以 Claude Code 内 `/status` 显示的 base URL 与凭据来源为准。

## 核心字段

### `env` —— 环境变量(接入 Clomio 就在这里)

`env` 里的变量会注入 Claude Code 进程,也是配置网关的地方。Clomio 推荐最小配置:

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

重点规则:

- `ANTHROPIC_BASE_URL` 只填根地址,例如 `https://api.clomio.ai`;Claude Code 会自己请求 `/v1/messages` 和 `/v1/messages/count_tokens`。
- `ANTHROPIC_AUTH_TOKEN` 会发送为 `Authorization: Bearer <key>`,适合大多数 Clomio/网关 key。
- `ANTHROPIC_API_KEY` 会发送为 `x-api-key: <key>`,适合明确要求 Anthropic Console key 或 `x-api-key` 的网关。
- 两者同时存在时,官方认证链路会按活跃登录/网关 token/API key 规则选择;为减少误判,日常只保留一种网关凭据,并用 `/status` 确认。
- 只有 `ANTHROPIC_BASE_URL` 而没有网关凭据时,已保存的 claude.ai 登录仍可能成为活跃凭据。用 `/status` 确认当前是否真的在用 Clomio key。

常用环境变量:

| 变量 | 作用 |
|------|------|
| `ANTHROPIC_BASE_URL` | 网关根地址,指向 Clomio(可换[线路](#/gateway-lines)),不要带 `/v1` |
| `ANTHROPIC_AUTH_TOKEN` | Clomio key 推荐放这里,走 `Authorization: Bearer` |
| `ANTHROPIC_API_KEY` | 直连 Anthropic Console 或网关要求 `x-api-key` 时使用 |
| `ANTHROPIC_CUSTOM_HEADERS` | 给网关追加自定义头,多行用 `\n` 分隔 |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设 `1` 关闭非必要的遥测/辅助请求,更干净也更省流量 |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设 `1` 后从网关 `/v1/models` 补充 `/model` 选择器 |
| `ENABLE_TOOL_SEARCH` | 控制 MCP tool search;自定义 base URL 下默认会退回非 tool-search 模式 |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 网关/上游不兼容新版 beta 字段时报错时可设 `1` 降低请求复杂度 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | 子代理使用的模型(可与主模型不同) |
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | 设 `1` 开启实验性的代理团队能力 |

### `model` —— 默认模型

```json
{ "model": "claude-sonnet-4-6" }
```

填模型 ID 或官方 alias。`ANTHROPIC_BASE_URL` 只改变请求发往哪里,不改变模型名本身。可用模型以 Clomio 分组/账号实际开放为准;会话里也可随时用 `/model` 切换。

如果你希望 `/model` 面板显示网关返回的模型,可以加:

```json
{
  "env": {
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}
```

### `permissions` —— 权限护栏

控制哪些工具调用需要确认。三个数组 `deny` / `ask` / `allow`,按 deny → ask → allow 顺序匹配,先命中者生效:

```json
{
  "permissions": {
    "allow": ["Bash(git*)", "Read"],
    "ask": ["Bash(rm*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "additionalDirectories": ["../shared-lib"]
  }
}
```

- `allow`:跳过确认直接执行(配好常用命令能少弹很多次授权)
- `ask`:每次询问,适合删除、部署、数据库修改
- `deny`:直接拒绝,从不执行(护住密钥文件、敏感目录)
- `additionalDirectories`:授予项目根目录以外的访问权(monorepo 常用)

### `apiKeyHelper` —— 动态取 key

如果网关 key 会轮换,可以用脚本输出凭据:

```json
{
  "apiKeyHelper": "~/bin/get-clomio-key.sh"
}
```

Claude Code 会调用脚本取 key,默认缓存一段时间并在 401 后重试获取。helper 输出的值会同时适配常见 key/token 场景,适合企业内部分发。

---

## 一份 Clomio 推荐配置

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.clomio.ai",
    "ANTHROPIC_AUTH_TOKEN": "你的密钥",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ENABLE_TOOL_SEARCH": "auto",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6"
  },
  "model": "claude-sonnet-4-6",
  "language": "chinese",
  "theme": "dark-daltonized",
  "verbose": true,
  "autoUpdatesChannel": "stable",
  "cleanupPeriodDays": 30
}
```

> 把密钥写进会进 git 的文件有泄露风险,个人密钥建议放 `settings.local.json` 或 shell secret 管理器。完整且最新字段以 [官方 settings 文档](https://docs.anthropic.com/en/docs/claude-code/settings) 和 [LLM gateway 文档](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) 为准。

---

## 体验类字段

下面这些控制交互体验,按喜好配:

```json
{
  "language": "chinese",
  "theme": "dark-daltonized",
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": true,
  "effortLevel": "high",
  "verbose": true,
  "showTurnDuration": true,
  "spinnerTipsEnabled": false,
  "feedbackSurveyRate": 0,
  "autoUpdatesChannel": "stable",
  "skipDangerousModePermissionPrompt": true,
  "teammateMode": "auto",
  "cleanupPeriodDays": 30,
  "attribution": { "commit": "", "pr": "" }
}
```

字段会随 Claude Code 版本增减。如果编辑器支持 schema,在文件顶部加:

```json
"$schema": "https://json.schemastore.org/claude-code-settings.json"
```

即可获得自动补全与校验。

---

## `count_tokens` 与分组兼容

Claude Code 会把主请求发到 `/v1/messages`,并可能额外调用 `/v1/messages/count_tokens` 估算上下文。Clomio/sub2api 的当前行为是:

- Claude/Anthropic 分组:转发或按上游能力处理 `count_tokens`。
- OpenAI 分组:只有当前分组开放 Messages 兼容能力时才能兼容 `/v1/messages`;`count_tokens` 返回 404,客户端本地估算。
- Grok 分组:是否支持 Messages 由分组能力决定；`count_tokens` 固定返回 404，主请求仍可正常使用。

因此只要 `/v1/messages` 能正常对话,单独的 `count_tokens` 404 通常可以忽略；如果主对话也失败，再检查 Key 分组是否支持 Messages。

## 配置排障顺序

1. `echo $ANTHROPIC_BASE_URL` 确认是 `https://api.clomio.ai`,没有 `/v1`。
2. `env | grep ANTHROPIC_` 确认只保留一种凭据变量。
3. 用 `curl "$ANTHROPIC_BASE_URL/v1/messages" ...` 验证网关与 key。
4. 启动 `claude`,运行 `/status`,看 `Anthropic base URL` 与 `Auth token/API key` 来源。
5. 若 MCP 工具异常,先设 `ENABLE_TOOL_SEARCH=false` 或 `auto`;确认网关支持 `tool_reference` 后再设 `true`。

### 官方经验转成的配置检查表

- `ANTHROPIC_BASE_URL` 只负责把请求送到网关;没有 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 或 `apiKeyHelper` 时,本机保存的 claude.ai 登录仍可能是活跃凭据。
- 托管设置高于命令行、本地、项目和用户设置;如果企业/MDM 下发了 `managed-settings.json`,用户侧改文件不会生效。
- `HTTPS_PROXY`、`HTTP_PROXY`、`SSL_CERT_FILE`、`NODE_EXTRA_CA_CERTS` 这类企业代理/证书变量会影响 Claude Code 访问网关、MCP 和更新检查;排障时与 `ANTHROPIC_*` 一起核对。
- GitHub Action、VS Code 扩展、advisor/security hooks 这类辅助路径不一定和 CLI 主会话使用同一套环境。若 `claude` 主会话正常但 CI/扩展/辅助审查直连官方或报 403,先检查版本、action `settings.env`、runner env 是否把 `ANTHROPIC_BASE_URL` 和凭据都传进去。
- `ANTHROPIC_AUTH_TOKEN` 与 `ANTHROPIC_API_KEY` 不要长期同时保留。Clomio 推荐 bearer token 形态就放 `ANTHROPIC_AUTH_TOKEN`;要求 `x-api-key` 的 Anthropic-compatible 网关才用 `ANTHROPIC_API_KEY`。
- 模型名、子代理模型和 `/model` 候选以 Clomio 控制台分组实际开放为准;网关 base URL 不会自动把 GPT/Grok 模型变成 Claude 模型。

## 参考资料

- [Anthropic Claude Code Settings](https://docs.anthropic.com/en/docs/claude-code/settings)
- [Anthropic Other LLM gateways](https://docs.anthropic.com/en/docs/claude-code/llm-gateway)
- [Anthropic Corporate proxy](https://docs.anthropic.com/en/docs/claude-code/corporate-proxy)
- [claude-code-action hardcoded base URL issue](https://github.com/anthropics/claude-code-action/issues/1418)
- [Claude Code VS Code custom gateway issue](https://github.com/anthropics/claude-code/issues/9010)

更多用法见 [Claude Code 进阶](#/claude-advanced)。