发布日期：2026-06-01 | 适用版本：Codex v0.135.0（2026-05-28）
Codex 是 OpenAI 推出的本地 AI 编程代理，以 Rust 编写，GitHub 仓库（openai/codex）截至 2026 年 6 月已获 87,300+ stars，发布了 805 个版本；它提供两种本地使用入口：Codex CLI（终端 TUI 模式）和Codex 桌面端（codex app，图形界面）。两者共享同一套核心能力——安全沙盒、MCP 工具集成、会话恢复、Agent Skills——但在交互方式和专属功能上有明显分工：CLI 面向脚本化、自动化和终端深度用户，桌面端则新增了并行工作区（Worktrees）、可视化代码审查（Review UI）、内置浏览器和 Computer Use 等 GUI 专属能力。本文提供两者的完整安装与使用教程，以及帮助你选择入口的决策框架。
安装：同一包，两种入口
Codex CLI 和桌面端来自同一个安装包，安装后通过不同命令启动：
推荐安装方式：
# 方式一：官方安装脚本（Mac/Linux，推荐）
curl -fsSL https://chatgpt.com/codex/install.sh | sh# 方式二：Homebrew（macOS）
brew install --cask codex# 方式三：npm
npm install -g @openai/codex# 方式四：Windows（PowerShell）
irm https://chatgpt.com/codex/install.ps1 | iex
安装后，两个入口的启动命令：
codex # 启动终端 TUI（CLI 模式）
codex app # 启动桌面图形界面
登录认证（四种方式）：
codex login # 浏览器 OAuth（推荐）
codex login --device-auth # 设备码流程（无浏览器环境）
printenv OPENAI_API_KEY | codex login --with-api-key # API Key
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token
支持 ChatGPT Plus / Pro / Business / Edu / Enterprise 套餐。
Codex CLI 完整教程
安全沙盒与批准模式
Codex CLI 的安全机制基于三档沙盒策略，通过 --sandbox（或 -s）参数设置：
| 沙盒模式 | 参数值 | 行为 |
|---|---|---|
| 工作区写入（默认） | workspace-write |
可读写工作目录，出界操作需人工确认 |
| 只读 | read-only |
仅浏览文件，不做任何变更 |
| 完全访问 | danger-full-access |
跨目录和网络操作，无需确认（仅限隔离环境） |
批准模式通过 --ask-for-approval（或 -a）控制：
codex -a untrusted # 所有命令执行前询问
codex -a on-request # 仅在不确定时询问
codex -a never # 从不询问（等同 --yolo）
最佳实践：日常开发用默认的
workspace-write；CI 脚本中使用--json --yolo组合获取结构化输出。
常用快捷键（TUI 模式）
| 快捷键 | 功能 |
|---|---|
Ctrl+L |
清屏（保留对话历史） |
Ctrl+O |
复制最新输出到剪贴板 |
Ctrl+R |
搜索提示词历史 |
Ctrl+G |
打开外部编辑器（$EDITOR）编辑输入 |
Tab（运行中） |
将下一轮输入排队（不打断当前任务） |
Esc×2 |
编辑上一条消息 |
@ |
模糊文件搜索，快速引用文件路径 |
!cmd |
直接执行本地 Shell 命令 |
Slash 命令速查
在 TUI 模式下输入 / 触发：
| 命令 | 功能 |
|---|---|
/review |
代码审查（支持分支对比、未提交变更） |
/model |
切换 AI 模型 |
/fork |
分叉当前会话为新分支 |
/permissions |
切换沙盒权限模式 |
/compact |
压缩会话历史，节省上下文 |
/side |
开启侧边视图 |
/diff |
查看当前会话产生的所有文件变更 |
/status |
查看会话状态 |
/keymap |
重绑 TUI 快捷键 |
/debug-config |
诊断配置加载层级 |
非交互执行（CI / 脚本化）
codex exec（别名 codex e）是 Codex CLI 专为脚本集成设计的子命令：
# 基础用法
codex exec "fix all failing tests"
codex e "refactor the authentication module"# 附带截图进行多模态分析
codex exec --image screenshot.png,diagram.png "explain this architecture"# CI 场景：JSON 输出 + 保存最终消息 + 工作区沙盒
codex exec --json --output-last-message result.txt --sandbox workspace-write "fix CI failure"# 从 stdin 读取提示词（支持管道）
echo "fix the bug in main.py" | codex exec -# 指定模型和配置覆盖
codex exec -m gpt-5.5 -c features.web_search=true "research and implement rate limiting"
会话恢复与 Fork
codex resume # 打开会话选择器
codex resume --last # 直接继续最近一次会话
codex resume <UUID> # 精确恢复指定会话codex fork --last # Fork 最近会话为新分支（不覆盖原始历史）
MCP 工具集成
# 添加 stdio MCP 服务器
codex mcp add myserver -- /path/to/server --arg1# 添加 HTTP MCP 服务器
codex mcp add myserver --url https://example.com/mcp# 一行命令接入 Obsidian vault
claude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian# 管理命令
codex mcp list --json
codex mcp remove myserver
配置也可写入 ~/.codex/config.toml，会话启动时自动加载。
插件市场
# 从 GitHub 安装 Agent Skills 或插件包
codex plugin marketplace add owner/repo# 安装特定版本或子目录
codex plugin marketplace add owner/repo@v1.0 --sparse plugins/# 更新和删除
codex plugin marketplace upgrade
codex plugin marketplace remove my-marketplace
多目录与云端执行
# 授权访问额外目录（不升级沙盒级别）
codex --add-dir /data/shared --sandbox workspace-write "process files"# 云端远程执行（Experimental）
codex cloud exec --env ENV_ID --attempts 3 "build and test the feature"
Codex 桌面端完整教程
# 启动桌面端
codex app # macOS：打开默认界面
codex app /path/to/your/project # 指定工作空间打开
桌面端专属功能
CLI 有的能力桌面端全部具备，以下是桌面端独有的扩展：
Worktrees（并行工作区）
同时管理多个独立的任务工作区，不同功能分支互不干扰，适合并行推进多个任务。
Automations（自动化工作流）
通过 GUI 配置定时触发或事件触发的自动化任务，无需手写 cron 脚本。
Review UI（可视化代码审查）
图形化展示 Codex 产生的所有文件变更，支持逐行审查、接受或拒绝，体验类似 GitHub PR 审查界面。
内置浏览器
直接在桌面端内打开网页，无需切换到外部浏览器，AI 可感知浏览器当前页面内容。
Chrome 扩展集成
通过浏览器扩展，在任意网页上触发 Codex 操作，实现网页内容与代码任务的无缝连接。
Computer Use（GUI 自动化）
控制桌面应用程序，模拟鼠标点击和键盘输入，适合需要操作 GUI 软件的自动化任务。
Appshots（应用快照）
保存应用程序的状态快照，便于在特定上下文下复现或恢复工作场景。
Local Environments UI
图形界面管理本地开发环境配置，替代手动编辑 .toml 配置文件。
共享核心功能
两种入口完全共享：/model、/compact、/diff、/permissions、/fork、/side、MCP 工具调用、Agent Skills、持久化记忆（Memory）、钩子系统（Hooks）。
CLI vs 桌面端：如何选择？
| 维度 | Codex CLI | Codex 桌面端 |
|---|---|---|
| 启动方式 | codex |
codex app |
| 界面类型 | 终端 TUI | 图形 GUI |
| 可视化代码审查 | 基础 /diff |
Review UI（完整 GUI） |
| 并行工作区 | 手动管理 | Worktrees 原生支持 |
| 自动化配置 | 命令行 + cron | Automations 图形界面 |
| 浏览器集成 | 无 | 内置浏览器 + Chrome 扩展 |
| Computer Use | 无 | 支持 |
| 脚本/CI 集成 | ✅（codex exec） |
不适合 |
| 远程 TUI | ✅（--remote） |
不支持 |
| Shell 补全 | ✅（bash/zsh/fish） | 不适用 |
| 轻量启动 | 极快 | 稍慢（GUI 初始化） |
选择建议：
- 全职开发者、喜欢终端工作流 → CLI，可最大化
codex exec和 MCP 集成效率 - 需要可视化审查、多任务并行 → 桌面端，Review UI 和 Worktrees 显著提升效率
- CI/CD 流水线、脚本自动化 → 仅 CLI（
codex exec --json） - 需要控制 GUI 应用或浏览器 → 桌面端（Computer Use + 内置浏览器）
- 两者结合 → 最佳实践：日常交互用桌面端，脚本化任务用 CLI 的
exec子命令
进阶配置
多配置文件管理
# ~/.codex/config.toml（默认配置）
model = "gpt-5.5"
web_search = "live"[sandbox]
default = "workspace-write"
# 使用特定配置文件覆盖
codex --profile work "start working on the API"
codex exec -c model=gpt-5.5 -c features.web_search=false "analyze this code"
使用外部模型 API
Codex CLI 支持通过 API Key 接入非 OpenAI 模型。七牛云 API Key 兼容 OpenAI 标准接口，激活即得最高 600 万免费 Token，可作为 Codex 的模型后端，在不更换工作流的前提下切换推理模型。关于如何将多种 AI 模型集成到 Codex 等编程工具的配置方法，可参考七牛云 AI 编程工具配置大全。
本地开源模型（Ollama）
# 启动本地模型（需先运行 Ollama）
codex --oss "help me refactor this function"
codex exec --oss "run tests and fix failures"
FAQ
Q：Codex CLI、Codex 桌面端、Codex Web 是同一个产品吗？
同一品牌，三个不同入口。CLI（codex）和桌面端（codex app）来自同一本地安装包，数据和配置共享；Codex Web（chatgpt.com/codex）是独立的云端版本，任务在 OpenAI 云端环境中执行，需要 GitHub 集成，不依赖本地安装。
Q：默认使用什么模型？Pro 用户有什么区别？
Codex 默认使用 gpt-5.5 模型。ChatGPT Pro 用户可通过 /model 切换访问 GPT-5.3-Codex-Spark（在文档中标注为 Pro 专属）。也可通过 -m 参数或配置文件指定其他任意模型。
Q：codex exec 和直接运行 codex 有什么区别？
codex（不带参数）进入交互式 TUI 终端，适合对话式工作流。codex exec "任务描述"（或 codex e）是非交互的单次执行，完成后自动退出，适合 CI/CD 管道、Shell 脚本和无人值守的自动化场景。两者都支持 --sandbox、--model、--image 等参数。
Q：怎么防止 Codex 修改我不想动的文件？
三层防护：① 默认沙盒 workspace-write 只能修改当前工作目录，出界操作需确认；② --sandbox read-only 完全禁止写操作；③ 使用 codex execpolicy 配置精细化规则文件，指定哪些路径或命令被允许执行。
Q：Codex CLI 在 Windows 上好用吗？
原生支持 Windows，通过 PowerShell 安装脚本安装。沙盒机制针对 Windows 单独适配（codex sandbox windows）。主要限制是部分依赖 Unix 特性的第三方 MCP 服务器可能需要额外配置，推荐配合 WSL2 使用以获得最佳兼容性。
总结
Codex v0.135.0 的 CLI 和桌面端已形成清晰的能力分工——CLI 是脚本化、CI 集成和终端深度用户的首选，而桌面端的 Review UI、Worktrees 和 Computer Use 则填补了 GUI 工作流的空白。两者安装自同一包，核心功能完全共享，可根据具体任务场景灵活切换。配合 MCP 工具生态和 codex plugin marketplace 的技能包系统，Codex 正在成为一个可深度定制的本地 AI 编程操作系统，而非单纯的代码补全工具。
相关资源
- Codex CLI GitHub 仓库 — 源码、Issues、Release Notes
- 七牛云 AI 编程工具配置大全 — Codex 接入外部模型 API 配置指南