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

# OpenClaw

> 了解如何在 OpenClaw 中配置 custom OpenAI-compatible provider，接入 siflow endpoint，让个人 AI assistant 执行跨渠道任务。

[OpenClaw](https://github.com/openclaw/openclaw) 是一个开源个人 AI assistant，可连接 WhatsApp、Telegram、飞书/Lark 等消息渠道，并通过 agent loop 代您执行任务。它支持 custom OpenAI-compatible providers，因此可以指向 siflow endpoint。

OpenClaw 需要 **Node.js 22.22.3+、24.15+ 或 25.9+**。推荐使用较新的 LTS 版本。如果使用不支持的 Node 版本安装，可能会静默拉取较旧的 placeholder release。

## 配置

### 1. 安装 OpenClaw

先检查 Node 版本：

```bash theme={null}
node -v
```

如果版本低于要求，请升级 Node。[官方下载页面](https://nodejs.org/en/download) 覆盖各平台和安装方式。

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node@24
  ```

  ```bash Windows (winget) theme={null}
  winget install OpenJS.NodeJS.LTS
  ```

  ```bash Linux/macOS (nvm) theme={null}
  nvm install 24 && nvm use 24
  nvm alias default 24
  ```
</CodeGroup>

<Warning>
  使用 nvm 时，请设置 default alias。否则新终端可能回退到旧 Node 版本，导致 npm 安装的命令从 `PATH` 中消失。
</Warning>

安装 OpenClaw：

```bash theme={null}
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

### 2. 完成 onboarding

`openclaw onboard` 会引导您完成交互式 setup wizard。请按如下方式回答：

1. **"I understand this is personal-by-default..."**：选择 **Yes**。
2. **Setup mode**：选择 **QuickStart (recommended)**。它应用的默认值，包括 Gateway port `18789`、loopback bind、token auth、Tailscale off，都适用于连接算秩。
3. **Model/auth provider**：选择 **Skip for now**。

   这里列出的 providers，例如 OpenAI、Anthropic、Google，是这些公司官方服务的 sign-in flows。选择 OpenAI 会让 OpenClaw 指向 `api.openai.com`，而不是算秩。算秩会在配置文件中作为 custom provider 添加。

<img src="https://mintcdn.com/siflow/MnqDOrFLyFtwF7sA/model-inference/media/openclaw-onboard-provider.png?fit=max&auto=format&n=MnqDOrFLyFtwF7sA&q=85&s=f70e0d6d67d4ba4e23648abff9fbf02e" alt="OpenClaw 初始化时跳过默认模型和认证 provider 配置" width="1696" height="940" data-path="model-inference/media/openclaw-onboard-provider.png" />

4. **Default model**：选择 **Keep current**。此时 provider 还没有凭证，请不要输入算秩模型。下方配置文件会将 `agents.defaults.model.primary` 设置为算秩模型。
5. **后续选项**，例如 Web search、Chat channels：选择 **Skip for now**。这些 agent extras 与模型 provider 独立，可稍后通过 `openclaw configure` 配置。

Wizard 结束后会进入 OpenClaw chat TUI。在 provider 配置完成前，消息会因模型错误失败，这是预期现象。输入 `/exit` 退出；`Ctrl+C` 不会退出 TUI。

### 3. 配置 provider

首先，在 [API 密钥](https://console.siflow.cn/model-inference/api_keys) 页面创建 API Key，然后将其存放到 gateway 可读取的位置。Gateway 以 daemon 方式运行，shell 中的 `export` 不会传递给它。请使用 OpenClaw 的 env file：

```bash theme={null}
echo 'SIFLOW_API_KEY=<Your API Key>' >> ~/.openclaw/.env
```

然后编辑 `~/.openclaw/openclaw.json`，添加算秩 custom provider，并将其设置为默认模型。Wizard 已经向该文件写入 gateway 和 agent settings。请合并以下 keys，不要替换整个文件。

```json theme={null}
{
  "models": {
    "providers": {
      "siflow": {
        "baseUrl": "https://api.siflow.cn/model-api/v1",
        "apiKey": "${SIFLOW_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "glm-5.2",
            "name": "siflow glm-5.2",
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "siflow/glm-5.2" }
    }
  }
}
```

| 字段                              | 说明                                                                               |
| ------------------------------- | -------------------------------------------------------------------------------- |
| `baseUrl`                       | siflow OpenAI-compatible endpoint：`https://api.siflow.cn/model-api/v1`。          |
| `apiKey`                        | `${VAR}` interpolation 会从 `~/.openclaw/.env`、当前工作目录的 `.env` 或环境变量读取。也可以直接粘贴 key。 |
| `api`                           | Wire protocol。使用 `openai-completions`。                                           |
| `contextWindow` / `maxTokens`   | 设置为所选模型的实际限制。                                                                    |
| `agents.defaults.model.primary` | 默认模型，格式为 `<provider>/<model>`。                                                   |

<Warning>
  请将 `contextWindow` 和 `maxTokens` 设置为所选模型的实际限制。过大的值会被平台拒绝。
</Warning>

OpenClaw 的 agent 功能依赖模型原生 tool calling。请使用支持该能力的模型。

也可以不手动编辑 `agents.defaults.model.primary`，而运行：

```bash theme={null}
openclaw models set siflow/glm-5.2
openclaw models list
```

如果想使用 Anthropic-compatible endpoint，请将 `api` 设置为 `anthropic-messages`，并将 `baseUrl` 设置为 `https://api.siflow.cn/model-api`。

Gateway 会监听 `~/.openclaw/openclaw.json`，并自动热加载 model 和 agent 变更。如果变更没有生效，可以强制重启：

```bash theme={null}
openclaw gateway restart
```

<Info>
  在 containers 或其他没有 systemd user services 的环境中，`openclaw gateway restart` 会报告 **"Gateway service disabled"**。这不会阻塞使用：chat TUI（`openclaw`）和 `openclaw agent --local` 会以内嵌方式运行 agent，并读取同一份配置，不需要 gateway。如果需要 gateway 用于 dashboard 或 messaging channels，请在另一个终端中运行 `openclaw gateway`。
</Info>

## 验证

```bash theme={null}
openclaw models list      # expect siflow/glm-5.2 with the "default,configured" tags

# one-shot task, runs the agent embedded — no gateway required
openclaw agent --agent main -m "introduce yourself in one sentence" --local
```

`agent` 命令要求消息放在 `-m` / `--message` 中，而不是 positional argument。还必须提供 session selector，例如 `--agent main`。

也可以通过 `openclaw chat` 启动 chat TUI。它是 `tui --local` 的 alias，与 setup wizard 进入的是同一种 embedded interface。发送消息并确认收到正常回复。

如果运行了 daemonized gateway，还可以检查：

```bash theme={null}
openclaw gateway status   # expect: running on port 18789
```

然后可以使用已连接的 channel，或通过 `openclaw dashboard` 打开 dashboard，地址为 `http://127.0.0.1:18789/`。

## 常见问题

* **Unknown model: siflow/glm-5.2 ... no matching models.providers\[...] entry**：默认模型已注册，但 provider block 缺失，或配置修改没有传递到 gateway。请检查 `~/.openclaw/openclaw.json` 中是否存在 `models.providers.siflow`，并重启 gateway。
* 如果认证失败，请检查 `~/.openclaw/.env` 中的 key 是否没有引号或多余空格，并在配置变更后重启 gateway。