本文档用于帮助用户将 HengxinAi 的 API 接入 Codex/Claude Code/OpenClaw/Hermes 等工具。配置完成后，用户可以像使用官方模型一样，在各类工具中调用 HengxinAi 提供的模型。

1. 准备工作

打开 HengxinAi 官网

注册并登录一个账户

充值任意金额

进入 令牌管理 页面

新建一个 API Key 并设置分组

复制并保存该 Key

请注意：

API Key 只在创建时完整展示一次，请妥善保存，不要提交到 Git 仓库。

OpenAI/Codex 兼容工具的 Base URL 使用 https://gpt.js.cn/v1。

Claude Code/Anthropic 兼容工具的 Base URL 使用 https://gpt.js.cn，不要在末尾添加 /v1。

模型名请以 HengxinAi 后台模型列表为准。本文示例使用 gpt-5.4，如后台模型名不同，请替换为实际可用模型。

2. 安装 Agent

2.1. Codex 安装

2.1.1 Codex App 安装

MacOS / Windows

下载并安装 Codex App

使用 API Key 进行登录

在 设置 -> 配置 -> 打开 config.toml

将下面配置信息粘贴并保存

重启 Codex App

# 将下面这个部分填入 config.toml 最开头
model_provider = "hengxinai"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.hengxinai]
name = "hengxinai"
base_url = "https://gpt.js.cn/v1"
wire_api = "responses"

如果 Codex App 提示无法读取 API Key，请确认：

登录时填写的是 HengxinAi 生成的 API Key，而不是 HengxinAi 登录密码

base_url 必须包含 /v1

修改 config.toml 后需要完全退出并重新打开 Codex App

2.1.2 Codex CLI 安装

MacOS / Linux / Windows

安装 Node.js，建议使用 Node.js 20 LTS 或更新版本

安装 Codex CLI

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

MacOS 也可以使用 Homebrew 安装：

brew install --cask codex
codex --version

推荐使用环境变量保存 API Key：

export HENGXINAI_API_KEY="填入你的 HengxinAi API Key"

如果希望长期生效，可以将上面这一行加入 ~/.zshrc 或 ~/.bashrc，然后重新打开终端。

配置 `config.toml`

打开或创建配置文件：

mkdir -p ~/.codex
nano ~/.codex/config.toml

写入以下内容：

model_provider = "hengxinai"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.hengxinai]
name = "hengxinai"
base_url = "https://gpt.js.cn/v1"
env_key = "HENGXINAI_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

启动测试：

codex "你好，请简单介绍一下你当前使用的模型"

如果你不想使用 HENGXINAI_API_KEY 这个环境变量名，也可以改用 OPENAI_API_KEY：

export OPENAI_API_KEY="填入你的 HengxinAi API Key"

同时将配置中的 env_key 改为：

env_key = "OPENAI_API_KEY"

2.2. Claude Code 安装

Claude Code 使用 Anthropic Messages 协议。接入 HengxinAi 时，请使用不带 /v1 的 Base URL。

2.2.1 安装

MacOS / Linux / WSL

npm install -g @anthropic-ai/claude-code
claude --version

也可以使用官方安装脚本：

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Windows PowerShell

irm https://claude.ai/install.ps1 | iex
claude --version

2.2.2 临时配置

临时配置只对当前终端窗口有效：

export ANTHROPIC_BASE_URL="https://gpt.js.cn"
export ANTHROPIC_API_KEY="填入你的 HengxinAi API Key"
export ANTHROPIC_MODEL="claude-sonnet-4-5"
claude

如果 HengxinAi 后台展示的 Claude 模型名不同，请将 ANTHROPIC_MODEL 替换为后台实际模型名。也可以先不设置 ANTHROPIC_MODEL，进入 Claude Code 后使用 /model 选择可用模型。

2.2.3 长期配置

zsh

echo 'export ANTHROPIC_BASE_URL="https://gpt.js.cn"' \u003e\u003e ~/.zshrc
echo 'export ANTHROPIC_API_KEY="填入你的 HengxinAi API Key"' \u003e\u003e ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' \u003e\u003e ~/.zshrc
source ~/.zshrc

bash

echo 'export ANTHROPIC_BASE_URL="https://gpt.js.cn"' \u003e\u003e ~/.bashrc
echo 'export ANTHROPIC_API_KEY="填入你的 HengxinAi API Key"' \u003e\u003e ~/.bashrc
echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' \u003e\u003e ~/.bashrc
source ~/.bashrc

PowerShell

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://gpt.js.cn", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "填入你的 HengxinAi API Key", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-5", "User")

设置完成后，关闭并重新打开终端，再运行：

claude

2.2.4 检查当前配置

进入 Claude Code 后运行：

/status

如果发现仍然在使用 Claude 官方账号或订阅，请检查当前终端是否存在旧变量：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY
echo $ANTHROPIC_MODEL

需要恢复官方 Claude Code 时，可以清理变量：

unset ANTHROPIC_BASE_URL
unset ANTHROPIC_API_KEY
unset ANTHROPIC_MODEL

2.3. OpenClaw 安装与配置

OpenClaw 支持通过自定义 provider 接入 OpenAI 兼容端点。不同 OpenClaw 版本的配置结构可能会变化，推荐优先使用交互式配置：

openclaw configure --section model

如果需要手动配置，可以编辑：

nano ~/.openclaw/openclaw.json

参考配置如下：

{
  "env": {
    "HENGXINAI_API_KEY": "填入你的 HengxinAi API Key"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "hengxinai": {
        "baseUrl": "https://gpt.js.cn/v1",
        "apiKey": "${HENGXINAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "hengxinai/gpt-5.4"
      }
    }
  }
}

保存后重启 OpenClaw：

openclaw restart

如果当前 OpenClaw 版本不支持 openai-responses，可以把 api 改成：

"api": "openai-completions"

同时确认 HengxinAi 后台该模型支持对应协议。

2.4. Hermes 安装与配置

Hermes 的配置一般位于 ~/.hermes/ 目录：

~/.hermes/config.yaml：模型、终端、压缩等非密钥配置

~/.hermes/.env：API Key 等密钥配置

2.4.1 配置 API Key

打开或创建 ~/.hermes/.env：

mkdir -p ~/.hermes
nano ~/.hermes/.env

写入：

OPENAI_API_KEY=填入你的 HengxinAi API Key

2.4.2 配置主模型

打开配置文件：

nano ~/.hermes/config.yaml

写入或合并以下内容：

model:
  provider: custom
  base_url: "https://gpt.js.cn/v1"
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-5.4"

如果你更习惯直接写死密钥，也可以把 api_key 改成明文字符串；如果想统一放在环境变量里，保留 ${OPENAI_API_KEY} 即可。Hermes 会优先使用 base_url 指向的自定义端点。

如果你已经通过 hermes model 配置过模型，也可以仅使用命令检查和切换：

hermes config
hermes model

2.4.3 配置辅助模型

Hermes 的视觉、网页提取、压缩、会话搜索等辅助任务也可以单独指定 HengxinAi。下面是自定义端点的同类写法：

auxiliary:
  vision:
    base_url: "https://gpt.js.cn/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-5.4"
    timeout: 120
  web_extract:
    base_url: "https://gpt.js.cn/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-5.4"
    timeout: 360

配置完成后运行：

hermes config check
hermes

3. 常见接入方式速查

工具	协议类型	Base URL	常用密钥变量
Codex App	OpenAI Responses	`https://gpt.js.cn/v1`	App 登录时填写
Codex CLI	OpenAI Responses	`https://gpt.js.cn/v1`	`HENGXINAI_API_KEY` 或 `OPENAI_API_KEY`
Claude Code	Anthropic Messages	`https://gpt.js.cn`	`ANTHROPIC_API_KEY`
OpenClaw	OpenAI Responses / Chat Completions	`https://gpt.js.cn/v1`	自定义 `HENGXINAI_API_KEY`
Hermes	OpenAI 兼容	`https://gpt.js.cn/v1`	`OPENAI_API_KEY`

4. 验证 API 是否可用

4.1. OpenAI 兼容接口验证

curl https://gpt.js.cn/v1/models \\\\
  -H "Authorization: Bearer 填入你的 HengxinAi API Key"

如果返回模型列表，说明 API Key 和 Base URL 基本可用。

也可以测试一次聊天请求：

curl https://gpt.js.cn/v1/chat/completions \\\\
  -H "Authorization: Bearer 填入你的 HengxinAi API Key" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "model": "gpt-5.4",
    "messages": [
      { "role": "user", "content": "请回复 OK" }
    ]
  }'

4.2. Claude Code 验证

ANTHROPIC_BASE_URL="https://gpt.js.cn" \\\\
ANTHROPIC_API_KEY="填入你的 HengxinAi API Key" \\\\
claude -p "请回复 OK"

如果提示模型不存在，请更换为 HengxinAi 后台实际可用的 Claude 模型名：

ANTHROPIC_MODEL="后台实际模型名" claude -p "请回复 OK"

5. 常见问题

5.1. 401 / Unauthorized

通常是 API Key 错误或环境变量没有生效。

处理方式：

确认复制的是 HengxinAi API Key，不是登录密码

确认 Key 前后没有多余空格

重新打开终端，让环境变量重新加载

使用 echo $HENGXINAI_API_KEY、echo $OPENAI_API_KEY 或 echo $ANTHROPIC_API_KEY 检查变量是否存在

5.2. 404 / Not Found

通常是 Base URL 写错。

Codex、OpenClaw、Hermes：使用 https://gpt.js.cn/v1

Claude Code：使用 https://gpt.js.cn

Claude Code 会自动拼接 /v1/messages，所以不要把 ANTHROPIC_BASE_URL 写成 https://gpt.js.cn/v1。

5.3. model not found

通常是模型名和 HengxinAi 后台不一致。

处理方式：

将文档中的 gpt-5.4 或 claude-sonnet-4-5 替换成后台实际模型名

重启对应工具

5.4. Codex 没有读取新配置

处理方式：

确认配置文件路径为 ~/.codex/config.toml

确认 TOML 格式正确，尤其是 [model_providers.hengxinai] 不要写错

完全退出 Codex App 或 CLI 后重新启动

如果使用项目级 .codex/config.toml，确认项目已被 Codex 信任

5.5. Claude Code 仍然走官方订阅

Claude Code 会优先读取环境变量中的 API Key。请运行：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

如果没有输出，说明当前终端没有加载配置。请重新执行导出命令，或者重新打开终端。

如果你想恢复官方订阅，运行：

unset ANTHROPIC_BASE_URL
unset ANTHROPIC_API_KEY
unset ANTHROPIC_MODEL

5.6. 请求超时或流式中断

处理方式：

更换网络环境后重试

降低模型推理强度，例如把 model_reasoning_effort = "high" 改成 "medium"

在 Codex CLI 中增大 stream_idle_timeout_ms

确认 HengxinAi 账户余额充足

6. 安全建议

不要把 API Key 写入公开仓库

不要截图公开带有 API Key 的配置文件

建议为不同工具创建不同 API Key，便于单独停用和追踪用量

若怀疑 Key 泄露，立即在 HengxinAi 后台删除旧 Key 并创建新 Key

OpenClaw 和 Hermes 具备执行命令、读写文件等能力，建议先在测试目录或容器中使用

7. 参考资料

Codex CLI 配置参考：https://www.mintlify.com/openai/codex/configuration/reference

Codex CLI 安装说明：https://www.mintlify.com/openai/codex/installation

Claude Code 安装说明：https://docs.anthropic.com/en/docs/claude-code/getting-started

Claude Code 环境变量说明：https://code.claude.com/docs/zh-CN/env-vars

OpenClaw 自定义 Provider 说明：https://docs.openclaw.ai/gateway/config-tools

Hermes 配置说明：https://hermes.dhuar.com/en/user-guide/configuration/

使用说明

1. 准备工作#

2. 安装 Agent#

2.1. Codex 安装#

2.1.1 Codex App 安装#

MacOS / Windows#

2.1.2 Codex CLI 安装#

MacOS / Linux / Windows#

配置 config.toml#

2.2. Claude Code 安装#

2.2.1 安装#

MacOS / Linux / WSL#

Windows PowerShell#

2.2.2 临时配置#

2.2.3 长期配置#

zsh#

bash#

PowerShell#

2.2.4 检查当前配置#

2.3. OpenClaw 安装与配置#

2.4. Hermes 安装与配置#

2.4.1 配置 API Key#

2.4.2 配置主模型#

2.4.3 配置辅助模型#

3. 常见接入方式速查#

4. 验证 API 是否可用#

4.1. OpenAI 兼容接口验证#

4.2. Claude Code 验证#

5. 常见问题#

5.1. 401 / Unauthorized#

5.2. 404 / Not Found#

5.3. model not found#

5.4. Codex 没有读取新配置#

5.5. Claude Code 仍然走官方订阅#

5.6. 请求超时或流式中断#

6. 安全建议#

7. 参考资料#

1. 准备工作

2. 安装 Agent

2.1. Codex 安装

2.1.1 Codex App 安装

MacOS / Windows

2.1.2 Codex CLI 安装

MacOS / Linux / Windows

配置 `config.toml`

2.2. Claude Code 安装

2.2.1 安装

MacOS / Linux / WSL

Windows PowerShell

2.2.2 临时配置

2.2.3 长期配置

zsh

bash

PowerShell

2.2.4 检查当前配置

2.3. OpenClaw 安装与配置

2.4. Hermes 安装与配置

2.4.1 配置 API Key

2.4.2 配置主模型

2.4.3 配置辅助模型

3. 常见接入方式速查

4. 验证 API 是否可用

4.1. OpenAI 兼容接口验证

4.2. Claude Code 验证

5. 常见问题

5.1. 401 / Unauthorized

5.2. 404 / Not Found

5.3. model not found

5.4. Codex 没有读取新配置

5.5. Claude Code 仍然走官方订阅

5.6. 请求超时或流式中断

6. 安全建议

7. 参考资料