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 不一样。你只要记住下表即可。

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-4k。
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-4k",
    "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-4k"
  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-4k",
  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 可以解码为有效图片文件。

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-4k",
    "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 位用于识别。