OpenAI Codex CLI 完整速查表：命令、配置、MCP 一网打尽

Codex CLI 是 OpenAI 推出的终端编码代理，能够在你的机器上读取、修改和运行代码。开源、Rust 构建、快速高效。

任务类型

Local Tasks 本地任务

直接在你的机器上完成（笔记本、台式机或服务器）
直接与本地文件系统交互修改文件和运行命令
可实时查看哪些文件被修改
默认在沙箱环境中运行以限制风险

Sandbox 沙箱

Mac 和 Linux 默认运行在沙箱环境
限制文件访问范围
控制命令执行权限
管理互联网访问
Windows 推荐使用 WSL 或 Docker 容器

Cloud Tasks 云端任务

多任务并行处理
随时随地工作
在隔离环境中运行
自动克隆 GitHub 仓库并切换分支
需要代码已推送到 GitHub
可自定义环境安装额外包

Codex 接口

接口	说明
IDE Extension	VS Code、Cursor、Windsurf 等编辑器扩展
CLI	终端交互，无需打开编辑器
Web	chatgpt.com/codex，配置云端任务
Mobile	ChatGPT iOS 应用，随时启动云端任务
SDK	API 库，GitHub Action，集成到 CI/CD

快速开始

# 1. 安装
npm i -g @openai/codex

# 2. 启动
codex

# 3. 更新
npm i -g @openai/codex@latest

包含在 ChatGPT Plus、Pro、Business、Edu 和 Enterprise 计划中。

CLI 命令参考

全局标志

codex [PROMPT]                    # 可选的初始指令
--image, -i <path>                # 附带图片(可逗号分隔多个)
--model, -m <model>               # 指定模型(如 gpt-5-codex)
--oss                             # 使用本地开源模型(需 Ollama)
--profile, -p <name>              # 加载配置文件
--cd, -C <path>                   # 设置工作目录

沙箱选项

--sandbox, -s <level>             # 沙箱级别:
# read-only        - 只读
# workspace-write  - 可写工作目录
# danger-full-access - 完全访问

批准选项

--ask-for-approval, -a <mode>
# untrusted   - 不信任的操作需批准
# on-failure  - 失败时批准
# on-request  - 请求时批准
# never       - 从不批准

快捷组合

--full-auto    # 自动模式: workspace-write + on-failure
--yolo         # 危险: 跳过所有批准和沙箱

交互模式

codex                           # 启动 TUI
codex "prompt"                  # 带初始提示启动
codex --search                  # 启用网络搜索
codex -i img.png "describe"     # 带图片输入

非交互执行

codex exec "task"                        # 执行任务(别名: codex e)
codex exec --json "task"                 # 输出 JSONL 格式
codex exec - < prompt.txt                # 从 stdin 读取提示
codex exec --skip-git-repo-check "task"  # 允许非 Git 目录

恢复会话

codex resume                      # 选择历史会话
codex resume --last               # 恢复最近会话
codex resume <SESSION_ID>         # 恢复指定会话
codex resume --last "continue"    # 恢复并追加指令

# 非交互式恢复
codex exec resume <SESSION_ID> "next step"
codex exec resume --last "implement the plan"

认证命令

codex login                       # ChatGPT OAuth 登录
codex login --with-api-key        # 从 stdin 读取 API key
codex login status                # 检查登录状态(exit 0 = 已登录)
codex logout                      # 注销

# 示例
printenv OPENAI_API_KEY | codex login --with-api-key

Codex Cloud

codex cloud                                    # 交互式任务管理
codex cloud exec --env <ENV_ID> "task"         # 提交任务
codex cloud exec --env <ENV_ID> --attempts 3 "task"  # 多次尝试(1-4)
codex apply <TASK_ID>                          # 应用云任务的 diff(别名: codex a)

MCP 管理

# 基础命令
codex mcp list                    # 列出已配置的服务器
codex mcp list --json             # JSON 格式输出
codex mcp get <name>              # 查看服务器配置
codex mcp remove <name>           # 删除服务器

# 添加 STDIO 服务器
codex mcp add <name> -- <command> [args...]
codex mcp add <name> --env KEY=VALUE -- <command>

# 添加 HTTP 服务器
codex mcp add <name> --url https://example.com/mcp
codex mcp add <name> --url <url> --bearer-token-env-var TOKEN_VAR

# OAuth 认证(需启用 RMCP)
codex --enable rmcp_client mcp login <name> --scopes scope1,scope2
codex mcp logout <name>

Shell 补全

codex completion bash
codex completion zsh
codex completion fish
codex completion power-shell
codex completion elvish

# 安装示例
# Zsh
codex completion zsh > "${fpath[1]}/_codex"
# Bash
codex completion bash >> ~/.bashrc

其他命令

codex mcp-server    # 将 Codex 作为 MCP 服务器运行
codex app-server    # 启动本地应用服务器(开发用)

配置文件

配置文件位置：~/.codex/config.toml（CLI 和 IDE 共享）

常用配置选项

# 默认模型
model = "gpt-5-codex"

# 模型提供商
model_provider = "ollama"

# 批准策略: untrusted | on-failure | on-request | never
approval_policy = "on-request"

# 沙箱级别: read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"

# 推理深度: minimal | low | medium | high
model_reasoning_effort = "high"

# 环境变量控制
[shell_environment_policy]
include_only = ["PATH", "HOME"]

Profile 配置

model = "gpt-5-codex"
approval_policy = "on-request"
profile = "deep-review"        # 设置默认 profile

[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"

[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"

使用：codex --profile deep-review

优先级顺序：CLI 显式标志 > Profile 值 > config.toml 根级别 > CLI 内置默认值

功能标志 (Features)

[features]
streamable_shell = true
web_search_request = true
unified_exec = false
rmcp_client = true
view_image_tool = true

功能标志	默认值	说明
unified_exec	false	使用统一的 PTY 支持的 exec 工具
streamable_shell	false	使用可流式传输的 exec-command/write-stdin
rmcp_client	false	启用 HTTP MCP 服务器的 OAuth 支持
apply_patch_freeform	false	包含自由格式的 apply_patch 工具
view_image_tool	true	包含 view_image 工具
web_search_request	false	允许模型进行网络搜索
ghost_commit	false	每轮创建幽灵提交

MCP 服务器配置

# STDIO 服务器
[mcp_servers.myserver]
command = "node"
args = ["server.js"]
env = { KEY = "value" }
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60

# HTTP 服务器
[mcp_servers.httpserver]
url = "https://example.com/mcp"
bearer_token_env_var = "MCP_TOKEN"
enabled = true

自定义模型提供商

[model_providers.custom]
name = "My Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "chat"

完整配置示例

model = "gpt-5-codex"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
profile = "default"

[features]
web_search_request = true
view_image_tool = true

[sandbox_workspace_write]
writable_roots = ["/extra/path"]
network_access = true

[shell_environment_policy]
inherit = "core"
include_only = ["PATH", "HOME", "USER"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "env:GITHUB_TOKEN" }

[profiles.fast]
model = "gpt-4.1"
approval_policy = "untrusted"

[profiles.thorough]
model = "gpt-5-pro"
model_reasoning_effort = "high"

[history]
persistence = "save-all"

[tui]
notifications = true

file_opener = "vscode"

安全提示

本地工作使用 --full-auto，避免 --yolo
多目录访问优先使用 --add-dir 而非 danger-full-access
CI 环境配合 --json 获取机器可读输出
MCP OAuth 需启用 rmcp_client 功能标志
仅在沙箱 VM 中使用 --yolo

退出代码

0 - 成功
非 0 - 失败（用于脚本判断）

if codex login status; then
  codex exec "task"
fi