📖 关于 Codex CLI
Codex CLI 是 OpenAI 推出的开源本地编程助手，可以在你的终端中运行。它使用先进的 AI 模型（如 GPT-5-Codex）来帮助你编写代码、修复错误、重构项目等。
安装方式：
npm install -g @openai/codex
# 或
brew install codex
# 或
brew install codex
🎯 基础命令
codex
核心命令
启动交互式 TUI（终端用户界面）模式，这是使用 Codex 的主要方式。
codex
📝 示例：
codex
启动交互式界面
codex "fix lint errors"
带初始提示启动
codex "Refactor the Dashboard component to React Hooks"
重构组件为 React Hooks
codex exec
自动化
非交互式"自动化模式"，适合在 CI/CD 管道中使用。执行完成后自动退出。
codex exec "任务描述"
📝 示例：
codex exec "explain utils.ts"
解释代码文件
codex exec --full-auto "update CHANGELOG for next release"
在 CI 中自动更新变更日志
codex exec "Write unit tests for utils/date.ts"
生成单元测试
codex resume
会话管理
恢复之前的会话，继续未完成的对话。支持选择器界面或直接指定会话 ID。
codex resume [选项] [SESSION_ID]
📝 示例：
codex resume
打开会话选择器
codex resume --last
恢复最近的会话
codex resume 7f9f9a2e-1b3c-4c7a-9b0e-123456789abc
通过 ID 恢复特定会话
codex login
认证
登录到 Codex，支持 ChatGPT 账号或 API Key 两种方式。
codex login [--api-key API_KEY]
📝 示例：
codex login
使用 ChatGPT 账号登录（推荐）
codex login --api-key "sk-..."
使用 API Key 登录
🔌 MCP (Model Context Protocol) 命令
codex mcp add
MCP
添加一个 MCP 服务器到配置中。MCP 服务器可以为 Codex 提供额外的工具和能力。
codex mcp add <名称> -- <命令> [参数...]
📝 示例：
codex mcp add docs -- docs-server --port 4000
添加文档服务器
codex mcp add playwright -- npx -y @playwright/mcp-server
添加 Playwright 浏览器自动化工具
codex mcp list
MCP
列出所有已配置的 MCP 服务器。
codex mcp list [--json]
📝 示例：
codex mcp list
以表格形式显示
codex mcp list --json
以 JSON 格式输出
codex mcp get
MCP
查看特定 MCP 服务器的详细信息。
codex mcp get <名称> [--json]
📝 示例：
codex mcp get docs
查看 docs 服务器信息
codex mcp remove
MCP
从配置中移除一个 MCP 服务器。
codex mcp remove <名称>
📝 示例：
codex mcp remove docs
移除 docs 服务器
codex mcp-server
MCP
将 Codex CLI 作为 MCP 服务器运行，可以被其他 AI 工具调用。
codex mcp-server
📝 示例：
npx @modelcontextprotocol/inspector codex mcp-server
使用 MCP Inspector 测试
🛠️ 工具命令
codex completion
工具
生成 Shell 自动补全脚本，支持 bash、zsh、fish。
codex completion <shell>
📝 示例：
codex completion bash
生成 Bash 补全脚本
codex completion zsh > ~/.zsh/completions/_codex
安装 Zsh 补全
codex completion fish
生成 Fish 补全脚本
codex debug seatbelt
调试
在 macOS 上测试沙箱行为（使用 Apple Seatbelt）。
codex debug seatbelt [--full-auto] [命令...]
📝 示例：
codex debug seatbelt ls /
测试读取根目录
codex debug landlock
调试
在 Linux 上测试沙箱行为（使用 Landlock）。
codex debug landlock [--full-auto] [命令...]
📝 示例：
codex debug landlock touch /tmp/test.txt
测试文件写入权限
⚙️ 重要标志参数
--model / -m
配置
指定使用的 AI 模型。
codex --model <模型名称>
📝 示例：
codex --model gpt-5-codex
使用 GPT-5-Codex 模型（推荐）
codex -m o3
使用 O3 模型
codex --model o4-mini
使用 O4-mini 模型
--sandbox
安全
设置沙箱模式，控制 Codex 的文件系统访问权限。
codex --sandbox <模式>
| 模式 | 说明 |
|---|---|
read-only |
只读模式（默认），只能读取文件 |
workspace-write |
可以写入工作目录 |
danger-full-access |
完全访问权限（危险） |
📝 示例：
codex --sandbox workspace-write
允许在工作目录中写入文件
--ask-for-approval / -a
安全
设置批准策略，控制何时需要用户批准命令执行。
codex --ask-for-approval <策略>
| 策略 | 说明 |
|---|---|
untrusted |
运行不受信任的命令前需要批准 |
on-failure |
命令失败时请求批准 |
on-request |
模型决定何时请求权限 |
never |
从不请求批准（自动执行） |
--full-auto
快捷
自动模式的快捷方式，等同于
--sandbox workspace-write --ask-for-approval on-failure
codex --full-auto "任务"
📝 示例：
codex --full-auto "create a todo app"
自动创建应用
--cd / -C
导航
指定工作目录，无需先 cd 到目标目录。
codex --cd <路径>
📝 示例：
codex --cd ~/projects/myapp "fix bugs"
在指定目录中工作
--image / -i
输入
附加图片文件到提示中，支持多个图片（逗号分隔）。
codex --image <图片路径>
📝 示例：
codex -i screenshot.png "Explain this error"
解释截图中的错误
codex --image img1.png,img2.jpg "Compare these designs"
比较多张图片
--profile
配置
使用预定义的配置文件（在 config.toml 中定义）。
codex --profile <配置名称>
📝 示例：
codex --profile full_auto
使用 full_auto 配置
📝 配置文件 (config.toml)
💡 配置文件位置
配置文件位于 ~/.codex/config.toml，可以设置默认行为，避免每次都输入命令行参数。
基础配置示例
配置
最常用的配置选项：
# ~/.codex/config.toml
# 默认模型
model = "gpt-5-codex"
# 批准策略
approval_policy = "on-request"
# 沙箱模式
sandbox_mode = "workspace-write"
# 允许网络访问（在 workspace-write 模式下）
[sandbox_workspace_write]
network_access = true
# 文件打开器（用于点击引用）
file_opener = "vscode" # 或 "cursor", "windsurf", "vscode-insiders"
完全权限配置
高级
给 AI 完全访问权限（谨慎使用）：
# ~/.codex/config.toml
approval_policy = "never"
sandbox_mode = "danger-full-access"
⚠️ 安全警告
使用 danger-full-access 和 never 组合会给 AI 完全的系统访问权限，存在安全风险。建议：
- 仅在受信任的环境中使用
- 或在 Docker 容器等已有沙箱保护的环境中使用
- 对于日常使用，推荐使用
workspace-write+on-request
配置文件（Profiles）
高级
定义多个配置文件，快速切换不同场景：
# ~/.codex/config.toml
# 默认配置
model = "gpt-5-codex"
approval_policy = "on-request"
# 定义配置文件
[profiles.safe]
approval_policy = "untrusted"
sandbox_mode = "read-only"
[profiles.auto]
approval_policy = "on-failure"
sandbox_mode = "workspace-write"
[profiles.yolo]
approval_policy = "never"
sandbox_mode = "danger-full-access"
📝 使用方式：
codex --profile safe
使用安全模式
codex --profile auto "build the app"
使用自动模式
MCP 服务器配置
高级
在配置文件中添加 MCP 服务器：
# ~/.codex/config.toml
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp-server"]
[mcp_servers.figma]
url = "http://127.0.0.1:3845/mcp"
bearer_token = "your-token"
[mcp_servers.docs]
command = "docs-server"
args = ["--port", "4000"]
env = { "API_KEY" = "your-key" }
💡 实用技巧
🎯 使用 @ 搜索文件
在交互模式中输入 @ 可以触发模糊文件名搜索，快速引用项目中的文件。
🖼️ 粘贴图片
在交互模式中可以直接 Ctrl+V / Cmd+V 粘贴图片到输入框，让 AI 分析图片内容。
⏮️ Esc-Esc 编辑历史消息
在空输入框中按两次 Esc 可以回到之前的消息进行编辑，从该点重新开始对话。
📁 AGENTS.md 文件
在项目根目录或 ~/.codex/ 创建 AGENTS.md 文件，可以给 Codex 提供项目特定的指导和上下文。
🔍 查看日志
日志文件位于 ~/.codex/log/codex-tui.log，可以用 tail -F ~/.codex/log/codex-tui.log 实时查看。
🌐 环境变量
使用 RUST_LOG 环境变量控制日志级别：
RUST_LOG=debug codex
🎬 常见使用场景
代码重构
场景
codex "Refactor the Dashboard component to React Hooks"
将类组件重构为 Hooks
codex "Extract common logic into a utility function"
提取公共逻辑
测试生成
场景
codex "Write unit tests for utils/date.ts"
生成单元测试
codex "Add integration tests for the API endpoints"
添加集成测试
代码审查
场景
codex "Look for vulnerabilities and create a security review report"
安全审查
codex "Review this repo and propose 3 high impact PRs"
提出改进建议
文档生成
场景
codex "Generate API documentation from the code"
生成 API 文档
codex "Add JSDoc comments to all functions"
添加代码注释
CI/CD 集成
场景
codex exec --full-auto "update CHANGELOG for next release"
自动更新变更日志
codex exec "fix the CI failure"
修复 CI 失败