信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。
云端的 Codex Cloud（Codex Web）已在Codex 云端任务与 ChatGPT：从需求到代码审查介绍，本篇聚焦本地使用：CLI、IDE 扩展与 ChatGPT 桌面应用中的本地模式。
1. 定位
【有据可查】OpenAI 的编程 Agent，本地客户端包括 Codex CLI、IDE 扩展、ChatGPT 桌面应用；共享 ~/.codex/config.toml 配置（CODEX_HOME 可改）。来源：Codex CLI、Advanced Configuration
2. 订阅方案结构（不列价格）
| 认证方式 | 计费来源 | 说明 | 层级 |
|---|---|---|---|
| Sign in with ChatGPT | ChatGPT 套餐（Plus/Pro/Business/Enterprise/Edu 等）内含 Codex 用量 | 不同套餐额度、可用模型、云端 VM 规格不同 | 有据可查：Codex CLI、Cloud environments |
| API Key | OpenAI API 账户按 token 计费 | 适合 CI/脚本 | 有据可查 |
自定义 provider / --oss |
你的网关或本地模型 | 见第 6 节 | 有据可查 |
具体额度与价格请看 OpenAI 官方定价页与帮助中心，变化频繁。
3. 安装与首次启动【有据可查】
npm install -g @openai/codex # 需要 Node.js
codex --version
cd 你的项目 && codex # 首次启动选择 "Sign in with ChatGPT" 或其它方式
来源：npm @openai/codex、Codex CLI 文档
首次配置三件事（实践建议）【社区共识】
- 在项目根运行
/init生成AGENTS.md，把"怎么跑测试、代码风格、禁区"写进去。 - 用
/permissions确认当前审批与沙箱。 - 用
/status看当前模型、账户与上下文。
4. 权限与安全模型：沙箱 × 审批【有据可查】
来源：Agent approvals & security、Advanced Configuration
| 维度 | 取值 | 含义 |
|---|---|---|
sandbox_mode |
read-only |
只读 |
workspace-write |
可写工作区，网络默认关闭（[sandbox_workspace_write] network_access = false） |
|
danger-full-access |
关闭沙箱，官方提示仅在环境本身已隔离时使用 | |
approval_policy |
on-request |
需要越出沙箱（如联网、写工作区外）时询问 |
never |
从不询问（适合非交互运行） | |
{ granular = {...} } |
按类别精细控制 | |
approvals_reviewer |
user / auto_review |
审批由你还是自动审查来做（不改变沙箱边界） |
⚠️ 【有据可查】approval_policy = "untrusted" 已退役，旧教程里的写法需迁移。
⚠️ 【有据可查】workspace-write 下某些环境会让 .git/ 与 .codex/ 保持只读，所以 git commit 可能仍需审批。
推荐组合（新手）：
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false # 自动剔除名字含 KEY/SECRET/TOKEN 的环境变量
【有据可查】ignore_default_excludes 默认是 true，即默认不会自动剔除含 KEY/SECRET/TOKEN 的变量；设为 false 才会剔除——这是很多人忽略的细节。
4.1 项目配置的安全边界【有据可查】
- 项目内
.codex/config.toml只在项目被信任时加载； - 且不能设置
openai_base_url、model_provider、model_providers、notify、profile等敏感键——防止恶意仓库把你的请求和凭据重定向到别处。
5. 常用命令与工作流【有据可查】
| 命令 | 作用 |
|---|---|
/init |
生成 AGENTS.md 脚手架 |
/model |
切换模型与推理强度 |
/permissions |
查看/调整权限 |
/status |
当前会话状态 |
/review |
审查当前改动 |
/resume |
恢复历史会话 |
/debug-config |
打印各配置层诊断，排查"为什么设置不生效" |
codex exec "任务"（codex e） |
非交互运行；--json 输出事件流 |
codex exec resume --last |
继续上一次非交互任务 |
codex resume |
恢复交互会话 |
codex --profile 名字 |
叠加 ~/.codex/名字.config.toml |
codex --config key=value |
单次覆盖任意配置（值按 TOML 解析） |
5.1 AGENTS.md 的加载规则【有据可查】
来源：Custom instructions with AGENTS.md
- 全局：
~/.codex/AGENTS.override.md优先，否则~/.codex/AGENTS.md； - 项目：从 Git 根目录一路走到当前目录，每层取一个文件（
AGENTS.override.md→AGENTS.md→ 备用名）； - 越靠近当前目录的越后拼接、优先级越高；总量默认上限 32 KiB（
project_doc_max_bytes）。
5.2 Profile 新写法【有据可查】
Codex 0.134.0 起，--profile 不再读取 config.toml 里的 [profiles.xxx]，改为独立文件 ~/.codex/xxx.config.toml（键写在顶层）。旧教程需迁移。
5.3 一个典型工作流
6. 接入自定义模型【有据可查】
# ~/.codex/config.toml（只能放用户级, 项目级会被忽略）
model = "你的模型ID"
model_provider = "mygw"
[model_providers.mygw]
name = "My Gateway"
base_url = "https://gateway.example.com/v1"
env_key = "MYGW_API_KEY"
wire_api = "responses" # 该网关需支持对应 API 形态
- 只想把内置 OpenAI provider 指向代理/数据驻留地址：用
openai_base_url，不要新建[model_providers.openai]（内置 IDopenai、ollama、lmstudio不可复用）。 - 本地模型：
codex --oss，配合oss_provider = "ollama"或"lmstudio"。 - 【待考察/推测】
wire_api可选值及第三方网关兼容性随版本变化，接入前用/debug-config与一条最小任务验证。
7. 常见报错
| 现象 | 可能原因 | 处理 | 层级 |
|---|---|---|---|
| 启动警告"忽略某些项目配置键" | 在项目 .codex/config.toml 里写了 provider 等敏感键 |
移到 ~/.codex/config.toml |
有据可查 |
--profile 不生效 |
仍用旧的 [profiles.x] 写法 |
迁移到 ~/.codex/x.config.toml |
有据可查 |
untrusted 报错/无效 |
该审批策略已退役 | 改为 on-request 等 |
有据可查 |
codex exec --oss 直接退出 |
未指定本地 provider | 设 oss_provider 或 --local-provider |
有据可查 |
git commit 总要审批 |
.git/ 在沙箱中只读 |
正常现象，或用 rules 调整 | 有据可查 |
| 401/403/429 | 见 API 报错速查：状态码、错误正文与重试 报错码对照表 | — | — |
8. 适合人群
- ✅ 已有 ChatGPT 付费订阅、想"一份订阅多处用"的人
- ✅ 重视"沙箱 + 审批"双层安全的开发者
- ✅ 需要 CI 自动化（
codex exec --json） - ⚠️ 所在地区不在 OpenAI 支持列表的用户：账号与合规风险高（见 AI 账号安全：登录态、密钥、授权与申诉）
9. 本篇无法核实/需谨慎的点
- 各套餐 Codex 额度与可用模型：未列出（变化快）。
wire_api当前全部可选值与第三方网关兼容情况。- IDE 扩展与桌面应用的个别设置差异未逐一核对。
小白练习：把本文流程逐项走通
练习目标：在练习项目中启动 Codex，并检查权限与改动。
上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。
-
先确认安装的是 CLI、IDE 扩展还是桌面应用。以下 npm 命令用于 CLI，桌面安装包按官方入口另行下载。
-
在终端分别运行 node --version 和 npm --version，随后执行安装命令，再单独运行 codex --version。
-
在文件管理器建立练习项目。用 cd 进入它，再运行 codex；原文中 cd 和启动写在同一行时，也可以分成两次执行。
-
完成登录后用状态入口确认当前认证方式和计费来源。用权限入口确认工作区范围及联网策略。
-
先发只读任务，再提出一个小改动。收到结果后查看 diff，自己打开文件，并运行项目已有测试。
-
修改 config.toml 前备份；只修改本次所需字段。profile 和审批策略按安装版本的官方文档核对，不混用不同版本的写法。