Codex客户端接入API指南
|
50

2036 字
|
10 分钟

本文介绍如何在 Codex 中接入 云石 API。Codex 有桌面客户端和命令行（Codex CLI）两种形态，接入方式对应两条路线：图形化（CC Switch）与手动配置（config.toml）。按你的使用场景选一条即可，全程约 5 分钟。

开始前请确保你已经拿到了 API Key（令牌），并且令牌选择了 gpt 分组。云石的 OpenAI 协议请求地址为 https://yyoo.xyz/v1。

一、适用版本

项目 要求 说明
Codex 桌面客户端 Windows 10+ / macOS 12+ 官网下载的最新正式版即可
Codex CLI 0.1xx 系列（实测 0.146.0 及以上） 新版仅支持 responses 格式，不再支持 chat completions
CC Switch（选路线 A 时） v3.16 及以上 低于该版本可能没有 Codex 专属面板
Node.js（仅 Codex CLI） 18.0 或更高（建议 20/22 LTS） 桌面客户端不需要 Node.js
云石令牌分组 必须是 gpt 分组 用其他分组会返回模型不存在或 404

版本核对日期：2026-09-23。软件迭代较快，实际以官方最新版为准；本文的步骤在新版本上通常同样适用。

二、前置条件

  • 已注册云石账号，并创建了 gpt 分组的 API Key（令牌）。如何获取见《云石新手教程》。
  • 令牌复制完整、首尾无空格。
  • 本机可以正常访问 https://yyoo.xyz。
  • Codex 已安装：客户端装好即可；CLI 用户请确认 codex --version 能输出版本号。

权限说明：本文所有操作都不需要管理员权限。

  • 命令行安装请不要加 sudo（Linux / macOS）或以管理员身份运行（Windows），否则会产生 root 属主的全局目录，后续升级、卸载都会报权限错误。
  • 如果提示 EACCES／权限不足，正确做法是改用用户级安装目录或换用原生安装脚本，而不是提权。
  • config.toml 与 auth.json 里含有密钥，建议将文件权限收紧为仅本人可读写（Linux / macOS：chmod 600 ~/.codex/config.toml ~/.codex/auth.json）。

三、安装配置

3.1 路线 A：用 CC Switch 图形化配置（推荐，桌面客户端）

第一步：下载并安装 Codex

从官网下载 Codex 客户端并安装，安装完成后会出现初始界面。此时不需要做任何操作：

Codex 客户端初始界面

第二步：在 CC Switch 中添加云石供应商

打开 CC Switch，点击右上角的「添加」（+）：

CC Switch 主界面，右上角为添加按钮

按下图填写配置（注意先在上方切到 Codex 面板）：

在 CC Switch 中填写云石供应商的地址、Key 与模型
  • 名称：云石（自定义，仅用于自己辨认）
  • 请求地址：https://yyoo.xyz/v1
  • API Key：粘贴你的令牌（sk- 开头）
  • 模型：填 gpt 分组中的模型名，例如 gpt-5.5
  • API 格式 / Protocol：选 responses（Codex 新版只认这种格式）
注意：令牌需要选择 gpt 分组，否则会报错。

填写完成后点「保存」，再点「启用」，可顺手点一下「测试连通性」。

第三步：完全退出并重启 Codex

只关窗口不一定生效，请从系统托盘（或任务栏）右键 完全退出 Codex 后再重新打开：

保存配置后完全退出并重启 Codex

3.2 路线 B：手动配置 config.toml（Codex CLI / 高级用户）

如果你用的是 Codex CLI，或者不想依赖 CC Switch，可以直接改配置文件。

第一步：安装 Codex CLI

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

第二步：创建配置目录（已存在则跳过）

# macOS / Linux
mkdir -p ~/.codex
# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"

第三步：写入 ~/.codex/config.toml

model = "gpt-5.5"
model_provider = "shouyin"

[model_providers.shouyin]
name = "shouyin"
base_url = "https://yyoo.xyz/v1"
wire_api = "responses"
env_key = "SHOUYIN_API_KEY"

第四步：设置环境变量并登录

# macOS / Linux
export SHOUYIN_API_KEY="sk-你的令牌"
# Windows PowerShell
setx SHOUYIN_API_KEY "sk-你的令牌"   # 设置后需重开窗口
codex login --with-api-key
codex login status
base_url 只写到 /v1 为止，不要自己再加 /responses，否则会返回 404——Codex 会自己拼接路径。

四、核心操作

  • 客户端日常使用：直接打开 Codex 客户端对话即可，请求会走 CC Switch 当前启用的云石供应商。
  • 切换供应商：在 CC Switch 里选中目标供应商点「启用」，然后重启 Codex；也可以在系统托盘菜单里快速切换。
  • 切换模型：在 CC Switch 供应商配置里改「模型」字段并保存重启；CLI 可用 codex -m gpt-5.5 临时指定。
  • CLI 单次执行（脚本化）： 
    codex exec "用一句话说明这个仓库的用途"
# 需要写入文件时（默认只读沙箱）
codex exec -s workspace-write --skip-git-repo-check "创建 fizzbuzz.py 并运行"
  • 继续上一轮会话：codex exec resume。

五、验证方法

按顺序做三步，能定位到具体是哪一层出了问题：

步骤 操作 预期结果
1. 客户端可用性 在 Codex 客户端里发一句「你好，用一句话自我介绍」 正常流式回复，说明接入成功
2. 供应商连通性 CC Switch 中点「测试连通性」 提示连通正常；失败则先查地址与 Key
3. CLI 连通性 codex --version 与 codex exec "Reply with exactly: OK" 输出版本号 / 输出 OK
配置完成后在 Codex 客户端中正常对话

验证通过后，如果想确认消耗情况，可登录云石后台查看使用日志（用量统计与账单）。

六、常见问题

1. 报 401 / 认证失败

令牌复制不完整或带了空格；或令牌不是 gpt 分组。重新复制一次令牌，注意首尾不要有空格。

2. 报 404 / 模型不存在

  • 令牌没选 gpt 分组；
  • 请求地址写错：应在 https://yyoo.xyz/v1 与 https://yyoo.xyz 之间二选一（Codex 需要 /v1）；又或者你在 base_url 后面又手动加了 /responses，造成路径重复。

3. 配置改了但 Codex 没变化

Codex 只在启动时读取配置。只关窗口不算退出，请从系统托盘彻底退出进程后重新打开。

4. 提示不支持的 API 格式

Codex 新版只支持 responses。请把协议/格式改为 responses（而不是 chat / chat completions）。

5. Windows 下 Node.js 权限报错

npm config set prefix "$env:APPDATA\npm"

改完重开终端，不要用管理员身份安装。

6. CC Switch 面板里找不到 Codex

CC Switch 版本过低，升级到 v3.16 及以上；或在设置里把 Codex 从「隐藏项」中放出来。

七、回滚 / 卸载

按接入方式选择对应的回滚动作，建议操作前先备份配置文件。

7.1 回滚到官方账号（保留软件）

  • 客户端：在 CC Switch 里停用（或删除）云石供应商，改用官方配置后重启 Codex。
  • CLI：删除 ~/.codex/config.toml 里的 model_provider 一行（或整段 [model_providers.xxx]），即可退回官方登录；也可单次覆盖：codex exec -c model_provider="openai" "..."。
  • 如设置了 SHOUYIN_API_KEY 环境变量，一并清除（Windows 用「系统属性 → 环境变量」删除，或 setx SHOUYIN_API_KEY ""）。

7.2 备份先于删除

# macOS / Linux
cp -r ~/.codex ~/.codex.bak-$(date +%Y%m%d)
# Windows
Copy-Item "$env:USERPROFILE\.codex" "$env:USERPROFILE\.codex.bak" -Recurse

7.3 完全卸载

对象 操作
Codex CLI npm uninstall -g @openai/codex，再删除 ~/.codex 目录
Codex 客户端 Windows：设置 → 应用 → 卸载；macOS：把 App 拖入废纸篓
CC Switch Windows：msiexec /x CC-Switch-v*-Windows.msi；macOS：brew uninstall --cask cc-switch
删除 ~/.codex 会同时清掉登录凭证与历史会话，请确认已备份。

八、更新记录

日期 版本 修改内容
2026-09-23 v2.0 知识库检查修订：补齐适用版本、前置条件、权限说明、验证方法、常见问题、回滚/卸载、更新记录；新增 Codex CLI 手动配置（config.toml）路线；补充 responses 格式与 /v1 路径限制说明；图片改为相对路径并补充 alt 文本
2026-09-22 v1.0 首次发布：Codex 客户端经 CC Switch 接入云石 API 的四步图文流程
Codex
上一篇
下一篇