快速开始

Codex 接入教程

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

预计 5 分钟

推荐方式

从密钥页一键导入到 CC Switch

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

创建密钥后，直接点击“导入到 CCS”

密钥页会把当前密钥和接口配置交给 CC Switch。教程页面不需要你再次粘贴密钥，也不会接触密钥内容。

请在你的密钥列表中操作

找到要使用的密钥，点击右侧“导入到 CCS”。

查看操作位置
或者手动填写
没有 CCS？也可以手动配置
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

推荐备用方式

从密钥页复制配置

如果一键导入没有反应，可以直接在密钥页使用“使用密钥”，按系统复制配置文件内容。

  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 打开目录。

没有“使用密钥”入口？查看手动配置方法

打开用户目录中的 ~/.codex/config.toml，加入下面的配置。接口地址和环境变量名称需要按平台文档调整。

config.toml 
model_provider = "custom"

[model_providers.custom]
name = "你的平台"
base_url = "https://api.your-domain.com"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"

还需要在系统中设置 CUSTOM_API_KEY 环境变量。正式部署时会根据你的真实接口地址补全 Windows 和 macOS 命令。

07

另一种客户端

Claude Code 配置

Claude Code 是命令行工具。先安装 Node.js 18+，再把平台提供的 Claude 接口地址和密钥写入当前终端会话。

⊞
WindowsPowerShell、Git Bash 或 WSL
1. 安装 Claude Code
PowerShell / Git Bash
npm install -g @anthropic-ai/claude-code
2. 当前窗口临时配置
PowerShell
$env:ANTHROPIC_BASE_URL="https://api.your-domain.com"
$env:ANTHROPIC_API_KEY="你的 API 密钥"
claude
  1. 3

    如果使用 Git Bash 或 WSL，把上面的 $env:... 改为 export ...。

  2. 4

    配置后运行 claude doctor 检查安装，再发送一条简单消息测试。

⌘
macOS终端（zsh）
1. 安装 Claude Code
终端
npm install -g @anthropic-ai/claude-code
2. 当前窗口临时配置
zsh
export ANTHROPIC_BASE_URL="https://api.your-domain.com"
export ANTHROPIC_API_KEY="你的 API 密钥"
claude
  1. 3

    想长期生效，可把两行 export 放入 ~/.zshrc，再运行 source ~/.zshrc。

  2. 4

    配置后运行 claude doctor 检查安装，再发送一条简单消息测试。

排查问题

常见问题

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

点击“导入到 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。