OpenAI Codex 使用手册

不知道你有没有这种感受：用过不少 AI 写代码工具，大部分只能写写几十行的小片段，补补单行代码。遇到真实项目里的活儿，比如批量改多处文件、排查整套工程 bug、写全套单元测试，往往就力不从心。

很多时候不是 AI 不够聪明，而是工具只停留在 “代码片段生成”，没法真正理解你的整个项目。

而 OpenAI Codex 就不太一样。它更像一个可以帮你干活的编程助理，不光能写代码，还能翻阅你本地完整项目、跑终端命令、管理 Git、定时帮你做代码巡检，甚至可以操控浏览器完成测试。

但有利必有弊。既然它能触碰你电脑里的文件和命令，安全这件事就绝对不能马虎。不少开发者刚上手，只顾着体验效率，忽略沙箱和权限设置，最后闹出代码被改乱的麻烦。

这份手册，不想堆砌一堆生硬的官方术语。我会把 Codex 的各种玩法、踩过的坑、安全注意事项讲明白，不管是个人开发者想提升效率，还是团队希望把它引入工作流，都可以拿来参考。

一、快速入门：三种接入方式

1. Codex Cloud 云端网页版

无需本地安装，直接对接 GitHub 仓库，适合不想配置本地环境的开发者。 操作步骤：

1. 访问 chatgpt.com/codex，登录账号并绑定 GitHub；
2. 选择需要操作的目标仓库，配置运行环境；
3. 在网页输入任务，后台异步执行，实时查看运行日志；
4. 任务结束打开 Diff 差异视图，逐行审核代码变更，一键生成 Pull Request。

✅最佳实践：执行任务前保证git status工作区干净，任务前后创建 Git 检查点，出现异常可以随时回滚代码。

2. CLI 命令行工具

环境依赖：Node.js 18+，适合重度终端使用者、CI/CD 流水线集成。

#全局安装
npm install -g @openai/codex
#启动交互会话
codex
#直接执行单次任务
codex "修复项目全部TypeScript类型错误"
#全自动模式，无需人工确认
codex --full-auto "为utils.ts所有函数编写单元测试"

核心常用参数：

• --sandbox read‑only：只读沙箱，仅读取文件禁止修改，用于代码审计；
• --search：开启联网搜索，获取最新技术文档与版本信息；
• codex doctor：环境诊断，检查 Git、终端、配置文件异常；
• codex cloud：向云端下发任务，执行结果同步回本地。

子代理 Subagents：可以把大型任务拆解，多个子任务并行运行，例如同时为 auth、user、order 模块编写单元测试，显著提升效率。

3. Codex 桌面客户端

支持 Windows、macOS（Intel / Apple Silicon），功能最完整。

1. 下载安装客户端，使用 ChatGPT 账号或者 OpenAI API‑Key 登录；
2. 选择本地项目文件夹，切换至 Local 本地模式；
3. 输入自然语言指令开展工程工作。

桌面端支持和 IDE 插件双向同步，共享会话线程与 Auto Context 上下文，IDE 写代码，桌面端处理大型重构任务，两端协同。

二、桌面端核心功能详解

桌面客户端集合 Codex 全部能力，也是日常本地项目的主力入口：

1. 多项目并行 Multitask 支持多个独立会话线程，不同项目任务上下文互相隔离，互不干扰，多项目切换无需重启工具。
2. Git Worktree 支持 利用 Git Worktree 隔离 AI 生成的代码改动。并行做 bug 修复、新功能开发，AI 的修改放在独立分支，不会污染正在手写的主工作区。
3. Computer Use 电脑操控 不止处理代码文本，可以操控桌面软件、浏览器，完成 GUI 自动化、网页测试，突破纯文本代码的局限。
4. 内置代码审查提交 Diff 差异视图逐行审阅每一处改动，暂存、commit 提交、push 推送、创建 PR，全部在客户端完成。
5. 独立集成终端 每一条对话线程自带独立终端，命令执行互不干扰，可保存可复用项目动作。
6. Automations 自动化任务 配置定时后台任务，周期性执行依赖扫描、监控 CI 状态、巡检代码质量。
7. Skills 技能体系 把团队标准化工作流封装成模板，桌面、CLI、IDE 插件通用，避免重复写大段提示词。
8. MCP 插件系统 依靠 MCP 协议对接 GitHub、文件系统等第三方工具，拓展工具边界。

划重点：能力越强，权限越大，沙箱安全是重中之重，不要随便关闭防护。

三、安全沙箱与配置（重中之重）

重要认知：审批弹窗不等于沙箱防护。审批是交互层面是否询问你，沙箱是内核层面限制能不能执行操作，两者组合形成纵深防御体系。

三种沙箱运行模式

1. read‑only只读模式：仅读取文件，禁止任何修改。适合架构分析、源码阅读、漏洞排查。
2. workspace‑write工作区读写：允许修改当前项目目录文件，目录之外文件禁止访问，高危系统操作依旧拦截，高风险动作会弹出人工确认，绝大多数日常开发首选。
3. danger‑full‑access完全无隔离：关闭沙箱防护，普通开发不要碰；仅 Docker 容器环境，以容器作为隔离边界才考虑启用。

配置文件 config.toml

配置文件路径：全局配置 ~/.codex/config.toml；项目级配置放在项目目录下 .codex/config.toml。

核心配置项：

approval_policy = "on‑request"
# on‑request询问确认 / never全部自动放行 / untrusted不可信操作必确认
sandbox_mode = "workspace‑write"

[history]
persistence = true
max_bytes = 104857600

[otel]
environment = "prod"
exporter = "otlp‑http"
log_user_prompt = false #关闭提示词记录，保护源码隐私

审批策略说明：

• on‑request：风险操作请求人工确认，推荐默认；
• never：全部自动放行，风险极高，禁止日常使用；
• untrusted：不可信操作强制弹窗确认。

企业安全最佳实践

1. 使用 Dev Container 容器方案，Docker 作为外部隔离层，官方提供参考镜像；
2. OTel 遥测开启审计，关闭log_user_prompt，保护源码、密钥隐私；
3. 将.env密钥、配置文件加入黑名单，禁止 AI 读取；
4. WSL1 版本不再被支持，Windows 用户务必升级 WSL2；
5. 禁止随意使用 --dangerously‑bypass‑approvals‑and‑sandbox（yolo）参数，会跳过全部安全防护。

四、两大高阶功能：Automations 自动化 + Skills 技能模板

1、Automations 自动化，解放重复工作

分为两类自动化任务：

• 独立自动化 Standalone：全新独立运行任务，支持 Cron 定时表达式。适合跨项目周期性巡检，例如每周一扫描项目依赖漏洞。
• 线程自动化 Thread：心跳唤醒原有会话，保留全部上下文，适合持续跟踪同一个任务，比如盯 PR 合并状态、监控 CI 报错。

实操小技巧：自动化任务尽量跑在独立 Git Worktree，改动隔离开，避免搞乱正在编辑的代码。 你可以直接用自然语言下达指令： “每天早上 9 点，帮我扫描这个项目依赖更新，输出一份报告。”

自动化任务还可以直接调用 Skills 模板，复用成熟工作流。

2、Skills 技能，把团队最佳实践沉淀下来

Skills 本质就是可复用工作流模板，保存在项目.codex/skills或者用户全局目录。 团队可以把内部的代码审查标准、单元测试模板、重构规则封装成 Skill。 之后对话直接输入$skill‑name一键调用，不用每次写一大段长长的提示词，减少重复劳动。

MCP 插件系统

依托 MCP 协议，接入各类第三方工具。但即便开启全自动模式，带有破坏性、副作用的 MCP 工具调用，依旧会强制要求人工审批，防止自动执行危险操作。

五、SDK 二次集成，嵌入自有系统

1. Node.js/TypeScript SDK

npm install @openai/codex‑sdk

适合服务端开发，可以创建、恢复对话线程，把 Codex 能力集成到自研平台。

2. Python SDK 要求 Python3.10+，需要本地克隆开源仓库，可编辑模式安装，适合 Python 技术栈二次开发。
3. exec 非交互模式 适配 CI/CD 流水线脚本，无交互自动执行工程任务。

codex exec --task "运行测试并报告失败用例"

六、实用经验与避坑指南

✅提示词怎么写效果更好

1. 需求讲细讲具体，拒绝模糊笼统的描述；
2. 可以给正反案例，明确告诉 AI 什么允许做、什么不能做；
3. 复杂大任务，先让 AI 输出执行计划，人确认之后，再执行代码修改；
4. 明确输出格式要求，降低 AI 乱输出的概率。

✅工程工作流经验

1. 大任务拆分处理，不要一次性丢给 AI 一整个大型重构；
2. 并行改动优先 Git Worktree 隔离，防止代码互相污染；
3. 自动化生成的结果，必须人工复核，不能直接扔上生产；
4. 企业统一托管配置，给团队成员统一沙箱和审批规则。

七、故障快速排错

1. 优先执行codex doctor，一键诊断环境、Git、终端、线程问题；
2. 沙箱异常，使用codex sandbox macos / linux命令单独测试沙箱行为；
3. Docker 环境沙箱报错：使用--sandbox danger‑full‑access，依靠 Docker 容器隔离；
4. WSL1 直接升级 WSL2，旧版本已经停止支持。

附录：术语简表

表格

结语：Codex 不是简单代码生成工具，而是软件工程智能代理。它能干重构、批量写测试、巡检项目、定时做工程监控，大幅减少开发者的重复体力劳动。 但能力和风险是一体两面。沙箱权限、人工审批、Git 快照回滚，这三道防线不能偷懒。AI 输出的代码无论看起来多完美，都一定要人工审核，不能无脑直接上生产。

个人开发者可以用来处理重构、bug 修复、单元测试；团队可以沉淀 Skills 标准化流程，做周期性代码巡检；企业落地，一定要做好权限管控和行为审计。