Codex CLI 使用教程

Codex CLI 是 OpenAI 的终端 AI 编程助手，提供多种安装方式：

方法 1: 使用 npm (推荐)

npm install -g @openai/codex

方法 2: 下载二进制文件

验证安装：

codex --version

应显示 Codex CLI 的版本信息

Codex CLI 使用 TOML 格式的配置文件。创建或编辑以下文件：

配置文件路径：

%USERPROFILE%\.codex\config.toml

配置内容：

创建认证配置文件，禁用默认的 OpenAI API Key 认证：

认证文件路径：

%USERPROFILE%\.codex\auth.json

文件内容：

{
  "OPENAI_API_KEY": null
}

将 OPENAI_API_KEY 设置为 null，然后使用环境变量 CRS_OAI_KEY 进行认证

配置 API 密钥环境变量：

方法 1: 临时设置（当前会话）

$env:CRS_OAI_KEY = "你的API密钥"

set CRS_OAI_KEY=你的API密钥

方法 2: 永久设置（用户环境变量）

[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "你的API密钥", [System.EnvironmentVariableTarget]::User)

验证配置：

echo $env:CRS_OAI_KEY

启动 Codex CLI：

codex

常用功能：

• 对话模式： 与 AI 助手进行自然语言对话
• 代码生成： 请求 AI 生成或修改代码
• 文件操作： 读取、编辑项目文件
• 命令执行： 运行系统命令
• MCP 扩展： 连接自定义工具和服务
• 退出： 输入 /exit 或按 Ctrl+C

问题 1: 找不到 codex 命令

原因： npm 全局安装路径未添加到 PATH
解决： 确认 npm 全局路径并添加到系统 PATH

问题 2: 配置文件未生效

检查项：

• 配置文件路径是否正确（%USERPROFILE%\.codex\）
• TOML 语法是否正确（使用等号 =，字符串用引号）
• base_url 是否正确

问题 3: API 连接失败

检查项：

• 环境变量 CRS_OAI_KEY 是否正确设置
• API Key 格式是否正确（包含 cr_ 前缀）
• 网络连接是否正常
• 防火墙是否阻止连接

问题 4: 环境变量未生效

解决： 关闭所有 PowerShell/CMD 窗口，重新打开

Codex CLI 提供多种安装方式：

方法 1: 使用 Homebrew (推荐)

brew install codex

方法 2: 使用 npm

npm install -g @openai/codex

方法 3: 下载二进制文件

验证安装：

codex --version

创建或编辑 Codex 配置文件：

配置文件路径：

~/.codex/config.toml

配置内容：

创建认证配置文件：

认证文件路径：

~/.codex/auth.json

文件内容：

{
  "OPENAI_API_KEY": null
}

配置 API 密钥环境变量：

方法 1: 临时设置（当前会话）

export CRS_OAI_KEY="你的API密钥"

方法 2: 永久设置

添加到 shell 配置文件：

# 添加到 ~/.zshrc
echo 'export CRS_OAI_KEY="你的API密钥"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc

# 添加到 ~/.bash_profile
echo 'export CRS_OAI_KEY="你的API密钥"' >> ~/.bash_profile

# 重新加载配置
source ~/.bash_profile

验证配置：

echo $CRS_OAI_KEY

启动 Codex CLI：

codex

问题 1: 找不到 codex 命令

解决： 确认安装路径在 PATH 中，或使用绝对路径运行

问题 2: 环境变量未生效

解决： 运行 source ~/.zshrc 或 source ~/.bash_profile

问题 3: API 连接失败

检查项： API Key、base_url 配置、网络连接

Codex CLI 提供多种安装方式：

方法 1: 使用 npm

sudo npm install -g @openai/codex

方法 2: 下载二进制文件

验证安装：

codex --version

创建或编辑 Codex 配置文件：

配置文件路径：

~/.codex/config.toml

配置内容：

创建认证配置文件：

认证文件路径：

~/.codex/auth.json

文件内容：

{
  "OPENAI_API_KEY": null
}

配置 API 密钥环境变量：

方法 1: 临时设置（当前会话）

export CRS_OAI_KEY="你的API密钥"

方法 2: 永久设置

添加到 shell 配置文件：

# 添加到 ~/.bashrc
echo 'export CRS_OAI_KEY="你的API密钥"' >> ~/.bashrc

# 重新加载配置
source ~/.bashrc

# 添加到 ~/.zshrc
echo 'export CRS_OAI_KEY="你的API密钥"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc

验证配置：

echo $CRS_OAI_KEY

启动 Codex CLI：

codex

问题 1: 找不到 codex 命令

解决： 确认 npm 全局路径在 PATH 中，或使用 sudo npm install -g @openai/codex 重新安装

问题 2: 环境变量未生效

解决： 运行 source ~/.bashrc 或 source ~/.zshrc，或重新打开终端

问题 3: 权限错误

解决： 确保 ~/.codex/ 目录有正确的读写权限