# Codex 使用手册

装好并接上 Clomio 后([Codex 接入](#/codex)),这里是日常使用速查。

---

## 启动方式

| 方式 | 命令 | 说明 |
|------|------|------|
| 交互模式 | `codex` | 进入对话界面 |
| 带提示启动 | `codex "看看当前文件夹里有什么"` | 进界面并执行一句 |
| 非交互(脚本/CI) | `codex exec "修掉 ESLint 报错,别改逻辑"` | 不进界面,直接出结果 |

`codex exec` 加 `--full-auto` 可全自动执行,适合写进自动化流程。

---

## 审批与沙箱:控制它的"动手"自由度

Codex 执行命令前会按你设的策略决定是否先问你。两个核心概念:

- **审批策略**(`approval_policy`):`untrusted` / `on-request` / `on-failure` / `never`——何时停下来征求同意。
- **沙箱**(`sandbox_mode`):`read-only`(只读)/ `workspace-write`(可改工作区)/ `danger-full-access`(完全放开,慎用)。

日常推荐 `on-request` + `workspace-write`:既能动手又有确认。进界面后可用 `/approvals` 快速调整。详见 [Codex 配置详解](#/codex-config)。

---

## 常用斜杠命令

进入界面后输入 `/` 触发(不同版本略有差异):

| 命令 | 作用 |
|------|------|
| `/model` | 切换模型 / 推理强度(范围取决于你的[分组](#/api-key)) |
| `/approvals` | 调整审批与沙箱策略 |
| `/init` | 为项目生成 `AGENTS.md` |
| `/compact` | 压缩当前对话,省 token |
| `/new` | 开一个新会话 |
| `/status` | 查看当前配置与会话状态 |
| `/diff` | 查看本次改动的 diff |
| `/mcp` | 查看已连接的 MCP 工具 |

---

## 项目说明:AGENTS.md

Codex 会读项目里的 `AGENTS.md` 作为"项目说明书",从仓库根向下逐层合并。把构建/测试命令、代码规范、目录约定、"别碰哪些文件"写进去,它就更懂你的项目。

```bash
# 在项目根目录,首次运行
/init
```

更多用法见 [Codex 进阶](#/codex-advanced)。

---

## 给它文件和图片

- **引用文件**:不少版本支持在输入里用 `@` 提及文件名快速带入;也可以直接把文件内容复制粘贴进对话框。
- **图片**:把图片复制后在终端粘贴,或给出图片路径,让它分析截图/设计图。

---

## 生成图片

Codex 可以直接生图,触发 `$imagegen` 并描述画面即可。需要先配好 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`;若提示工具不可用,可安装生图 skill。完整步骤见 [Codex 生图](#/codex-image)。

---

## 推荐的 Codex 接入形态

如果你是按 Clomio / OpenAI-compatible 网关接 Codex,推荐把 Codex provider 配成 **Responses wire API**:

```toml
model_provider = "clomio"
model = "gpt-5.4"

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

要点:

- `base_url` 写到 API 版本根,也就是带 `/v1`,不要写到 `/v1/responses`。
- `wire_api = "responses"` 让 Codex 使用 OpenAI Responses 形状,适合工具调用、流式事件和 Codex 会话状态。
- `env_key` 建议用业务专属变量,如 `CLOMIO_API_KEY`;不要把多个工具都挤在 `OPENAI_API_KEY` 里,排障时更清楚。
- 控制台复制模板可能使用 `experimental_bearer_token` + `requires_openai_auth = true` 的自包含方式;长期配置建议改回 `env_key`。两种方式不要同时写。
- 不要同时写 `requires_openai_auth = true` 和 `env_key`；前者会走 Codex/OpenAI 认证链路并忽略 `env_key`。Clomio 推荐 `env_key`。
- provider/base URL/auth 相关配置放用户级 `~/.codex/config.toml` 或 profile 文件；项目 `.codex/config.toml` 里的 `model_provider`、`[model_providers.*]`、`base_url`、`env_key` 可能被 Codex 忽略。
- 分组要选 OpenAI/Codex/GPT 类分组;Claude-only 分组不支持 `/v1/responses`。

完整配置项仍以 [Codex 配置详解](#/codex-config) 为准。

---

## 多套配置:Profile

给不同[网关线路](#/gateway-lines)或场景各建一个 profile,启动时切换:

```bash
codex --profile crs
```

配置写法见 [Codex 配置详解 · Profile](#/codex-config)。

---

## MCP:接外部工具

```bash
codex mcp add context7 -- npx -y @upstash/context7-mcp   # 添加
codex mcp --help                                          # 查看所有子命令
```

会话里用 `/mcp` 查看已连接工具。CLI 与 IDE 扩展共用同一份 MCP 配置。

---

## Responses 流式/WS 排障

看到 Codex 卡在流式输出或工具结果回传时,先分清入口:

- HTTP/SSE: `POST /v1/responses`,看是否有 `stream: true`、`previous_response_id`、`function_call_output.call_id`。
- WebSocket: `GET /v1/responses` 只作为 Upgrade 入口,首帧必须是 `response.create` 类 payload;它不是查询历史响应的 REST 接口。启用 Codex WS v2 时同时需要 provider 里的 `supports_websockets = true` 和 `[features].responses_websockets_v2 = true`;不稳定时改成 `supports_websockets = false` 回落 HTTP/SSE。
- 续接:下一轮仍通过 `POST /v1/responses` 或 WS 首帧携带上下文/`previous_response_id`,不要请求“按 response id 查询”的 GET 路径。
- `previous_response_id` 必须是 Responses 返回的 `resp_*`。不要把 Claude Messages 的 `msg_*`、Chat Completions 的 `chatcmpl-*`、工具调用 id 或你自己生成的会话 id 填进去。
- HTTP 工具结果必须带原始函数调用的 `call_id`；如果你只保存了工具输出文本,没保存 `call_id` / item reference,就让 Codex/SDK 重新跑一轮或压缩上下文,不要手工伪造。

常见判断:

| 现象 | 先查 |
|------|------|
| 400 提到 `function_call_output` | 工具输出是否带回原始 `call_id` |
| 400 提到 `previous_response_id must be a response.id` | 是否把 `msg_*`、`chatcmpl-*` 或自定义 id 当成 `resp_*` 用 |
| 400 提到 encrypted/signature | 是否跨账号/跨会话复用了旧 `previous_response_id` |
| 流式没有最终事件 | SSE 是否出现 `response.failed` / `response.cancelled`,WS 是否被 close |
| `No available accounts supporting model` | 除模型名外,还要查本地账号槽位、冷却、临时不可调度 |

## 卡顿 / 报错怎么办

- 网络卡顿:换条[网关线路](#/gateway-lines)(改 `base_url`),通常立刻见效。
- 鉴权 401 / 模型不存在:核对 `base_url`、密钥、分组与模型名,见 [故障排查](#/troubleshooting)。

---

> 具体任务怎么做,见 [实战场景库](#/recipes)。