> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 接入 HingNet AI

> 将 OpenClaw 配置为通过 HingNet AI 聚合平台调用 AI 模型

## 前置条件

<Steps>
  <Step title="HingNet AI 账号与 API Key">
    登录 [HingNet AI 控制台](https://models.hingnet.com.cn/panel)，创建可用于模型调用的 API Key（格式如 `sk-xxxx`）。HingNet AI API 基础地址为 `https://models.hingnet.com.cn`。
  </Step>

  <Step title="OpenClaw 已安装并启动">
    确保 OpenClaw CLI 已安装且 Gateway 可正常运行。参见 [安装与启动](/ecosystem/openclaw-setup)。
  </Step>
</Steps>

## 协议背景

<Info>
  不同品牌模型的接口协议并不相同，HingNet AI 同时支持以下三类协议。你可以按需配置一个或多个 provider。
</Info>

| 协议                   | 典型接口                                               | 适用模型                |
| -------------------- | -------------------------------------------------- | ------------------- |
| OpenAI（GPT 协议）       | `POST /v1/chat/completions` 或 `POST /v1/responses` | GPT 系列及 OpenAI 兼容模型 |
| Anthropic（Claude 协议） | `POST /v1/messages`                                | Claude 系列           |
| Google（Gemini 协议）    | `POST .../models/{model}:generateContent`          | Gemini 系列           |

## 配置 HingNet AI 模型提供方

编辑 OpenClaw 配置文件 `~/.openclaw/openclaw.json`。

<Warning>
  以下示例使用 JSON5 写法（允许注释与尾逗号）；若你环境严格要求 JSON，请去掉注释与尾逗号。示例中的模型 ID 需替换为你在 HingNet AI 控制台中实际启用的模型 ID。
</Warning>

### GPT（OpenAI 协议）

用于对接 GPT 系列以及任何走 OpenAI 协议的模型。

```json5 theme={null}
{
  agents: {
    defaults: {
      model: { primary: "hingnet-openai/gpt-5.4" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      "hingnet-openai": {
        baseUrl: "https://models.hingnet.com.cn",
        apiKey: "${HINGNET_API_KEY}",
        api: "openai-completions",
        // 如 HingNet AI 要求额外请求头，可在此追加
        // headers: { "X-HingNet-Project": "xxx" },
        models: [
          { id: "gpt-5.4", name: "GPT 5.4 (via HingNet AI, OpenAI protocol)" },
        ],
      },
    },
  },
}
```

### Claude（Anthropic 协议）

用于对接 Claude 系列（Anthropic 原生 messages 协议，推荐 `claude-opus-4-6`）。

```json5 theme={null}
{
  agents: {
    defaults: {
      model: { primary: "hingnet-anthropic/claude-opus-4-6" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      "hingnet-anthropic": {
        baseUrl: "https://models.hingnet.com.cn",
        apiKey: "${HINGNET_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-opus-4-6", name: "Claude Opus 4.6 (via HingNet AI, Anthropic protocol)" },
        ],
      },
    },
  },
}
```

### Gemini（Google 协议）

Gemini 走 Google 原生协议，接口与鉴权方式不同于 OpenAI / Anthropic。

```json5 theme={null}
{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3-pro-preview" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      google: {
        baseUrl: "https://models.hingnet.com.cn",
        apiKey: "${HINGNET_API_KEY}",
      },
    },
  },
}
```

**配置说明：**

| 字段                                 | 说明                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------- |
| `agents.defaults.model.primary`    | OpenClaw 默认模型，格式为 `provider/model`                                         |
| `models.providers.*.baseUrl`       | 对应协议的 HingNet AI 入口地址                                                      |
| `models.providers.*.apiKey`        | HingNet AI 平台的 API Key                                                     |
| `models.providers.*.api`           | 请求协议类型：`openai-completions`（GPT）或 `anthropic-messages`（Claude），Gemini 无需指定 |
| `models.providers.*.models[].id`   | HingNet AI 控制台中的实际模型 ID，需完全一致（含前缀、大小写）                                     |
| `models.providers.*.models[].name` | 在 OpenClaw 中展示的模型名称                                                        |

<Tip>
  若只需一种协议，仅配置对应的 provider 即可。多协议可同时配置，在 `agents.defaults.model.primary` 中指定默认使用的模型。
</Tip>

### 使用环境变量（推荐）

为避免在配置文件中写死密钥，推荐使用系统环境变量：

```bash theme={null}
export HINGNET_API_KEY="YOUR_HINGNET_API_KEY"
```

配置中使用 `${HINGNET_API_KEY}` 占位符即可引用。确保启动 OpenClaw 的进程环境中已设置该变量。

## 重启 Gateway

修改配置后需重启 Gateway 使其生效。

**直接启动：**

```bash theme={null}
openclaw gateway --port 18789 --verbose
```

**守护进程模式（systemd）：**

```bash theme={null}
systemctl --user restart openclaw-gateway.service
```

重启后建议执行健康检查：

```bash theme={null}
openclaw doctor
```

## 验证集成

### curl 验证协议连通性

分别验证已配置的协议是否打通。

**GPT（OpenAI 协议）：**

```bash theme={null}
curl -X POST "https://models.hingnet.com.cn/v1/chat/completions" \
  -H "Authorization: Bearer ${HINGNET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{ "role": "user", "content": "你好，请用一句话介绍你自己。" }],
    "temperature": 0.7
  }'
```

**Claude（Anthropic 协议）：**

```bash theme={null}
curl -X POST "https://models.hingnet.com.cn/v1/messages" \
  -H "Authorization: Bearer ${HINGNET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "你好，请介绍你自己" }]
  }'
```

**Gemini（Google 协议）：**

```bash theme={null}
curl -X POST "https://models.hingnet.com.cn/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "Authorization: Bearer ${HINGNET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "你好" }] }]
  }'
```

### 终端验证

```bash theme={null}
openclaw agent --message "请说明你当前是通过 HingNet AI 聚合平台调用模型的。"
```

若配置正确：

* 终端会返回模型生成的文本
* HingNet AI 控制台的「调用日志 / 监控」中可看到对应调用记录

### Web UI 验证

1. 打开 OpenClaw Web UI
2. 在「Models / 模型配置」中确认可看到已配置的 HingNet AI 模型条目
3. 在 WebChat / Playground 中选择模型，发送测试消息，确认返回正常

## 常见问题排查

<AccordionGroup>
  <Accordion title="401 / 403 — 鉴权失败">
    * 检查 HingNet AI API Key 是否正确、未过期、权限充足
    * 使用上方的 curl 命令单独测试 HingNet AI 接口
    * 示例验证：

    ```bash theme={null}
    curl -X POST "https://models.hingnet.com.cn/v1/messages" \
      -H "Authorization: Bearer YOUR_HINGNET_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [{ "role": "user", "content": "你好，请介绍你自己" }]
      }'
    ```
  </Accordion>

  <Accordion title="404 — 模型不存在">
    * 确认模型 ID 与 HingNet AI 控制台中的完全一致（包括前缀、大小写）
    * 在 HingNet AI 控制台查看当前可用模型列表
  </Accordion>

  <Accordion title="curl 成功但 OpenClaw 报错">
    * 确认 OpenClaw 读取的是当前 `~/.openclaw/openclaw.json`
    * 确认 `agents.defaults.model.primary` 与对应 provider 的 `models[].id` 一致
    * 如使用环境变量，确保启动 OpenClaw 的同一进程环境中已设置相关变量
  </Accordion>

  <Accordion title="超时或连接失败">
    * 检查网络连通性：`curl -I https://models.hingnet.com.cn`
    * 确认各 `baseUrl` 地址正确
    * 如有代理，确保 OpenClaw 进程也使用了相同的代理配置
  </Accordion>
</AccordionGroup>