Skip to main content
Codex 可以在 macOS 上通过 npm 安装。你可以把 Codex CLI 指向 AIOAGI 的 OpenAI 兼容接口，再使用 AIOAGI API Key 调用平台支持的代码模型。
Codex 版本、VS Code 扩展界面、模型名、端点和支持策略可能变化。请以控制台、开发者指南和 OpenAI Codex 官方文档的最新说明为准。

​
准备条件

  • macOS 12 或更高版本
  • Node.js LTS 版本
  • Git
  • 可用的 AIOAGI API Key
  • 一个本地代码项目，用于验证 Codex 是否可正常读取仓库

OpenAI Codex 配置文档

查看 config.toml、模型和 Provider 配置方式。

OpenAI Codex IDE 扩展

查看 Codex 与编辑器集成的官方说明。

AIOAGI API Key 指南

如果你还没有创建 API Key，可以先完成控制台配置。

开发者指南

核对当前端点、模型和 OpenAI 兼容接口说明。

​
安装步骤

1

安装命令行工具

如果你的系统还没有 Git 或编译工具，先安装 Xcode Command Line Tools：
xcode-select --install
安装后执行下面的命令验证 Git：
git --version
2

安装 Node.js

你可以使用 Node.js 官网安装包、Homebrew 或 nvm 安装 Node.js LTS 版本。安装完成后验证：
node --version
npm --version
3

安装 Codex CLI

执行下面的命令安装 Codex CLI：
npm install -g @openai/codex
安装后验证：
codex --version
4

创建 AIOAGI API Key

登录 AIOAGI 控制台，在 令牌管理 中创建 API Key。建议为 Codex 单独创建一个 Token 组，便于统计用量和控制额度。
5

配置 Codex

在当前 macOS 用户目录下创建或更新 ~/.codex/config.toml，把 Codex 指向 AIOAGI 的 OpenAI 兼容接口。
6

启动 Codex

进入你的代码项目目录，执行 codex。首次接入时先发送一个简单问题，确认模型能正常返回内容。

​
AIOAGI 接入配置

​
推荐方式：使用用户环境变量

macOS 默认 shell 通常是 zsh。先把 API Key 写入 ~/.zshrc： 
echo 'export OPENAI_API_KEY="sk-your-aioagi-api-key"' >> ~/.zshrc
source ~/.zshrc
如果你使用 bash，把上面的 ~/.zshrc 改成 ~/.bashrc 或 ~/.bash_profile。 然后创建 Codex 配置目录和配置文件： 
mkdir -p ~/.codex
nano ~/.codex/config.toml
在 config.toml 中写入下面的内容： 
model_provider = "aioagi"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[model_providers.aioagi]
name = "AIOAGI"
base_url = "https://api.aiearth.dev/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
如果你的网络更适合 CDN 加速线路，也可以把 base_url 改成： 
base_url = "https://api.aiearth.vip/v1"
gpt-5.1-codex 仅作为配置示例。模型 ID、可用模型和调用策略可能变化，请先在控制台或开发者指南中确认后再配置。

​
是否需要 OPENAI_BASE_URL

如果你按上面的 config.toml 配置了 [model_providers.aioagi].base_url，不需要再设置 OPENAI_BASE_URL。Codex 会从 config.toml 读取 AIOAGI 的 base URL，OPENAI_API_KEY 只负责提供密钥。 如果你不定义 AIOAGI Provider，而是改用 Codex 内置 openai Provider 的代理方式，请在用户级 config.toml 中配置 openai_base_url： 
model_provider = "openai"
model = "gpt-5.1-codex"
openai_base_url = "https://api.aiearth.dev/v1"
这种方式仍需要保留 OPENAI_API_KEY。不要把 OPENAI_BASE_URL 和 [model_providers.aioagi].base_url 当作两项必填配置同时维护。

​
兼容方式：使用 auth.json

如果你不想把 API Key 写入 shell 配置，也可以在 ~/.codex 下创建 auth.json： 
mkdir -p ~/.codex
nano ~/.codex/auth.json
写入： 
{
  "OPENAI_API_KEY": "sk-your-aioagi-api-key"
}
此时 config.toml 仍保留 AIOAGI Provider 配置： 
model_provider = "aioagi"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[model_providers.aioagi]
name = "AIOAGI"
base_url = "https://api.aiearth.dev/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
不要把包含真实 API Key 的 ~/.zshrc、auth.json、config.toml 截图或终端输出提交到公开仓库。

​
启动和验证

进入你的代码项目目录后，执行： 
codex
你可以先用下面这类提示词验证接入是否成功： 
请先阅读当前仓库结构，再总结主要目录和入口文件。
如果 Codex 能正常读取仓库并返回结果，说明 CLI 安装、配置文件和 API Key 已基本可用。

​
集成到 VS Code

安装好 Codex CLI 后，你可以在 VS Code 中安装 Codex 扩展。
1

打开扩展面板

在 VS Code 中点击 Extensions，搜索 Codex。
2

安装官方扩展

选择 OpenAI 官方 Codex 扩展并安装。安装后重新加载 VS Code。
3

打开项目

在 VS Code 中打开你的项目目录，并确认当前集成终端可以执行 codex --version。
4

验证集成

先在 VS Code 集成终端执行 codex，再使用扩展入口检查是否能正常调用 Codex。

​
常见问题

关闭并重新打开终端。然后执行 npm prefix -g，确认全局安装路径是否加入了 PATH。如果你使用 nvm，请确认当前终端已经加载 nvm 配置。
不建议使用 sudo npm install -g 作为长期方案。优先使用 nvm 安装 Node.js，或配置用户级 npm 全局目录后再安装 Codex。
检查 OPENAI_API_KEY 是否完整复制。再确认 Token 组额度、模型权限、base_url 和网络代理设置。你也可以参考 常见问题 中的 Codex 排障条目。
到控制台确认当前 API Key 可访问的模型列表，并核对 model 是否与模型 ID 完全一致。如果平台近期调整了模型别名或支持策略，请以控制台和开发者指南最新信息为准。

​
使用建议

  • 为 Codex 单独创建 API Key，便于统计开发工具用量
  • 先用小额度 Token 组完成连通性测试，再切换到正式额度
  • 第一次接入时优先测试读取仓库、解释文件和生成简单补丁
  • 修改 ~/.zshrc、auth.json 或 config.toml 后，重新打开终端和 VS Code
  • 模型名、价格和支持策略可能变化，请以控制台和开发者指南为准

​
相关文档