# Claude Code 使用手册

装好并接上 Clomio 后([Claude Code 接入](#/claude-code)),这里是日常使用的速查。Claude Code 的主请求是 Anthropic `/v1/messages`;`/v1/messages/count_tokens` 只用于 token 估算,不是主对话路径。

---

## 启动方式

| 方式 | 命令 | 说明 |
|------|------|------|
| 交互模式 | `claude` | 进入对话界面,最常用 |
| 带提示启动 | `claude "解释这个项目"` | 进界面并立即执行一句 |
| 非交互(出结果就退) | `claude -p "解释这个函数"` | 适合脚本/一次性任务 |
| 管道输入 | `cat logs.txt \| claude -p "解释报错"` | 把文件内容喂给它分析 |
| 指定模型 | `claude --model claude-sonnet-4-6` | 本次会话使用指定模型 |

首次启动后建议立刻运行 `/status`,确认:

- `Anthropic base URL` 是 `https://api.clomio.ai` 或你选择的 Clomio 线路;
- 凭据来源是 `ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_API_KEY`,而不是误用本机保存的 claude.ai 登录;
- 当前项目目录与权限模式符合预期。

---

## 常用命令

```bash
claude update      # 更新到最新版(任何安装方式都适用)
claude -c          # 继续最近一次对话
claude --resume    # 弹出历史会话选择器,挑一个恢复
claude commit      # 让它帮你生成并创建一次 Git 提交
claude doctor      # 检查安装健康状况
claude mcp         # 管理 MCP 服务器(接外部工具)
claude logs <id>   # 查看 background/daemon 会话日志
```

---

## 常用 CLI 标志

| 标志 | 作用 | 示例 |
|------|------|------|
| `--model` | 指定模型 | `claude --model claude-sonnet-4-6` |
| `--permission-mode` | 权限模式(如 `plan` 只读规划) | `claude --permission-mode plan` |
| `--allowedTools` | 本次允许的工具 | `claude --allowedTools "Bash(git*)" "Read"` |
| `--add-dir` | 临时授权额外目录 | `claude --add-dir ../shared` |
| `--verbose` | 详细日志 | `claude --verbose` |
| `--mcp-config` | 临时加载 MCP 配置 | `claude --mcp-config ./mcp.json` |
| `--dangerously-skip-permissions` | 跳过所有权限确认 | 谨慎用于隔离环境 |

---

## 键盘快捷键

| 按键 | 作用 |
|------|------|
| `Ctrl + C` | 取消当前输入 / 生成 |
| `Ctrl + D` | 退出会话 |
| `Ctrl + L` | 清屏 |
| `↑ / ↓` | 浏览命令历史 |
| `Esc` `Esc` | 编辑上一条消息 |
| `Ctrl + O` | 任务像卡住时,查看 background 输出(再按一次切回) |
| `\` + `Enter` | 多行输入(所有终端通用) |
| `Option + Enter` | 多行输入(macOS 默认) |

---

## 斜杠命令

进入界面后输入 `/` 触发:

| 命令 | 作用 |
|------|------|
| `/help` | 帮助 |
| `/status` | 查看当前 base URL、凭据来源、模型、项目状态 |
| `/model` | 切换模型(可选范围取决于你的[分组](#/api-key)与网关模型发现) |
| `/compact` | 压缩当前对话,省 token |
| `/clear` | 清空对话(话题跑偏想重来) |
| `/config` | 打开设置界面(也可 `/config verbose=true` 改单项) |
| `/permissions` | 管理工具权限 |
| `/init` | 为项目自动生成 `CLAUDE.md` |
| `/vim` | 开启 Vim 风格编辑 |
| `/ide` | 检查 / 连接 IDE |
| `/doctor` | 安装健康检查 |
| `/agents` | 管理子代理 |
| `/mcp` | 查看已连接的 MCP 工具 |

---

## 上下文管理(省 token)

对话越长越费 token。两招控制:

- **`/compact [描述]`**:把当前长对话压缩成摘要,保留要点继续聊。
- **`claude -c` / `claude --resume`**:换个时间继续之前的会话,不必把所有背景重讲一遍。

Claude Code 会尝试调用 `/v1/messages/count_tokens` 做上下文估算。sub2api 对 Anthropic/Kiro 等可支持路径会转发;对 OpenAI/Grok 分组或不支持 count_tokens 的上游会返回 404 让客户端本地估算。主对话仍然看 `/v1/messages` 是否正常。

---

## 发图片给它

让 Claude 看截图/设计图,三种方式任选:

- 把图片**拖**进 Claude Code 窗口
- 复制图片后在终端 **`Ctrl + V`** 粘贴(macOS)
- 直接给路径:`分析这个图:/path/to/image.png`

然后用自然语言提问,比如「这张报错截图是什么原因?」「用 HTML/CSS 还原这个设计」。

---

## 连接 IDE

Claude Code 支持 VS Code 与 JetBrains:

- **VS Code**:在内置终端里运行 `claude`,扩展会自动安装;用 `/ide` 检查连接。详细接入(指向 Clomio)见 [VS Code 集成](#/vscode)。如果扩展不是从该 shell 启动,请在 VS Code 自己的 `claudeCode.environmentVariables` 里配置 `ANTHROPIC_BASE_URL` 和 key。
- **JetBrains**:安装官方插件后,用 `/ide` 连接。
- 连上后,Claude 的改动会以 diff 直接显示在编辑器里。

---

## MCP:接外部工具

让 Claude 连上数据库、文档检索、浏览器等外部能力:

```bash
claude mcp add <名字> <命令> [参数...]   # 添加
claude mcp list                          # 列出
claude mcp get <名字>                    # 查看详情
claude mcp remove <名字>                 # 删除
claude mcp login <名字>                  # HTTP/SSE/OAuth 型 MCP 登录
claude mcp logout <名字>                 # 清除 MCP 登录
```

会话里用 `/mcp` 查看已连接的工具。用 `-s project|user` 指定配置存放范围。

自定义 `ANTHROPIC_BASE_URL` 时,官方 Claude Code 默认会把 MCP tool search 从“按需发现工具”退回到更兼容的模式,因为很多代理不转发 `tool_reference`。表现为模型先等待 MCP 连接,或一次性加载工具列表。排障建议:

```bash
# 网关不支持 tool_reference 时最稳
export ENABLE_TOOL_SEARCH=false

# 工具较少时自动决定是否按需搜索
export ENABLE_TOOL_SEARCH=auto

# 只有确认网关透传 tool_reference beta 块时再强开
export ENABLE_TOOL_SEARCH=true
```

也可以写进 `settings.json` 的 `env`。

---

## Base URL 与 count_tokens 快速判断

- `/status` 里 `Anthropic base URL` 必须是不带 `/v1` 的根地址,例如 `https://api.clomio.ai`。
- 如果日志或错误里出现 `/v1/v1/messages`,就是 base URL 多写了 `/v1`。
- `count_tokens` 404 只代表 token 估算端点不可用;OpenAI 分组和不支持该端点的上游都会这样回退,不等于主对话失败。
- Grok 分组只有在启用 Messages 兼容能力时才适合跑 Claude Code；否则请使用 Grok 的 Responses 或 Chat 端点。

## Clomio / sub2api 分组相关提示

| 现象 | 原因 | 处理 |
|------|------|------|
| 403: key 未分组 | API Key 的 `group_id` 为空,且系统不允许未分组调度 | 在控制台把 key 绑定到分组 |
| 403: group 不允许 `/v1/messages` | OpenAI 平台分组未开放 Messages 兼容能力 | 换 Anthropic 分组,或使用已开放 Messages 兼容能力的 OpenAI 分组 |
| 404: `Token counting is not supported` | OpenAI/Grok 分组或上游不支持 count_tokens | 只要主对话正常可忽略;否则换 Anthropic 分组 |
| 非 Claude Code 客户端被拒 | 分组开启 `claude_code_only` | 用官方 Claude Code 客户端,或换非 only 分组 |
| 模型列表不完整 | 网关模型发现默认关闭 | 设 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 后重启 |

---

> 想把常用提示词固化成命令、用子代理做大范围探索?见 [Claude Code 进阶](#/claude-advanced)。具体任务怎么做,见 [实战场景库](#/recipes)。