HOHAI 新手接入文档

最重要的两个地址

新手快速开始

如果你第一次使用 API 网关，按下面 6 步做即可。不要跳过第 5 步“验证”，否则后面排错会很麻烦。

不知道自己该看哪一节？

获取 API Key

API Key 是你调用接口时使用的密钥。所有工具都需要填写它。

1. 打开控制台：https://api.hohai.eu.org/console。
2. 注册或登录账号。
3. 进入 令牌 / API Key / Token 页面。
4. 点击 新建令牌，建议命名为具体用途，例如 claude-code-mac、codex-laptop。
5. 复制生成的 Key。格式通常类似 sk-xxxxxxxx。
6. 回到本文档，把命令里的 sk-your-api-key 替换成你的真实 Key。

选择正确地址

不同工具使用的协议格式不同，因此 Base URL 不一样。你只要记住下表即可。

支持的模型

下面列出的是当前网关已开放、可直接调用的模型 ID，共 50 个（清单生成于 2026-09-15）。价格、倍率和额度消耗请以 模型定价 页面为准，模型上下线也以控制台里的模型列表为准。

Claude 系列 8 个

支持 Anthropic 原生格式（/v1/messages），Claude Code 的 Base URL 填 https://api.hohai.eu.org（不带 /v1）；同时也兼容 OpenAI 格式。

GPT / Codex 系列 6 个

OpenAI 兼容格式，Base URL 填 https://api.hohai.eu.org/v1。

Gemini 系列 6 个

OpenAI 兼容格式，Base URL 填 https://api.hohai.eu.org/v1。

Grok 系列 7 个

OpenAI 兼容格式，Base URL 填 https://api.hohai.eu.org/v1。

图像生成 4 个

走图像接口 /v1/images/generations，请求示例见 图像生成 API；部分模型也支持对话格式。

其他模型 19 个

包含 DeepSeek、Qwen、GLM、Kimi、MiniMax 等系列，同样是 OpenAI 兼容格式，Base URL 填 https://api.hohai.eu.org/v1；具体归属可在 模型定价 页查看。

Claude Code 配置

Claude Code 适合在终端里做代码编辑、文件分析和项目辅助。配置时使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY。

第 1 步：确认 Node.js 已安装

Claude Code 需要 Node.js。先在终端输入：

node -v
npm -v

如果能看到版本号，例如 v18、v20、v22，说明已安装。没有版本号则先看 Node.js 安装。

第 2 步：安装 Claude Code

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

第 3 步：临时配置环境变量

临时配置只在当前终端窗口有效，适合先测试。

export ANTHROPIC_BASE_URL=https://api.hohai.eu.org
export ANTHROPIC_API_KEY=sk-your-api-key

第 4 步：启动 Claude Code

claude

如果正常进入 Claude Code 界面，说明配置基本成功。

第 5 步：持久化配置

如果你不想每次打开终端都重新输入环境变量，可以写入 Shell 配置文件。

macOS / Linux：先确认你使用的是 Zsh 还是 Bash

echo $SHELL

如果输出包含 zsh，使用 Zsh 命令；如果输出包含 bash，使用 Bash 命令。

Zsh 用户

echo 'export ANTHROPIC_BASE_URL=https://api.hohai.eu.org' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-your-api-key' >> ~/.zshrc
source ~/.zshrc

Bash 用户

echo 'export ANTHROPIC_BASE_URL=https://api.hohai.eu.org' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY=sk-your-api-key' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 临时配置

$env:ANTHROPIC_BASE_URL="https://api.hohai.eu.org"
$env:ANTHROPIC_API_KEY="sk-your-api-key"

Windows PowerShell 持久化配置

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.hohai.eu.org", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-your-api-key", "User")

Codex CLI 配置

Codex CLI 使用 OpenAI 兼容格式，因此地址需要带 /v1。

第 1 步：确认 Node.js 已安装

node -v
npm -v

第 2 步：安装 Codex CLI

npm install -g @openai/codex

第 3 步：临时配置环境变量

export OPENAI_BASE_URL=https://api.hohai.eu.org/v1
export OPENAI_API_KEY=sk-your-api-key

第 4 步：启动 Codex

codex

第 5 步：持久化配置

Zsh 用户

echo 'export OPENAI_BASE_URL=https://api.hohai.eu.org/v1' >> ~/.zshrc
echo 'export OPENAI_API_KEY=sk-your-api-key' >> ~/.zshrc
source ~/.zshrc

Bash 用户

echo 'export OPENAI_BASE_URL=https://api.hohai.eu.org/v1' >> ~/.bashrc
echo 'export OPENAI_API_KEY=sk-your-api-key' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 临时配置

$env:OPENAI_BASE_URL="https://api.hohai.eu.org/v1"
$env:OPENAI_API_KEY="sk-your-api-key"

Windows PowerShell 持久化配置

[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://api.hohai.eu.org/v1", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")

OpenClaw 配置

OpenClaw 是一个 AI 客户端，通常按 OpenAI 兼容格式接入。配置时只需要填 Base URL、API Key 和模型名。

第 1 步：打开设置页面

进入 OpenClaw 的 Settings / Provider / API 或类似配置页面。不同版本界面名称可能略有不同，只要找到 API 服务商配置即可。

第 2 步：填写以下信息

第 3 步：保存并测试

保存后发送一句简单测试，例如：

你好，请用一句话回答：当前 API 是否连接成功？

如果能正常回复，说明 OpenClaw 已接入成功。

项目代码接入 OpenAI 兼容接口

文本对话使用 /v1/chat/completions。如果要生成图片，请查看图像生成 API章节，不要把生图请求写到聊天接口中。

Node.js 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.hohai.eu.org/v1"
});

const res = await client.chat.completions.create({
  model: "gpt-5.6-luna",
  messages: [
    { role: "user", content: "Hello" }
  ]
});

console.log(res.choices[0].message.content);

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.hohai.eu.org/v1"
)

res = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "Hello"}]
)

print(res.choices[0].message.content)

curl 示例

curl https://api.hohai.eu.org/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

图像生成 API

图像生成使用 OpenAI 兼容的 /v1/images/generations 接口。文本对话仍使用 /v1/chat/completions，两个接口的请求字段和返回结构不同。

接口地址和前置准备

https://api.hohai.eu.org/v1/images/generations

1. 在控制台创建 API Key，并设置到服务端环境变量。
2. 从模型定价或 /v1/models 复制完整的图像模型 ID，例如 gpt-image-2。
3. 确认账号余额、Key 限额和图像模型渠道均可用。

先查看可用模型

curl https://api.hohai.eu.org/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

模型列表只用于发现模型，最终仍要通过一次实际生图请求确认图像渠道可用。

curl 示例

curl https://api.hohai.eu.org/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A serene koi pond at sunset, ukiyo-e style.",
    "size": "1024x1024",
    "n": 1
  }'

Windows PowerShell 示例

if ([string]::IsNullOrWhiteSpace($env:OPENAI_API_KEY)) {
  throw "请先设置 OPENAI_API_KEY"
}

$headers = @{
  Authorization = "Bearer $env:OPENAI_API_KEY"
  "Content-Type" = "application/json"
}

$body = @{
  model = "gpt-image-2"
  prompt = "A serene koi pond at sunset, ukiyo-e style."
  size = "1024x1024"
  n = 1
} | ConvertTo-Json

$result = Invoke-RestMethod `
  -Uri "https://api.hohai.eu.org/v1/images/generations" `
  -Method Post -Headers $headers -Body $body

$result.data[0].url

Node.js 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.hohai.eu.org/v1"
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A serene koi pond at sunset, ukiyo-e style.",
  size: "1024x1024",
  n: 1
});

const image = result.data[0];
console.log(image.url || "返回了 Base64 图片数据");

返回结果

接口可能返回 data[0].url，也可能返回 data[0].b64_json。客户端必须兼容两种格式；Base64 需要解码成图片文件后再展示。

{
  "data": [
    { "url": "https://example.com/image.jpg" }
  ]
}

生图成功标准

• HTTP 状态码为 200；
• data 数组至少有一项；
• 返回项存在 url 或 b64_json；
• URL 可以下载，或 Base64 可以解码为有效图片文件。

Codex Desktop 安装与配置

OpenAI 的桌面客户端。装好之后把 ~/.codex/config.toml 指向 https://api.hohai.eu.org/v1，就能用同一把 HOHAI Key 驱动。

PS：官方现在已经把chatgpt桌面和codex桌面合并一起了，并且命名为 chatgpt，所以你下载的时候，估计是chatgpt哈

本教程专注于 Codex Desktop 桌面客户端的安装，以及使用 HOHAI 中转 API 的完整配置流程。跟着一步步操作，几分钟即可上手。

一、Codex Desktop 是什么？

Codex Desktop 是 OpenAI 推出的 AI 编程桌面客户端，官方将其定义为"用于管理 AI 编程代理（agents）的开发工作中心"。

简单来说，它就是一个 AI + IDE + 自动化开发助手，核心能力包括：

• 🤖 AI 自动编写、修改、调试代码
• 🔍 智能查 Bug 并给出修复方案
• 📝 自动生成测试用例和技术文档
• 🔄 自动化开发任务（部署、整理代码等）
• 👥 支持多个 AI Agent 同时工作，每个任务有独立 workspace
• 🌐 支持多种模型（gpt-5.6-sol、gpt-5.6-luna 等）
• 🌍 支持中文界面

二、安装 Codex Desktop

macOS 用户

1. 打开 App Store
2. 搜索 Codex
3. 点击下载安装即可

Windows 用户

1. 访问微软商店：https://apps.microsoft.com/detail/9plm9xgg6vks
2. 点击 获取 / 下载
3. 按提示完成安装

系统要求：Windows 10 19041 以上，需联网

切换中文界面

安装完成后首次打开默认为英文界面，手动切换方法：

1. 打开 Codex Desktop
2. 点击左上角 File → Settings
3. 进入 General
4. 找到 Language for the app UI，选择 Chinese (China)
5. 如果未生效，请确保网络通畅（需下载语言包），然后重启软件

注意：改成中文时，软件会下载语言包，你需要开着全局VPN状态，否则会改不了中文。

三、HOHAI 中转 API 配置

PS：如果你已经之前通过命令行正常配置且可以正常使用codex了，那就不需要再配置了

安装完 Codex Desktop 后，还需要配置 API 才能使用。这里我们使用 HOHAI 中转 API 平台，支持 Claude Code、Gemini Pro、OpenAI Codex 等模型，按量计费，扣费透明。

第一步：注册并获取 API Key

1. 访问 HOHAI 官网 并注册账号
2. 登录后，点击 接口密钥 页面
3. 点击 创建新密钥
4. 关键配置（务必注意）：
   • 密钥类型/分组：务必选择 codex（否则无法使用！）
   • 令牌名称：随意填写
5. 创建成功后，复制生成的 API Key（格式为 sk-xxx），妥善保存

⚠️ 重要提醒：API Key 只在创建时显示一次，请立即复制保存！

第二步：创建配置文件

Codex Desktop 的配置文件位于用户主目录下的 .codex 文件夹中，需要创建两个文件：auth.json 和 config.toml。

配置目录位置：

• Windows：C:\Users\<你的用户名>\.codex\
• macOS：/Users/<你的用户名>/.codex/

Windows 用户操作步骤：

1. 打开文件资源管理器，导航到 C:\Users\<你的用户名>\
2. 如果看不到 .codex 目录，请先开启 "显示隐藏的项目"（查看 → 显示 → 隐藏的项目）
3. 如果没有 .codex 文件夹，手动创建
4. 在其中创建 auth.json 和 config.toml 两个文件

macOS 用户操作步骤：

打开终端（Terminal），执行以下命令：

mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml

第三步：编辑 auth.json

将以下内容写入 auth.json（将 sk-xxx 替换为你自己的 API Key）：

{"OPENAI_API_KEY":"sk-xxx"}

注意注意注意，auth.json文件里，只保留上面这一行内容，如果有其他，麻烦全部删除，一定要删除，一定要删除，一定要删除，否则会报401

第四步：编辑 config.toml

将以下内容写入 config.toml：

model_provider = "hohai"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.hohai]
name = "hohai"
base_url = "https://api.hohai.eu.org/v1"
wire_api = "responses"
requires_openai_auth = true

注意注意注意，上面这些内容，一定要放在config文件最上面，一定要放在最上面，一定要放在最上面！！！！否则会报错

各配置项说明：

• model_provider — 自定义提供商名称，需与下方 [model_providers.xxx] 对应
• model — 使用的模型名称，可选 gpt-5.6-luna、gpt-5.5 等
• model_reasoning_effort — 模型思考努力程度，可选 high（高）、medium（中）、low（低）
• disable_response_storage — 禁用响应存储（建议开启）
• preferred_auth_method — 认证方式，使用 API Key 时设为 apikey
• base_url — HOHAI 中转 API 地址
• wire_api — API 协议格式，codex 使用 responses

💡 切换模型：如果想使用最新的 gpt-5.6-luna，将 model = "gpt-5.6-sol" 改为 model = "gpt-5.6-luna" 即可。

第五步：Desktop 客户端内指定配置路径（可选）

Codex Desktop 会自动读取 .codex 目录下的配置文件。如果配置后未生效，可手动指定：

1. 打开 Codex Desktop
2. 进入 设置 → 配置
3. 在 Custom config.toml settings 下的 user config 中填写配置文件路径
   • Windows：C:\Users\<你的用户名>\.codex\config.toml
   • macOS：/Users/<你的用户名>/.codex/config.toml

四、启动与验证

1. 打开 Codex Desktop 应用
2. 输入一句简单的测试内容，例如：hello
3. 如果能正常回复，说明 API 配置成功 ✅

五、使用技巧

你可以直接给 Codex 一个任务目标，它会自动规划并执行。以下是常见使用场景：

写代码 — 帮我写一个 Python 爬虫，抓取豆瓣电影 Top250

修改代码 — 给这个项目添加用户登录功能

查 Bug — 这段代码报了 NullPointerException，帮我排查

写测试 — 为 src/utils.js 中的所有函数编写单元测试

写文档 — 帮我写一份 API 接口文档

代码重构 — 重构这个模块，使用设计模式优化代码结构

自动化任务 — 帮我配置 CI/CD 流水线

使用建议：

• 给出清晰的任务目标，Codex 会自动规划并执行
• 可以同时开启多个 Agent 处理不同任务
• 查看 Code Diff 确认修改内容后再应用

六、常见问题排查

Q：安装后打开软件无法使用？

Codex Desktop 需要 API Key 才能调用模型，请确保已完成上文的 API 配置步骤。

Q：配置完成后无法正常响应？

按以下步骤逐一排查：

1. 确认 API Key 正确：登录 HOHAI，检查密钥是否选择了 codex 分组
2. 确认配置文件路径正确：Windows 为 C:\Users\<用户名>\.codex\，macOS 为 /Users/<用户名>/.codex/
3. 确认配置文件内容无误：auth.json 中的 API Key 是否正确替换，config.toml 中的 base_url 是否正确
4. 重启 Codex Desktop 后再试

Q：切换中文界面后没变化？

确保网络开着全局VPN（需要下载语言包），重新切换一次语言设置，然后重启应用。

Q：配置文件修改后不生效？

在 Desktop 客户端内手动指定配置文件路径，确认文件编码为 UTF-8，然后重启 Codex Desktop。

参考链接

HOHAI 官网：https://api.hohai.eu.org/

Codex Desktop Windows 版：https://apps.microsoft.com/detail/9plm9xgg6vks

Codex 官方文档：https://github.com/openai/codex

Claude Code 桌面版配置

带图形界面的 Claude Code。用它自带的 Developer → Configure Third-Party Inference 面板接入，Gateway base URL 填 https://api.hohai.eu.org（不带 /v1）。

关于 Claude Code 桌面版

桌面应用为您提供具有图形界面的 Claude Code，专为并行运行多个会话而构建：用于管理并行工作的侧边栏、带有集成终端和文件编辑器的拖放布局、可视化差异审查、实时应用预览、GitHub PR 监控和自动合并以及计划任务。无需终端。

核心优势：

• ✅ 无需订阅，无需登录 Claude Code 账号直接使用
• ✅ HOHAI 一个密钥切换使用平台支持的多个模型
• ✅ 保留 Claude Desktop 所有原生功能（Artifacts、Projects、长上下文、代码解释器等）

📋 准备工作

第一步：下载 Claude Code 桌面版

前往官方下载地址：https://claude.com/download

• macOS（Intel 和 M 系列芯片）
• Windows（x64）
• Windows ARM64（仅限远程会话）

第二步：创建 API 令牌

创建一个 API 令牌 密钥，分组使用 claude 分组

⚙️ 配置 API 方法

步骤 1：开启开发者模式

打开 Claude Desktop，在顶部菜单栏依次选择：

Help（帮助）→ Troubleshooting（故障排除）→ Enable developer mode（启用开发者模式）

应用会自动重启。

步骤 2：进入 API 配置界面

顶部会新出现 Developer（开发者） 选项 → 点击 Configure Third-Party Inference（配置第三方推理），会弹出一个第三方的 API 配置面板。

步骤 3：填写 API 令牌配置

• Gateway base URL（API 地址）：https://api.hohai.eu.org
• Gateway API key（API 令牌）：粘贴你自己生成的 sk- 开头的密钥

步骤 4：配置模型 ID

下拉到 Model list，点击 +Add，填入平台上支持 Anthropic 协议的模型 ID，例如：

• claude-opus-4-7

最后点击 Apply locally 重启应用完成配置。

✅ 验证使用

完全退出 Claude Desktop（包括后台进程），然后重新打开。重启后，在聊天界面的模型选择中，你就能看到自己配置的模型 ID 了！

Gemini CLI 配置

Google 的开源命令行工具，走 Gemini 原生协议，网关地址填 https://api.hohai.eu.org/v1beta。

基本介绍

Gemini CLI 是谷歌提供的开源命令行 AI 工具，将 Gemini 的强大功能直接带入您的终端。它提供轻量级的 Gemini 访问方式，为您提供从提示到模型的最直接路径。通过设置中转站（代理），您可以在网络受限的情况下正常使用 Gemini CLI 服务。

🚀 为什么选择 Gemini CLI？

• 🧠 强大的 Gemini 3.0 Pro：访问 100 万 token 上下文窗口
• 🔧 内置工具：Google 搜索基础功能、文件操作、Shell 命令、网页抓取
• 🔌 可扩展：支持 MCP（模型上下文协议）进行自定义集成
• 💻 终端优先：专为在命令行中工作的开发者设计
• 🛡️ 开源：Apache 2.0 许可证

📦 安装方式

快速安装

使用 npx 即时运行（无需安装）

# 使用官方仓库
npx https://github.com/google-gemini/gemini-cli

使用 npm 全局安装

npm install -g @google/gemini-cli

使用 Homebrew 安装（macOS/Linux）

brew install gemini-cli

系统要求

• Node.js 版本 20 或更高
• macOS、Linux 或 Windows

配置

方式一：使用配置文件（推荐）

步骤 1：创建配置目录

Gemini CLI 的全局配置文件位于用户主目录下的 .gemini 文件夹中,请确保该目录存在，如果不存在请手动创建。

• Windows: C:\Users\用户名文件夹\ .gemini
• macOS / Linux: ~/.gemini

步骤 2：在 .gemini 目录下创建 .env 文件，添加以下内容：

GOOGLE_GEMINI_BASE_URL=https://api.hohai.eu.org/v1beta
GEMINI_API_KEY=YOUR_API_TOKEN_HERE
GEMINI_MODEL=gemini-3.1-pro

参数说明：

• GEMINI_API_KEY: 这是你创建的key
• GEMINI_MODEL: 你想要使用的模型（默认为 gemini-3.1-pro）

注意，YOUR_API_TOKEN_HERE 需要改成你在接口密钥那里创建的key哦，sk- 开头那个。

步骤 3：在 .gemini 目录下创建 settings.json 文件，内容如下：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

方式二： 设置环境变量

在使用中转站之前，您需要配置以下环境变量 macOS / Linux:

# 设置 API 密钥
export GEMINI_API_KEY=sk-xxxxx

# 设置 API 中转站地址
export GOOGLE_GEMINI_BASE_URL=https://api.hohai.eu.org/v1beta

# 设置使用的模型 ID
export GEMINI_MODEL="gemini-3.1-pro"

注意：您也可以将这些环境变量添加到 .bashrc、.zshrc 或其他 shell 配置文件中，这样每次启动终端时都会自动设置这些变量。

Windows (PowerShell):

setx GOOGLE_GEMINI_BASE_URL "https://api.hohai.eu.org/v1beta"
setx GEMINI_API_KEY "YOUR_API_TOKEN_HERE"
setx GEMINI_MODEL "gemini-3.1-pro"

🚀 快速开始

基本使用

在当前目录启动

gemini

包含多个目录

gemini --include-directories ../lib,../docs

使用特定模型

gemini -m gemini-3.8-flash

脚本非交互模式

获取简单文本响应：

gemini -p "解释这个代码库的架构"

获取结构化 JSON 输出：

gemini -p "解释这个代码库的架构" --output-format json

快速示例

启动新项目

cd new-project/
gemini
> 为我编写一个 Discord 机器人，使用我提供的 FAQ.md 文件回答问题

分析现有代码

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> 给我一个昨天所有更改的摘要

📋 主要功能

代码理解与生成

• 查询和编辑大型代码库
• 使用多模态能力从 PDF、图片或草图生成新应用
• 使用自然语言调试问题和故障排除

自动化与集成

• 自动化操作任务，如查询拉取请求或处理复杂的变基操作
• 使用 MCP 服务器连接新功能
• 在脚本中非交互式运行以实现工作流自动化

高级功能

• 使用内置 Google 搜索获取实时信息
• 对话检查点以保存和恢复复杂会话
• 自定义上下文文件（GEMINI.md）为您的项目定制行为

常用命令和功能示例

探索代码库

> 描述这个系统架构的主要组成部分
> 有哪些安全机制？
> 为新开发者提供一份分步骤的入门文档

处理现有代码

> 为 GitHub issue #123 实现一个初稿
> 帮我将这个代码库迁移到最新版本的 Java。先制定一个计划

自动化工作流程

> 制作一个幻灯片，展示过去 7 天的 git 历史，按功能和团队成员分组
> 制作一个全屏 Web 应用用于墙上显示，展示我们互动最多的 GitHub issues

系统交互

> 将此目录中的所有图像转换为 png，并使用 exif 数据中的日期重命名它们
> 按支出月份整理我的 PDF 发票

GitHub 集成

使用 Gemini CLI GitHub Action 将 Gemini CLI 直接集成到您的 GitHub 工作流中：

• 拉取请求审查：自动代码审查，提供上下文反馈和建议
• Issue 分类：基于内容分析自动标记和优先级排序 GitHub issues
• 按需帮助：在 issues 和拉取请求中提及 @gemini-cli 获取调试、解释或任务委派的帮助
• 自定义工作流：构建适合您团队需求的自动化、定时和按需工作流

故障排除

如果您在使用过程中遇到问题，可以参考以下几点：

1. 检查环境变量是否正确设置：

   echo $GEMINI_API_KEY
   echo $GOOGLE_GEMINI_BASE_URL

2. 检查网络连接是否稳定，中转站是否可访问：

   curl -I https://api.hohai.eu.org/

3. 查看是否有错误信息输出，这些信息通常会指示问题所在
4. 如果使用 SOCKS 代理，确保代理格式正确，例如 socks5://<user>:<pass>@<proxy>:<port>
5. 使用内置命令报告问题：

   # 在 CLI 中直接报告 bug
   /bug

发布版本说明

预览版（Preview）

每周二 UTC 23:59 发布新的预览版本。使用 preview 标签安装：

npm install -g @google/gemini-cli@preview

稳定版（Stable）

每周二 UTC 20:00 发布新的稳定版本。使用 latest 标签安装：

npm install -g @google/gemini-cli@latest

每夜版（Nightly）

每天 UTC 00:00 发布每夜版本。使用 nightly 标签安装：

npm install -g @google/gemini-cli@nightly

MCP 服务器使用

在 ~/.gemini/settings.json 中配置 MCP 服务器以扩展 Gemini CLI 的自定义工具：

> @github 列出我的开放拉取请求
> @slack 向 #dev 频道发送今天提交的摘要
> @database 运行查询查找不活跃用户

📚 相关资源

• 官方路线图：查看即将推出的功能
• NPM 包：包注册表
• GitHub Issues：报告 bug 或请求功能
• 安全建议：安全更新

卸载

如果您需要卸载 Gemini CLI，请参考官方的卸载指南。

OpenCode 配置

终端里的 AI 编码代理。先用 opencode auth login 注册自定义 provider，再到 opencode.json 里把 baseURL 指向 HOHAI。

基本介绍

OpenCode 是一款专为终端打造的 AI 编码代理工具，通过优化的键盘操作流程为命令行用户提供高效的开发体验。其客户端/服务器分离架构不仅支持本地运行，还可通过移动应用实现远程控制。

📦 安装 OpenCode

可通过 NPM 命令安装 OpenCode 官方 CLI 程序：

npm i -g opencode-ai@latest

此外 OpenCode 官网 https://opencode.ai 也提供应用程序插件等其他安装方式。

⚙️ 接入步骤

步骤 1：初始化服务商（Provider）

先不要直接启动 OpenCode，而是在终端中执行以下命令：

opencode auth login

然后在服务商列表中，选择 other（在最下面，可以直接搜索）。

系统会提示你输入：

• Provider ID：请填写一个唯一标识名（例如 hohai），后续配置需与之严格一致
• API Key 令牌：可填写任意内容（如 admin），因为实际密钥可通过配置文件安全引用

💡 这一步的作用是让 OpenCode 在本地凭证管理器中注册一个自定义服务商，便于后续引用密钥。

步骤 2：修改配置文件接入 API

打开 OpenCode 配置目录：

• macOS / Linux：~/.config/opencode/
• Windows：Users\你的用户名\.config\opencode

在该目录下创建或编辑配置文件 opencode.json，内容如下：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hohai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HOHAI",
      "options": {
        "baseURL": "https://api.hohai.eu.org/v1",
        "apiKey": "sk-XXXXXXXX"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT-5.6-sol"
        }
      }
    }
  }
}

⚠️ 注意："hohai" 必须和步骤 1 中输入的 Provider ID 完全一致！apiKey 改为你自己的 API 令牌。

步骤 3：重启并验证

保存配置文件后，运行 OpenCode：

opencode

在聊天界面输入命令：

/models

即可在模型列表中看到你配置的中转站及其模型（如 "GPT-5.6-sol"）。选择后即可正常使用！

⚠️ 注意事项

• Provider ID 必须一致：配置文件中的键名必须与 auth login 时输入的 ID 完全相同（区分大小写）
• API 令牌：令牌分组建议使用 Default 默认分组（所有模型可用），打开无限额度，永不过期
• API 地址格式：确保 baseURL 正确，可先用 curl 或 Postman 测试是否响应
• 若修改配置后未生效，请尝试完全退出 OpenCode 并重新启动

N8N 工作流接入

N8N 通过内置的 OpenAI 节点调用 HOHAI，只需要把 Base URL 改成网关地址即可。

第 1 步：新建工作流

在 N8N 里新建一个工作流（Workflow）。

第 2 步：选择触发方式

先加一个触发器，例如 Manual Trigger（手动触发），方便边配边测。

第 3 步：添加 OpenAI 节点

点击 + 添加下一个节点，在节点列表里搜索并选择 OpenAI。

第 4 步：选择操作类型

Resource 选 Text，Operation 选 Message a Model。聊天场景必须选这一项，其他操作走的是另一套接口。

第 5 步：填写凭证接入 HOHAI

在 Credential 里点 Create new credential，按下面填写：

填好后点 Save。提示连接成功就说明地址和 Key 都对了。

第 6 步：选模型并测试运行

1. 把 Model 填成 gpt-5.6-luna，或者直接手填你想用的模型 ID。
2. 在 Messages 里加一条 User 消息，内容填 你好。
3. 点击 Execute Step，能看到模型正常返回文本就说明接入成功。

在 Codex 里生成图片

Codex 不会主动把生图请求发到中转站，需要把 base URL、Key 和请求格式一次讲清楚，并让它用流式请求避免超时。

image2生图不能在codex直接说我要生图，不然会自动调用 官方的api 去生图，所以你，你需要显性告诉codex去哪里调用，显性告诉他 baseurl + key，并且让他用流，这样才不会超时。

反正很简单，你在codex调用的时候，就让他们用下面我们给的格式去生图，直接把下面的请求丢给他，并且带上你的 api key。

调用格式

文生图

curl --http1.1 -sS \
  -X POST "https://api.hohai.eu.org/v1/images/generations" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  --data-raw '{
    "model": "gpt-image-2",
    "prompt": "<画图提示词>",
    "size": "1024x1024",
    "quality": "medium"
  }'

图生图

curl --http1.1 -sS \
  -X POST "https://api.hohai.eu.org/v1/images/edits" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Expect:" \
  -F "model=gpt-image-2" \
  -F "prompt=<改图提示词>" \
  -F "size=1024x1024" \
  -F "quality=medium" \
  -F "image=@<参考图片路径>;type=image/png"

例子

假如我的key api是 sk-aaaaaa;那你可以这样说：

帮我生成一个图片，按照我下面给的请求格式去请求，base url和key我已经包含在下面了：

curl --http1.1 -sS \
  -X POST "https://api.hohai.eu.org/v1/images/generations" \
  -H "Authorization: Bearer sk-aaaaaa" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: application/json" \
  --data-raw '{
    "model": "gpt-image-2",
    "prompt": "<画图提示词>",
    "size": "1024x1024",
    "quality": "medium"
  }'

然后就可以了，你可以试试

Codex 历史记录迁移

把本地历史会话里的 model_provider 统一改成 hohai，切到中转站之后还能看到之前的对话。

先完全关闭 Codex 客户端，windows 用户打开 powershell 再执行下面这段脚本，mac 用户直接打开控制台(直接粘贴就行)：

这段脚本的目标就是把能检测到的所有历史记录里的 model_provider 统一改成 hohai，可以做到用中转站的同时，访问本来官号的对话

如果要迁移到其他的 provider，只需要将第二行的 $TargetProvider = "hohai" 改成你目标的名字就可以

如果你以后想要改成官方帐号登陆，会话要迁移回去的话，只需要把脚本开头的 hohai 改成 openai 即可。

windows

$CodexHome = Join-Path $env:USERPROFILE ".codex"
$TargetProvider = "hohai"
$BackupDir = Join-Path $env:USERPROFILE ("Desktop\codex-provider-to-" + $TargetProvider + "-backup-" + (Get-Date -Format yyyyMMdd-HHmmss))

if (-not (Test-Path $CodexHome)) {
  Write-Host "未找到 Codex 目录：$CodexHome" -ForegroundColor Red
  exit 1
}

New-Item -ItemType Directory -Force $BackupDir | Out-Null

Write-Host "CodexHome: $CodexHome" -ForegroundColor Cyan
Write-Host "TargetProvider: $TargetProvider" -ForegroundColor Cyan
Write-Host "BackupDir: $BackupDir" -ForegroundColor Yellow
Write-Host ""

# 备份关键数据
Copy-Item (Join-Path $CodexHome "config.toml") (Join-Path $BackupDir "config.toml") -Force -ErrorAction SilentlyContinue
Copy-Item (Join-Path $CodexHome ".codex-global-state.json") (Join-Path $BackupDir ".codex-global-state.json") -Force -ErrorAction SilentlyContinue
Copy-Item (Join-Path $CodexHome "session_index.jsonl") (Join-Path $BackupDir "session_index.jsonl") -Force -ErrorAction SilentlyContinue

$SessionsDir = Join-Path $CodexHome "sessions"
$ArchivedDir = Join-Path $CodexHome "archived_sessions"

if (Test-Path $SessionsDir) {
  Copy-Item $SessionsDir (Join-Path $BackupDir "sessions") -Recurse -Force
}

if (Test-Path $ArchivedDir) {
  Copy-Item $ArchivedDir (Join-Path $BackupDir "archived_sessions") -Recurse -Force
}

Get-ChildItem $CodexHome -File -Filter "state_*.sqlite*" -ErrorAction SilentlyContinue | ForEach-Object {
  Copy-Item $_.FullName (Join-Path $BackupDir $_.Name) -Force
}

Write-Host "备份完成。" -ForegroundColor Green
Write-Host ""

# 迁移 JSONL 里的 model_provider
$JsonChangedCount = 0
$JsonFilesScanned = 0

function Update-JsonlProvider {
  param(
    [string]$Path,
    [string]$TargetProvider
  )

  if (-not (Test-Path $Path)) {
    return
  }

  $script:JsonFilesScanned++

  $Text = Get-Content $Path -Raw -Encoding UTF8

  if ($Text -notmatch '"model_provider"\s*:') {
    return
  }

  $NewText = [regex]::Replace(
    $Text,
    '"model_provider"\s*:\s*"[^"]*"',
    '"model_provider":"' + $TargetProvider + '"'
  )

  if ($NewText -ne $Text) {
    $Utf8NoBom = New-Object System.Text.UTF8Encoding($false)
    [System.IO.File]::WriteAllText($Path, $NewText, $Utf8NoBom)
    $script:JsonChangedCount++
    Write-Host "JSONL updated: $Path"
  }
}

if (Test-Path $SessionsDir) {
  Get-ChildItem $SessionsDir -Recurse -File -Filter "*.jsonl" -ErrorAction SilentlyContinue | ForEach-Object {
    Update-JsonlProvider -Path $_.FullName -TargetProvider $TargetProvider
  }
}

if (Test-Path $ArchivedDir) {
  Get-ChildItem $ArchivedDir -Recurse -File -Filter "*.jsonl" -ErrorAction SilentlyContinue | ForEach-Object {
    Update-JsonlProvider -Path $_.FullName -TargetProvider $TargetProvider
  }
}

$SessionIndex = Join-Path $CodexHome "session_index.jsonl"
if (Test-Path $SessionIndex) {
  Update-JsonlProvider -Path $SessionIndex -TargetProvider $TargetProvider
}

Write-Host ""
Write-Host "JSONL 迁移完成。" -ForegroundColor Green
Write-Host "- 扫描文件数：$JsonFilesScanned"
Write-Host "- 改写文件数：$JsonChangedCount"
Write-Host ""

# 迁移 SQLite 里的 model_provider
$sqlite3 = Get-Command sqlite3 -ErrorAction SilentlyContinue

if (-not $sqlite3) {
  Write-Host "未找到 sqlite3，跳过 SQLite 迁移。" -ForegroundColor Yellow
  Write-Host "如果 Codex 客户端仍不显示历史，安装 sqlite3 后再跑一次。"
  Write-Host "可用命令：winget install SQLite.SQLite"
} else {
  $SqliteChangedDbs = 0

  Get-ChildItem $CodexHome -File -Filter "state_*.sqlite" -ErrorAction SilentlyContinue | ForEach-Object {
    $Db = $_.FullName
    Write-Host "SQLite: $Db" -ForegroundColor Cyan

    $Tables = sqlite3 $Db "SELECT name FROM sqlite_master WHERE type='table';"

    $DbChanged = $false

    foreach ($Table in $Tables) {
      if ([string]::IsNullOrWhiteSpace($Table)) {
        continue
      }

      $Cols = sqlite3 $Db "PRAGMA table_info('$Table');"
      $HasModelProvider = $false

      foreach ($Col in $Cols) {
        $Parts = $Col -split "\|"
        if ($Parts.Count -ge 2 -and $Parts[1] -eq "model_provider") {
          $HasModelProvider = $true
          break
        }
      }

      if ($HasModelProvider) {
        Write-Host "  table: $Table"
        Write-Host "  before:"
        sqlite3 $Db "SELECT model_provider, COUNT(*) FROM '$Table' GROUP BY model_provider ORDER BY COUNT(*) DESC;"

        sqlite3 $Db "UPDATE '$Table' SET model_provider = '$TargetProvider' WHERE model_provider IS NOT NULL AND model_provider != '$TargetProvider';"

        Write-Host "  after:"
        sqlite3 $Db "SELECT model_provider, COUNT(*) FROM '$Table' GROUP BY model_provider ORDER BY COUNT(*) DESC;"

        $DbChanged = $true
      }
    }

    if ($DbChanged) {
      sqlite3 $Db "PRAGMA wal_checkpoint(TRUNCATE);" | Out-Null
      $SqliteChangedDbs++
    }

    Write-Host ""
  }

  Write-Host "SQLite 迁移完成，处理数据库数：$SqliteChangedDbs" -ForegroundColor Green
}

Write-Host ""
Write-Host "迁移完成。" -ForegroundColor Green
Write-Host "备份目录：$BackupDir" -ForegroundColor Yellow
Write-Host ""
Write-Host "现在确认 config.toml 里是："
Write-Host "model_provider = `"$TargetProvider`"" -ForegroundColor Cyan
Write-Host ""
Write-Host "然后重启 Codex 客户端。"

Mac

CODEX_HOME="$HOME/.codex"
TARGET_PROVIDER="hohai"
BACKUP_DIR="$HOME/Desktop/codex-provider-to-${TARGET_PROVIDER}-backup-$(date +%Y%m%d-%H%M%S)"

if [ ! -d "$CODEX_HOME" ]; then
  echo "未找到 Codex 目录：$CODEX_HOME"
  exit 1
fi

mkdir -p "$BACKUP_DIR"

echo "CodexHome: $CODEX_HOME"
echo "TargetProvider: $TARGET_PROVIDER"
echo "BackupDir: $BACKUP_DIR"
echo ""

# 备份关键数据
cp -f "$CODEX_HOME/config.toml" "$BACKUP_DIR/config.toml" 2>/dev/null || true
cp -f "$CODEX_HOME/.codex-global-state.json" "$BACKUP_DIR/.codex-global-state.json" 2>/dev/null || true
cp -f "$CODEX_HOME/session_index.jsonl" "$BACKUP_DIR/session_index.jsonl" 2>/dev/null || true

if [ -d "$CODEX_HOME/sessions" ]; then
  cp -R "$CODEX_HOME/sessions" "$BACKUP_DIR/sessions"
fi

if [ -d "$CODEX_HOME/archived_sessions" ]; then
  cp -R "$CODEX_HOME/archived_sessions" "$BACKUP_DIR/archived_sessions"
fi

find "$CODEX_HOME" -maxdepth 1 -type f -name "state_*.sqlite*" -exec cp -f {} "$BACKUP_DIR/" \;

echo "备份完成。"
echo ""

# 迁移 JSONL 里的 model_provider
JSON_CHANGED_COUNT=0

replace_jsonl_provider() {
  local file="$1"

  if grep -q '"model_provider"' "$file"; then
    perl -0pi -e 's/"model_provider"\s*:\s*"[^"]*"/"model_provider":"'"$TARGET_PROVIDER"'"/g' "$file"
    JSON_CHANGED_COUNT=$((JSON_CHANGED_COUNT + 1))
    echo "JSONL updated: $file"
  fi
}

if [ -d "$CODEX_HOME/sessions" ]; then
  while IFS= read -r file; do
    replace_jsonl_provider "$file"
  done < <(find "$CODEX_HOME/sessions" -type f -name "*.jsonl")
fi

if [ -d "$CODEX_HOME/archived_sessions" ]; then
  while IFS= read -r file; do
    replace_jsonl_provider "$file"
  done < <(find "$CODEX_HOME/archived_sessions" -type f -name "*.jsonl")
fi

if [ -f "$CODEX_HOME/session_index.jsonl" ]; then
  replace_jsonl_provider "$CODEX_HOME/session_index.jsonl"
fi

echo ""
echo "JSONL 迁移完成，改写文件数：$JSON_CHANGED_COUNT"
echo ""

# 迁移 SQLite 里的 model_provider
if ! command -v sqlite3 >/dev/null 2>&1; then
  echo "未找到 sqlite3，跳过 SQLite 迁移。"
  echo "macOS 一般自带 sqlite3，如果没有，需要先安装。"
else
  SQLITE_CHANGED_DBS=0

  for db in "$CODEX_HOME"/state_*.sqlite; do
    [ -f "$db" ] || continue

    echo "SQLite: $db"

    TABLES=$(sqlite3 "$db" "SELECT name FROM sqlite_master WHERE type='table';")

    DB_CHANGED=0

    while IFS= read -r table; do
      [ -n "$table" ] || continue

      HAS_COL=$(sqlite3 "$db" "PRAGMA table_info(\"$table\");" | awk -F'|' '$2=="model_provider"{print $2}')

      if [ "$HAS_COL" = "model_provider" ]; then
        echo "  table: $table"
        echo "  before:"
        sqlite3 "$db" "SELECT model_provider, COUNT(*) FROM \"$table\" GROUP BY model_provider ORDER BY COUNT(*) DESC;"

        sqlite3 "$db" "
          UPDATE \"$table\"
          SET model_provider = '$TARGET_PROVIDER'
          WHERE model_provider IS NOT NULL
            AND model_provider != '$TARGET_PROVIDER';
        "

        echo "  after:"
        sqlite3 "$db" "SELECT model_provider, COUNT(*) FROM \"$table\" GROUP BY model_provider ORDER BY COUNT(*) DESC;"

        DB_CHANGED=1
      fi
    done <<< "$TABLES"

    if [ "$DB_CHANGED" = "1" ]; then
      sqlite3 "$db" "PRAGMA wal_checkpoint(TRUNCATE);" >/dev/null 2>&1 || true
      SQLITE_CHANGED_DBS=$((SQLITE_CHANGED_DBS + 1))
    fi

    echo ""
  done

  echo "SQLite 迁移完成，处理数据库数：$SQLITE_CHANGED_DBS"
fi

echo ""
echo "迁移完成。"
echo "备份目录：$BACKUP_DIR"
echo ""
echo "现在确认 ~/.codex/config.toml 里是："
echo "model_provider = \"hohai\""
echo ""
echo "然后重启 Codex 客户端。"

Pi 配置

终端里的 AI 编程代理。在 ~/.pi/agent/models.json 里注册自定义 provider，按格式选 openai-responses 或 anthropic-messages。

Pi 是一个可在终端中运行的 AI 编程代理。本文介绍 Pi 的安装方法，以及如何通过 models.json 配置 HOHAI。

说明：本文中的模型名称仅为示例。请将 models[].id 替换为你的中转站实际支持的模型 ID。

官方地址

• Pi 官网
• Pi 文档
• 自定义模型配置文档

一、系统要求

• Windows 10/11、macOS 或主流 Linux 发行版
• Node.js 22 或更高版本
• npm 10 或更高版本
• 可访问 npm 仓库和中转站 API 的网络连接

检查 Node.js 和 npm 版本：

node --version
npm --version

二、安装 Pi

方式一：官方安装脚本

macOS / Linux

curl -fsSL https://pi.dev/install.sh | sh

Windows PowerShell

powershell -c "irm https://pi.dev/install.ps1 | iex"

方式二：npm

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

方式三：pnpm

pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent

方式四：Bun

bun add -g --ignore-scripts @earendil-works/pi-coding-agent

验证安装

pi --version

如果系统提示找不到 pi 命令，请重新打开终端，让新的 PATH 配置生效。

三、配置文件位置

Pi 使用以下文件配置自定义提供商和模型：

Windows 也可以写成：

%USERPROFILE%\.pi\agent\models.json

例如，用户名为 123 时，完整路径是：

C:\Users\123\.pi\agent\models.json

创建配置文件

Windows PowerShell

$piDir = Join-Path $env:USERPROFILE ".pi\agent"
New-Item -ItemType Directory -Force $piDir | Out-Null
notepad (Join-Path $piDir "models.json")

macOS / Linux

mkdir -p ~/.pi/agent
vim ~/.pi/agent/models.json

四、配置 OpenAI 兼容中转站（Codex）

{
  "providers": {
    "hohai": {
      "baseUrl": "https://api.hohai.eu.org/v1",
      "api": "openai-responses",
      "apiKey": "你的API密钥",
      "models": [
        {
          "id": "gpt-5.6-sol",
          "name": "GPT-5.6 Sol",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 16384
        }
      ]
    }
  }
}

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

配置文件中写：

"apiKey": "$PI_RELAY_API_KEY"

Windows PowerShell：

$env:PI_RELAY_API_KEY = "你的API密钥"

macOS / Linux：

export PI_RELAY_API_KEY="你的API密钥"

五、配置 Anthropic 兼容中转站（Claude）

{
  "providers": {
    "hohai": {
      "baseUrl": "https://api.hohai.eu.org",
      "api": "anthropic-messages",
      "apiKey": "你的API密钥",
      "models": [
        {
          "id": "claude-opus-5",
          "name": "Claude Opus 5",
          "reasoning": true,
          "input": ["text", "image"]
        }
      ]
    }
  }
}

六、接口类型对照

根据中转站提供的接口选择 api：

七、启动和选择模型

进入项目目录：

cd 你的项目目录

启动 Pi：

pi

在 Pi 中输入以下命令打开模型选择器：

/model

选择你在 models.json 中配置的提供商和模型即可。

Pi 每次打开 /model 时都会重新读取 models.json，修改配置后通常不需要重启 Pi。

Hermes 配置

Nous Research 的自我改进型代理。安装脚本跑完后，在配置向导里选 Custom endpoint，把 API base URL 填成 https://api.hohai.eu.org。

关于 Hermes

由 Nous Research 开发的自我改进的 AI 代理工具。唯一具备内置学习循环的代理——它通过经验创造技能，在使用过程中改进技能，推动自身坚持掌握知识，并逐步建立一个跨会话中自我认知的深入模型。

• 官网：https://hermes-agent.nousresearch.com
• GitHub：https://github.com/nousresearch/hermes-agent

安装要求：

• 系统：Linux、macOS，Windows 用户需要先安装 WSL2（Windows 子系统 Linux）；安卓手机用户可以用 Termux
• 模型：要求大模型至少支持 64,000 token 的上下文窗口

📦 第一步：运行安装脚本

打开终端命令行工具运行以下安装脚本，安装脚本会自动处理所有依赖——Python、Node.js、ripgrep、ffmpeg，全部帮你装好。装完之后会自动进入配置向导。

Linux / macOS / WSL2：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Windows PowerShell：

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

安卓 / Termux：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

验证是否安装成功：

hermes doctor

看到全部是绿色 ✅，第一步安装过程就完成了。

⚙️ 第二步：配置 API 令牌

1. 进入配置向导

安装完成后会自动进入配置向导，选 Quick setup 即可快速上手。

或者使用以下命令手动进入：

hermes setup

2. 选择模型供应商

选择最下面的：Custom endpoint (enter URL manually)

3. 填写配置信息

• API base URL：https://api.hohai.eu.org
• API key：你创建的 API 令牌
• Select model 模型 ID：输入平台上支持的模型 ID

其他两项直接回车即可，然后可以选择配置聊天客户端或者跳过完成设置。

输入 Y 回车即可进入终端聊天界面。

🚀 使用 Hermes

启动聊天对话：

hermes

更新到最新版本：

hermes update

检查当前安装版本：

hermes version

重新配置单个设置：

hermes model          # 选择 LLM 供应商和模型
hermes tools          # 配置启用的工具
hermes gateway setup  # 设置消息平台
hermes config set     # 设置单个配置值
hermes setup          # 运行完整配置向导

手动卸载：

rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent
rm -rf ~/.hermes

cc-switch 切换工具

如果你经常在官方 API 和 HOHAI 之间切换，可以使用 cc-switch 管理环境变量。这样不需要每次手动修改配置。

安装

npm install -g cc-switch

添加 HOHAI 配置

cc-switch add hohai \
  --anthropic-url https://api.hohai.eu.org \
  --openai-url https://api.hohai.eu.org/v1 \
  --key sk-your-api-key

切换到 HOHAI

cc-switch use hohai

查看当前配置

cc-switch status

切换回官方 API

cc-switch use official

Node.js 安装

Claude Code、Codex CLI、cc-switch 通常都需要 Node.js 和 npm。建议使用 Node.js LTS 版本。

先检查是否已安装

node -v
npm -v

如果提示 command not found，说明没有安装。

macOS 安装

# 方式 1：Homebrew
brew install node

# 方式 2：nvm，适合需要切换 Node 版本的用户
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

Windows 安装

winget install OpenJS.NodeJS.LTS

也可以到 Node.js 官网下载安装包。安装完成后，重新打开 PowerShell，再运行 node -v。

Ubuntu / Debian Linux 安装

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

验证安装成功

node -v
npm -v

验证是否配置成功

配置完成后，建议先做最小测试。

检查环境变量是否存在（不打印密钥）

macOS / Linux

test -n "$ANTHROPIC_BASE_URL" && echo "ANTHROPIC_BASE_URL 已设置"
test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY 已设置"
test -n "$OPENAI_BASE_URL" && echo "OPENAI_BASE_URL 已设置"
test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY 已设置"

Windows PowerShell

@("ANTHROPIC_BASE_URL","ANTHROPIC_API_KEY","OPENAI_BASE_URL","OPENAI_API_KEY") |
  ForEach-Object {
    if ([string]::IsNullOrWhiteSpace([Environment]::GetEnvironmentVariable($_))) {
      "$_ 未设置"
    } else {
      "$_ 已设置"
    }
  }

文本对话 curl 测试

curl https://api.hohai.eu.org/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "请用一句话回答：API 是否连接成功？"}
    ]
  }'

图像生成 curl 测试

curl https://api.hohai.eu.org/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A simple blue circle on a white background.",
    "size": "1024x1024",
    "n": 1
  }'

文本接口成功结果

如果文本请求成功，你会看到一段 JSON 返回，其中一般包含：

• id：请求编号；
• choices：模型返回内容；
• usage：token 用量；
• model：实际调用模型。

生图接口成功结果

生图请求成功时，data 数组至少有一项，并且返回项包含 url 或 b64_json。如果返回 Base64，需要先解码保存为图片文件。

常见错误

401 Unauthorized

含义：API Key 无效、未填写、复制错误，或环境变量没有生效。

处理方法：

1. 确认命令里的 sk-your-api-key 已替换成真实 Key。
2. 确认 Key 没有多复制空格、换行或中文引号。
3. 检查环境变量：

test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY 已设置"
 test -n "$OPENAI_API_KEY" && echo "OPENAI_API_KEY 已设置"

404 Not Found

含义：Base URL 路径错误。最常见原因是 /v1 加错或漏加。

• Claude Code：https://api.hohai.eu.org，不带 /v1。
• Codex / OpenClaw / OpenAI SDK：https://api.hohai.eu.org/v1，带 /v1。

model not found / 模型不存在

常见原因：

• 模型名拼写错误；
• 账号未开通该模型；
• 工具使用了默认模型，但该模型不在你的可用列表中；
• Claude 模型被当成 OpenAI 模型调用，或反过来。

处理方法：进入控制台查看可用模型列表并复制完整模型名，也可以对照本文档的 支持的模型。

图像模型错误：No eligible media accounts

含义：当前没有可调度的图像媒体账号，或该图像渠道没有余额、权限或可用配额。

处理方法：确认图像模型对应的渠道已启用，再检查媒体账号状态、额度和冷却状态；更换模型前先确认模型详情页的接口类型。

图像接口返回 502 / 524

含义：图像上游渠道错误、连接被网关关闭或等待上游响应超时。

处理方法：先确认请求使用的是 /v1/images/generations、模型 ID 和 JSON 字段正确，再稍后重试；如果持续出现，应检查对应图像渠道日志。

insufficient_quota / balance not enough / 余额不足

含义：账号余额不足、Key 的每日预算不足，或该模型消耗超过限制。

处理方法：

• 检查余额；
• 检查 API Key 的每日限额；
• 换用低成本模型测试；
• 避免一次性设置过大的 max_tokens。

rate_limit_exceeded / 429

含义：请求频率过高，超过 RPM/TPM/并发限制。

处理方法：

• 降低并发；
• 增加请求间隔；
• 检查代码里是否出现循环重试；
• 必要时联系平台调整限额。

Connection refused / timeout

含义：网络连接失败、地址填错、代理异常或服务临时不可用。

处理方法：

1. 确认 Base URL 正确。
2. 浏览器打开 https://api.hohai.eu.org 看是否能访问。
3. 检查本机代理、VPN、防火墙设置。
4. 稍后重试，或查看平台公告。

npm 权限错误：EACCES

macOS / Linux 安装全局 npm 包时可能遇到权限错误。推荐修改 npm 全局目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

node: command not found

说明 Node.js 没安装，或安装后终端没有刷新。参考 Node.js 安装。

环境变量不生效

• 确认你写入了正确的配置文件：Zsh 是 ~/.zshrc，Bash 是 ~/.bashrc。
• 执行 source ~/.zshrc 或重新打开终端。
• Windows 用户持久化设置后，必须重新打开 PowerShell。
• VS Code 用户可能需要重启 VS Code，才能读取新的环境变量。

安全使用建议

API 网关可以方便地接入多种 AI 工具，但也需要正确管理 Key 和用量。

FAQ

1. sk-your-api-key 是什么？

这是示例占位符。你需要把它替换成控制台生成的真实 API Key，例如 sk-xxxxxx。

2. Claude Code 为什么不带 /v1？

Claude Code 使用 Anthropic 风格配置，工具自身会拼接接口路径。因此 Base URL 填 https://api.hohai.eu.org 即可。

3. OpenAI 兼容工具为什么要带 /v1？

OpenAI 兼容 SDK 和多数客户端会请求 /v1/chat/completions、/v1/models 等路径，因此 Base URL 通常需要写到 /v1。

4. 我可以同时配置 Claude Code 和 Codex 吗？

可以。它们使用不同环境变量，互不冲突：

• Claude Code：ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY
• Codex / OpenAI SDK：OPENAI_BASE_URL、OPENAI_API_KEY

5. 为什么工具能打开，但模型没有回复？

常见原因是余额不足、模型名错误、Key 没权限、请求超时或客户端默认模型不可用。先用 curl 验证，再排查客户端。

6. API Key 泄露怎么办？

立即进入控制台禁用或删除该 Key，然后新建一个 Key。建议每个工具单独建 Key，泄露时影响范围更小。

7. 可以把 API Key 放在前端网页里吗？

不建议，也不安全。前端代码会暴露给用户。正确做法是把 Key 放在你的后端服务器，由后端调用 API。

8. 配置后还是失败，应该提供什么信息给客服？

请提供以下信息，避免只说“不能用”：

• 你使用的工具：Claude Code / Codex / OpenClaw / SDK；
• 你填写的 Base URL；
• 错误码或报错截图；
• 请求的大致时间；
• 模型名；
• 不要发送完整 API Key，最多只提供 Key 的前 6 位和后 4 位用于识别。