huigen.慧根 API
控制台
接入教程

Codex API 配置图文教程：从创建令牌到首次调用

慧根 API 编辑 · 发布 / 更新于

为 Codex CLI 配置慧根 API，核对 config.toml、Responses 协议、环境变量和令牌分组，并排查首次调用失败。

Codex API 配置图文教程：从创建令牌到首次调用操作路线图
图解路线 · 正文按步骤说明操作与检查结果。 点击图片查看大图

开始前：按图了解完整路线

这条路线使用慧根一键配置助手，适合第一次接入。你不需要先手写配置文件。先准备可登录的慧根账户、对应分组令牌和一台 Windows、macOS 或 Linux 电脑。

步骤 1—2：创建并复制对应分组令牌

1. 登录后进入 API 令牌页

打开 API 令牌页。未登录时先完成登录，找到创建令牌入口；名称写成方便辨认的用途，例如“我的 Codex”。在分组选项中选择 Codex，并核对页面上的有效期、可用额度和模型限制，再保存。

完成后检查：新令牌的分组为 Codex，有效期和额度能够覆盖这次测试。名称只是便于识别，不能代替分组。

Codex 与 Claude 分组对应及令牌输入位置示意
图 1 · 分组核对示意，非后台截图。 点击图片查看大图

2. 复制令牌，留在本机备用

按令牌页面提供的复制方式取得令牌。复制后不要贴进浏览器搜索框，也不要发送到聊天。若只能在创建时查看完整令牌，按页面提示安全保存。

完成后检查：你已取得刚创建的令牌，而不是账户密码、令牌名称或其他服务的密钥。

步骤 3：下载并打开适合系统的助手

3. 选择客户端和操作系统

打开配置助手，点击 Codex 标签，在“你的电脑系统”下选择自己的系统。确认按钮显示“下载并配置 Codex”后再下载。

完成后检查：页面上的客户端、分组和电脑系统三项都正确。

慧根线上配置助手：选择 Codex、操作系统并下载
图 2 · 2026-11-02 截取的线上实际配置页面；下方按系统选择运行方法。 点击图片查看大图

Windows：双击下载的 .cmd 文件

打开浏览器下载列表或下载文件夹，找到 huigen-setup-codex-windows.cmd，阅读文件后运行。如果文件没有按预期启动，在该文件所在目录打开终端，用下面的命令运行；不要在任意目录直接粘贴。

cmd /d /c ".\huigen-setup-codex-windows.cmd"

macOS / Linux：在文件所在目录用 bash 运行

选好系统后，配置页会显示该系统文件名和运行命令。打开终端，进入下载文件所在目录，复制配置页显示的那条命令；文件名包含所选系统，不要把 Windows 的 .cmd 命令用于 macOS 或 Linux。

首次打开时请阅读系统提示。若文件来源或内容与你预期不符，先停止核对。

对应系统的运行命令

以下命令都需要在下载文件所在目录执行。若浏览器给文件名添加了编号，请以配置页和实际下载文件名为准。

# macOS
bash "./huigen-setup-codex-macos.command"

# Linux
bash "./huigen-setup-codex-linux.sh"

步骤 4—5：运行助手并输入令牌

4. 选择项目文件夹并处理依赖

按助手提示填写项目目录，或接受默认目录。缺少客户端时，助手会询问是否安装。若提示缺少 Node.js、Git 或其他依赖，按提示和官方安装说明处理，重新打开终端再运行助手。

完成后检查：依赖检查不再报错，助手进入令牌输入步骤。创建目录、安装软件或工作区信任提示，需要你按自己的环境确认。

项目目录、客户端安装、隐藏输入令牌和首次测试的操作顺序
图 3 · 运行步骤示意，非真实终端执行结果。 点击图片查看大图

5. 在隐藏输入处粘贴令牌并回车

确认提示需要的是 Codex 分组令牌后，只粘贴一次并按回车。隐藏输入时看不到星号或字符也正常。助手会在本机独立配置目录保存连接信息和令牌。

完成后检查：助手提示配置已保存并开始启动 Codex。如果报令牌格式错误，重新复制并检查是否带入空格、换行或示例占位符。

步骤 6—7：确认调用成功，准备下次启动

6. 发送一次最小请求

先输入下面这句话，暂时不要要求修改代码：

请只回复“连接成功”，不要读取或修改任何文件。

完成后检查：客户端返回回答且没有鉴权或路由错误。回答文字可能不同，关键是请求能够正常完成。此步骤会产生实际模型调用费用。

7. 回到调用记录核对，再保存启动入口

打开调用记录，按刚才的时间寻找请求，核对模型、分组和消耗。Windows 可使用助手建立的快捷方式或重新运行助手；macOS / Linux 按助手最后输出的启动文件路径运行。

完成后检查：能找到对应调用记录。若客户端有回复而本站没有记录，先核对是否仍然在使用其他服务的配置。

接入完成应同时满足
  • 使用了对应分组的令牌。
  • 客户端正常回复一次小请求。
  • 本站调用记录能找到这次请求。

手动配置时核对这几个字段

已有配置时先备份，并合并字段，避免覆盖其他 provider。默认配置文件通常在用户目录的 .codex/config.toml；使用了 CODEX_HOME 时，应核对该目录内的配置。慧根的连接字段如下：

model = "gpt-6.1-sol"
model_provider = "huigen"

[model_providers.huigen]
name = "Huigen API"
base_url = "https://huigen.xyz/v1"
wire_api = "responses"
env_key = "HUIGEN_API_KEY"

env_key 是环境变量名称，不是令牌本身。需要在启动 Codex 的进程环境中提供 HUIGEN_API_KEY。不熟悉环境变量时，使用前面的配置助手完成隐藏输入，避免把真实令牌写进命令历史。

wire_api = "responses" 表示使用 Responses 协议；这里的 Base URL 是 API 前缀，不能填成完整的 /v1/responses 地址。关于路径拼接，参见API 地址什么时候加 /v1。

失败时按客户端、鉴权、路由顺序排查

  • 找不到 codex：检查客户端安装和 PATH，重新打开终端。
  • 缺少环境变量或 401：确认在同一个启动环境中提供了令牌，且令牌未撤销、未过期。
  • 404：检查 Base URL 是否重复拼接 /v1，以及请求协议是否正确。
  • “无可用渠道”：核对 Codex 分组、模型标识和渠道状态，参考分组与渠道排错教程。
  • 429 或 503：结合响应正文区分限流、额度和上游临时不可用，减少并发，避免连续重复请求。

需要协助时记录客户端版本、发生时间、HTTP 状态和去掉令牌的报错正文。不要发送包含认证信息的完整配置。

继续阅读