API 开发文档

快速集成指南与完整 API 参考

工具接入

WEI HUB 提供 OpenAI 兼容接口，因此大多数支持 OpenAI Base URL 与 API Key 的工具都可以直接接入。

OpenCode Trae Hermes Cherry Studio Continue Open WebUI OpenClaw

通用接入方式

对于支持 OpenAI 协议的客户端或开发工具，通常只需要替换 Base URL 为当前平台的 /v1 地址，并填入控制台创建的 API Key。

统一根地址

bash

https://api.wei.run/v1

不知道该看哪个工具？

OpenCode：适合支持自定义 Provider 或 OpenAI Compatible 类型的开发工具接入。
Trae：适合在界面里添加自定义模型，并填写完整请求地址的接入方式。
Hermes：适合需要编辑 ~/.hermes/config.yaml 和 ~/.hermes/.env 的本地配置接入。
Cherry Studio：适合桌面端用户，通过自定义服务商填写 API Key、API Address 和模型。
Continue：适合 VS Code / JetBrains 用户，通过 OpenAI provider 和 apiBase 接入。
Open WebUI：适合自建网页聊天入口，在连接设置里添加 OpenAI-compatible 服务。
OpenClaw：适合使用脚本、本地引导或手动配置文件完成接入。

Base URL 和完整请求地址怎么区分

大多数 SDK 和工具要填 Base URL，例如 https://api.wei.run/v1。
少数工具会要求完整接口地址，例如 Trae 的自定义请求地址需要填到 /v1/chat/completions。

使用平台提供的安装脚本、本地引导命令或手动配置文件，都可以把 OpenClaw 接到 WEI HUB。点击后可直接跳到下方配置章节。

OpenCode

如果 OpenCode 当前版本支持自定义 OpenAI 兼容 Provider，可直接把 WEI HUB 作为外部模型服务接入。

适合谁

使用 OpenCode 做代码开发，并且工具支持自定义 OpenAI Provider 的用户。

要填什么

Base URL、API Key、Model ID。

先测什么

保存后发送一条最小聊天消息，确认模型能返回内容。

接入前请先确认

你当前使用的 OpenCode 版本支持自定义 Provider，或支持 OpenAI Compatible 类型。
你已经在 WEI HUB 控制台创建好了可用的 API Key（sk- 开头）。
你已经知道要填写的模型 ID，或准备先用一个当前平台真实可用的模型做测试。

打开 OpenCode 的 Provider / Model 配置页面。
选择自定义 Provider，或选择 OpenAI Compatible 类型。
将 Base URL 设置为 WEI HUB 的 /v1 地址，并填入控制台生成的 API Key。
选择你在 WEI HUB 中实际可用的模型 ID 作为默认模型。

最少需要填写哪几项

如果 OpenCode 支持 OpenAI 兼容接入，通常只需要填写 Base URL、API Key 和 Model 这 3 项，就可以完成第一次联调。

配置项	推荐值
Base URL	https://api.wei.run/v1
API Key	sk-your-api-key
Model	YOUR_MODEL_ID

配置完成后怎么确认成功

保存配置后，在 OpenCode 中发送一条最小测试消息。
如果模型正常返回内容，说明 OpenCode 已经成功接到 WEI HUB。
如果失败，优先检查 Base URL、API Key 和 Model ID 是否填写正确。

常见问题

在 OpenCode 里找不到自定义 Provider 入口怎么办？

先确认当前 OpenCode 版本是否支持自定义 Provider 或 OpenAI Compatible 类型。如果界面里没有这个入口，就不能按本页方式直接接入。

配置都填了，但还是调用失败怎么办？

优先检查 Base URL 是否带上了 /v1、API Key 是否有效，以及模型 ID 是否是当前平台真实可用的值。

我不知道 Model 应该填什么怎么办？

请先回到 WEI HUB 的模型列表或控制台，确认一个当前真实可用的模型 ID，再把它填写到 OpenCode 中。

Trae

如果 Trae 支持通过 OpenAI 方式添加自定义模型，你可以直接把 WEI HUB 作为外部模型服务接入。整个过程通常不复杂，重点是把模型 ID、API Key 和请求地址填写正确。

适合谁

希望在 Trae 界面里添加自定义模型并直接使用的用户。

要填什么

服务商 OpenAI、自定义模型、Model ID、API Key、完整请求地址。

先测什么

选择刚添加的模型，发送一条简短测试消息。

接入前请先确认

你当前使用的 Trae 版本支持添加自定义模型。
你已经在 WEI HUB 控制台创建好了可用的 API Key（sk- 开头）。
你已经确认了一个当前真实可用的模型 ID。
你准备通过 OpenAI 兼容方式完成接入。

打开 Trae，进入模型管理或模型配置页面。
点击“添加模型”。
在服务商中选择 OpenAI。
在模型类型或模型选择中，选择“自定义模型”。
在模型 ID 中，填写 WEI HUB 当前真实可用的模型 ID。
在 API 密钥中，填写你在 WEI HUB 控制台创建的 API Key。
在自定义请求地址中，填写 https://api.wei.run/v1/chat/completions。
保存配置。
返回 Trae，选择刚刚添加的模型进行测试。

配置项	推荐值
服务商	OpenAI
模型类型	自定义模型
Model ID	YOUR_MODEL_ID
API Key	sk-your-api-key
自定义请求地址	https://api.wei.run/v1/chat/completions

推荐填写的请求地址

text

https://api.wei.run/v1/chat/completions

配置完成后怎么确认成功

保存配置后，在 Trae 中切换到你刚刚添加的模型。
发送一条最小测试消息，例如 Reply with: connection ok。
如果模型正常返回内容，说明 Trae 已经成功接到 WEI HUB。

常见问题

模型 ID 应该填什么？

模型 ID 需要填写 WEI HUB 当前真实可用的模型名称，不能只填厂商名，也不能只填一个泛化能力标签。如果你不确定，请先回到 WEI HUB 的模型列表或控制台确认。

API Key 填什么？

这里需要填写你在 WEI HUB 控制台创建的 API Key，通常以 sk- 开头。

请求地址应该填哪个？

按当前这条接入方式，自定义请求地址填写 https://api.wei.run/v1/chat/completions。

为什么保存后还是请求失败？

优先检查模型 ID 是否是当前真实可用的值、API Key 是否有效，以及自定义请求地址是否完整填写正确。

Hermes

如果你当前使用的 Hermes 版本支持自定义 OpenAI-compatible endpoint，可以把 WEI HUB 作为外部模型服务接入。第一次配置时，通常只需要准备 Base URL、API Key 和一个真实可用的模型 ID。

适合谁

需要通过 Hermes 本地 agent / CLI 调用 WEI HUB 模型的用户。

要填什么

~/.hermes/.env 中的 API Key，以及 config.yaml 里的 Base URL 和默认模型。

先测什么

重新加载 Hermes 后发送 Reply with: connection ok。

Hermes 是什么

Hermes 是一个可以连接不同大模型服务的 AI agent / CLI 工具。它支持官方内置 Provider，也支持任何 OpenAI-compatible endpoint。如果你希望在 Hermes 里调用 WEI HUB 提供的模型，就需要把接口地址、API Key 和模型 ID 配置到 Hermes。

接入前你需要准备什么

你已经安装并能正常运行 Hermes。
你知道 Hermes 的配置目录通常在 ~/.hermes/。
你已经在 WEI HUB 控制台创建好了可用的 API Key（sk- 开头）。
你已经确认了一个当前真实可用的模型 ID。
你本机有一个可以编辑配置文件的环境，或知道如何打开 ~/.hermes/config.yaml。

Hermes 常用配置文件

主配置文件： ~/.hermes/config.yaml

环境变量文件： ~/.hermes/.env

最少需要填写哪几项

第一次接入时，你只需要先确认 Base URL、API Key 和 Model ID 这 3 个值。先跑通最小配置，再考虑多个模型或高级能力。

配置项	推荐值
Base URL	https://api.wei.run/v1
API Key	sk-your-api-key
Model	YOUR_MODEL_ID

1. 推荐方式：先用最小配置接入

如果你没有配置过 Hermes，建议先走最小配置方式。先让 Hermes 成功调用一次 WEI HUB，再继续做更复杂的配置。

先在 ~/.hermes/.env 中准备 API Key

bash

# ~/.hermes/.env
OPENAI_API_KEY=sk-your-api-key

再在 ~/.hermes/config.yaml 中填写最小配置

yaml

# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: https://api.wei.run/v1
  api_key: ${OPENAI_API_KEY}
  default: YOUR_MODEL_ID

使用这个示例时请注意

不同版本的 Hermes，配置字段命名可能略有差异。如果你本机已有现成配置结构，优先保持原有结构风格，只替换 provider、base_url、api_key 和默认模型。
从安全角度看，更推荐把 API Key 放在 ~/.hermes/.env 中，再在 config.yaml 里通过环境变量引用，而不是长期把明文密钥直接写进配置文件。
如果模型列表没有自动出现，不要先卡在“自动列模”上。更稳的做法是先手工填写一个当前真实可用的模型 ID 做最小测试。

2. 进阶方式：按你当前版本的配置结构手动扩展

如果你已经熟悉 Hermes 的配置结构，也可以继续扩展多个 provider、多个模型或其他高级能力。但第一版接入建议先把最小路径跑通，再继续深度配置。

配置完成后怎么确认成功

保存 ~/.hermes/.env 和 ~/.hermes/config.yaml。
重新打开 Hermes，或重新进入当前会话 / 模型选择流程，让新配置生效。
发送一条最小测试消息，例如 Reply with: connection ok。
如果模型正常返回内容，说明 Hermes 已经成功接到 WEI HUB。

常见问题

我没用过 Hermes，应该先从哪里看？

先确认 Hermes 已经安装成功，并且你知道配置目录在 ~/.hermes/。如果你还没有完成基础安装，建议先按 Hermes 官方方式安装并能正常运行，再回来做 WEI HUB 接入。

Hermes 的配置文件在哪里？

Hermes 的主配置通常在 ~/.hermes/config.yaml，API Key 等敏感信息更推荐放在 ~/.hermes/.env。

为什么我填了 API Key，还是报认证失败？

优先检查 API Key 是否有效、Base URL 是否完整写成 /v1 地址，以及当前配置是否真的把该 API Key 传给了 WEI HUB 对应的 custom endpoint。

模型列表没有自动出现怎么办？

第一次测试不要依赖自动发现模型列表。更稳的方式是直接填写一个当前真实可调用的模型 ID，先验证最小请求是否能成功返回。

Windows 用户能直接配置吗？

根据 Hermes 官方 FAQ，Windows 原生不是主要运行方式。更推荐在 WSL2 中运行 Hermes，再在 WSL2 环境里完成接入配置。

Cherry Studio

Cherry Studio 支持添加自定义服务商。你可以按 OpenAI 兼容方式填写 WEI HUB 的 API Key、API Address 和模型 ID。

适合谁

使用桌面聊天客户端，希望通过自定义服务商接入模型的用户。

要填什么

服务商名称、OpenAI 类型、API Key、API Address、Model ID。

先测什么

回到聊天窗口选择该模型，发送最小测试消息。

接入前请先确认

你已经安装 Cherry Studio，并能进入服务商配置页面。
你已经在 WEI HUB 控制台创建好了可用的 API Key。
你已经确认了一个当前真实可用的模型 ID。

打开 Cherry Studio 的设置页面，进入服务商或模型服务配置。
新增一个自定义服务商，名称可以填写 WEI HUB。
服务商类型选择 OpenAI 或 OpenAI 兼容类型。
填写 API Key 和 API Address。
添加或填写你要使用的模型 ID。
保存后在聊天窗口选择该模型发送测试消息。

配置项	推荐值
服务商名称	WEI HUB
服务商类型	OpenAI
API Key	sk-your-api-key
API Address	https://api.wei.run/v1
模型	YOUR_MODEL_ID

配置完成后怎么确认成功

保存服务商配置后，回到聊天窗口选择刚添加的模型。
发送一条最小测试消息，例如 Reply with: connection ok。
如果模型正常返回内容，说明 Cherry Studio 已经成功接到 WEI HUB。

Continue

Continue 适合在 VS Code 或 JetBrains 中使用。通过 OpenAI provider 并把 apiBase 指向 WEI HUB 的 /v1 地址，就可以接入平台模型。

适合谁

在 VS Code 或 JetBrains 里使用 AI 辅助编码的用户。

要填什么

provider、model、apiBase、apiKey 和 roles。

先测什么

先启用 chat 或 edit 角色，确认一次对话可用。

接入前请先确认

你已经安装 Continue 插件，并能打开配置文件。
你已经在 WEI HUB 控制台创建好了可用的 API Key。
你已经确认了一个当前真实可用的模型 ID。

Continue 配置示例

yaml

name: WEI HUB
version: 0.0.1
schema: v1

models:
  - name: WEI HUB Chat
    provider: openai
    model: YOUR_MODEL_ID
    apiBase: https://api.wei.run/v1
    apiKey: sk-your-api-key
    roles:
      - chat
      - edit
      - apply

使用时请注意

provider 使用 openai，apiBase 填写 WEI HUB 的 /v1 根地址。
model 必须替换成当前平台真实可用的模型 ID。
建议先用于 chat 或 edit 角色测试，确认可用后再扩展到更多 Continue 能力。

Open WebUI

Open WebUI 可以连接 OpenAI-compatible 服务。你可以在管理后台添加 WEI HUB 的 /v1 地址和 API Key，再选择可用模型进行测试。

适合谁

自建网页聊天入口，想统一接入 WEI HUB 模型的团队或个人。

要填什么

OpenAI-compatible URL、API Key、Model ID。

先测什么

保存连接后在聊天界面选择模型，发送最小测试消息。

进入 Open WebUI 管理后台。
打开 Settings / Admin Settings 中的 Connections 或 OpenAI 连接配置。
新增一个 OpenAI-compatible 连接。
填写 URL、API Key 和模型 ID。
保存后回到聊天界面选择模型并发送测试消息。

配置项	推荐值
URL	https://api.wei.run/v1
API Key	sk-your-api-key
Model IDs	YOUR_MODEL_ID

使用时请注意

URL 通常填写 WEI HUB 的 /v1 根地址，不需要填到具体 chat/completions。
如果模型没有自动出现，可以先手动填写一个真实可用的模型 ID。
如果返回 401 或 404，优先检查 API Key 和模型 ID。

OpenClaw

通过平台提供的安装脚本或本地引导命令，把 OpenClaw 接入到当前平台的 OpenAI 兼容接口。

适合谁

使用 OpenClaw，并希望通过脚本或配置文件接入 WEI HUB 的用户。

要填什么

Provider 名称、Base URL、API Key、Model ID、默认模型路径。

先测什么

完成配置后重启 gateway，再发送一次最小模型调用。

接入前请先确认

你本地已经安装 OpenClaw，并且可以正常运行相关命令。
你已经在 WEI HUB 控制台创建好了可用的 API Key（sk- 开头）。
你知道自己要使用的模型 ID，或者至少准备先用默认示例模型做测试。
如果你使用的是 macOS / Linux 脚本方式，请确认本机已安装 jq。

1. 使用安装脚本自动配置

这是最省事的方式。脚本会自动备份现有配置，并写入 Base URL、API Key、默认模型、Provider 名称与模型别名。未提前传入 API Key 时，脚本会在终端中提示输入。

脚本地址

text

http://localhost:3001/setup-openclaw-provider.sh
http://localhost:3001/setup-openclaw-provider.ps1

安装脚本命令

bash

curl -fsSL http://localhost:3001/setup-openclaw-provider.sh | bash

# Optional: provide key non-interactively
curl -fsSL http://localhost:3001/setup-openclaw-provider.sh | WEIAPI_API_KEY=sk-your-api-key bash

自定义参数示例

bash

# Optional: override base URL, model, alias, and provider name
curl -fsSL http://localhost:3001/setup-openclaw-provider.sh | \
  WEIAPI_API_KEY=sk-your-api-key \
  WEIAPI_BASE_URL=https://api.wei.run/v1 \
  WEIAPI_MODEL_ID=qwen3.5-plus \
  WEIAPI_MODEL_ALIAS=qwen3.5-plus \
  WEIAPI_PROVIDER_NAME=custom-api-wei-run \
  bash

Windows 执行示例

powershell

iwr http://localhost:3001/setup-openclaw-provider.ps1 -OutFile .\setup-openclaw-provider.ps1
powershell -ExecutionPolicy Bypass -File .\setup-openclaw-provider.ps1

# Optional: provide key non-interactively
powershell -ExecutionPolicy Bypass -File .\setup-openclaw-provider.ps1 -ApiKey "sk-your-api-key"

脚本会自动帮你做什么

自动备份当前 openclaw.json，避免覆盖后无法回退。
写入 Base URL、API Key、Provider 配置，以及对应模型定义。
把配置模式设为 merge，并把当前 Provider 对应模型加入 models.providers。
把默认主模型指向 custom-api-wei-run/qwen3.5-plus；如果你传入自定义参数，则会改成你指定的值。

2. 使用本地引导向导

如果你更偏好交互式流程，可运行 openclaw 自带引导：Yes -> QuickStart -> Custom Provider，然后按下面建议值逐项填写。

OpenClaw 引导命令

bash

openclaw onboard

引导向导建议填写

Base URL: https://api.wei.run/v1
API Key 填写控制台创建的 sk- 开头密钥。
Provider Type 选择 Custom Provider / OpenAI-compatible。
Model ID 直接填写 WEI HUB 中实际可用的模型 ID，例如 qwen3.5-plus。
保存后如需设为默认主模型，可将该 provider 设为 primary。

3. 手动编辑配置文件

如果你已经熟悉 OpenClaw 配置结构，或希望精确控制 Provider 名称、默认模型与字段写法，可以直接编辑 openclaw.json。

推荐配置示例

json

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom-api-wei-run/qwen3.5-plus"
      },
      "models": {
        "custom-api-wei-run/qwen3.5-plus": {
          "alias": "qwen3.5-plus"
        }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "custom-api-wei-run": {
        "baseUrl": "https://api.wei.run/v1",
        "api": "openai-completions",
        "apiKey": "sk-your-api-key",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus (Custom Provider)",
            "contextWindow": 1000000,
            "maxTokens": 32768,
            "input": ["text", "image"],
            "reasoning": false,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      }
    }
  }
}

默认配置文件路径

macOS / Linux: ~/.openclaw/openclaw.json

Windows: $HOME\\.openclaw\\openclaw.json

配置键	说明
models.providers.*.baseUrl	上游 API 根地址，建议填写本平台 /v1 根路径。
models.providers.*.api	协议类型。对大多数模型使用 openai-completions。
models.providers.*.apiKey	在控制台创建的 API Key（sk- 开头）。
models.providers.*.models[].id	直接填写 WEI HUB 中实际可用的模型 ID，例如 qwen3.5-plus。
models.providers.*.models[].input	模型输入类型数组；如需图像输入，必须包含 image。
agents.defaults.model.primary	默认主模型路由入口，可映射到你最常用的模型。

配置完成后怎么确认成功

先执行 openclaw gateway restart，让 OpenClaw 重新加载配置。
打开 OpenClaw 的 Provider / Model 配置界面，确认已经出现 custom-api-wei-run（或你自定义的 Provider 名称）。
确认默认主模型已经指向对应的 provider/model 组合，例如 custom-api-wei-run/qwen3.5-plus。
发送一条最小测试请求；如果能正常返回模型结果，说明接入已经成功。

配置更新后（可选）重启

bash

openclaw gateway restart

常见问题

执行脚本时报 jq: command not found 怎么办？

Bash 版本脚本依赖 jq 来修改 JSON。请先安装 jq，或者改用 Windows PowerShell 脚本 / 手动编辑配置方式。

已经填了 API Key，但还是接不通怎么办？

先检查 API Key 是否有效、Base URL 是否正确，以及 OpenClaw 是否已经重新加载了最新配置。

为什么 OpenClaw 里看不到 provider 或模型？

通常是配置没有成功写入、没有重启 gateway，或者 model ID 填写的不是当前平台真实可用的模型 ID。