Codex App（桌面端）配置

桌面 App 如何接入

Codex App 的模型网关配置保存在本机 config.toml。macOS App 与本机 Codex CLI 默认读取同一个配置文件，修改后需要完全退出并重启 App。Windows App 读取 Windows 用户目录下的配置；WSL 的配置不会自动替代它。

本文说明桌面 App；终端使用方法见 Codex CLI 接入配置。官方依据见 连接模型网关：macOS / Windows App。

1. 准备密钥和模型

在 AIMirrorX 控制台 创建 API 密钥，并确认模型与渠道支持 Responses、流式输出和工具调用。

模型需使用当前 Codex 版本认识的原始模型名，且网关实际路由到对应模型。如果使用自定义别名，需由服务管理员提供匹配的 Codex 模型目录，详见下方“模型目录”。本文不承诺某个固定型号在当前账户可用。

2. 编辑配置文件

如果 App 的启动环境设置了 CODEX_HOME，使用该目录内的 config.toml。已有配置时合并字段，保留其他设置，不要重复定义同名键或 Provider 表。以下前三项顶层设置必须放在 TOML 表头之前。

model = "YOUR_RESPONSES_MODEL_ID"
model_provider = "aimirrorx"
web_search = "disabled"

[model_providers.aimirrorx]
name = "AIMirrorX"
base_url = "https://api.aimirrorx.com/v1"
env_key = "AIMIRRORX_API_KEY"
wire_api = "responses"
requires_openai_auth = false

将 YOUR_RESPONSES_MODEL_ID 替换为实际模型 ID。base_url 以 /v1 结尾，不追加 /responses；env_key 填环境变量名称，不能填密钥本身。首次验证关闭内置网页搜索，确认网关支持相应能力后再调整。

此方案使用 AIMirrorX API 密钥认证，requires_openai_auth 为 false，不需要手工改写 auth.json。

3. 让桌面 App 读取密钥

桌面启动的 App 不一定继承终端中的 export。需要把 AIMIRRORX_API_KEY 提供给真正启动 App 的进程；仅在 CLI 终端设置变量不足以保证桌面 App 能读取。

macOS

完全退出 Codex App 后，在终端执行以下当前登录会话的设置，再从桌面重新打开 App：

launchctl setenv AIMIRRORX_API_KEY "YOUR_AIMIRRORX_API_KEY"

替换密钥占位符，不要原样复制。此方式作用于当前用户登录会话，注销或重启后需重新设置。若单位已通过启动器或密钥管理工具提供变量，沿用该方式即可。不要将真实密钥放入项目、截图或 Git。

Windows

完全退出 Codex App。在 PowerShell 中设置当前用户的环境变量：

[Environment]::SetEnvironmentVariable(
  "AIMIRRORX_API_KEY",
  "YOUR_AIMIRRORX_API_KEY",
  "User"
)

也可通过 Windows“环境变量”界面创建同名用户变量。替换占位符后，注销并重新登录 Windows，再启动 App，让桌面启动进程获取新变量；仅关闭一个聊天窗口不等于退出整个 App。此变量会保留在用户环境设置中。

Windows App 使用 Windows 用户配置和环境变量；在 WSL 内运行的 CLI 则使用 WSL 内的设置。

4. 重启与验证

1. 完全退出并重新打开 Codex App。
2. 打开本地项目，新建聊天，确认 Provider 为 aimirrorx、模型为实际配置的 ID。
3. 发送简单的项目概述请求，确认响应正常，再开始开发任务。
4. 若仍使用旧设置，检查受信项目中的 .codex/config.toml、profile 或受管配置是否覆盖用户配置。

此 Provider 配置控制模型请求。MCP、插件、语音及其他连接能力有各自的网络路径、登录或权限；AIMirrorX 密钥不会自动授予这些权限。本文不修改 App 的审批与沙箱设置。

模型目录

• 使用 Codex 已识别的原始模型名时，需确认其内置元数据与网关实际路由一致。
• 自定义别名需要 Codex 兼容的模型元数据。普通 GET /v1/models 仅返回模型 ID 时，不能当作 Codex 模型目录。
• 如果管理员提供真实的目录 URL，在 Provider 表中使用 model_catalog_url；提供本地文件时，在顶层使用 model_catalog_json 和实际存在的绝对路径。
• 不要添加不存在的目录文件或自行猜测 URL；已有 model_catalog_json 会优先于远程目录。

常见问题

相关文档

• Codex CLI 接入配置
• AIMirrorX 协议与地址
• 官方：连接模型网关
• 官方：配置字段参考