Codex: Codex 命令行工具
最后更新：2026-08-31
Codex CLI 是开发者最常用的方式，本节深入 CLI 的高级用法和配置。
📋 前置知识：已完成 CLI 安装（见第 2 课），了解基本命令
1. 你将学到
- CLI 高级参数
- CLI 配置文件
- 输出格式控制
- 与其他工具集成
2. CLI 高级参数
(1) 完整参数列表
| 参数 | 说明 | 示例 |
|---|---|---|
--model |
指定模型 | --model o3 |
--sandbox |
沙箱模式 | --sandbox readonly |
--approval-policy |
审批策略 | --approval-policy approve |
--auto-edit |
Auto Edit 模式 | — |
--full-auto |
Full Auto 模式 | — |
--quiet |
静默模式，减少输出 | — |
--json |
JSON 格式输出 | — |
--context |
指定上下文文件 | --context AGENTS.md |
--system-prompt |
自定义系统提示 | --system-prompt "你是..." |
--max-tokens |
最大输出 token 数 | --max-tokens 4096 |
--temperature |
温度参数 | --temperature 0.2 |
(2) 常用组合
BASH
# 只读代码审查
codex --sandbox readonly "审查代码安全性"
# 自动修复 lint 错误
codex --full-auto --approval-policy approve "修复所有 lint 错误"
# 指定模型 + 静默模式
codex --model o3 --quiet "重构认证模块"
# 自定义系统提示
codex --system-prompt "你是 Rust 专家，代码风格遵循 Rust API Guidelines" "优化算法性能"
3. CLI 配置文件
(1) 全局配置
TOML
# ~/.codex/config.toml
model = "gpt-5-codex"
approval_policy = "ask"
sandbox_mode = "workspace-write"
[output]
format = "text" # text / json / markdown
color = true
progress = true
[context]
auto_compact = true
max_files = 50
exclude = ["node_modules/", ".git/", "dist/"]
(2) 项目配置
TOML
# .codex/config.toml
model = "deepseek-coder"
approval_policy = "approve"
[context]
include = ["src/**/*.ts", "tests/**/*.ts"]
▶ 示例 1: Alice 的 CLI 配置
TOML
# Alice 的全局配置
model = "gpt-5-codex"
approval_policy = "ask"
[output]
format = "text"
color = true
[context]
auto_compact = true
exclude = ["node_modules/", ".next/", "dist/", "coverage/"]
[sandbox]
mode = "workspace-write"
blocked_paths = [".env", ".env.local", "secrets/"]
4. 非交互模式
Codex CLI 支持非交互模式，适合脚本集成：
(1) 单次执行
BASH
# 直接传入任务，执行完退出
codex --quiet "为 app.py 添加类型注解"
# 输出到文件
codex --quiet "生成 API 文档" > api-docs.md
(2) 管道输入
BASH
# 从 stdin 读取输入
echo "解释这段代码" | codex --quiet
# 从文件读取
cat error.log | codex --quiet "分析错误日志，找出根因"
# 结合 git
git diff | codex --quiet "审查这段变更"
(3) JSON 输出
BASH
# JSON 格式输出，适合程序解析
codex --json "列出所有 TODO 注释" > todos.json
JSON 输出示例：
JSON
{
"task": "列出所有 TODO 注释",
"status": "completed",
"files_modified": [],
"files_read": ["src/main.ts", "src/utils.ts"],
"result": "Found 5 TODO comments:\n- src/main.ts:12\n- src/utils.ts:45\n..."
}
5. 与其他工具集成
(1) Git Hooks
BASH
# pre-commit hook：自动修复 lint
# .git/hooks/pre-commit
#!/bin/bash
codex --full-auto --quiet "修复所有 lint 错误"
git add -A
(2) CI/CD 集成
YAML
# GitHub Actions
- name: Code Review
run: |
codex --sandbox readonly --quiet "审查 PR 变更，关注安全性和性能"
(3) Makefile 集成
MAKEFILE
# Makefile
lint-fix:
codex --full-auto "修复所有 lint 错误"
test-gen:
codex --full-auto "为 src/ 下的所有文件生成单元测试"
review:
codex --sandbox readonly "审查当前变更"
▶ 示例 2: Bob 的自动化工作流
BASH
# Bob 的 daily-dev.sh 脚本
#!/bin/bash
# 拉取最新代码
git pull origin main
# 自动修复 lint
codex --full-auto --quiet "修复所有 lint 错误"
# 生成缺失的测试
codex --full-auto --quiet "为没有测试的源文件生成单元测试"
# 运行测试
npm test
# 如果全部通过，提交
if [ $? -eq 0 ]; then
git add -A
git commit -m "chore: auto lint-fix and test generation"
fi
6. 调试与日志
BASH
# 详细输出模式
codex --verbose "修复 bug"
# 保存日志
codex --log-file codex.log "修复 bug"
# 查看审计记录
cat ~/.codex/audit.log
❓ 常见问题
Q CLI 和 App 能同时运行吗？
A 可以，但不建议在同一项目上同时操作。不同项目可以并行使用。
Q 非交互模式支持所有功能吗？
A 基本支持，但 Computer Use 等需要交互确认的功能在非交互模式下受限。
Q 如何限制 CLI 的执行时间？
A 使用系统 timeout 命令：
timeout 300 codex --quiet "修复 bug"。Q JSON 输出的完整格式是什么？
A 包含 task、status、files_modified、files_read、result 等字段。运行
codex --json --help 查看完整 schema。Q 管道模式下 Codex 能修改文件吗？
A 可以，但需要
--approval-policy approve 或 --full-auto 模式。默认 ask 模式在管道中会卡住等待确认。📖 小节
- CLI 高级参数：
--model/--sandbox/--quiet/--json - 非交互模式：单次执行、管道输入、JSON 输出
- 集成场景：Git Hooks、CI/CD、Makefile
- 配置优先级：命令行 > 环境变量 > 项目 > 全局
📝 作业
- 基础题（难度⭐）：用 CLI 非交互模式执行一次代码审查，输出到文件。
- 进阶题（难度⭐⭐）：创建 Makefile 集成 Codex 常用任务。
- 挑战题（难度⭐⭐⭐）：编写一个 Git Hook，在 commit 前自动让 Codex 审查变更质量。
