一个为所有人的API使用指南
返回官网 ↗
使用指南工具接入教程

Codex

把已经安装好的 Codex 接到你的 API。先分清本机客户端与云端任务,再配置模型服务。

开始前,把三样信息放在手边

已经装好工具即可继续。打开官网「自助服务」,登录后创建或查看自己的 API 密钥,并复制页面提供的 API 地址;从「模型与价格」复制完整模型 ID。别把官网首页、登录密码或模型的宣传名称填进去。确认账户和密钥都有可用额度。

下面的 API_HOST、YOUR_API_KEY、YOUR_MODEL_ID 都是占位文字,使用前逐个换成你的实际信息。地址里 /v1 是否保留,要看本篇要求;不要追加 /chat/completions 或 /responses。示例不会自动连接,也不会自动带入你的密钥。

1. 确认使用的是本机 Codex

本篇的文件配置适用于 Codex CLI 和读取本机配置的客户端,不是浏览器里的云端任务。只想用鼠标配置,可直接按 CC Switch 教程的 Codex 分支操作。

2. 打开配置文件,填写服务信息

macOS / Linux 在用户主目录打开 .codex/config.toml;Windows 打开 %USERPROFILE%\.codex\config.toml。没有文件时先启动一次 Codex。把示例放到对应位置,MY_API_KEY 是环境变量的名字,不是真实密钥。

字段示意 · 非软件截图
Base URL
https://API_HOST/v1
wire_api
responses
model
YOUR_MODEL_ID
env_key
MY_API_KEY
配置示例

修改配置前先保留原文件。已有同名项目时修改对应值,不要再重复添加一份;保留其他设置。配置中若有真实密钥,不要分享文件或截图。

model_provider = "my_api"
model = "YOUR_MODEL_ID"

[model_providers.my_api]
name = "My API"
base_url = "https://API_HOST/v1"
wire_api = "responses"
env_key = "MY_API_KEY"
requires_openai_auth = false

3. 准备密钥,然后启动

按下方写法设置 MY_API_KEY;在同一个终端进入测试文件夹,再运行 codex。env_key 会从这里取密钥,不需要把你原有的 auth.json 改成别人的文件。桌面程序从图标启动时未必读到终端变量,建议改用 CC Switch 配置该客户端。

如果配置使用 MY_API_KEY,需要在启动工具的同一个终端中设置它。下面先展示写法,密钥要在你自己的电脑上填写;之后从该终端启动工具。关闭终端后需要重新设置。

macOS / Linux 终端
export MY_API_KEY="YOUR_API_KEY"
codex
Windows PowerShell
$env:MY_API_KEY = "YOUR_API_KEY"
codex

4. 选模型,再调整思考强度

进入后用 /model 确认模型。客户端提供档位时,先用默认或 Medium,再按任务调高;也可把 model_reasoning_effort = "medium" 放在 config.toml 顶层、任何 [表名] 之前。仅填写当前模型支持的档位。

5. 确认协议与请求去向

本篇使用 OpenAI Responses,wire_api 必须是 "responses"。Base URL 保留 /v1,不能把 Harness 的 Chat Completions 设置原样套过来。模型本身还要支持 Codex 的工具与流式请求;普通聊天成功不能保证整套 Agent 能力。

验证一:收到第一条回复

新建一个空的测试文件夹,在工具中选择它作为工作区,再新开一个会话。确认当前选中的是刚添加的提供方和模型,发送下面这句话。收到正常回复且没有错误,才说明基本连接成功;它不能证明所有工具都已接通。测试会产生正常的 API 用量。

请只回复:连接成功。

预期:工具显示模型回复「连接成功」。若是登录页、报错或一直转圈,先查看下方排查表,不要反复发送。

验证二:让它实际读取一个文件

在刚才的测试文件夹里,用文本编辑器新建 hello.txt,内容写「API connection test 27」。保存后发送下面的要求;出现读取权限提示时,只允许访问这个测试文件夹。

请使用文件读取工具打开当前工作区的 hello.txt,告诉我文件内容,不要修改任何文件。

预期:能看到读取 hello.txt 的工具执行记录,回答包含 API connection test 27。只有一段口头回复、没有读取记录,不算工具调用验证成功。确认结束后,可以自行删除这个测试文件夹。

遇到问题,先按现象检查

401 / Invalid API key

确认地址和密钥来自同一个平台,密钥完整、未过期或被禁用。不要把完整密钥发给客服。

404 / model not found

先核对地址是否多写或少写 /v1,再核对模型 ID 和协议;模型列表可见也不代表所有协议都能使用。

429 / quota / balance

查看账户余额、密钥额度和请求频率,按错误提示处理;提高思考强度不能解决额度问题。

能聊天,不能读文件

确认模型支持工具调用、软件给了工作区读取权限,且工具执行过程没有报错。

没有思考强度选项

先检查模型能力声明,再检查当前模型与客户端版本是否支持可调档位。模型支持思考,不一定支持多个强度。

官方说明与适用范围

配置说明核对于 2026-11-08。工具更新后菜单可能变化,以下官方资料可用于核对;教程中的 API 信息始终以本平台当前提供的内容为准。