# CLI 实战场景

Claude Code、Codex、Grok CLI、worktree 与线路切换的实操模板。适合“我该怎么问、怎么让工具动手、怎么排查 CLI 配置”的场景。

相关配置见 [Claude Code](#/claude-code)、[Codex](#/codex)、[Grok](#/grok)、[Base URL 与 /v1 规则](#/base-url-matrix)。

---

## 快速读懂一个陌生项目

进到项目目录、启动工具后,从宽到窄地问:

```text
给我一个代码库概览:用了什么技术栈、目录怎么组织。
```

```text
这个项目的认证(登录)是怎么处理的?涉及哪些文件?
```

```text
从前端到数据库,把一次登录的完整流程讲一遍。
```

小技巧:先问大方向,再聚焦到具体模块;让它顺带列一份"项目术语表"。

---

## 定位某个功能的代码

```text
帮我找处理用户认证的相关文件。
```

```text
这些文件之间是怎么协作的?
```

用项目里实际的业务词汇提问,命中更准。

---

## 修 Bug

把报错**原样**发给它,越完整越好:

```text
我运行 npm test 时报了下面的错(贴完整报错 + 复现步骤):
...
```

```text
给我几种修 user.ts 第 45 行这个空指针的方案,说明各自利弊。
```

```text
按你建议的方案改 user.ts,加上空值检查。
```

说明错误是偶发还是必现、贴上复现命令和堆栈,诊断会更准。

---

## 重构旧代码

```text
找出代码库里用了过时写法 / 废弃 API 的地方。
```

```text
建议怎么用现代写法重构 utils.js,保持原有行为不变。
```

```text
按上面的方案重构,然后跑测试确认行为没变。
```

要点:**小步、可测试地改**,每改一块就跑测试,不要一口气重写一大片。

---

## 补测试

```text
找出 notification 模块里没被测试覆盖的函数。
```

```text
给通知服务写测试,重点覆盖边界情况和报错分支。
```

```text
跑新写的测试,修掉失败的。
```

---

## 生成 Pull Request

```text
总结我对认证模块做的改动。
```

```text
帮我创建一个 PR。
```

```text
在 PR 描述里补充这次安全性改进的说明,以及怎么测试。
```

提交前自己过一遍它生成的内容,让它顺便指出潜在风险。

---

## 写文档

```text
找出 auth 模块里缺少注释的函数。
```

```text
给这些函数补上注释,风格按项目现有的来,带上用法示例。
```

---

## 用 Git 工作树并行多任务

需要同时推进多个任务、又想各自隔离时,用 Git worktree:

```bash
# 为一个新分支建独立工作目录
git worktree add ../project-feature-a -b feature-a

# 进去单独跑一个工具实例
cd ../project-feature-a
claude   # 或 codex
```

每个工作树文件隔离、共享同一份 Git 历史,互不干扰。

---

## 当成 Unix 工具用

非交互模式可以把 AI 接进脚本和管道:

```bash
cat build-error.txt | claude -p '简明解释这个构建错误的根本原因' > 分析.txt
```

```bash
codex exec "检查与 main 分支的差异,只报告拼写错误,每条两行"
```

---

## 先 curl,再 CLI

CLI 报错时不要先改一堆配置。先用同一把 Key、同一模型、同一 Base URL 发最小请求,确认网关和分组可用。

OpenAI/Codex/Grok Responses:

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer $CLOMIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"控制台里的模型名","input":"ping","max_output_tokens":8,"store":false}'
```

Claude/Anthropic Messages:

```bash
curl https://api.clomio.ai/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"}]}'
```

如果 curl 不通,先修 Key/分组/模型/Base URL;如果 curl 通而 CLI 不通,再查 CLI 实际读取的配置文件、环境变量和协议模式。

---

## Claude Code:读代码、改代码、看状态

适合 Claude 分组 Key + `ANTHROPIC_BASE_URL=https://api.clomio.ai`。进项目目录后:

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

常用开场:

```text
先不要改文件。请阅读这个仓库,告诉我入口、主要模块、测试命令和最容易踩坑的地方。
```

```text
我希望修复这个报错。请先复现并定位根因,再给最小修改方案:
[贴完整报错和复现命令]
```

如果 Claude Code 报认证或模型错误,先在 Claude 里跑 `/status`,确认 Base URL 是 `https://api.clomio.ai`,再检查密钥是否属于 Claude 分组。

---

## Codex Responses:让 Codex 执行任务

适合 OpenAI/Codex 分组 Key + `base_url = "https://api.clomio.ai/v1"` + `wire_api = "responses"`:

```toml
model_provider = "clomio"
model = "控制台里的 Codex/OpenAI 模型名"

[model_providers.clomio]
name = "Clomio"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
```

任务写法:

```text
你不是独自工作。请只修改我指定的文件,不要回退或覆盖他人改动。先审计现状,再给我改动和校验命令。
```

Codex 常用 `POST /v1/responses`;WebSocket 入口是 `GET /v1/responses`。不要自行拼响应详情查询路径。多轮 HTTP 调用要用下一次 `POST /v1/responses` 的 `previous_response_id`/工具结果关联。

非交互任务推荐显式选 profile 或一次性覆盖 provider,避免读错项目级配置:

```bash
export CLOMIO_API_KEY="你的 OpenAI/Codex 分组密钥"
codex exec --profile clomio "先不要改文件,总结这个仓库的测试命令"
# 或临时覆盖模型/供应商
codex -c model_provider=clomio exec "检查当前 diff 的潜在问题"
```

---

## Grok CLI:干净环境排查

Grok 只用 Grok 分组 Key,不要混入旧 `OPENAI_*`:

```bash
env -i PATH="$PATH" \
  GROK_MODELS_BASE_URL="https://api.clomio.ai/v1" \
  XAI_API_KEY="你的 Grok 分组密钥" \
  grok --model "控制台里的 Grok 对话模型" --prompt "ping"
```

如果 GUI 或包装器固定测 `/v1/chat/completions`,Grok 分组失败是预期;用 `/v1/responses` curl 判断对话主链路。

---

## 通用排障路径

按这个顺序排:

1. **安装失败**:确认下载域名是 `https://help.clomio.ai`,终端里关闭代理后重试。
2. **401/403**:密钥是否复制完整、是否选错分组、余额/订阅/API Key quota 是否耗尽。
3. **404**:路径和分组是否匹配;OpenAI-compatible 要带 `/v1`,Anthropic-compatible 不要手动多拼。
4. **model not found / unsupported**:先 `GET /v1/models`,使用列表里的模型名;不要自行拼模型详情查询路径。
5. **429**:触发并发、RPM 或 5h/1d/7d 金额限速;降低并发、等 reset_at 后再试。
6. **能 test 但业务失败**:用同一个 Key、同一个 Base URL、同一个模型发最小 curl,排除客户端配置差异。

---

## 换线路不换协议

线路只改变网络入口,不改变协议。国内网络不稳时,把域名从 `api.clomio.ai` 换成 `sub.qazwc.com` 或 `crs.qazwc.com`,其余规则不变:

| 场景 | 默认线路 | 换到三网优化 |
|------|------|------|
| Claude Code | `https://api.clomio.ai` | `https://crs.qazwc.com` |
| Codex / OpenAI SDK / Grok | `https://api.clomio.ai/v1` | `https://crs.qazwc.com/v1` |
| Hermes/OpenClaw Anthropic-compatible | `https://api.clomio.ai` | `https://crs.qazwc.com` |
| Hermes/OpenClaw OpenAI-compatible | `https://api.clomio.ai/v1` | `https://crs.qazwc.com/v1` |

也就是说:换线路只替换域名,不要把 Claude 改成带 `/v1`,也不要把 OpenAI/Codex/Grok 改成不带 `/v1`。

---