codex-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex CLI

OpenAI's terminal coding agent. Reads, edits, and runs code locally with configurable sandbox and approval controls. Built in Rust, open source.

OpenAI推出的终端编码代理工具。可在本地读取、编辑并运行代码，支持可配置的沙箱与审批控制。基于Rust构建，开源免费。

Quick Reference

快速参考

```bash

bash

undefined

Interactive session

交互式会话

codex "your prompt here"

Non-interactive (scripting/CI)

非交互式（脚本/CI场景）

codex exec "your prompt here" codex exec --json "prompt" # JSONL output codex exec -o result.txt "prompt" # Save last message

codex exec "your prompt here" codex exec --json "prompt" # 输出JSONL格式结果 codex exec -o result.txt "prompt" # 将最后一条消息保存到文件

Code review

代码审查

codex review # Review current branch vs main codex review --uncommitted # Review all uncommitted changes codex review --base develop # Review against specific branch codex review --commit abc123 # Review a specific commit

codex review # 审查当前分支与main分支的差异 codex review --uncommitted # 审查所有未提交的变更 codex review --base develop # 与指定分支对比审查 codex review --commit abc123 # 审查指定提交

Session management

会话管理

codex resume # Pick from recent sessions codex resume --last # Continue most recent codex fork --last # Fork most recent into new thread

codex resume # 从最近的会话中选择恢复 codex resume --last # 继续最近一次的会话 codex fork --last # 将最近一次会话分支为新线程

Cloud tasks (experimental)

云任务（实验性功能）

codex cloud exec --env ENV_ID "task" codex cloud list codex cloud apply TASK_ID codex cloud diff TASK_ID ```

codex cloud exec --env ENV_ID "task" codex cloud list codex cloud apply TASK_ID codex cloud diff TASK_ID

undefined

Key Flags

关键标记

Flag	Short	Purpose
`--model`	`-m`	Select model (e.g. `gpt-5.3-codex`, `o3`)
`--sandbox`	`-s`	`read-only` / `workspace-write` / `danger-full-access`
`--ask-for-approval`	`-a`	`untrusted` / `on-failure` / `on-request` / `never`
`--full-auto`		Shortcut: `-a on-request -s workspace-write`
`--image`	`-i`	Attach image(s) to prompt
`--search`		Enable live web search
`--cd`	`-C`	Set the working directory for the `codex` command. This directory will be used as the base for operations by subcommands like `exec`, `review`, `cloud exec`, etc. This flag should be passed directly to the `codex` command. For example: `codex --cd /path/to/project review`.
`--add-dir`		Grant additional writable directories
`--config`	`-c`	Override config value (e.g. `-c model="o3"`)
`--profile`	`-p`	Load named config profile
`--oss`		Use local model provider (LM Studio / Ollama)
`--json`		(exec only) JSONL output
`--output-last-message`	`-o`	(exec only) Write last message to file
`--yolo`		Bypass all approvals and sandbox (DANGEROUS)

标记	简写	用途
`--model`	`-m`	选择模型（例如 `gpt-5.3-codex` 、 `o3` ）
`--sandbox`	`-s`	设置沙箱模式： `read-only` / `workspace-write` / `danger-full-access`
`--ask-for-approval`	`-a`	设置审批模式： `untrusted` / `on-failure` / `on-request` / `never`
`--full-auto`		快捷设置： `-a on-request -s workspace-write`
`--image`	`-i`	为提示词附加图片
`--search`		启用实时网页搜索
`--cd`	`-C`	设置codex命令的工作目录，该目录将作为 `exec` 、 `review` 、 `cloud exec` 等子命令的操作基础。此标记需直接传递给codex命令，例如： `codex --cd /path/to/project review`
`--add-dir`		额外授予可写入的目录权限
`--config`	`-c`	覆盖配置值（例如 `-c model="o3"` ）
`--profile`	`-p`	加载指定名称的配置文件
`--oss`		使用本地模型提供商（LM Studio / Ollama）
`--json`		仅适用于exec命令：输出JSONL格式结果
`--output-last-message`	`-o`	仅适用于exec命令：将最后一条消息写入文件
`--yolo`		绕过所有审批与沙箱限制（危险操作）

Approval Modes

审批模式

untrusted (default): Only trusted commands (ls, cat, sed…) run without asking. Others prompt user.
on-failure: Run all commands freely. Only prompt if a command fails.
on-request: Model decides when to ask.
never: Never prompt. Failures go straight back to model.

untrusted（默认）：仅信任的命令（如ls、cat、sed等）可直接运行，其他命令需询问用户。
on-failure：所有命令可自由运行，仅当命令执行失败时才提示用户。
on-request：由模型决定何时向用户请求审批。
never：从不提示用户，执行失败结果直接返回给模型。

Sandbox Modes

沙箱模式

read-only: No file writes, no network.
workspace-write: Write only in workspace + specified dirs. Configurable network access.
danger-full-access: Unrestricted. Use only in isolated environments.

read-only：禁止文件写入，无网络访问权限。
workspace-write：仅可在工作区及指定目录写入，网络访问权限可配置。
danger-full-access：无任何限制，仅在隔离环境中使用。

Slash Commands (Interactive)

斜杠命令（交互式会话）

Command	Purpose
`/model`	Switch model mid-session
`/permissions`	Adjust approval/sandbox settings
`/review`	Run code review
`/diff`	Show git diff including untracked files
`/compact`	Summarize conversation to free tokens
`/mention`	Attach file to conversation
`/new`	Start new conversation in same session
`/resume`	Resume saved conversation
`/fork`	Fork current conversation
`/init`	Generate AGENTS.md scaffold
`/mcp`	List MCP tools
`/status`	Show session config and token usage
`/ps`	Show background terminals
`/quit`	Exit

命令	用途
`/model`	会话中途切换模型
`/permissions`	调整审批/沙箱设置
`/review`	执行代码审查
`/diff`	显示包含未跟踪文件的git差异
`/compact`	总结对话内容以释放令牌
`/mention`	为对话附加文件
`/new`	在同一会话中开启新对话
`/resume`	恢复已保存的对话
`/fork`	分支当前对话
`/init`	生成AGENTS.md脚手架文件
`/mcp`	列出MCP工具
`/status`	显示会话配置与令牌使用情况
`/ps`	显示后台终端
`/quit`	退出会话

Common Patterns

常见使用场景

CI/CD Automation

CI/CD自动化

```bash

bash

undefined

Run task non-interactively with JSON output

以非交互式方式运行任务并输出JSON结果

codex exec --json --full-auto "fix all lint errors" | process_results.sh

codex exec --json --full-auto "修复所有lint错误" | process_results.sh

Structured output with schema

使用指定 schema 生成结构化输出

codex exec --output-schema schema.json "analyze this codebase" ```

codex exec --output-schema schema.json "分析此代码库"

undefined

Code Review in CI

CI中的代码审查

```bash codex review --base main --title "PR #42: Add auth" ```

bash

codex review --base main --title "PR #42: 添加认证功能"

Multi-Directory Projects

多目录项目

```bash codex --cd ./backend --add-dir ./shared "update the API" ```

bash

codex --cd ./backend --add-dir ./shared "更新API"

Image-Driven Development

基于图像的开发

```bash codex -i mockup.png "implement this UI exactly" ```

bash

codex -i mockup.png "严格按照此UI实现功能"

Local OSS Models

本地开源模型

```bash codex --oss --CPA ollama -m codellama "refactor this function" ```

bash

codex --oss --CPA ollama -m codellama "重构此函数"

Configuration

配置

Config file: `~/.codex/config.toml` (user-level), `.codex/config.toml` (project-level).

For full configuration reference including all keys, MCP server setup, model providers, sandbox permissions, shell environment policies, and OpenTelemetry: see references/config-reference.md.

配置文件：用户级为

~/.codex/config.toml

，项目级为

.codex/config.toml

。

完整配置参考（包括所有配置项、MCP服务器设置、模型提供商、沙箱权限、Shell环境策略及OpenTelemetry）请查看references/config-reference.md。

MCP Server Management

MCP服务器管理

```bash codex mcp list # List configured servers codex mcp add <name> # Add MCP server codex mcp remove <name> # Remove MCP server codex mcp login <name> # Authenticate with server codex mcp logout <name> # Remove server credentials ```

Configure in config.toml:

```toml [mcp_servers.my-server] command = "npx" args = ["-y", "@my/mcp-server"] enabled = true ```

bash

codex mcp list                       # 列出已配置的服务器
codex mcp add <name>                 # 添加MCP服务器
codex mcp remove <name>              # 删除MCP服务器
codex mcp login <name>               # 登录MCP服务器进行身份验证
codex mcp logout <name>              # 删除服务器凭证

在config.toml中配置：

toml

[mcp_servers.my-server]
command = "npx"
args = ["-y", "@my/mcp-server"]
enabled = true