第 01 章

安装与首次运行

从安装脚本到第一次对话——迈出终端 AI 代理的第一步

装好只需一条命令，跑起来只要一秒钟

装了却不知道干嘛

你刚装上 Codex CLI，却不知道下一步该做什么

装完不知咋用

你在网上刷到 Codex CLI，兴冲冲装好了。终端里输入 codex，弹出一堆提示——要模型、要 key、要搞清楚 MCP 和 Skills。你只想让它帮你改个 bug。

第一印象卡住

你对着私钥认证、配置文件、沙盒机制一头雾水。Codex 在等你输入指令，你却不知道说什么。怎么暂停？怎么退出？不小心关了终端怎么办？

不知道能干什么

你只当它是个命令行 ChatGPT。不知道它支持 IDE 集成、附图分析、会话恢复、Sub-agents。你只用了 1%。

本章目标很单纯：先装好 → 跑起来 → 完成第一次对话 → 懂得恢复 → IDE 装上。其余的先不管。
不聊 Skills、不聊 MCP、不聊复杂配置——那些留给后续章节。

开始之前

适合谁

已经听过 Codex CLI，但还没跑过第一次对话的人
对命令行不太熟悉，但想用 AI 辅助编码的开发者
用过 Claude Code 等替代品，想迁移到 Codex CLI 的人

你将学会

用 4 种方式之一安装 Codex CLI
启动交互式 REPL 并完成第一次对话
理解常用快捷键与恢复会话
在你的 IDE 里集成 Codex CLI

本章暂不覆盖

Skills（第 03 章）：可复用的任务指令
MCP（第 06 章）：工具扩展
沙箱与权限（第 09 章）：安全边界

安装方式概览

四种途径，选一种即可

方式	适用平台	命令 / 链接	推荐场景
独立安装脚本	macOS / Linux / Windows	`curl` 或 `powershell` 一行命令	大多数用户的首选
Homebrew	macOS / Linux	`brew install --cask codex`	已使用 Homebrew 管理包的用户
npm	全平台（需 Node.js）	`npm install -g @openai/codex`	Node.js 开发者；偏好 unified 包管理
GitHub Releases	macOS / Linux	下载预编译二进制	企业环境；需要离线安装或固定版本

说明：安装脚本会把二进制放到 ~/.local/bin（macOS/Linux）或自动配置 PATH（Windows）。安装完成后请确认 codex 命令可用。

独立安装脚本（推荐）

一行命令完成安装，自动处理依赖与 PATH

macOS / Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh

脚本会下载预编译 Rust 二进制并将其安装到 ~/.local/bin/codex。

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

临时绕过执行策略，从远程拉取 .ps1 安装脚本并执行。

注意：从远程 URL 下载并直接执行脚本存在信任风险。安装前建议打开链接预览脚本内容，确认来源可信再执行。

包管理器安装

Homebrew 与 npm 两种方案

Homebrew（macOS / Linux）

brew install --cask codex

适合已经用 Homebrew 管理软件包的用户。用 --cask 标志安装预构建应用包，而非从源码编译。

npm（全平台）

npm install -g @openai/codex

需要 Node.js 环境。-g 全局安装后，codex 命令对当前用户全局可用。

验证安装：安装完成后，重新打开终端并运行 codex --version。能看到版本号即表示安装成功。

GitHub Releases 二进制

手动下载预编译二进制适用于特殊场景

支持的架构

macOS arm64（Apple Silicon：M1/M2/M3/M4）
macOS x86_64（Intel Mac）
Linux x86_64（主流服务器与桌面）
Linux arm64（ARM 服务器与树莓派）

下载与安装

访问 GitHub 仓库的 Releases 页面
下载对应平台的 .tar.gz 或 .zip
解压后将二进制放入 PATH 中的目录

# 示例：Linux x86_64
tar xzf codex-x86_64-unknown-linux-gnu.tar.gz
sudo mv codex /usr/local/bin/

适用场景：企业内网、无外网访问环境、需要精确控制版本，或 CI/CD 集成。普通用户优先选择安装脚本。

首次运行

直接输入 `codex`，启动交互式 REPL

最简单的启动

$ codex

不带任何参数启动交互式 TUI（终端用户界面）。Codex 会提示你选择模型并等待输入。

指定模型

$ codex -m gpt-5.6-terra

-m 或 --model 跳过模型选择，直接以指定模型启动。适合你已经明确要用的模型。

带图启动

$ codex -i screenshot.png
$ codex -i img1.png,img2.png

启动时附图。支持多张图片、逗号分隔。适合让 Codex 看 UI 截图或错误提示。

选哪个模型

GPT-5.6 家族：Sol / Terra / Luna 三层怎么选

模型	定位	何时用	价格（每 1M tokens 输入/输出）
`gpt-5.6-sol`	旗舰（`gpt-5.6` 别名指向它）	复杂重构、架构设计、深度调试、长任务 Agent	$5 / $30
`gpt-5.6-terra`	平衡型（日常默认）	日常开发、代码审查、测试、多 Agent 工作流	$2.50 / $15
`gpt-5.6-luna`	高吞吐低成本	分类、提取、批量摘要、简单改动	$1 / $6

上下文窗口：三层共享 1,050,000 tokens（1.05M），最大输出 128K——能一次吞下整个中型项目，长任务也不易断片。

怎么选：不确定就先上 gpt-5.6-terra——性能接近旗舰、价格只有 Sol 的一半；遇到硬骨头（大型迁移、安全审查）再切 -m gpt-5.6-sol；批量跑简单任务用 luna 省钱。

预判解惑：如果你 -m 指定了一个不存在的模型名，Codex 会直接报错而不是悄悄降级。确认模型名拼写无误（注意是 sol 不是 pro，terra 不是 mini）。

代码在哪跑

理解"控制面"与"执行面"的分离——Codex 最关键的一个架构概念

先建立一个心智模型：Codex 其实分两层。控制面（agent 的大脑）负责理解你的指令、规划步骤、决定调用哪些工具；执行面（Code Mode host）负责真正读写文件、跑命令、执行测试。默认情况下这两层叠在你的本地机器上，但它们可以被拆开。

默认：两层都在本地

你敲 codex，控制面和执行面一起在你这台机器上跑。Codex 直接读写本地文件、在本地 shell 执行命令。适合绝大多数日常开发——简单、零配置。

可选：执行面搬到远程

本地只留控制面（thin-client），把"跑代码"这件事托管给一台远程 host。从 0.146.0 起，只需一个标志：

codex --code-mode-host wss://my-build-server:8080

App Server 会经 WebSocket 长连接到这台远程 host，所有文件操作和命令都在那边执行，结果再传回本地界面。

三个"远程"别搞混	是谁在跑代码	典型场景
Code Mode 远程（本页）	你自己的一台服务器 / 云主机	本地算力不足、跑长任务、想合上笔记本让它继续跑
Codex Cloud	OpenAI 的云端容器	把整个任务丢给 OpenAI，它开个隔离沙盒跑完直接给你提 PR
Codex Remote	你的 Mac / Windows 主机	手机扫 QR 配对，在路上用手机监控、审批家里电脑上的任务

关键区别：Code Mode 远程 = "我的另一台机器帮我跑"；Codex Cloud = "OpenAI 帮我跑"；Codex Remote = "我用手机管我电脑上跑的任务"。三者完全不同，初学者最常把前两个搞混。

起步建议：新手先用本地模式跑通全流程。等你真正遇到"这台机器扛不住 / 要合盖走人 / 需要 GPU"的场景，再按第 05 章配置 Code Mode 远程。

参数	作用	示例
`-m <model>`	指定模型（如 `gpt-5.6-terra`、`gpt-5.6-sol`）	`codex -m gpt-5.6-terra`
`-i <file>`	附图（多张用逗号分隔）	`codex -i design.png`
`-p <profile>`	选择配置 Profile	`codex -p work`
`-s <sandbox>`	选择沙箱模式	`codex -s readonly`

认证方式

三种模型提供方，选一种即可

方式	适合谁	如何配置
ChatGPT 设备码登录	ChatGPT Plus / Pro / Business 订阅用户	`codex login`，浏览器授权即可
OpenAI API Key	按量计费、用 OpenAI 官方模型的开发者	设置 `OPENAI_API_KEY` 环境变量
DeepSeek API	追求低成本、国内网络顺畅的开发者	一键脚本配置，推荐 `deepseek-v4-flash`

没有 ChatGPT 订阅？觉得 OpenAI 官方 API 偏贵？推荐第三种——用 DeepSeek。deepseek-v4-flash 是目前接入 Codex 最便宜好用的模型，下一页手把手配置。

接入 DeepSeek（性价比之选）

用 `deepseek-v4-flash`，上下文 1M、价格远低于官方

第一步：获取 API Key

前往 DeepSeek 开放平台创建一个以 sk- 开头的 API Key，复制备用。

第二步：一键配置脚本（推荐）

# macOS / Linux
bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh)

# Windows (PowerShell)
irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

脚本会自动备份旧配置、写入 ~/.codex/models.json 与 config.toml，并提示你粘贴 API Key。前提：已至少启动过一次 Codex（即 ~/.codex 目录已存在）。

为什么推荐 deepseek-v4-flash：它是目前 DeepSeek 唯一支持接入 Codex 的模型，上下文窗口高达 1M tokens，价格远低于 OpenAI 官方模型，国内网络访问也更顺畅。deepseek-v4-pro 预计 2026 年 8 月初也会支持接入。

手动配置：不想用脚本，也可手动编辑 ~/.codex/config.toml 新增 [model_providers.deepseek] 段，并写入 models.json 声明模型元数据。脚本写入的内容与此一致，详见 DeepSeek 官方文档。

Responses API 是什么

Codex 与模型对话用的是"新协议"，而非传统 Chat 接口

对比项	Chat Completions（传统）	Responses API（Codex 用）
定位	普通对话补全	为 Agent / 编程助手原生设计
内置工具	仅 function call	原生支持 `web_search`、`apply_patch` 等
推理能力	无原生思维链字段	`reasoning` 字段控制思考深度（low / high / max）
流式格式	以 `data: [DONE]` 结尾	语义化事件序列，无 `[DONE]`
上下文管理	每次自行拼接历史	支持思维链、工具调用结果的结构化传递

你无需手写 Responses API。DeepSeek 的 base_url（https://api.deepseek.com）原生兼容该格式，Codex 会自动用它的协议来调用——你只管配好 Key 和模型，剩下的交给 Codex。

基本操控

掌握三个快捷键，从容控制 Codex

操作	效果	使用场景
`Esc`	暂停当前操作（中断思考或执行）	Codex 走神了、方向不对、想改 prompt
`Ctrl + D`	优雅退出，保存会话	做完工作、关闭终端前
`/exit` 或 `/quit`	命令退出	`Esc` 已占用时用命令退出

会话自动保存：即使你直接关闭终端（未退出），Codex 也会自动保存当前会话状态。下次用 codex resume 即可恢复。

恢复会话

不会丢失对话——三种恢复方式

CLI：`codex resume`

# 列出历史会话，按提示选择
$ codex resume

# 直接恢复最近一次会话
$ codex resume --last

在终端直接调用。支持 --last 恢复最新会话，--all 显示全部。

TUI 内：`/resume`

# 在已运行的 Codex 会话内
/resume

启动后在提示符下输入 /resume，弹出会话列表选择器。

指定会话 ID

# 恢复指定 UUID 的会话
$ codex resume <thread-id>

# 也可传 prompt 作为恢复后的首个输入
$ codex resume <thread-id> -p "继续上次的任务"

适合明确知道要回到哪次对话。thread-id 是会话的唯一标识。

IDE 集成

让终端与编辑器无缝衔接

主流编辑器支持

编辑器	扩展名 / 方式
VS Code	扩展 "Codex"
Cursor	原生支持
Windsurf	原生支持
JetBrains	插件 "Codex"

`/ide` 命令

# 查看 IDE 集成状态
/ide status

# 启用 / 关闭 IDE 上下文
/ide on
/ide off

IDE 上下文包括：当前选中的代码、打开的文件、光标位置。开启后 Codex 能自动看到你正在编辑的内容。

为什么装 IDE 扩展：不装扩展的话，TUI 里看不到你编辑器里装了什么；装了扩展之后，/ide 会自动抓取编辑器上下文——省去复制粘贴。

常见错误

装好后最常遇到的三类问题

`command not found: codex`

原因：安装目录不在 $PATH 中。独立安装脚本默认输出到 ~/.local/bin，npm 全局目录可能未被系统识别。

修复：

# 确认 codex 在哪里
$ which codex
# 若为空，则手动加入 PATH
$ export PATH="$HOME/.local/bin:$PATH"      # 独立脚本安装
$ export PATH="$(npm bin -g):$PATH"          # npm 安装

API Key 无效

原因：Key 未设置、已过期，或账号没有对应模型的访问权限。用 DeepSeek 时，Key 必须是以 sk- 开头的 DeepSeek Key（非 OpenAI Key）。