Codex CLI 完全指南：第一章·安装与初始化

什么是 Codex CLI

Codex CLI 是 OpenAI 开源的终端 AI 编程助手，运行在本地命令行环境中。它能够理解你的代码仓库、执行 shell 命令、读写文件，并通过对话式交互完成从代码生成到项目部署的完整开发流程。整个工具用 Go 语言编写，以单个二进制文件分发，安装极简。

与 GitHub Copilot 这类侧边栏补全工具不同，Codex 是一个全功能 AI 代理——它能主动浏览文件、搜索代码、执行命令、创建 PR，甚至是自行安装依赖。你只需用自然语言描述需求，它就会像一位高级工程师一样理解上下文并付诸行动。

系统要求

操作系统：macOS、Linux、Windows（通过 WSL2）
架构：x86_64 或 ARM64
最低配置：1GB 可用内存，200MB 磁盘空间
网络：需要访问 api.openai.com（或你配置的模型提供商 API）
推荐工具：Git（版本控制）、Docker（沙箱模式）

安装方式

方式一：一键脚本安装（推荐）

打开终端，执行以下命令：

# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

脚本会自动检测操作系统和架构，下载对应版本并安装到 /usr/local/bin/codex，最后将其添加到 PATH。安装完成后关闭终端重开，或执行：

source ~/.bashrc   # 或 source ~/.zshrc

验证安装：

codex --version

如果输出版本号，说明安装成功。

方式二：Homebrew 安装

macOS 用户也可以通过 Homebrew 安装：

brew install opencodeai/homebrew-codex/codex

Homebrew 会处理依赖和版本更新，更适合习惯用包管理器的 macOS 开发者。

方式三：npm 安装

如果你已经有 Node.js 环境，npm 是最快的全局安装方式：

npm install -g @opencode-ai/codex

安装后 codex 命令同样可用。

方式四：手动下载

从 GitHub Releases 页面下载对应架构的二进制文件：

访问 github.com/anomalyco/codex/releases

下载对应平台的 tar.gz 包

解压后将 codex 二进制移动到 PATH 目录

tar -xzf codex_linux_amd64.tar.gz
sudo mv codex /usr/local/bin/
sudo chmod +x /usr/local/bin/codex

方式五：从源码编译

适合想要尝鲜最新特性或参与贡献的开发者：

git clone https://github.com/anomalyco/codex.git
cd codex
go build -o codex ./cmd/codex
sudo mv codex /usr/local/bin/

需要 Go 1.21+ 环境。

认证与登录

OpenAI 平台认证

Codex CLI 默认使用 OpenAI API，你需要一个 API Key。获取步骤：

进入 API Keys 页面，点击 "Create new secret key"

复制生成的密钥（注意：密钥只显示一次）

配置 API Key 有三种方式：

环境变量（推荐）：

export OPENAI_API_KEY="sk-your-api-key-here"

建议将这一行写入 shell 配置文件：

echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc

通过 codex login 命令：

codex login

这个命令会启动浏览器 OAuth 流程，或者直接在终端中提示你粘贴 API Key。OAuth 是最简单的方式——它会自动创建 API Key 并注入环境。

通过配置文件（不推荐，有泄露风险）：

# codex.yaml 中
openai:
  api_key: "sk-..."

Chat Pro 订阅者

如果你订阅了 ChatGPT Pro（$200/月），可以直接使用 Chat 账号登录：

codex login --pro

这会使用你的 ChatGPT 订阅凭证，享受无速率限制的 GPT-4 访问。

验证认证状态

运行以下命令确认认证成功：

codex --help

如果命令能正常运行并显示帮助信息，认证已通过。你也可以直接试用：

codex "hello, what model are you using?"

初始化项目

进入你的项目目录，初始化 Codex 配置：

cd /path/to/your/project
codex init

这个命令会在项目根目录生成 codex.yaml 配置文件，你可以根据项目需要定制 AI 行为规则、忽略规则和模型参数。

初始化后，目录结构大致如下：

my-project/
├── codex.yaml          # Codex 配置文件
├── AGENTS.md           # AI 行为指南（可选，手动创建）
└── ...

第一次对话

直接在终端中输入：

codex "请解释这个项目的结构和主要技术栈"

Codex 会扫描当前目录的文件，理解项目结构，然后给出分析和建议。这是验证安装是否完整的最快方式。

更新

保持 Codex 最新以获取新功能和修复：

脚本安装用户：

codex update

Homebrew 用户：

brew upgrade codex

npm 用户：

npm update -g @opencode-ai/codex

故障排查

命令找不到

如果终端提示 codex: command not found，检查 PATH：

which codex                # 查找安装位置
echo $PATH | tr ':' '\n'  # 查看 PATH 包含哪些目录
export PATH="$PATH:/usr/local/bin"  # 手动添加

API Key 无效

常见原因：

Key 已过期或被撤销——去 OpenAI 控制台新建一个
账户余额不足——检查 platform.openai.com/usage
网络代理拦截——确保能访问 api.openai.com

curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

返回模型列表表示 Key 和网络均正常。

连接超时

如果下载或 API 调用超时，检查是否需要配置代理：

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
codex "hello"

Windows WSL 注意事项

WSL2 下安装与 Linux 一致，但需要确保：

Git 在 WSL 内已配置（不要用 Windows 宿主机的 Git）
项目文件存放在 WSL 文件系统（/home/...）而非 /mnt/c/...，否则文件监听和权限可能出问题
Docker Desktop 已开启 WSL2 集成（如需沙箱模式）

下一步

安装完成后，建议依次阅读：

第二章·配置体系深度解析：了解 codex.yaml 和 AGENTS.md 的完整配置能力
第三章·模型提供商配置：切换到 Claude、Gemini 或本地模型
第四章·命令执行体系：掌握 exec 命令和执行策略

至此，Codex CLI 已就绪。输入 codex 开始你的 AI 编程之旅。