Codex CLI

概述

Codex CLI 是 OpenAI 推出的轻量级开源编程智能体，直接运行在你的终端中。它由 Rust 编写核心（codex-rs），能够理解自然语言指令，自主读取/写入文件、执行 Shell 命令并完成编码任务。

开发者：OpenAI
类型：开源软件
许可：Apache License 2.0
语言：Rust（核心）+ TypeScript
GitHub：https://github.com/openai/codex
Stars：77,256+

TIP

Codex CLI 是独立的终端工具，不同于：

旧的 OpenAI Codex 模型（已停用的代码生成模型）
Codex Web（chatgpt.com/codex 上的云端智能体）
Codex IDE 扩展（VS Code / Cursor / Windsurf 扩展）

系统要求

要求	说明
操作系统	macOS 12+ / Ubuntu 20.04+ / Debian 10+ / Windows 11（需 WSL2）
内存	4 GB 最低，8 GB 推荐
处理器	x64 或 ARM64
Git	2.23+（可选，推荐，用于内置 PR 辅助功能）
Rust	仅从源码构建时需要
网络	需要互联网连接

安装

Windows 用户请使用 WSL2 安装

Codex CLI 在 Windows 原生环境下兼容性不佳，强烈建议在 WSL2（Ubuntu 24.04）中安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 Codex CLI
npm install -g @openai/codex

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
codex

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

方式一：npm（跨平台，推荐）

bash

npm install -g @openai/codex

方式二：Homebrew（macOS）

bash

brew install --cask codex

方式三：GitHub Releases 二进制下载

从 https://github.com/openai/codex/releases/latest 下载对应平台二进制：

平台	文件
macOS Apple Silicon	`codex-aarch64-apple-darwin.tar.gz`
macOS Intel	`codex-x86_64-apple-darwin.tar.gz`
Linux x86_64	`codex-x86_64-unknown-linux-musl.tar.gz`
Linux ARM64	`codex-aarch64-unknown-linux-musl.tar.gz`

还提供 DotSlash 文件，用于团队版本锁定工作流。

方式四：从源码构建

bash

git clone https://github.com/openai/codex.git
cd codex/codex-rs
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
cargo build
cargo run --bin codex -- "解释这个代码库"

认证配置

方式一：ChatGPT 登录（推荐）

bash

codex
# 选择 "Sign in with ChatGPT"

支持以下 ChatGPT 计划：

ChatGPT Plus
ChatGPT Pro
ChatGPT Business
ChatGPT Edu
ChatGPT Enterprise

登录命令：

bash

codex login    # 交互式登录
codex logout   # 登出

方式二：API Key

bash

export OPENAI_API_KEY=sk-xxxxx
codex

# 或使用登录命令
codex login --api-key

支持组织/项目范围：

bash

export OPENAI_ORGANIZATION=org-xxxxx
export OPENAI_PROJECT=proj-xxxxx

方式三：Amazon Bedrock

bash

# 在 ~/.codex/config.toml 中配置
[model_providers.amazon-bedrock]
# 使用 AWS SigV4 认证
# 配置 aws.profile 和 aws.region

基础使用

交互式 TUI

bash

codex                          # 启动交互式 TUI
codex "explain this codebase"  # 带初始提示启动
codex -m <model> "prompt"      # 指定模型
codex --search "prompt"        # 启用实时网络搜索
codex --full-auto "prompt"     # 全自动模式
codex resume                   # 恢复上次会话
codex resume --last            # 恢复最近的会话
codex fork                     # 分叉一个之前的会话
codex app                      # 启动桌面应用（macOS/Windows）

非交互模式

bash

codex exec "fix the bug in main.py"    # 非交互执行
codex exec --json "prompt"             # JSONL 输出
codex exec -o output.txt "prompt"      # 将最后消息写入文件
codex exec --ephemeral "prompt"        # 不持久化会话
codex review                           # 运行代码审查

关键 CLI 标志

标志	说明
`-m, --model <MODEL>`	指定使用的模型
`-s, --sandbox <MODE>`	沙箱策略：`read-only` / `workspace-write` / `danger-full-access`
`-a, --ask-for-approval <MODE>`	审批策略：`untrusted` / `on-failure` / `on-request` / `never`
`--full-auto`	低摩擦沙箱自动执行的便捷别名
`--oss`	使用开源本地提供商（Ollama 或 LM Studio）
`--local-provider <PROVIDER>`	指定 `lmstudio` 或 `ollama`
`-i, --image <FILE>`	附加图片到提示
`-p, --profile <PROFILE>`	使用 config.toml 中的配置档案
`-C, --cd <DIR>`	设置工作目录
`--add-dir <DIR>`	添加额外可写目录
`--search`	启用实时网络搜索
`--no-alt-screen`	以内联模式运行 TUI

DANGER

--dangerously-bypass-approvals-and-sandbox（别名 --yolo）会跳过所有确认和沙箱限制，极其危险，请谨慎使用。

核心功能

沙箱模式

Codex CLI 的安全核心，限制 AI 的文件系统和网络访问：

模式	说明
`read-only`（默认）	只能读取文件，禁止网络访问
`workspace-write`	可读所有文件 + 可写当前工作目录和 tmp，默认禁止网络
`danger-full-access`	无任何限制

平台实现：

macOS：Seatbelt（/usr/bin/sandbox-exec）
Linux：Landlock 和 Bubblewrap（bwrap）
Windows：RestrictedToken 沙箱

审批策略

策略	说明
`untrusted`	仅"已知安全"命令（ls, cat, sed）自动批准，其余需用户确认
`on-failure`（已弃用）	自动批准所有，仅在失败时上报
`on-request`（默认）	由模型决定何时请求审批
`never`	从不请求审批，失败返回给模型处理

Guardian 自动审查器

可选的 AI 审批系统，使用子代理收集上下文并做出风险决策：

toml

# config.toml
approvals_reviewer = "auto_review"

风险等级：Low / Medium / High / Critical

协作模式

模式	说明
Plan	只读模式，智能体创建计划但不执行
Default	标准执行模式，读取、写入和执行命令

MCP 服务器支持

通过 Model Context Protocol 连接外部工具：

toml

# ~/.codex/config.toml
[mcp_servers.example]
default_tools_approval_mode = "auto"
supports_parallel_tool_calls = true

网络搜索

内置网页搜索工具，三种模式：

禁用（disabled）
缓存（cached）
实时（live）

bash

codex --search "查找最新的 React 19 新特性"

会话管理

Resume：恢复之前的会话
Fork：分叉一个之前的会话，不影响原始会话
Ghost Snapshots/Undo：通过 Ghost 提交实现撤销功能

实时语音（实验性）

基于 WebSocket 的实时音频对话功能。

桌面应用

bash

codex app  # 启动桌面 GUI（macOS/Windows）

代码审查

bash

codex review  # 自动化代码审查

配置

配置文件位置

~/.codex/config.toml

关键配置项

toml

# 模型选择
model = "gpt-5.4"
model_provider = "openai"
model_reasoning_effort = "medium"
model_context_window = 200000

# 沙箱
sandbox_mode = "workspace-write"
sandbox_workspace_write = true

# 审批
approval_policy = "on-request"
approvals_reviewer = "auto_review"

# 开发者指令
instructions = "Always use TypeScript strict mode"
developer_instructions = "Follow project coding standards"
model_instructions_file = ".codex-instructions.md"

# MCP 服务器
[mcp_servers.slack]
default_tools_approval_mode = "auto"

# 自定义模型提供商
[model_providers.my-provider]
base_url = "https://api.example.com/v1"
api_key_env = "MY_PROVIDER_API_KEY"

# 配置档案
[profiles.work]
model = "gpt-5.4"
sandbox_mode = "workspace-write"

[profiles.personal]
model = "gpt-4.1-mini"
sandbox_mode = "read-only"

# 通知
notify = "terminal-notifier -title 'Codex' -message 'Task complete'"

# 日志
# 日志位于 ~/.codex/log/codex-tui.log
# 设置 RUST_LOG=debug 环境变量查看详细日志

配置档案

使用 -p 标志切换配置：

bash

codex -p work "fix the bug"    # 使用 work 档案
codex -p personal "explain"    # 使用 personal 档案

执行策略规则

持久化的命令允许/拒绝规则，通过 .rules 文件管理：

运行时批准的命令可保存为策略修订
支持命令前缀模式匹配

网络策略

主机级出站网络访问的允许/拒绝规则：

可持久化为策略修订
支持域名和 IP 模式

支持的 AI 模型

内置提供商

提供商	认证方式	示例模型
OpenAI（默认）	ChatGPT OAuth / API Key	gpt-5.4, o4-mini, gpt-4.1
Amazon Bedrock	AWS SigV4	Claude 3.7 Sonnet
Ollama（本地/OSS）	本地	gpt-oss:20b
LM Studio（本地/OSS）	本地	openai/gpt-oss-20b

当前默认模型

gpt-5.4（v0.123.0 起）

模型配置选项

toml

model = "gpt-5.4"                          # 模型名称
model_reasoning_effort = "medium"           # 推理努力级别：none/minimal/low/medium/high/xhigh
model_verbosity = "medium"                  # 详细程度（GPT-5 模型）：low/medium/high
model_context_window = 200000               # 上下文窗口大小

自定义提供商

支持添加任何 OpenAI 兼容的 API 端点：

toml

[model_providers.my-custom]
base_url = "https://my-api.example.com/v1"
api_key_env = "MY_CUSTOM_API_KEY"

安全特性

多层安全体系

沙箱隔离 — 平台原生沙箱限制文件系统和网络访问
审批策略 — 四级审批，从最严格到最宽松
--full-auto 标志 — 便捷的沙箱自动执行模式（网络禁用）
Guardian 自动审查器 — AI 风险评估，风险等级分级
执行策略规则 — 持久化的命令允许/拒绝规则
网络策略 — 主机级出站访问控制
文件系统沙箱 — 细粒度目录读写权限
MCP 工具审批 — 按服务器和工具的审批模式
只读模式 — Plan 模式下只能读取和计划
自定义 CA 证书 — 企业 TLS 拦截代理支持

审批决策

用户面对审批请求时可选择：

批准一次
本次会话内批准
带策略修订批准
中止

本地模型支持

Ollama

bash

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull codellama:13b

# 使用 Codex CLI
codex --oss "explain this code"

LM Studio

bash

# 在 LM Studio 中加载模型后
codex --oss --local-provider lmstudio "write a function"

常见工作流

代码探索

bash

codex "解释这个项目的架构和主要模块"

Bug 修复

bash

codex "main.py 中的用户认证在特定条件下返回 500 错误，找到并修复"

代码生成

bash

codex "为用户模型编写 FastAPI 的 CRUD 端点"

代码审查

bash

codex review

自动化脚本

bash

# 非交互模式 + JSON 输出，适合 CI/CD
codex exec --json "检查是否有安全漏洞" | jq '.'

大规模重构

bash

codex --full-auto "将所有 class 组件迁移为函数式组件"

故障排查

bash

# 查看日志
cat ~/.codex/log/codex-tui.log

# 设置调试级别日志
export RUST_LOG=debug
codex "test"

# 常见问题
# - 登录失败：检查网络和 ChatGPT 订阅状态
# - 沙箱错误：macOS 确保 Seatbelt 可用，Linux 确保 Landlock/bwrap 已安装
# - 模型不可用：检查 API Key 和模型名称
# - WSL2 问题：确保 Git for Windows 已安装

Codex CLI ​

概述 ​

系统要求 ​

安装 ​

方式一：npm（跨平台，推荐） ​

方式二：Homebrew（macOS） ​

方式三：GitHub Releases 二进制下载 ​

方式四：从源码构建 ​

认证配置 ​

方式一：ChatGPT 登录（推荐） ​

方式二：API Key ​

方式三：Amazon Bedrock ​

基础使用 ​

交互式 TUI ​

非交互模式 ​

关键 CLI 标志 ​

核心功能 ​

沙箱模式 ​

审批策略 ​

Guardian 自动审查器 ​

协作模式 ​

MCP 服务器支持 ​

网络搜索 ​

会话管理 ​

实时语音（实验性） ​

桌面应用 ​

代码审查 ​

配置 ​

配置文件位置 ​

关键配置项 ​

配置档案 ​

执行策略规则 ​

网络策略 ​

支持的 AI 模型 ​

内置提供商 ​

当前默认模型 ​

模型配置选项 ​

自定义提供商 ​

安全特性 ​

多层安全体系 ​

审批决策 ​

本地模型支持 ​

Ollama ​

LM Studio ​

常见工作流 ​

代码探索 ​

Bug 修复 ​

代码生成 ​

代码审查 ​

自动化脚本 ​

大规模重构 ​

故障排查 ​

Codex CLI

概述

系统要求

安装

方式一：npm（跨平台，推荐）

方式二：Homebrew（macOS）

方式三：GitHub Releases 二进制下载

方式四：从源码构建

认证配置

方式一：ChatGPT 登录（推荐）

方式二：API Key

方式三：Amazon Bedrock

基础使用

交互式 TUI

非交互模式

关键 CLI 标志

核心功能

沙箱模式

审批策略

Guardian 自动审查器

协作模式

MCP 服务器支持

网络搜索

会话管理

实时语音（实验性）

桌面应用

代码审查

配置

配置文件位置

关键配置项

配置档案

执行策略规则

网络策略

支持的 AI 模型

内置提供商

当前默认模型

模型配置选项

自定义提供商

安全特性

多层安全体系

审批决策

本地模型支持

Ollama

LM Studio

常见工作流

代码探索

Bug 修复

代码生成

代码审查

自动化脚本

大规模重构

故障排查