Codex 进阶配置

Codex CLI 配置远不止 base_url + key。本章覆盖 config.toml 全部可调项 + AGENTS.md 项目规范 + 自定义工具。

完整 ~/.codex/config.toml 模板

# 主配置
model_provider = "Shuro"
model = "gpt-5.5"
model_reasoning_effort = "medium"      # high / medium / low
disable_response_storage = true        # 不在服务端保存对话

# 默认权限策略
approval_policy = "on-request"         # on-request / never / always
sandbox_policy = "workspace-write"     # 沙盒级别

# 性格 / 工作风格
personality = "pragmatic"              # pragmatic / academic / concise

# Provider 定义
[model_providers.Shuro]
name = "Shuro"
base_url = "https://shuro.vip/v1"
wire_api = "responses"                 # responses / chat
requires_openai_auth = true            # 从 auth.json 读 key
request_max_retries = 3
stream_idle_timeout_ms = 30000

# 多 Provider 备用
[model_providers.Shuro_chat]
name = "Shuro (Chat API)"
base_url = "https://shuro.vip/v1"
wire_api = "chat"
requires_openai_auth = true

[model_providers.local_ollama]
name = "Local Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"
env_key = "OLLAMA_FAKE_KEY"           # ollama 不要 key 但要占位

# 信任目录（避免每次问）
[projects."/Users/mini/Documents/Github"]
trust_level = "trusted"

[projects."/Users/mini/work"]
trust_level = "trusted"

# Sandbox 策略
[sandbox_workspace_write]
network_access = false                # 沙盒内禁止网络（默认）
exclude_tmpdir_env_var = false
exclude_slash_tmp = false
writable_roots = ["/tmp", "~/.codex/memories"]

# Profile 切换（按场景）
[profiles.coding]
model = "gpt-5.5"
model_reasoning_effort = "medium"

[profiles.thinking]
model = "gpt-5.5"                      # 主力模型 + 高推理力度跑难题
model_reasoning_effort = "high"

[profiles.fast]
model = "gpt-5.4-mini"                 # 轻量模型跑简单任务
model_reasoning_effort = "low"

# TODO/VERIFY: Claude 经 /v1/chat/completions（wire_api="chat"）在 Shuro 未复测
[profiles.claude]
model_provider = "Shuro"
model = "claude-opus-4-7"
wire_api = "chat"

Profile 切换

# 用 thinking profile 跑一个难题
codex --profile thinking "为什么这个测试随机失败？"

# 用 fast profile 跑简单任务
codex --profile fast -p "改个变量名"

# 切到 Claude
codex --profile claude

profile 是 config.toml 的"快照"，运行时按 profile 名切。

AGENTS.md（项目规范文件）

跟 Claude Code 的 CLAUDE.md 对应，Codex 用 AGENTS.md：

项目根/
├── AGENTS.md           ← Codex 启动自动读
└── ...

模板：

# <项目名>

## Codex 行为约定

### 工作方式
- 修改文件前先 `Read`
- 写代码前 `Grep` 找类似模式
- 跑测试用 `pnpm test`，**不要**用 `npm test`

### 编码规范
- 缩进 2 空格
- 单引号
- 不要 default export

### 严禁
- 不要碰 `src/legacy/`
- 不要改 `prisma/migrations/`（手工管理）
- 提交前必须跑 lint

sandbox 模式详解

Codex 在受控沙盒里跑 shell 命令，三种级别：

级别	含义	适合
read-only	只读文件，无写入无网络	探索代码
workspace-write	可写工作目录，无网络	日常编码（默认）
danger-full-access	完全访问	⚠️ 仅信任的本地脚本

切换：

codex --sandbox read-only          # 临时切只读
codex --sandbox workspace-write    # 默认

或 config.toml 里默认：

sandbox_policy = "workspace-write"

自定义命令（类似 Claude Code 的 slash command）

~/.codex/prompts/ 下放 markdown 文件：

mkdir -p ~/.codex/prompts
cat > ~/.codex/prompts/review.md <<'EOF'
请审查当前 git diff，关注：
1. 安全漏洞
2. 性能问题
3. 测试覆盖

输出格式：必改 / 建议 / 亮点
EOF

调用：

/review

自定义 Subagent

~/.codex/agents/ 下：

mkdir -p ~/.codex/agents
cat > ~/.codex/agents/test-runner.md <<'EOF'
---
name: test-runner
model: gpt-5.4
description: 跑测试并修复失败的
---

跑 pnpm test，分析失败，修复，重跑。
EOF

MCP（同 Claude Code 用法）

# ~/.codex/config.toml
[mcp.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_..." }

详见 MCP。

性能调优

减少 reasoning token

model_reasoning_effort = "low"        # 简单任务用低思考

gpt-5 系列默认带思考，简单任务用 low 能省 50%+ token。

关闭响应存储

disable_response_storage = true

OpenAI 默认在服务端缓存响应（用于改进模型），关掉省心 + 数据不出端。

流式空闲超时

stream_idle_timeout_ms = 30000        # 默认 60000

如果上游不稳，调短让客户端更快感知掉线。

环境变量

export OPENAI_BASE_URL="https://shuro.vip/v1"      # config.toml 也行
export OPENAI_API_KEY="sk-..."                       # auth.json 也行
export CODEX_DEFAULT_PROFILE="coding"                # 默认 profile
export CODEX_LOG_LEVEL="info"                        # debug / info / warn

调试

# 开 debug 模式
codex --debug exec "..."

# 看完整请求日志
tail -f ~/.codex/logs/*.log

# 看配置加载是否对
codex config

常见踩坑

踩坑	原因	解决
profile 没生效	没传 --profile	加 --profile xxx
requires_openai_auth + env_key 冲突	两个互斥	二选一
sandbox 阻止 npm install	network_access = false	临时 --sandbox danger-full-access 或 --full-auto
AGENTS.md 没被读	不在项目根	移到根目录

跟 Claude Code 对比

	Claude Code	Codex CLI
配置文件	settings.json + CLAUDE.md	config.toml + AGENTS.md
鉴权	环境变量	env_key OR auth.json
Slash	/xxx	/xxx（同 Markdown 文件）
Subagent	~/.claude/agents/	~/.codex/agents/
MCP	~/.claude/mcp.json	config.toml [mcp.xxx]
沙盒	Default/AutoAccept/Plan 三模式	read-only / workspace-write / full-access
模型	Claude 系列	GPT-5.5 / GPT-5.4 / Claude（via Shuro）

Shuro 一把 key 两个工具都通，按场景选用。