安装与基础配置
目标不是“把 Codex 装上”，而是建立一个可重复、可诊断、权限边界清楚的工作环境。本页以 CLI 为主；IDE 扩展和桌面端可沿用同一套账户、仓库规则与配置思路。
安装前检查#
| 项目 | 建议 |
|---|---|
| 操作系统 | macOS、Linux；Windows 优先参考官方当前支持说明 |
| Node.js | 使用仍在维护的 LTS 版本 |
| Git | 确认 git --version 正常，仓库身份已配置 |
| 工作目录 | 从一个有版本控制、可运行测试的小项目开始 |
| 敏感数据 | 不要把生产密钥直接放进提示词或仓库 |
安装 CLI：
npm install -g @openai/codex
codex --version
codex
首次启动会引导登录。组织账户、API 账户和可用模型可能受管理员策略影响；以终端中的实际提示与官方设置页为准。
先验证最小闭环#
不要一开始就在大型仓库执行重构。进入一个测试仓库，要求 Codex 只读分析：
阅读 README、package.json 和测试配置。
不要修改文件。告诉我：
1. 如何启动项目；
2. 如何运行最小测试；
3. 你还缺少什么信息。
如果它能正确说明仓库结构和验证命令，才进入修改任务。这样可以把“安装问题”“仓库问题”和“任务表达问题”分开。
配置文件放在哪里#
Codex 使用 TOML 配置。常见入口是用户级 ~/.codex/config.toml，也可结合项目规则和命令行参数覆盖。配置项会随版本演进，修改前先对照官方配置参考。
一个克制的起点：
# ~/.codex/config.toml
model = "gpt-5-codex"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
示例表达的是配置结构，不代表所有账户都能使用同一模型名。若 CLI 报未知字段或模型不可用，先删除自定义项回到默认值，再逐项恢复。
三层上下文要分清#
- 全局设置：模型、审批策略、沙箱、界面偏好。
- 仓库规则：通过
AGENTS.md固化测试、目录、代码风格与禁区。 - 当前任务：本次目标、范围、验收标准和交付格式。
把项目约定塞进每次提示词会重复，把临时需求写进 AGENTS.md 又会污染长期规则。三层分离后，任务才容易复用和审计。
权限模式怎么选#
| 场景 | 推荐起点 | 理由 |
|---|---|---|
| 阅读和解释代码 | 只读或最小权限 | 不需要写文件 |
| 日常仓库开发 | workspace-write + 按需审批 | 可修改工作区，外部动作需确认 |
| CI / 无交互任务 | 明确白名单和固定命令 | 避免流程等待审批或越权 |
| 含密钥或生产资源 | 隔离环境 + 人工审批 | 降低数据与外部副作用风险 |
不要为了少一次确认就长期放宽权限。正确做法是把必要命令、目录和网络访问缩小到任务所需范围。
常用启动检查#
codex --version
git status --short
pwd
进入 Codex 后，可使用官方命令查看状态、切换模式或检查配置。命令名称可能随版本变化，应以命令参考为准。
升级与回退#
升级前记录版本，升级后用一个小仓库复跑最小闭环。若行为变化：
- 运行
codex --version记录现场； - 临时移走自定义配置，排除旧字段；
- 检查
AGENTS.md是否存在冲突规则； - 用最小任务复现；
- 再查官方故障排查页或提交带版本信息的问题。
完成标准#
- CLI 能启动并登录；
- 能在测试仓库完成只读分析；
- 知道用户配置、仓库规则和任务提示的边界；
- 默认权限不超过任务所需；
- 出问题时能提供版本、命令、目录和完整报错。