AruHub 文档

主题

OpenClaw 配置教程 ​

本页只帮助你让 OpenClaw 使用 AruHub 模型 API。不同版本的菜单名称可能略有不同，请以当前客户端界面为准。

1. 这是什么工具 ​

OpenClaw 是一个可自行运行的个人 AI 助手平台。它由 Gateway（网关，即本机负责连接界面、工具和模型服务的程序）和控制界面等部分组成，可以通过不同模型提供回答并调用工具。

本页覆盖 OpenClaw 的模型 Provider 配置、默认模型选择和首次调用测试，不覆盖完整服务器部署、远程暴露服务、反向代理或消息平台接入。

2. 适合什么用户 ​

适合已经安装 OpenClaw，希望把默认模型服务改为 AruHub 的用户。新手建议优先使用 OpenClaw Control UI（控制界面）的 Settings 页面；只有界面无法完成时，再使用配置文件方式。

模型 API 配置与微信、Telegram、WhatsApp 等消息平台接入不是同一件事。本页只处理模型 API，不展开消息平台配置。

3. 开始前准备 ​

准备以下内容：

配置项应填写的内容
Base URLhttps://api.aruhub.com/v1
API Key登录 AruHub 后，在“我的密钥”页面创建；示例只使用 sk-xxxxxxxx
模型 ID从 AruHub 模型价格页、客户端实际加载出的模型列表或 AruHub /v1/models 返回结果确认

还需要符合 OpenClaw 当前安装文档要求的 Node.js 版本。官方当前支持 macOS、Linux 和 Windows；Windows 命令行方案建议使用 WSL2，也提供 PowerShell 安装脚本和原生 Hub 应用。

API Key 相当于账户密码。不要把它发给其他人，不要上传到 GitHub、网盘、截图或公开聊天。ChatGPT 账户登录不是 AruHub API Key。

4. 安装或打开工具 ​

如果已经能运行 OpenClaw，可直接跳到下一节。首次安装时按官方当前方式选择一种。

macOS、Linux 或 WSL2 ​

打开终端运行：

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

Windows 原生 ​

打开 PowerShell 运行：

powershell
iwr -useb https://openclaw.ai/install.ps1 | iex

已安装合适 Node.js 版本 ​

在 PowerShell 或终端运行：

bash
npm install -g openclaw@latest

然后运行官方首次向导：

bash
openclaw onboard --install-daemon

安装后依次检查：

bash
openclaw --version
openclaw doctor
openclaw gateway status

启动控制界面：

bash
openclaw dashboard

浏览器打开 Control UI 后，保持 Gateway 正常运行。

5. 创建 AruHub API Key ​

  1. 浏览器登录 AruHub。
  2. 打开“我的密钥”。
  3. 点击创建密钥，设置便于识别的名称。
  4. 复制生成的 Key，并保存到自己的密码管理器。
  5. 本页所有示例只写 sk-xxxxxxxx；配置时替换成真实值，但不要截图展示。

不要使用 ChatGPT 网站登录信息，也不要把其他服务的 Token 当成 AruHub Key。

6. 配置 Base URL ​

图形化方式 ​

  1. 在 OpenClaw Control UI 左侧打开 Settings。
  2. 进入 Agents & Tools → Model Providers。
  3. 点击页面顶部的 Model Setup，添加自定义模型服务；若当前版本没有该入口，打开 Advanced 的原始 JSON5 编辑器。
  4. Provider ID 填写 aruhub。
  5. Base URL 填写：
text
https://api.aruhub.com/v1

Base URL 只到 /v1。不要写成 /v1/v1，也不要填成 https://api.aruhub.com/v1/chat/completions。

配置文件方式 ​

OpenClaw 当前默认配置文件是：

text
~/.openclaw/openclaw.json

该文件使用 JSON5，JSON5 是允许注释和较宽松写法的 JSON 配置格式。用文本编辑器打开，先保留其他已有设置，再把以下结构合并进去：

json5
{
  models: {
    mode: "merge",
    providers: {
      aruhub: {
        baseUrl: "https://api.aruhub.com/v1",
        apiKey: "sk-xxxxxxxx",
        api: "openai-completions",
        models: [
          {
            id: "replace-with-model-id",
            name: "AruHub 模型",
            reasoning: false,
            input: ["text"]
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "aruhub/replace-with-model-id"
      }
    }
  }
}

字段名需保持大小写：baseUrl、apiKey、api、models。对于使用 /v1/chat/completions 的模型，api 填 openai-completions。只有在确认模型与 AruHub 当前接口都支持 Responses API 时，才选择对应模式。

7. 填写 API Key ​

图形界面中找到 API Key 字段，粘贴真实 AruHub Key。粘贴后检查开头和结尾没有空格，再点击保存。

配置文件示例中的 sk-xxxxxxxx 只是占位符。若在自己的配置文件中替换真实值：

  1. 不要把文件提交到 GitHub。
  2. 不要复制整个配置文件到公开问题。
  3. OpenClaw 支持 SecretRef 等密钥引用方式时，长期使用应优先按官方 Secret Management 文档保存密钥。

8. 填写或选择模型 ​

  1. 在 AruHub 模型价格页、客户端加载结果或 /v1/models 中找到准确模型 ID。
  2. 不要使用展示名称猜测 ID。
  3. 图形界面中把 Model ID 填为准确值。
  4. 配置文件方式要同时替换：
    • models 数组中的 id；
    • agents.defaults.model.primary 中 aruhub/ 后面的部分。
  5. 默认模型路由必须是 provider/model 格式，例如占位写法：
text
aruhub/replace-with-model-id

保存后可以在终端查看 OpenClaw 实际识别的模型：

bash
openclaw models list
openclaw models status

9. 保存配置 ​

在 Control UI 中 ​

  1. 检查 Provider ID、Base URL、API Key 和 Model ID。
  2. 点击 Save 或 Apply。
  3. 如果页面提示需要重启，按界面提示应用并重启 Gateway。
  4. 页面重新连接后，再打开 Model Providers 确认值仍存在。

使用配置文件 ​

保存 ~/.openclaw/openclaw.json 后，在 PowerShell 或终端运行：

bash
openclaw config validate
openclaw gateway restart

然后检查：

bash
openclaw gateway status
openclaw config get agents.defaults.model --json

成功时应看到 Gateway 正常，默认模型中包含 aruhub/ 路由。若验证失败，不要反复重启，先按报错行检查 JSON5 结构。

10. 发起第一次测试 ​

打开 Control UI 的聊天页面，发送一条不涉及文件或外部账号的消息：

text
请只回复：AruHub 模型连接测试成功

不要一开始就启用消息平台、自动化工具或高权限 Skills。先验证纯文本模型请求，再逐步增加其他能力。

11. 如何确认配置成功 ​

同时检查以下项目：

  1. openclaw models status 显示的默认模型是 aruhub/你的模型ID。
  2. Control UI 收到模型回复，没有 401、404、429 或模型不可用错误。
  3. AruHub 用量记录中出现相近时间和相同模型的请求。
  4. 重新打开 Settings 后，Provider 仍是 aruhub，不是其他默认服务。

工具或 Skills 能运行不代表模型请求一定成功；工具层和模型 API 是两条不同的配置链路。

12. 常见问题 ​

配置后仍然调用默认服务 ​

检查 agents.defaults.model.primary 是否以 aruhub/ 开头。保存后必须 Apply 并重启 Gateway；已经打开的旧会话可能保留原模型，建议新建聊天测试。

Provider 名称或模型路由错误 ​

Provider ID 建议统一为 aruhub。默认模型使用 aruhub/准确模型ID，斜线前后不能互换，也不要只填展示名称。

API Key 未加载 ​

重新打开 Model Providers，确认 Key 字段已保存。配置文件方式检查 apiKey 字段或 SecretRef，但不要在日志或截图中显示真实 Key。

配置修改后未重启 ​

运行 openclaw config validate，然后 openclaw gateway restart。浏览器页面断开几秒属于重启过程，等待后刷新。

401 ​

通常表示密钥无效、复制不完整或加载了其他服务的 Key。重新从“我的密钥”创建或复制，避免前后空格。

404 ​

检查 Base URL 是否正好是 https://api.aruhub.com/v1，模型 ID 是否存在，以及 api 是否与模型所需接口类型一致。

429 ​

可能是频率、并发、额度或模型服务暂时限流。降低请求频率，检查余额和用量记录，等待后再试，不要无间隔循环重试。

模型不可用 ​

重新从价格页、实际加载列表或 /v1/models 确认模型 ID，并确认当前账户和接口类型支持该模型。

工具或 Skills 能运行，但模型请求失败 ​

工具可运行只说明本地工具链正常。继续检查 Model Provider、默认模型路由、API Key 和模型请求错误正文。

13. 如何重置或修改配置 ​

  • 更换模型：在 Settings → Model Providers/Model Setup 修改模型，并同步修改默认路由；或编辑配置文件的 id 和 primary。
  • 修改 Key：在 Provider 设置替换后 Apply 并重启。
  • 修改 Base URL：确保只保留 https://api.aruhub.com/v1，保存后验证配置并重启。
  • 删除旧 Provider：先备份 ~/.openclaw/openclaw.json，再从 models.providers 删除对应 Provider，并把默认模型改为仍然存在的路由。
  • 修改后使用 openclaw models status 和新聊天验证，不要只看设置界面。

14. 安全注意事项 ​

  • API Key 相当于账户密码，不要发给其他人。
  • 不要把 Key 上传到 GitHub、网盘、截图或公开聊天。
  • 不要在支持请求中提供完整配置文件；只提供已遮盖的 Provider、Base URL、模型 ID 和错误信息。
  • 模型 API 与 Telegram、WhatsApp 等消息平台凭证分开管理。
  • 新手先测试纯文本请求，再考虑工具、Skills 或消息平台权限。

15. 相关文档 ​

AruHub · 统一 API 网关

Copyright © 2026 AruHub