# Codex 进阶

掌握这几项,Codex 能更好地贴合你的项目与工作流。

---

## AGENTS.md:项目指令

`AGENTS.md` 是 Codex 版的项目说明书,任务开始前会被读取。Codex 会**从仓库根目录向下逐层合并** AGENTS.md,越靠近当前目录的优先级越高。

- **快速生成**:首次在项目里运行 `/init`,Codex 会起草一份。
- **放什么**:项目的构建/测试命令、代码规范、目录约定、"别碰哪些文件"等。
- **大小上限**:合并后的指令有字节上限(默认 32 KiB,由 `project_doc_max_bytes` 控制),内容多时可在 config 里调大,改完重启 Codex 生效。

---

## config.toml:配置与 Profile

除了 [Codex 接入](#/codex) 里的基础配置,`config.toml` 还支持分层与多套切换。

- **Profile(多套配置)**:用 `--profile 名字` 启动时,Codex 先读 `~/.codex/config.toml`,再叠加对应 profile 的配置。适合在多个供应商/线路间切换——比如给 Clomio 的不同[网关线路](#/gateway-lines)各建一个 profile。
- **项目级配置**:项目目录下的 `.codex/config.toml` 只在 trusted 项目中加载,并从项目根到当前目录逐层叠加。团队可共享 AGENTS/rules、沙箱、MCP、hooks 等不含凭据的规则;`model_provider`、`[model_providers.*]`、`base_url`、`env_key`、`experimental_bearer_token`、`requires_openai_auth` 这类 provider/auth 配置请放用户级或 profile 文件,不要提交到仓库。受管环境配置了 requirements 时,危险审批/沙箱组合可能被禁止。
- **推理强度**:`model_reasoning_effort` 可设 `low` / `medium` / `high`,越高越细致但越慢越费 token。

---

## Responses / WS 排障速查

Codex 默认走 OpenAI Responses,在网关上最常见的是两类入口:

| 入口 | 用途 | 注意 |
|------|------|------|
| `POST /v1/responses` | 普通 Responses 请求、SSE 流式、工具调用 | 多轮续接用请求体里的 `previous_response_id` |
| `GET /v1/responses` | Codex Responses WebSocket v2 入口 | 这是 WS/升级连接入口,不是 HTTP 查询历史响应 |

不要把排障文档写成“按 response id 发 GET 查询历史”:当前 OpenAI/Clomio Codex 路径不是这么查历史响应的。需要续接时,客户端会在下一次 `POST /v1/responses` 里带 `previous_response_id`,或由 Codex 自己维护会话。

工具调用相关的 400 优先看请求体形状:

- HTTP `function_call_output` 必须带回模型给出的 `call_id`，并且要有能匹配该 `call_id` 的 item 引用；缺少这些字段会直接返回 400。
- `invalid_encrypted_content`、`thinking_signature_invalid` 一般不是“模型不支持 Responses”,而是上游拒绝了旧会话里的加密内容/持久项引用;排查时看是否误用了别的账号、别的会话或过期的 `previous_response_id`。
- 如果流式请求中途失败,Responses SSE 终止事件应看 `event: response.failed` 或 `event: response.cancelled`,不要按 Chat Completions 的 `[DONE]` 习惯判断。
- `No available accounts supporting model` 不一定等于模型永久不可用;也可能是临时限速、额度或并发导致。状态码也有提示:`404 model_not_found` 更偏“当前分组没有该模型”,`503 No available accounts` 更偏“服务暂时不可用”。
- HTTP 手写工具结果不能只带 `previous_response_id + function_call_output`;还需要原始 `call_id` 和可匹配的 `item_reference`。如果有 `function_call_output`,网关不会为了重试而盲删 `previous_response_id`,避免破坏工具上下文。WS v2 会维护更多上下文,但 `store:false` 或跨轮工具输出仍要求能匹配原始工具调用。

实操建议:先拿到请求 ID,再按顺序查请求路径、请求体是否 `stream:true`、是否有 `previous_response_id` / `function_call_output.call_id` / `item_reference`、SSE 终止事件。若是 WS 问题，注意区分“新请求可以继续使用同一个 session”与“旧连接已经关闭”。

---

### Responses 路由对应关系

公开入口包括 `POST /v1/responses`、`POST /v1/responses/*subpath` 和用于 WebSocket Upgrade 的 `GET /v1/responses`。没有按 response id 发 GET 的历史查询路由。普通 HTTP GET 过鉴权后应是 426 WebSocket upgrade required。图像能力可在 OpenAI 分组和 Grok 分组走 `/v1/images/generations`、`/v1/images/edits`。视频能力仅在 Grok 分组开放。

## MCP:接入外部工具

MCP(Model Context Protocol)让 Codex 能调用外部工具/数据源(查文档、操作浏览器、读数据库等)。配置就放在 `config.toml` 里,**CLI 和 IDE 扩展共用同一份**。

两种添加方式:

```bash
# 方式一:命令行添加(以 context7 文档检索为例)
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 查看所有子命令
codex mcp --help
```

```toml
# 方式二:在 config.toml 里手写一个 server
[mcp_servers.my-db]
command = "/usr/local/bin/my-mcp-server"
env = { DB_URL = "postgres://..." }
timeout_secs = 30
```

会话里用 `/mcp` 查看已连接的工具。常见可接入的有文档检索、Playwright(浏览器)、GitHub 等。

---

## 非交互 / 脚本化:`codex exec`

`exec` 子命令让 Codex **不进交互界面、直接出结果**,适合写进脚本或 CI:

```bash
codex exec --full-auto "修掉所有 ESLint 报错,不要改业务逻辑"
```

---

## 切换线路与分组

- **卡顿 / 不稳定** → 换[网关线路](#/gateway-lines):改 `config.toml` 里 `base_url`。
- **换模型能力** → 改 `config.toml` 里 `model`,或用 profile 切换。
- **更便宜 / 不同模型** → 控制台给密钥换分组。

---

> 基础安装与接入见 [Codex 接入](#/codex);报错排查见 [故障排查](#/troubleshooting)。