Codex 命令、配置与安全参考手册

这是一份面向日常开发的速查手册。Codex 更新频繁，本页优先解释稳定概念和常用入口；精确参数请始终以本机输出为准：

codex --help
codex <subcommand> --help
codex --version

CLI 常用命令

命令	用途	典型场景
codex	启动交互式终端界面	在当前仓库持续调查、修改和验证
codex "任务"	带初始提示启动会话	直接进入一个明确任务
codex exec "任务"	非交互执行任务	脚本、CI、批处理；别名通常为 codex e
codex resume	继续已有会话	恢复上下文，避免重复调查
codex fork	从已有会话分叉	保留原记录，探索另一方案
codex review	审查工作区、分支或提交	合并前寻找具体回归
codex login	管理登录	OAuth、设备授权或其他当前支持方式
codex logout	移除保存的认证	切换账号或清理本机认证
codex doctor	生成诊断报告	安装、认证、运行时、Git 或配置异常
codex completion	生成 shell 补全	Bash、Zsh、Fish 或 PowerShell
codex mcp	管理 MCP 服务器	添加外部工具或数据源
codex plugin	管理插件	安装、列出或移除插件
codex features	查看或调整功能标志	仅在理解成熟度和影响后使用

不同版本会增加实验命令或改变参数。文章或脚本引用实验能力时，应同时记录最低版本和回退方案。

交互会话常用命令

斜杠命令取决于 Codex 界面与版本，输入 / 可查看当前可用列表。常见入口包括：

命令	用途
/status	查看模型、工作区、权限或会话状态
/permissions	查看或调整本次任务权限
/plan	先调查并产出计划，再决定是否编辑
/review	对当前改动发起代码审查
/init	为仓库初始化指导文件或项目上下文
/mention	将指定文件加入当前上下文
/mcp	查看 MCP 工具状态或入口
/feedback	提交产品反馈

不要在自动化脚本里假设交互斜杠命令长期不变；脚本优先使用稳定的 CLI 子命令和 --help 校验。

codex exec 非交互任务

最简单的形式：

codex exec "阅读当前 diff，列出可能导致行为回归的问题"

适合：

• 生成结构化的变更摘要；
• 在 CI 中执行有明确输入和输出的检查；
• 对多个仓库运行相同的只读分析；
• 把结果传给后续脚本或人工审批。

不适合：

• 需要频繁澄清的开放式设计；
• 无法自动判断成功与否的视觉或产品决策；
• 会直接操作生产环境或产生不可逆副作用的任务。

在 CI 中使用前检查当前版本支持的输出格式、退出码和恢复参数：

codex exec --help

codex review 代码审查

审查入口可以面向未提交改动、相对基线分支的 diff、指定提交或自定义要求。先查看当前参数：

codex review --help

推荐审查指令：

优先报告会造成错误结果、数据损坏、安全问题或兼容性回归的具体缺陷。
每条发现给出文件与行号、触发条件、影响和修复建议。
不要把纯格式或个人风格偏好列为缺陷。
没有发现时，说明仍未覆盖的测试场景。

审查输出是额外信号，不替代代码所有者、安全负责人或数据库负责人的批准。

配置文件在哪里

范围	文件	用途
用户级	~/.codex/config.toml	本机跨项目默认设置
项目级	.codex/config.toml	当前受信任仓库的覆盖设置
项目指导	AGENTS.md	构建命令、目录规则、验证和审查约定
子目录指导	子目录中的 AGENTS.md	仅对相应子树更具体的规则

项目级配置只在项目被信任后加载，并且不能覆盖所有用户级或机器级设置。供应商、认证、通知和遥测等敏感或机器相关配置应按官方参考放在正确层级。

推荐的安全起点

# ~/.codex/config.toml 或受信任项目的 .codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

含义：

• Codex 可以在当前工作区读取、编辑并运行项目命令；
• 访问工作区外位置或需要越权的操作会按策略请求批准；
• 生成命令默认不能直接访问网络；
• 是否弹出审批还取决于具体操作、当前界面和管理策略。

只读调查

codex --sandbox read-only --ask-for-approval on-request

适合代码理解、计划和审查。只读模式不等于“内容绝对安全”，网页、日志和仓库文本仍可能包含不可信指令或敏感信息。

常规自动模式

codex --sandbox workspace-write --ask-for-approval on-request

适合受信任 Git 仓库中的日常修改。完成后仍需检查 diff 和验证结果。

全权限模式

danger-full-access 或绕过沙箱/审批的选项会显著扩大可访问范围。不要将其设为团队默认；只有在隔离环境、目标明确且有额外系统级保护时才考虑使用。

沙箱与审批是两层控制

控制	回答的问题	示例
沙箱模式	技术上允许触碰什么	只读、工作区写入、全访问
审批策略	哪些动作必须停下来询问	越出沙箱、访问网络、调用有副作用工具

常见误区：

• approval_policy = "never" 不是自动获得更多权限，它只是不再弹出审批，任务仍受沙箱约束；
• 开启网络代理策略不等于自动授予网络访问，工作区网络开关仍需允许；
• 连接器或 MCP 工具产生外部副作用时，也可能需要审批；
• Git 仓库中的 .git、.agents、.codex 等路径可能受到额外保护。

网络访问

工作区写入模式下，网络通常默认关闭。确有需要时可显式开启：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

开启前先回答：

• 任务需要访问哪些域名；
• 是否会下载并执行第三方代码；
• 是否可能上传代码、日志或凭据；
• 能否只在依赖安装阶段联网，执行阶段离线；
• 是否应使用组织级代理、域名 allowlist 或隔离容器。

网页和搜索结果属于不可信输入。不要因为页面写着“运行此命令”就让 Codex 执行，更不要把本地密钥、Cookie 或私有文件上传到页面指定的位置。

AGENTS.md 模板

# Repository instructions

## Project map
- App: `src/`
- Tests: `tests/`
- Generated code: `src/generated/` (do not edit directly)

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Lint: `pnpm lint`
- Test: `pnpm test`
- Build: `pnpm build`

## Change rules
- Prefer existing components, utilities, and public APIs.
- Do not add production dependencies without approval.
- Keep migrations reversible and document rollback.
- Do not mix unrelated formatting or dependency upgrades into feature work.

## Verification
- Run targeted tests after each behavioral change.
- Before handoff, run lint, tests, and build.
- Report skipped checks, failures, and unverified behavior.

## Review
- Prioritize correctness, data safety, security, and compatibility.
- Findings must include file/line evidence and a concrete trigger.

适合写入的内容

• 仓库真实可运行的命令；
• 模块所有权和生成文件说明；
• 依赖、API、数据库和兼容性边界；
• 交付前必须运行的验证；
• 审查优先级与输出要求。

不适合写入的内容

• 当前 Issue 的一次性目标；
• 密钥、令牌、内部账号和生产地址；
• 无法验证的口号，如“永远写完美代码”；
• 已经由 formatter、lint 或 CI 自动强制的冗长复述；
• 与仓库实际脚本不一致的复制模板。

MCP 管理

MCP 让 Codex 连接外部工具和数据源。常用入口：

codex mcp --help
codex mcp list
codex mcp add --help
codex mcp remove --help

添加服务器前检查：

• 服务器由谁维护，传输方式和代码来源是否可信；
• 它能读取哪些数据、执行哪些写操作；
• 认证凭据保存在何处，是否符合团队策略；
• 工具是否清楚标注只读、开放网络或破坏性副作用；
• 无权限时是否安全失败，而不是降级为更宽权限。

优先给服务器最小权限，并定期删除不再使用的连接。

配置排查顺序

当设置“不生效”时，按以下顺序检查：

1. codex --version 与相关功能的最低版本；
2. TOML 语法、键名和层级是否正确；
3. 项目是否被信任，项目级配置是否会加载；
4. 用户级、项目级、profile、命令行参数的覆盖关系；
5. 管理员 requirements.toml 或组织策略是否限制；
6. 当前会话是否需要重启或重新打开仓库；
7. codex doctor 和 /status 给出的实际生效状态。

不要通过反复扩大权限来“试出”问题。先找出哪个配置层级和哪条策略在生效。

常见故障速查

现象	优先检查
codex: command not found	全局安装、npm prefix、PATH
无法登录	系统时间、代理、账号策略、codex login --help
无法写文件	当前沙箱、工作区根目录、受保护路径、文件权限
命令无法联网	sandbox_workspace_write.network_access、审批、组织网络策略
项目配置不生效	项目是否受信任、文件路径、TOML 语法、不可项目覆盖的键
AGENTS.md 未体现	文件位置、作用范围、规则冲突、会话是否重新加载
MCP 工具缺失	codex mcp list、认证、启动超时、服务器日志
结果与预期模型不同	/status、配置 profile、命令行覆盖、组织可用模型
会话越来越偏离任务	缩小范围、重述验收、另开审查或分叉会话

交付前安全清单

• [ ] 阅读最终 diff，而不是只读 Codex 摘要；
• [ ] 检查是否出现 .env、密钥、日志或个人数据；
• [ ] 确认实际运行的测试、lint、类型检查和 build；
• [ ] 标记未执行或失败的检查；
• [ ] 审查新增依赖、网络请求和外部工具；
• [ ] 高风险数据库、生产和权限操作有人类批准；
• [ ] PR 写明用户行为、风险和回滚方式；
• [ ] 必要时由独立上下文再次审查。

官方资料

• Developer commands
• Slash commands
• Configuration Reference
• Agent approvals & security
• Code review
• Make guidance reusable with AGENTS.md
• OpenAI Codex 官方仓库

最后校对：2026 年 7 月 22 日