Codex 使用第三方 API 教程

Codex 是 OpenAI 推出的 AI 编程助手，支持 CLI 命令行版和桌面 App 版。两者共享同一套配置文件，本教程适用于 macOS 和 Windows。

---

前置准备

1. 已安装 Codex CLI 或 Codex App（见下方安装说明）
2. 已在第三方中转(https://hongmacc.com) 注册账号并获取 API Key

---

安装 Codex（如未安装）

Codex CLI

# 方式一：npm 安装（跨平台）
npm install -g @openai/codex

# 方式二：Homebrew（macOS）
brew install codex

Codex App

平台	下载方式
macOS（Apple Silicon）	官网下载
macOS（Intel）	官网下载 Intel 专版
Windows	Microsoft Store 搜索 “Codex”，或运行：winget install Codex -s msstore

---

配置文件位置

Codex CLI 和 App 共享同一配置目录：

平台	配置文件路径
macOS / Linux	~/.codex/config.toml
Windows	%USERPROFILE%\.codex\config.toml

API Key 建议存放在同目录的 .env 文件：

平台	Key 文件路径
macOS / Linux	~/.codex/.env
Windows	%USERPROFILE%\.codex\.env

---

配置方法

方式一：简单替换 Base URL（快速上手）

适合只需要换 API 地址、保留其他默认配置的场景。

步骤 1：编辑 config.toml

model           = "gpt-5.5"
model_provider  = "openai"
openai_base_url = "https://hongmacc.com/v1"

步骤 2：写入 API Key

编辑 ~/.codex/.env（Windows：%USERPROFILE%\.codex\.env）：

OPENAI_API_KEY=你的API_KEY

---

方式二：自定义 Provider（推荐，更灵活）

适合需要明确标注来源、使用多个 Provider 切换的场景。

步骤 1：编辑 config.toml

model          = "gpt-5.5"
model_provider = "hongmacc"

[model_providers.hongmacc]
name    = "HongMacc API"
base_url = "https://hongmacc.com/v1"
env_key  = "HONGMACC_API_KEY"

字段说明：

• model：调用的模型名称，填 hongmacc.com 支持的模型标识符
• model_provider：与下方 [model_providers.xxx] 的 ID 一致
• base_url：API 地址，需包含 /v1 路径
• env_key：指向存 Key 的环境变量名

步骤 2：写入 API Key

编辑 ~/.codex/.env（Windows：%USERPROFILE%\.codex\.env）：

HONGMACC_API_KEY=你的API_KEY

---

macOS 完整操作步骤

# 1. 创建配置目录（如不存在）
mkdir -p ~/.codex

# 2. 编辑配置文件
nano ~/.codex/config.toml

粘贴以下内容后保存（Ctrl+O → Enter → Ctrl+X）：

model          = "gpt-5.5"
model_provider = "hongmacc"

[model_providers.hongmacc]
name     = "HongMacc API"
base_url = "https://hongmacc.com/v1"
env_key  = "HONGMACC_API_KEY"

# 3. 写入 API Key
echo 'HONGMACC_API_KEY=你的API_KEY' >> ~/.codex/.env

# 4. 运行验证
codex "hello, 测试连接"

---

Windows 完整操作步骤

打开 PowerShell：

# 1. 创建配置目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"

# 2. 编辑配置文件（用记事本打开）
notepad "$env:USERPROFILE\.codex\config.toml"

写入以下内容保存：

model          = "gpt-5.5"
model_provider = "hongmacc"

[model_providers.hongmacc]
name     = "HongMacc API"
base_url = "https://hongmacc.com/v1"
env_key  = "HONGMACC_API_KEY"

# 3. 写入 API Key
Add-Content "$env:USERPROFILE\.codex\.env" "HONGMACC_API_KEY=你的API_KEY"

# 4. 运行验证
codex "hello, 测试连接"

---

多 Provider 切换（进阶）

如果你同时使用多个 API 服务，可以在 config.toml 中配置多个 Provider，通过修改 model_provider 字段快速切换：

# 当前使用 hongmacc
model          = "gpt-5.5"
model_provider = "hongmacc"

[model_providers.hongmacc]
name     = "HongMacc API"
base_url = "https://hongmacc.com/v1"
env_key  = "HONGMACC_API_KEY"

# 备用：官方 OpenAI
[model_providers.official]
name     = "OpenAI Official"
base_url = "https://api.openai.com/v1"
env_key  = "OPENAI_API_KEY"

.env 文件中同时写入两个 Key：

HONGMACC_API_KEY=你的hongmacc_KEY
OPENAI_API_KEY=你的openai_KEY

切换时只需修改 config.toml 顶部的 model_provider = "official" 即可。

---

注意事项

• base_url 需要包含 /v1，与 Claude App 不同（Codex 不自动追加）
• 自定义 Provider ID 不能 使用 openai、ollama、lmstudio（系统保留名）
• .env 文件中的 Key 不要用引号包裹
• hongmacc.com 的 API 需要兼容 OpenAI Responses API 协议

---

验证配置

# CLI 验证
codex "说一句话证明连接成功"

# 如连接失败，开启调试模式查看详细错误
DEBUG=true codex "测试"

---

常见问题

Q：提示 model_provider not found

检查 config.toml 中 model_provider = "xxx" 的值与 [model_providers.xxx] 的 ID 完全一致。

Q：提示 401 Unauthorized

• 确认 .env 文件中的 Key 名称与 env_key 字段一致
• 登录 hongmacc.com 后台确认 Key 未过期

Q：提示 unsupported wire_api 或协议错误

hongmacc.com 需要支持 OpenAI Responses 协议，联系平台客服确认接口类型。

Q：Codex App 不读取 config.toml 的配置

确保编辑的是 ~/.codex/config.toml（用户根目录下），而非项目目录中的 .codex/config.toml。重启 App 后生效。

---

配置文件速查

文件	作用
~/.codex/config.toml	主配置（模型、Provider、行为策略）
~/.codex/.env	API Key 存储（不提交到 git）
.codex/config.toml（项目目录）	项目级配置，覆盖用户级设置

---

参考资料

• Codex 官方文档 - Config Basics
• Codex 官方文档 - Config Advanced
• Codex 官方文档 - Config Reference
• Codex App Windows 安装
• Codex Quickstart
• Codex CLI 终端配置指南