# Claude Code 进阶

跑通基础使用后,这几项能力能让 Claude Code 真正融入你的工作流。本页同时补充 Clomio/sub2api 网关下的兼容要点。

---

## CLAUDE.md:让 Claude 记住项目规则

`CLAUDE.md` 是项目的说明书,Claude 每次开始会话都会读它。把项目的构建命令、代码规范、目录约定写进去,就不用每次重复交代。

- **生成**:在项目根目录运行 `/init`,Claude 会自动扫描并起草一份。
- **分层**:`~/.claude/CLAUDE.md`(全局)放你个人的通用偏好,对所有项目生效;每个项目目录下的 `CLAUDE.md` 放该项目专属规则。
- **别塞太满**:只写当前任务真正需要的内容。大段参考资料单独放文件,在 CLAUDE.md 里写明“需要时去看 xxx 文件”即可,避免拖慢、干扰判断。
- **别放密钥**:仓库内 `CLAUDE.md` 往往会提交到 git,不要写 Clomio key、cookie、token。

> 一句话: `CLAUDE.md` 写得好,后面少纠正很多次。

---

## 自定义命令 / 技能

把你常输入的一整段提示词,固化成一个斜杠命令,下次一个 `/名字` 就能调用。

- 机制很简单:在 `.claude/commands/` 下放一个 Markdown 文件,文件名就是命令名,正文就是被注入的提示词。支持 YAML frontmatter 设置描述、允许的工具、模型、以及 `$ARGUMENTS` / `$1` 参数。
- 有真实逻辑或带配套文件的,放 `.claude/skills/<名字>/SKILL.md` 更合适;只是“插入一段提示词”的,用命令即可。

实用建议:

- **用过痛了再做**:不要提前造一堆命令,等你真的反复手敲同一段时再固化。
- **一个命令一个明确产物**:`/pr` 就开 PR、`/release-notes` 就写发布说明。
- **把正文当契约**:写清先读什么、做什么、跳过什么、输出什么格式。
- **配好 `allowed-tools`**:否则需要跑 `gh` 十次的命令会弹十次授权。
- **别把密钥写进正文**:`.claude/commands/` 会进 git,密钥放环境变量或 `settings.local.json`。

---

## 子代理:保护主对话的上下文

子代理(subagent)是另开的一个 Claude 会话,有独立的上下文窗口,适合做大范围探索或并行任务而不污染主对话。

- 定义在 `.claude/agents/`(项目)或 `~/.claude/agents/`(个人),Markdown + YAML frontmatter。
- **让它们只读**:推荐给探索型子代理只保留只读工具,把改文件的活交回主会话。
- **按成本分层**:用较便宜模型做第一遍粗筛,只把可疑文件交给更强模型复核。
- **并行要避开同文件编辑**:多人或多 worker 改文档/代码时,先约定文件所有权,不要让子代理直接写同一批文件。

如果给子代理单独指定模型,可在配置中设置:

```json
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6"
  }
}
```

---

## MCP 与 tool search

MCP 能让 Claude Code 接数据库、浏览器、文档检索、工单系统等外部能力。基础命令:

```bash
claude mcp add <名字> <命令> [参数...]
claude mcp list
claude mcp get <名字>
claude mcp login <名字>
claude mcp remove <名字>
```

自定义 `ANTHROPIC_BASE_URL` 下要特别注意 tool search:

- 官方 Claude Code 默认启用按需 tool search,但当 `ANTHROPIC_BASE_URL` 指向非官方 host 时,默认会退回更兼容的加载方式。
- 原因是很多网关/代理不会完整透传 `tool_reference` blocks 和对应 beta header。
- 如果 Clomio 线路或你的自建代理已确认支持,可设 `ENABLE_TOOL_SEARCH=true`;否则优先用 `auto` 或 `false`。

推荐配置:

```json
{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto"
  }
}
```

排障:

- `/mcp` 看服务器是否连接、是否有工具数。
- `claude mcp get <名字>` 看命令、环境变量、认证状态。
- HTTP/SSE MCP 认证失败时用 `claude mcp login <名字>`。
- 工具很多导致首轮很慢时,先 `ENABLE_TOOL_SEARCH=auto:5` 或 `false`。
- 强开 `ENABLE_TOOL_SEARCH=true` 后若 400 报 `tool_reference`、`anthropic-beta`、未知字段,说明代理/上游没有完整兼容,改回 `auto` 或 `false`。

---

## 网关兼容与 sub2api 真实路由

Claude Code 接 Clomio 时,应把它当作 Anthropic Messages 客户端:

```text
ANTHROPIC_BASE_URL=https://api.clomio.ai
Claude Code -> POST /v1/messages
Claude Code -> POST /v1/messages/count_tokens  # 可选 token 估算
```

不要把 OpenAI `/v1/responses` 写成 Claude Code 主路径。sub2api 当前 `/v1` 路由会按 API Key 绑定分组的 `platform` 分流:

| key 绑定分组平台 | `/v1/messages` 行为 | `/v1/messages/count_tokens` 行为 |
|------------------|---------------------|----------------------------------|
| `anthropic` | 走 Anthropic/Claude 网关主路径 | 校验余额/订阅后转发;不计并发、不记使用量 |
| `openai` | 只有当前分组开放 Messages 兼容能力时才转 OpenAI 兼容调度 | 返回 404,客户端本地估算 |
| `grok` | Messages API 直接 404 | 返回 404 |
| `antigravity` / `kiro` 等 | 按服务端能力转发或委派 | 不支持时返回 404 让客户端 fallback |

其他真实行为:

- **未分组 Key**:生产使用不建议空分组；若当前站点不允许未分组 Key，网关会按 Anthropic 错误格式返回 403。
- **分组平台是入口分流依据**:同一根地址 `/v1` 下,不是靠客户端路径猜平台,而是看 Key 绑定的分组。
- **Claude Code only**:这类分组要求请求来自 Claude Code。非 Claude Code 客户端可能会被拒绝。
- **Anthropic API key passthrough**:Anthropic APIKey 账号可开启透传,此时上游鉴权使用 `x-api-key`;对 Claude Code 接入 Clomio 的用户侧 key,仍推荐 `ANTHROPIC_AUTH_TOKEN`。
- **辅助端点**:真实 Claude Code 还可能访问 `/api/claude_cli/bootstrap`、`/api/claude_code/user_settings`、`/api/event_logging/batch` 等非 Messages 辅助端点。sub2api 对这些端点有 stub/drop/可选 forward,避免客户端因辅助请求失败影响主对话。

---

## 企业网关、认证与代理细节

官方 Claude Code 网关文档把 `ANTHROPIC_BASE_URL` 定义为“指向网关”的变量;凭据可以来自 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`apiKeyHelper` 或已登录会话。接 Clomio 时推荐显式设置 `ANTHROPIC_BASE_URL=https://api.clomio.ai` 加一个网关 key,否则“只改 base URL、不改凭据”可能仍在用本机保存的 claude.ai 登录。

网络代理按标准环境变量走:

```bash
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY="localhost,127.0.0.1"
```

Claude Code 官方说明不支持 SOCKS 代理;如需 SOCKS,先在本机转成 HTTP/HTTPS 代理再给 `HTTPS_PROXY`。

## 几个高频操作

| 操作 | 命令 / 快捷键 |
|------|--------------|
| 查看当前网关/凭据 | `/status` |
| 切换模型 | `/model`(方向键选,回车确认) |
| 压缩当前对话 | `/compact` |
| 清空对话 | `/clear` |
| 新开对话 | macOS `Command + N` / Windows `Ctrl + N` |
| 误操作 | 先 `Esc`,不行再 `Ctrl + C` |
| 任务像卡住了 | `Ctrl + O` 看 background 输出,再按一次切回 |
| 检查安装 | `claude doctor` |

---

## 发文件 / 图片给 Claude

不用手敲完整路径:在文件管理器里复制文件,回到终端对话框粘贴即可。图片同理,粘贴后 Claude 能直接看。

---

## 网关问题快速定位

```bash
# 1. base URL 必须是根地址
printf '%s\n' "$ANTHROPIC_BASE_URL"

# 2. 看是否混用了两种凭据
env | grep '^ANTHROPIC_'

# 3. 直接打 Claude Code 主路径
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"}]}'

# 4. 可选:验证 token 估算端点;404 不一定影响主对话
curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages/count_tokens"   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"ping"}]}'
```

常见结论:

- curl 到 `/v1/messages` 401:凭据变量/密钥错。
- curl 到 `/v1/messages` 403 且提示未分组:key 没绑分组。
- `/status` 没有 `Anthropic base URL`:变量没有传到 Claude Code 进程。
- `/status` 显示 claude.ai 登录而不是 token/API key:清理冲突变量或 `/logout` 后重试。
- 400 提到未知 beta/字段:先设 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`,并关闭或降级 tool search。

> 想换更快的网关线路?见 [网关线路](#/gateway-lines)。配置层面的问题见 [Claude Code 接入](#/claude-code)。