快速接入

最快只需要一个 Base URL 和一个 API Key。

1. 登录 Hivewa 后台

   确认你已经有管理员或用户账户，并能在平台中创建可用的 API Key。

2. 获取 API Key

   在用户侧或后台创建令牌，记下以 sk- 开头的密钥。

3. 设置 Base URL

   将客户端指向 https://hivewa.store/v1，即可按 OpenAI 兼容方式调用。

最小 curl 示例

curl https://hivewa.store/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "Hello from Hivewa"}
    ]
  }'复制

注册账号

如果站点开放注册，先创建一个 Hivewa 账户，再继续充值和创建 API Key。

1. 打开注册页

   进入主站注册页面，填写系统要求的注册信息。

2. 完成验证

   如果启用了邮箱验证、邀请码或注册限制，请按页面提示完成。

3. 进入控制台

   注册成功后即可登录控制台，继续充值和创建令牌。

登录使用

登录后你可以查看余额、令牌、使用量和个人设置。

1. 进入登录页

   使用你注册或管理员分配的账户凭据登录 Hivewa。

2. 确认权限

   登录成功后，先确认你所在分组、订阅或令牌权限是否已经准备好。

3. 开始创建令牌

   在控制台中进入 API Key 页面，为客户端接入准备 Bearer Token。

额度充值

调用模型前，请先确认账户有足够的余额、订阅或兑换额度。

• 如果站点开启了充值或购买入口，可直接在钱包或订阅页完成。
• 如果站点使用兑换码模式，请先兑换余额或订阅额度。
• 如果是内部部署，也可能由管理员直接分配账户余额与订阅。

获取令牌

所有对外 API 调用都依赖 Bearer Token，所以这一步是接入前的核心操作。

1. 进入令牌管理

   登录后打开用户控制台中的 API Key / 令牌管理页面。

2. 创建新令牌

   填写名称，必要时限制分组、用途或额度，然后创建一条新的 Key。

3. 妥善保存

   复制生成的 sk-... 密钥，保存到环境变量或密码管理器中。

Authorization: Bearer sk-your-token复制

Codex 配置

Codex 是 Hivewa 当前最推荐的接入方式之一。

export OPENAI_API_KEY="sk-your-token"
export OPENAI_BASE_URL="https://hivewa.store/v1"复制

如果你的环境支持配置文件，也可以把这两个值写进对应的环境变量管理或 shell profile。

推荐检查顺序

1. 先确认 API Key

   确保你拿到的是 Hivewa 平台生成的有效令牌，而不是兑换码、管理员 JWT 或其他临时字符串。

2. 再确认 Base URL

   大多数 OpenAI 兼容工具都应该填写 https://hivewa.store/v1，不要重复在工具内部再拼一个 /v1。

3. 最后确认模型

   如果工具支持自定义模型名，请以 GET /v1/models 的返回结果为准。

验证命令

curl https://hivewa.store/v1/models   -H "Authorization: Bearer sk-your-token"复制

Claude Code 配置

通过 OpenAI 兼容入口接入 Hivewa 时，关键是让 Claude Code 指向正确的兼容地址。

export OPENAI_API_KEY="sk-your-token"
export OPENAI_BASE_URL="https://hivewa.store/v1"复制

OpenCode 配置

OpenCode 一般支持自定义 OpenAI Provider，填写 Hivewa 的兼容地址即可。

{
  "provider": "openai-compatible",
  "baseUrl": "https://hivewa.store/v1",
  "apiKey": "sk-your-token"
}复制

OpenClaw 配置

OpenClaw 支持自定义 Provider 时，可以直接按 OpenAI 兼容方式接入。

{
  "base_url": "https://hivewa.store/v1",
  "api_key": "sk-your-token"
}复制

接口概述

Hivewa 暴露的是 OpenAI 兼容接口，最常用的是 Chat Completions 和 Responses。

调用原则

• 客户端统一走 OpenAI 兼容协议，不需要为不同模型单独改 SDK。
• 可见模型由后台分组、账号状态和路由规则共同决定。
• 如果你的工具支持新版接口，优先考虑 /v1/responses；兼容性优先时用 /v1/chat/completions。

Chat Completions

适合最常见的对话式调用。

POST /v1/chat/completions
Authorization: Bearer sk-your-token
Content-Type: application/json

{
  "model": "gpt-5.4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Write a short summary."}
  ]
}复制

Responses

适合新版 OpenAI 风格客户端与更统一的响应结构。

POST /v1/responses
Authorization: Bearer sk-your-token
Content-Type: application/json

{
  "model": "gpt-5.4",
  "input": "Explain how to connect to Hivewa."
}复制

模型与 Base URL

模型可见性取决于你的分组、令牌权限和后台路由配置。

GET /v1/models
Authorization: Bearer sk-your-token复制

返回结果中的模型列表，就是这个令牌当前可见的模型集合。

OpenAI OAuth 账号

管理员可以通过后台 API 把 OpenAI OAuth 授权结果直接创建成系统账号。

POST /api/v1/admin/openai/create-from-oauth
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "session_id": "SESSION_ID",
  "code": "CODE_FROM_CALLBACK",
  "state": "STATE_FROM_CALLBACK",
  "redirect_uri": "https://your-callback.example.com/openai/callback",
  "name": "my-openai-oauth",
  "concurrency": 1,
  "priority": 0,
  "group_ids": [1]
}复制

这个接口会自动完成换码和创建账号，不需要你手动拼接 credentials。

调用前准备

• 先拿到管理员登录态 JWT。
• 先调 /api/v1/admin/openai/generate-auth-url 获取 session_id。
• 回调后拿到 code 和 state，再发起创建请求。

错误排查

接入失败时，优先看请求地址、鉴权头和后台账号状态。

• 401：令牌无效、过期，或管理员接口缺少 JWT。
• 429：令牌或账号触发限流。
• 503：没有可调度账号，或上游全部异常。
• 模型不存在：分组未放行，或模型映射没有配置。

建议的排查顺序

1. 先看 URL

   确认客户端真的在访问 https://hivewa.store/v1。

2. 再看认证

   确认请求头带了正确的 Bearer Token。

3. 再查模型列表

   调用 /v1/models 看该令牌的可见模型。

4. 最后看后台

   检查账号状态、分组绑定、代理和限流是否异常。

Q&A