安装、配置与环境准备

01四个入口总览

02桌面端安装与第一次上手

macOS 安装

1. 点击「Download for macOS」下载 .dmg 安装包；
2. 打开下载好的 .dmg 文件；
3. 把 Codex 图标拖进「Applications（应用程序）」文件夹；
4. 首次启动若弹出「无法验证开发者」——打开「系统设置 → 隐私与安全性」，点「仍要打开」即可（正常现象，不是病毒）。

Windows 安装

1. 在下载页点「Download for Windows」；
2. 运行安装程序，按提示完成安装；
3. 打开应用，用 ChatGPT / OpenAI 账号登录。

安装后验证

登录成功后，左侧栏出现 Projects 和 Chats 两个入口，顶部显示当前账号信息 → 安装成功。

选择项目目录

第一次打开、登录完成后，系统会让你选一个项目目录——也就是 Codex 要进入哪个文件夹工作。新手建议先选一个干净的练习目录，不要直接选 C 盘，也不要一上来就选重要工作项目。

AI-Codex-Projects
└── hello-codex
    └── index.html

选择项目目录后，Codex 才知道该读哪些文件、改哪些文件、在哪里运行命令。

02·b第一次打开后的推荐流程（8 步）

别一上来就丢大任务。把下面 8 步当成"开机自检"，跑通一遍你就理解了 Codex 的基本循环：

1. 登录 ChatGPT：合并后默认用 ChatGPT 账号即可，全球套餐（含 Free）可用。
2. 选一个练习目录：如 AI-Codex-Projects/hello-codex，不要直接选 C 盘或重要工作项目。
3. 新建或选一个 thread：一个清楚的任务开一个 thread。
4. 在任务窗口输入一个简单任务：先别写复杂需求。
5. 等 Codex 修改文件：它会读文件、改代码、跑命令。
6. 打开 Review Pane：看它实际改了什么。
7. 查看 diff：绿=新增、红=删除，确认无误。
8. 没问题再继续修改：满意后让它接着做，或你自己 commit。

请帮我做一个简单的网页，要求：
1. 浅色背景
2. 页面中间显示文字 Hello, Codex
3. 字体清晰
4. 页面整体水平和垂直居中
5. 只使用 HTML 和 CSS

这个任务足够简单，适合用来熟悉 Codex App 的基本流程。

03必须记住的核心概念

03·b看懂 Diff：每次任务后必看

Diff 就是代码改动对照。可以这样记：绿色 = 新增内容，红色 = 删除内容。比如 Codex 原来没有写标题，后来加了一句 <h1>Hello, Codex</h1>，这一行就会显示为新增；如果它删掉了一段旧代码，那段就显示为删除。

04Sandbox 沙盒与权限控制

Codex 不是普通聊天工具，它能读文件、改文件、运行命令，所以必须有一个"围栏"限制它能碰哪里。你可以把 Sandbox 理解成：Codex 可以在围栏里干活，但不能随便跑到围栏外乱动你的电脑。

界面上通常对应三类权限选项：

05GPT-5.6 模型与推理强度

合并后统一到 GPT-5.6 家族，跨 ChatGPT Work、桌面应用、Codex CLI 与 IDE 扩展提供三档推荐模型：

推理强度（4 档）

普通任务用默认推荐模型即可；复杂任务再考虑切更强模型或提高推理强度。

引导 / 中途插入对话

当 Codex 正在执行任务时，如果你发现它理解错了，不应该让它继续跑，这时就该及时插入对话、纠正方向。如果不主动引导，它会排队执行——只有跑完上一个任务，才会执行你发的下一个任务。简单说：AI 跑偏了，立刻拦。

计划模式

开启计划模式后，Codex 不会立刻动手，而是先整理出一份工作计划，跟你确认后再开始。对于所有复杂任务，建议都先开计划模式，可以查漏补缺，避免它一上来就改错地方。

06Codex CLI 安装与常用命令

CLI 适合愿意打开终端的人。先确认已装 Node.js：

node -v
npm -v
npm install -g @openai/codex
codex --version

brew install --cask codex
codex

Windows 建议用 PowerShell / Windows Terminal，先装 Node.js 再安装。CLI 命令分两类：终端命令（在 PowerShell/Terminal 里输入）和斜杠命令（进入 Codex 后输入）。

两种登录方式：ChatGPT 账号 vs API Key

新手优先用 ChatGPT 账号登录：在终端输 codex 或 codex login → 选 Sign in with ChatGPT → 浏览器自动打开登录页 → 登录成功后结果传回终端，CLI 即可使用。API Key 登录更适合自动化脚本、CI/CD、服务器任务。

完整 CLI 命令表

# 先走到项目里，再启动
cd D:\AI-Codex-Projects\hello-codex
codex

# 不想先 cd，也可以直接指定目录
codex -C ./hello-codex

注释 / Annotations

在多功能区（右侧）的注释功能：当用 Codex 内置浏览器打开网页后，可以圈选局部、让 AI 只修改网页的具体部分——这就是合并后的 Annotations 批注能力，适合"指哪改哪"的精细调整。

不要在 C:\ 根目录、系统目录或重要项目里直接运行 Codex。

07IDE 扩展与 Codex Web

IDE 扩展：在编辑器里直接调用 Codex，把 AI 能力嵌进日常编码流，Skills 与项目规则可在 CLI / IDE / 桌面端之间复用。

Codex Web：入口 chatgpt.com/codex，适合不想一直占用本地电脑、需要远程跑任务的人。基本流程：把代码推到 GitHub → 打开 Codex Web 选仓库 → 配置 Environment（用什么语言、怎么装依赖、怎么启动）→ 下发任务 → 完成后 review 并合并 PR。

08新手安全建议清单

• 每个项目先 git init，改坏能回退。
• 沙盒选"请求批准"，别一上来开完全访问。
• 复杂任务先开计划模式，确认后再动手。
• 先用简单仓库 / 干净目录练手。
• PR 里一定看 diff，看不懂的改动不要合并，满意后再 merge。

09进阶：连接第三方 API（按需，非入门必需）

三种接入方案怎么选：

手动配置：先备份再改

cp ~/.codex/config.toml ~/.codex/config.toml.backup
cp ~/.codex/auth.json ~/.codex/auth.json.backup

model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.ciyuan]
name = "ciyuan"
base_url = "https://ciyuan.today/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = false

export OPENAI_API_KEY="这里填你的key"
open -a Codex   # 先彻底关闭 Codex 再启动

验证时用只读任务确认配置生效：

请只读说明当前工作区路径、你准备使用的模型和验证方式。不要修改任何文件。

CCX + CC Switch（多供应商切换）

docker run -d \
  --name ccx \
  -p 3000:3000 \
  -e PROXY_ACCESS_KEY=your-proxy-access-key \
  -e APP_UI_LANGUAGE=zh-CN \
  -v $(pwd)/.config:/app/.config \
  crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest

npm install -g cc-switch
cc-switch init
cc-switch use <配置名>