知更AI接入教程

快速开始

Codex 接入教程

跟随下面的步骤，在 Windows 或 macOS 上完成安装、导入和连接测试。

预计 5 分钟

推荐方式

登录后自动填好密钥，一键导入 CC Switch

导入后由 CC Switch 本地保存
  1. 1安装工具
  2. 2选择密钥
  3. 3一键导入
  4. 4连接测试
最快路径

不用复制粘贴，密钥自动带入

在控制台登录状态下打开本页，会自动读取你账号下的 API 密钥并填进下面所有配置里。选好密钥，点“一键导入 CC Switch”即可，没有密钥也能在这里直接创建。

密钥只在你的浏览器里使用，不会发送给第三方。

或者手动核对
核对接口地址与密钥（已自动填好）
01

准备工具

下载安装

需要安装 Codex 和 CC Switch。选择你的电脑系统后，使用对应的下载入口。

Codex Windows 10 及以上
下载
CC Switch 请选择 Windows 安装版
下载
02

准备凭证

创建 API 密钥

登录控制台后，本页顶部会自动列出你的密钥，没有的话点“一键创建”即可。习惯在控制台操作，也可以进入密钥管理页新建，再点操作栏的“导入到 CCS”。

  1. 1

    打开平台的密钥管理页面。

  2. 2

    点击创建密钥，名称可填写“我的电脑”。

  3. 3

    点击右侧导入到 CCS，不要再手动复制密钥。

API 密钥列表中导入到 CCS 的操作位置
点击箭头所指的“导入到 CCS”，即可唤起 CC Switch。
03

写入配置

导入到 CC Switch

点击“导入到 CCS”后，浏览器会直接唤起 CC Switch。你只需要在 CC Switch 中确认导入。

CC Switch 导入 Codex 配置界面示意图
核对供应商名称、端点和应用类型后确认导入。
  1. 1

    浏览器询问是否打开 CC Switch 时，选择允许。

  2. 2

    在导入确认窗口中核对应用为 Codex。

  3. 3

    确认导入并启用刚添加的供应商。

回到密钥页操作
04

完成

重启并测试连接

完全退出正在运行的 Codex，再重新打开。进入对话后选择平台支持的模型并发送测试消息。

收到正常回复即表示配置成功

如果模型列表暂时没有更新，关闭 Codex 后重新打开一次，再检查 CC Switch 中当前供应商是否已经启用。

Codex 成功回复测试消息的界面示意图
连接成功界面示意。
05

快捷定位

找到 Codex 配置文件

需要手动查看或修改配置时，按你的系统使用下面任意一种方式打开 config.toml。

⊞
Windows资源管理器或 PowerShell
配置文件路径
%USERPROFILE%\.codex\config.toml
  1. 1

    按 Win + R，粘贴 %USERPROFILE%\.codex，回车。

  2. 2

    PowerShell 直接打开：notepad "$HOME\.codex\config.toml"

⌘
macOS隐藏目录：Finder 或终端
配置文件路径
~/.codex/config.toml
  1. 1

    打开 Finder 的“前往”→“前往文件夹”，或按 ⌘ + ⇧ + G，输入 ~/.codex 后回车。隐藏目录也可以这样直接进入。

  2. 2

    按 ⌘ + Space 搜索“终端”并回车，在终端输入 open ~/.codex，即可在 Finder 中打开隐藏目录。

  3. 3

    想显示隐藏文件，在 Finder 按 ⌘ + ⇧ + .；终端直接编辑：open -e ~/.codex/config.toml

06

推荐备用方式

复制配置文件

一键导入没反应时，直接复制下方已填好密钥的 config.toml 和 auth.json；也可以在控制台密钥页点“使用密钥”复制。

  1. 1

    在密钥列表找到要使用的密钥，点击操作栏的使用密钥。

  2. 2

    切换到自己的系统标签页：macOS / Linux 或 Windows。

  3. 3

    分别复制 config.toml 和 auth.json 两个代码框的完整内容。

  4. 4

    按下方路径打开配置目录，粘贴并保存对应文件；目录不存在时先创建 .codex 文件夹。

密钥列表中使用密钥的操作位置
点击密钥操作栏的“使用密钥”，打开系统配置复制窗口。
⌘
macOS / Linux复制后放入用户目录
使用密钥窗口中的 macOS 配置内容
点击图片可查看完整窗口；两个代码框右上角都可以单独复制。
  1. 1

    配置目录：~/.codex；文件名必须分别是 config.toml 和 auth.json。

  2. 2

    可按 ⌘ + Space 搜索“终端”，输入 open ~/.codex 打开目录。

⊞
Windows复制后放入用户目录
使用密钥窗口中的 Windows 配置内容
点击图片可查看完整窗口；两个代码框右上角都可以单独复制。
  1. 1

    配置目录：%USERPROFILE%\.codex；文件名必须分别是 config.toml 和 auth.json。

  2. 2

    按 Win + R，输入 %USERPROFILE%\.codex 打开目录。

展开查看已填好密钥的配置文件

把下面两段分别保存为 config.toml 和 auth.json，接口地址和密钥已经按你的账号填好。

config.toml 
model_provider = "custom"

[model_providers.custom]
name = "知更AI"
base_url = "https://api.zhigeng.io"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"
auth.json 
{
  "OPENAI_API_KEY": "你的 API 密钥"
}

两个文件都放在 ~/.codex（Windows 为 %USERPROFILE%\.codex）目录下。登录控制台后打开本页，密钥会自动填好。

!

排错

常见报错速查

把客户端里看到的报错粘进搜索框，或按类型筛选，就能看到原因和处理办法。Codex 与 Claude Code 通用。

类型报错信息原因怎么解决
认证401 Unauthorized / Invalid API key / INVALID_API_KEY密钥填错、多了空格，或密钥已被删除在本页顶部重新选择密钥，配置会自动更新；手动填写时确认整串复制、前后无空格
认证API key is disabled / API_KEY_DISABLED密钥被停用控制台「API 密钥」里把它改回启用，或新建一个
认证unexpected status 401（Codex）auth.json 没生效，或系统里还有旧的 OPENAI_API_KEY 环境变量覆盖完全退出 Codex 重开；删掉旧的 OPENAI_API_KEY 环境变量后再试
认证Invalid API key · Please run /login（Claude Code）Claude Code 仍在用官方账号登录态，没读到环境变量在 Claude Code 里执行 /logout，重新打开终端确认 ANTHROPIC_BASE_URL 已生效
余额insufficient balance / INSUFFICIENT_BALANCE / 402账户余额不足控制台充值或使用兑换码，余额到账后立即可用
余额quota exceeded / API key quota exhausted这个密钥设置的额度已用完在密钥设置里调高额度或改成不限，或换一个密钥
限流429 Too Many Requests / concurrency limit并发或速率超过限制减少同时运行的会话，稍等几十秒再试；需要更高并发请联系客服
分组403 Forbidden / group not allowed / 分组不可用密钥所在分组不支持当前客户端或已下线Codex 选 OpenAI 分组的密钥，Claude Code 选 Claude 分组；在本页顶部按分组重新选择即可
模型model not found / unsupported model / 模型不存在所选模型不在该分组内，或模型名拼写错误改用分组支持的模型；Codex 建议保持配置里的 gpt-5.5
模型context_length_exceeded / 上下文过长对话太长超过模型上限Codex 输入 /compact 压缩上下文，或开一个新会话
地址404 Not Found接口地址填错或多加了路径地址只填 https://api.zhigeng.io，不要自己追加其它路径
网络stream disconnected before completion / stream error网络中途断开或上游响应超时直接重试；频繁出现可换「亚洲入口」或申请直连白名单
网络502 / 503 / 504 / No available accounts / upstream error上游临时繁忙或维护等 1～2 分钟重试，留意群公告；持续超过 10 分钟请联系客服
网络ECONNREFUSED / ENOTFOUND / getaddrinfo failed / 请求超时本机网络、代理或 DNS 无法访问接口先用浏览器打开 https://api.zhigeng.io 看能否访问；开了代理请让 api.zhigeng.io 走直连或稳定节点
网络certificate verify failed / SSL 错误系统时间不准，或代理、杀毒软件拦截了 HTTPS校准系统时间，关闭 HTTPS 扫描或换代理节点后重试
网络直连地址无法连接 / 连接被重置当前 IP 不在直连白名单在控制台「直连白名单」添加当前 IP，约 1 分钟后生效；不用直连就改回默认地址

排查问题

常见问题

先按错误提示快速检查，仍无法解决时再联系平台客服。

点击“导入到 CCS”没有反应

确认 CC Switch 已经安装并至少启动过一次。仍然无反应时，重新安装 CC Switch，以恢复 ccswitch:// 协议关联；也可以使用上面的手动填写方式。

提示 401 或 API Key 无效

重新复制完整密钥，检查前后是否带有空格，并确认密钥没有被删除、禁用或用完额度。

导入后仍然连接旧地址

先在 CC Switch 中确认新供应商处于“已启用”状态，然后完全退出 Codex 并重新打开。

模型列表为空或模型不可用

模型由平台按密钥权限提供。刷新后仍为空时，请检查密钥权限或向平台客服确认当前可用模型。

提示 400：请求参数无效

先确认接口地址是平台提供的完整地址，不要自行追加或删除路径；再检查模型名称、请求协议和客户端版本是否与平台说明一致。

提示 403：没有权限或分组不可用

通常是密钥没有对应分组权限、账户被禁用，或当前模型不在套餐范围内。换一个有权限的密钥测试，并向平台客服确认分组和模型权限。

提示 404：接口或模型不存在

检查端点是否复制完整，以及模型 ID 是否拼写正确。不要把其他客户端的路径直接套用到 Codex，按平台提供的 Codex 接入地址填写。

提示 429：请求过多、余额不足或额度用完

先暂停重复重试，查看平台余额、额度和限流提示。多个客户端同时使用同一密钥时，也可能更容易触发频率限制。

提示 500、502 或 503

这类状态通常表示上游服务或中转线路暂时异常。等待几分钟后重试；如果持续出现，请把错误时间、模型名称和完整错误码发给平台客服，不要发送 API 密钥。

请求超时、一直转圈或网络错误

确认电脑可以访问接口域名，暂时关闭可能拦截请求的代理或安全软件后再试。长上下文或复杂任务也可能需要更长时间，请避免连续点击发送。

提示不支持 Responses 或协议不匹配

Codex 配置需要使用平台明确支持的协议。不要凭经验把 Chat Completions 地址改成 Responses 地址；请以平台提供的 Codex 专用配置为准。

提示模型不存在或无法选择模型

模型名称必须使用平台实际开放的模型 ID。先在平台模型列表或公告中确认名称，再在 Codex 中选择；不要只根据网上教程填写旧模型名。

提示上下文过长或超过 Token 限制

新建一个对话、减少一次发送的文件数量，或换用平台支持更大上下文的模型。长对话可以先让 Codex 总结，再继续后面的任务。

导入后配置没有生效

在 CC Switch 中确认供应商已经启用，然后完全退出 Codex（包括终端窗口）再重新打开。仍无效时，检查配置文件的修改时间和当前供应商端点。

找不到 config.toml

先启动一次 Codex 或完成一次 CC Switch 导入，再按“配置文件”章节定位。macOS 的 .codex 默认隐藏，可以用 Finder 的“前往文件夹”直接输入 ~/.codex。

密钥疑似泄露或误发给别人

立即在平台密钥管理页禁用或删除旧密钥，再创建新密钥并重新导入。不要把包含密钥的导入链接发到群聊、工单或公开网页。

不知道应该把哪些信息发给客服

请提供操作系统、Codex/CC Switch 版本、发生时间、模型名称、HTTP 状态码和脱敏后的错误信息。请隐藏 API Key、邮箱、余额截图和完整导入链接。

Claude Code 提示“不是内部或外部命令”

先确认 Node.js 已安装，再重新打开终端。运行 node -v 和 npm -v 检查环境；安装完成后用 claude doctor 检查 PATH 和安装状态。

Claude Code 安装时提示 npm 权限错误

不要直接给 npm 命令加 sudo。macOS 可使用 Node.js 官方安装包或 Node 版本管理器后重试；Windows 请使用 PowerShell、Git Bash 或 WSL，并确认 Node.js 为 18 或更高版本。

Claude Code 提示 401、403 或无效密钥

确认 ANTHROPIC_BASE_URL 是平台提供的 Claude 接口地址，密钥没有空格且仍然有效。平台要求 Bearer 认证时使用 ANTHROPIC_AUTH_TOKEN；不要同时设置两个认证变量。

Windows 配置后 Claude Code 仍然连接官方地址

PowerShell 使用 $env:变量名=值，Git Bash/WSL 使用 export 变量名=值，两种写法不能混用。配置后在同一个终端运行 claude，不要只打开新的图形终端窗口。

Claude Code 和 Codex 的配置能不能混用

不能直接混用。Codex 使用 ~/.codex/config.toml 与 auth.json，Claude Code 使用 ANTHROPIC_BASE_URL 等环境变量；请按对应章节配置各自的端点和密钥。

Claude Code 提示模型不存在或 Messages API 不支持

Claude Code 需要平台提供兼容 Anthropic Messages API 的端点。模型 ID 必须使用平台实际开放的名称；不要把 Codex 的 Responses 配置或模型名复制到 Claude Code。