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 |
快速开始
bash
# 1. 安装
npm i -g @openai/codex
# 2. 启动
codex
# 3. 更新
npm i -g @openai/codex@latest包含在 ChatGPT Plus、Pro、Business、Edu 和 Enterprise 计划中。
CLI 命令参考
全局标志
bash
codex [PROMPT] # 可选的初始指令
--image, -i <path> # 附带图片(可逗号分隔多个)
--model, -m <model> # 指定模型(如 gpt-5-codex)
--oss # 使用本地开源模型(需 Ollama)
--profile, -p <name> # 加载配置文件
--cd, -C <path> # 设置工作目录沙箱选项
bash
--sandbox, -s <level> # 沙箱级别:
# read-only - 只读
# workspace-write - 可写工作目录
# danger-full-access - 完全访问批准选项
bash
--ask-for-approval, -a <mode>
# untrusted - 不信任的操作需批准
# on-failure - 失败时批准
# on-request - 请求时批准
# never - 从不批准快捷组合
bash
--full-auto # 自动模式: workspace-write + on-failure
--yolo # 危险: 跳过所有批准和沙箱交互模式
bash
codex # 启动 TUI
codex "prompt" # 带初始提示启动
codex --search # 启用网络搜索
codex -i img.png "describe" # 带图片输入非交互执行
bash
codex exec "task" # 执行任务(别名: codex e)
codex exec --json "task" # 输出 JSONL 格式
codex exec - < prompt.txt # 从 stdin 读取提示
codex exec --skip-git-repo-check "task" # 允许非 Git 目录恢复会话
bash
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"认证命令
bash
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-keyCodex Cloud
bash
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 管理
bash
# 基础命令
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 补全
bash
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其他命令
bash
codex mcp-server # 将 Codex 作为 MCP 服务器运行
codex app-server # 启动本地应用服务器(开发用)配置文件
配置文件位置：~/.codex/config.toml（CLI 和 IDE 共享）
常用配置选项
toml
# 默认模型
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 配置
toml
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)
toml
[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 服务器配置
toml
# 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自定义模型提供商
toml
[model_providers.custom]
name = "My Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "chat"完整配置示例
toml
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- 失败（用于脚本判断）
bash
if codex login status; then
codex exec "task"
fi相关资源
- 配置文件：
~/.codex/config.toml - 会话记录：
~/.codex/sessions/ - 完整文档：Codex CLI overview, AGENTS.md