Codex
Codex 是 OpenAI 推出的 Agentic Coding Environment（智能体编程环境）。它是让模型真正进入项目、读取代码、修改文件、运行命令并验证结果的开发工作台。在 Codex 中，用户可以把修 Bug、写功能、补测试、改文档等任务交给智能体。Codex 会结合项目上下文执行多步操作，并在完成后给出变更说明和验证结果。其通过配置可接入云知声 MaaS 平台上的 AI 模型，支持按量付费/模型资源包、Token Plan 两种接入方式。
一、安装 Codex
- 安装或更新 Node.js（v18.0 或更高版本）。
- 在终端中执行以下命令安装 Codex。
npm install -g @openai/codex执行以下命令验证安装。
codex --version二、配置接入凭证
接入需要编辑配置文件 ~/.codex/config.toml 并配置环境变量 OPENAI_API_KEY。请根据您的接入方式选择对应配置。
1.配置环境变量
将 OPENAI_API_KEY 环境变量设置为实际使用的 API Key。
- 在终端中执行以下命令，查看默认 Shell 类型。
echo $SHELL- 根据 Shell 类型设置环境变量：
# 将 YOUR_API_KEY 替换为实际使用的 API Key
echo 'export OPENAI_API_KEY="YOUR_API_KEY"' >> ~/.bash_profile- 执行以下命令使环境变量生效。
source ~/.bash_profile2.模型配置
根据模型支持的接入方式，选择以下一种配置：
找到 Codex 配置文件
Windows 一般是：
C:\Users\你的用户名\.codex\config.toml如果没有这个文件，就新建一个。
双击 config.toml 打开。
如果弹出“选择打开方式”，选 记事本 或 VS Code 都可以。打开后你要编辑的就是这个文件。
选择接入方式
通过Responses API接入
通过 Responses API 接入,适用于支持 OpenAI Responses API 的模型，可使用最新版 Codex。
- 在 config.toml 中添加以下配置：
model_provider = "unisound"
model = "u2-flash"
approval_policy = "never"
service_tier = "default"
wire_api = "responses"
[model_providers.unisound]
name = "unisound"
base_url = "https://maas-api.unisound.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"- 重启 Codex 生效
保存 config.toml 后，完全退出 Codex，再重新打开。(务必重启再打开才能使用）setx 设置的环境变量仅对新启动的进程生效，因此必须重新打开 Codex 才能读取到 API Key。
通过Chat/Completions API 接入
适用于仅支持 Chat/Completions API 的模型，需安装Codex 0.80.0（新版本 Codex 已不再支持wire_api = "chat" 配置）：
- 在 config.toml 中添加以下配置：
model = "u2-flash"
model_provider = "unisound"
[model_providers.unisound]
name = "unisound"
base_url = "https://maas-api.unisound.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"- 重启 Codex 生效
保存 config.toml 后，完全退出 Codex，再重新打开。(务必重启再打开才能使用）setx 设置的环境变量仅对新启动的进程生效，因此必须重新打开 Codex 才能读取到 API Key。
验证配置
配置完成后，新建终端窗口，执行以下命令启动 Codex：
codex如果正常进入对话界面，说明配置成功。
三、使用 CC Switch 接入
CC Switch 是社区开源的桌面 GUI，支持在多个 API Key 或计费套餐之间一键切换，无需手动修改 ~/.codex/config.toml。
安装
- macOS：执行
brew tap farion1231/ccswitch && brew install --cask cc-switch，或从 Releases 下载 .dmg。 - Windows：从 Releases 下载 .msi 安装包或便携版 .zip。
- Linux：Arch 发行版执行
paru -S cc-switch-bin；其他发行版从 Releases 下载 .deb / .rpm / .AppImage。
要求 CC Switch v3.17 及以上版本（首次支持 Codex）。
添加供应商
- 在 CC Switch 主界面顶部图标栏选中 Codex 图标，点击右上角 + 进入添加新供应商，按下表填入配置后点击添加。
| 计费方案 | 配置信息 |
|---|---|
| Token Plan | 供应商名称：云知声 API Key：控制台获取 请求地址：https://maas-api.unisound.com/v1 |
| 按量计费 | 供应商名称：云知声 API Key：控制台获取 请求地址：https://maas-api.unisound.com/v1 |
同时展开高级选项填写模型名称
云知声兼容三种协议，CC Switch 高级选项的「上游格式」按实际使用的协议选择：
| 云知声接入协议 | 上游格式选择 | 请求地址 | 是否开启路由 |
|---|---|---|---|
| Responses API | Responses | https://maas-api.unisound.com/v1 | 否，直连不转换格式 |
| Chat/Completions API | Chat Completions | https://maas-api.unisound.com/v1 | 是，由路由接管转换协议 |
| Anthropic Messages | Anthropic Messages | https://maas-api.unisound.com/anthropic | 是，由路由接管转换协议 |
开启协议转换路由（上游格式选择 Chat Completions / Anthropic Messages 时）
CC Switch 的本地路由会在本机启动代理，自动完成协议转换：
- 打开「设置 → 路由」，开启路由总开关。
- 勾选 Codex 接管。
- 保持 CC Switch 在后台运行。
上游格式选择 Responses 时为直连模式，无需开启路由，跳过此步。
验证配置
- 回到主界面，点击云知声供应商卡片将其设为当前供应商。
- 完全退出并重启 Codex。
- 在 Codex 中发送一条消息，收到云知声模型回复即配置成功。
- 如需切回官方模型，在 CC Switch 中点击对应供应商卡片即可一键切换，无需修改任何文件。
四、快速接入能力模型
我们预置 U2-ASR、U2-TTS、U2-TTS-Clone、U1-OCR 模型能力，只需在 Codex 中添加对应模型 Skill，即可快速调用相关模型服务，无需单独对接各类模型 API 接口。
点击下方链接跳转至对应 Skill 页面，可通过对话或命令行安装 Skill，安装完成后 Skill 将会引导您进行相关模型的配置。