Codex 接入

Codex 提供桌面应用、IDE 插件和命令行工具三种形态，它们共用用户目录下的 .codex 配置。接入前需要一把分组包含当前可用 OpenAI 兼容模型的 Lunora API Key。

更简单的方式

不想手动编辑配置文件时，优先使用 CC Switch 一键导入。本页保留完整手动配置，方便首次安装和问题排查。

1. 选择 Codex 客户端

形态	适合用户	官方入口
桌面应用	希望使用独立图形界面	Codex
IDE 插件	主要在 VS Code 等编辑器中工作	Codex IDE 文档
CLI	熟悉终端，希望从项目目录启动	Codex CLI 文档

桌面应用和 IDE 插件无需先安装 CLI。三种形态可以共用下面的 config.toml 和 auth.json。

2. 创建匹配的 Lunora Key

1. 打开“可用渠道”。
2. 找到准备在 Codex 中使用的模型。
3. 记录模型名称、所属分组和当前状态。
4. 创建一把选择该分组的 API Key。

不要把订阅兑换码或不包含目标模型的 Key 填入 Codex。详见创建和保护 API Key。

3. 方式一：控制台生成配置

这是手动接入中最推荐的方式：

1. 进入 Lunora API 密钥页面。
2. 找到准备给 Codex 使用的 Key。
3. 点击右侧 使用密钥。
4. 切换到 Codex 标签并选择当前操作系统。
5. 复制页面生成的 config.toml 和 auth.json。
6. 分别保存到 .codex 配置目录。

Lunora 当前界面示例，模型、价格与可用状态以控制台实时显示为准。

4. 找到配置目录

• macOS/Linux：~/.codex/
• Windows：%USERPROFILE%\.codex\

macOS/Linux 创建目录：

mkdir -p ~/.codex

Windows 按 Win + R，输入：

%USERPROFILE%\.codex

目录不存在时，在用户目录中新建 .codex 文件夹。不要把配置放进某个项目的 .codex 目录，除非你明确知道客户端的配置优先级。

5. 方式二：手动配置 config.toml

在 .codex 目录创建 config.toml。模型名称必须替换为“可用渠道”当前显示的值：

model_provider = "Lunora"
model = "控制台显示的模型名称"
review_model = "控制台显示的模型名称"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"

[model_providers.Lunora]
name = "Lunora"
base_url = "https://api.uselunora.com"
wire_api = "responses"
requires_openai_auth = true

Codex 使用 API 根地址

base_url 必须填写 https://api.uselunora.com，末尾不要添加 /v1、/v1/responses 或 /v1/chat/completions。Codex 这里使用 wire_api = "responses"，不要照搬 WorkBuddy 的完整端点。

如果现有 config.toml 已包含其他配置，只修改供应商、模型和与 Lunora 接入直接相关的字段，不要整份覆盖你的审批、沙箱或工作区设置。

6. 保存 auth.json

在同一 .codex 目录创建 auth.json：

{
  "OPENAI_API_KEY": "你的_Lunora_API_Key"
}

auth.json 包含真实 Key，不要提交到 GitHub、同步到公开网盘或放进项目仓库。

7. 完全重启应用

Codex 通常只在启动时读取配置：

• 桌面应用：彻底退出应用，包括后台或托盘进程，再重新打开。
• IDE 插件：按 Ctrl/Cmd + Shift + P，运行 Developer: Reload Window，或直接重启编辑器。
• CLI：关闭旧终端，新开终端后重新进入项目目录。

只关闭一个聊天窗口不会重新加载配置。

8. 完成最小验证

先在临时目录或测试项目中运行只读任务，不要用真实业务项目做第一次验证。

CLI 可运行：

codex "请只回复：ok"

成功标准：

1. Codex 正常返回。
2. Lunora 控制台出现请求记录。
3. 请求模型和 API Key 分组正确。
4. 用量变化与短测试相符。

9. 安装命令行版本

先确认 Node.js/npm 可用，然后安装：

npm install -g @openai/codex

检查版本：

codex --version

CLI 与桌面应用、IDE 插件使用同一份 .codex 配置。修改配置后重新打开终端。

常见问题

修改配置后没有变化

桌面应用需彻底退出后台进程，IDE 插件需重载窗口，CLI 需重开终端。还要确认修改的是当前用户目录下的 .codex，不是另一个账号或项目目录。

401 或 403

检查 auth.json 是否为合法 JSON、Key 是否完整和启用，并确认 Key 分组包含当前模型。不要把兑换码、其他服务商 Key 或被截断的 Key 填入文件。

404 或协议错误

确认 base_url 为裸地址 https://api.uselunora.com，并且 wire_api = "responses"。删除手动附加的 /v1 或具体接口路径后完全重启。

模型不存在或不可用

返回“可用渠道”复制当前模型名称，确保大小写、连字符完全一致。模型和渠道状态会更新，不要继续使用旧截图中的固定名称。

codex: command not found

确认 npm 全局目录已进入 PATH，重新打开终端后运行 codex --version。Windows 如果存在多个 Node.js 环境，还需确认安装和运行使用的是同一个环境。

桌面版可以用，IDE 或 CLI 不可以用

分别确认它们由同一个系统用户启动，并读取同一个 .codex 目录。IDE 从桌面图标启动时，可能不会继承旧终端里的临时环境变量，因此应优先使用配置文件。