小蓝中转站使用文档

接入 Codex ​

Codex 更像一套长期使用的本地工作流：默认模型、网关地址和行为偏好通常写在 config.toml，真正的 Key 再交给环境变量。

环境未配置时，先完成 Windows 快速接入 或 macOS 快速接入。

和 Claude Code 不同，Codex 不是“只写两个环境变量就完事”的工具。
它更适合把长期默认值固定下来，这样你换项目、重开终端或切模型时，不用每次都从头再配。

Codex 这里最容易记错的一点是 Base URL。
它走的是 OpenAI 兼容接口，所以这里要写：

txt
https://xiaolan.ainb.plus/v1

不是根地址。
Claude Code、Gemini CLI、Cherry Studio 这些工具各自对地址的要求不完全一样，Codex 这一页只记住一条：Codex 的 base_url 要带 /v1。

开始前先检查 ​

这些命令用于确认本机能安装和运行 Codex：node 和 npm 用来安装 CLI，git 用来读取项目仓库，npm registry 用来判断下载源是否适合国内网络。

bash
node -v
npm -v
git --version
npm config get registry

npm 下载慢时，先切镜像源：

bash
npm config set registry https://registry.npmmirror.com

为什么更推荐 config.toml + 环境变量 ​

OpenAI 官方当前文档里，自定义 Provider 更稳的写法是：

  • config.toml 负责说明模型、网关和协议
  • 环境变量负责提供 API Key

这样做有三个好处：

  1. 模型和网关配置能稳定保留在 Codex 的正式配置里
  2. Key 不用手改缓存文件，轮换更方便
  3. 出问题时更容易判断是配置层问题，还是鉴权层问题

如果你以前用过官方登录流程，~/.codex/auth.json 可能已经存在。
那是 Codex 自己的认证缓存，不代表接入 小蓝中转站 时还要继续手动编辑它。当前这套接法不依赖手改 auth.json。

方式一：使用 CC-Switch（图形界面） ​

如果你已经在用 CC-Switch，可以通过图形界面写入 Codex 配置：

这种方式适合不想手动编辑配置文件的用户。保存后仍然建议启动 Codex 做一次最小测试。

  1. 打开 CC-Switch，进入 Codex 面板。
  2. 创建配置档案：
    • Base URL：https://xiaolan.ainb.plus/v1
    • API Key：填入 小蓝中转站控制台创建的 Key
    • Model：从模型广场复制模型名
  3. 保存并应用。
  4. 重启终端中的 Codex。

模型怎么选 ​

Codex 配置里的 model 要从模型广场复制。第一次测试可以先选轻量模型，确认配置文件和 Key 正常；真实代码任务再切换到支持 Responses / OpenAI 兼容调用、代码能力更强的模型。

第一次接入时，建议把这三个概念分开看：

  • Key 分组：决定这把 Key 能走哪些可用渠道
  • 模型权限：决定这把 Key 能调用哪些模型
  • config.toml 里的 model：决定 Codex 当前默认请求哪个模型

推荐顺序：

  1. 在模型广场找到目标模型。
  2. 确认 Key 所选分组能使用该模型。
  3. 复制完整模型名。
  4. 写入 config.toml 的 model 字段。

如果启动后提示模型不存在，先检查 model 字段是否完整，再检查 Key 的分组和模型权限。

方式二：手动配置文件 ​

按下面步骤手动创建 Codex 配置。
手动方式的好处是每一层都看得见：你知道地址写在哪、模型写在哪、Key 从哪里读。

1. 安装 Codex CLI ​

Codex CLI 官方常见安装方式有三种：

  1. npm 全局安装
  2. Homebrew 安装
  3. GitHub Release 二进制压缩包

如果你已经装好 Node.js，优先继续用 npm；如果你平时主要用 Homebrew 管理命令行工具，可以直接走 Homebrew。

官方入口：

方式一：npm

bash
npm install -g @openai/codex@latest
codex --version

macOS 上用浏览器安装 Node.js 的机器，执行这一步时更常见的写法是：

bash
sudo npm install -g @openai/codex@latest
codex --version

终端出现钥匙图标或 Password: 提示后，密码不会显示任何字符，直接输入完成后按回车即可。

方式二：Homebrew

bash
brew install --cask codex
codex --version

方式三：GitHub Release

不想通过 npm 或 Homebrew 安装时，再去官方发布页下载对应系统压缩包。

2. 创建配置目录 ​

bash
mkdir -p ~/.codex
cd ~/.codex

3. 编写 config.toml ​

在 ~/.codex 目录下新建 config.toml，写入以下内容。将 model 字段替换为模型广场复制的模型名。

toml
# 默认使用这组自定义 Provider
model_provider = "xiaolan"

# 改成模型广场复制的真实模型名
model = "replace-with-model-from-pricing"

# 复杂代码任务通常比 low 更稳
model_reasoning_effort = "high"

# 需要执行高风险操作时先询问
approval_policy = "on-request"

# 允许在当前项目目录里读写文件
sandbox_mode = "workspace-write"

[model_providers.xiaolan]
# 只是本地显示名称，方便你自己识别
name = "小蓝中转站"

# Codex 走的是 OpenAI 兼容接口，所以地址要带 /v1
base_url = "https://xiaolan.ainb.plus/v1"

# Codex 自定义 Provider 走 Responses API 协议
wire_api = "responses"

# 告诉 Codex：真正的 Key 去环境变量里取
env_key = "小蓝中转站_API_KEY"

这几项分别负责的事情可以这样理解：

  • model_provider = "xiaolan"：告诉 Codex 默认使用这一组自定义 Provider
  • model = "..."：告诉 Codex 默认请求哪个模型
  • base_url = "https://xiaolan.ainb.plus/v1"：告诉 Codex 请求发往哪个网关地址
  • wire_api = "responses"：告诉 Codex 按哪种接口协议和网关通信
  • env_key = "小蓝中转站_API_KEY"：告诉 Codex 去哪个环境变量里读 Key

这份配置里最关键的是三项：

  • base_url = "https://xiaolan.ainb.plus/v1"
  • wire_api = "responses"
  • env_key = "小蓝中转站_API_KEY"

前两项决定请求会不会正确发到 小蓝中转站；最后一项决定 Codex 去哪里找你的 Key。

4. 写入 小蓝中转站_API_KEY ​

macOS / Linux ​

把下面这一行追加到 ~/.zshrc、~/.bashrc 或你当前 shell 的配置文件里：

bash
export 小蓝中转站_API_KEY="sk-你的专属Key"

保存后执行：

bash
source ~/.zshrc

如果你用的是 Bash，把 ~/.zshrc 换成对应的 ~/.bashrc 或 ~/.bash_profile。

Windows PowerShell ​

powershell
[Environment]::SetEnvironmentVariable("小蓝中转站_API_KEY", "sk-你的专属Key", "User")

写完后，完全关闭当前终端，再重新打开一个新窗口。

5. 启动 Codex ​

为了避免在根目录产生不必要的文件，建议建个测试目录启动：

bash
mkdir -p ~/codex-test
cd ~/codex-test
codex

如果你在 Windows PowerShell 里测试，对应写法可以换成：

powershell
mkdir $env:USERPROFILE\codex-test
cd $env:USERPROFILE\codex-test
codex

配置文件放哪里 ​

最常见的是两层：

  • 用户级默认配置：~/.codex/config.toml
  • 项目级覆盖配置：项目根目录 .codex/config.toml

OpenAI 官方当前文档把项目级 .codex/config.toml 作为覆盖层。
也就是说，你完全可以先把 小蓝中转站、默认模型和常用行为写进用户级配置；等某个仓库想单独限制模型时，再在那个仓库里额外补一份项目级配置。

不确定主目录时：

bash
echo $HOME

Windows PowerShell：

powershell
echo $env:USERPROFILE

最小验证 ​

进入一个测试目录：

bash
mkdir -p ~/codex-xiaolan-test
cd ~/codex-xiaolan-test
codex

进入后发送：

txt
创建一个 hello.js，打印 hello xiaolan。

第一次不急着让它直接改大型仓库。先确认四件事：

  1. codex 能正常启动
  2. 不会跳回官方登录流程
  3. 能正常返回回复
  4. 当前模型确实是你在 config.toml 里写的那一个

这四件事都成立，再切到真实项目目录会更稳。

如果这一条测试已经成功，后面再遇到问题，范围通常就能明显缩小到：

  • 当前项目目录里是否有另一份 .codex/config.toml
  • 当前终端有没有读到新的 小蓝中转站_API_KEY
  • 当前切换的模型是不是超出了这把 Key 的分组或模型权限

排障 ​

  • 流量似乎没有走网关？
    回去检查 config.toml 里的 [model_providers.xiaolan]，确认 base_url 和 wire_api 没有拼写错误。
  • 提示 API Key 无效或未提供？
    先检查 echo $小蓝中转站_API_KEY 或 echo $env:小蓝中转站_API_KEY 是否真有值。很多问题不是 Codex 不认 Key，而是当前终端根本没拿到这个变量。
  • 响应慢？
    先在配置里换个轻量模型试一次，排查是模型排队、上下文过大，还是本地网络问题。
  • TOML 解析失败？
    检查等号、引号和段落名。[model_providers.xiaolan] 必须使用英文方括号，不要漏掉下划线。
  • 改了配置还不生效？
    关闭所有 Codex 进程，重新打开终端。再确认当前项目目录里是不是还有另一份 .codex/config.toml 把用户级配置覆盖了。
  • Base URL 写成根地址会怎样？
    Codex 走的是 OpenAI 兼容接口，少了 /v1 时，请求路径通常不会按预期拼接，表现往往像接口异常、请求失败或始终进不了正常对话。
  • 以前配过官方账号，现在担心冲突？
    先不要急着删 auth.json。当前这套 小蓝中转站 接法主要看 config.toml 和 小蓝中转站_API_KEY，优先把这两层核对清楚。

小蓝中转站使用文档

© 2026 小蓝中转站