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

# OpenClaw

> 安装 OpenClaw、对接 MixRoute API，快速搭建自托管 AI 助手

## 项目介绍

OpenClaw 是一个开源、自托管的个人 AI 助手平台，将消息应用连接到运行在你自己硬件上的 AI 代理。专为开发者和高级用户设计，无需交出数据控制权即可拥有自主 AI 助手。

* **GitHub**：[https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)
* **项目文档**：[https://docs.openclaw.ai](https://docs.openclaw.ai/)
* **官方主页**：[https://openclaw.ai](https://openclaw.ai/)

OpenClaw 完全开源，你可以在 [OpenClaw 的 GitHub 仓库](https://github.com/openclaw/openclaw) 浏览源码、提交 Issue 或参与贡献。本教程涵盖安装、配置，以及将 OpenClaw 对接 MixRoute API 的完整步骤。

## 🌟 核心特性

### 多渠道集成

* **Canvas 界面**：可渲染交互式 Canvas 界面
* **语音支持**：支持 macOS/iOS/Android 语音交互
* **单一网关**：通过一个 Gateway 进程统一管理所有渠道
* **多渠道集成**：支持 Telegram、Discord、WhatsApp、iMessage 等多种消息渠道，也可通过插件扩展更多平台

### 自托管与数据安全

* **数据本地化**：上下文和技能存储在你的本地计算机，而非云端
* **开源透明**：MIT 开源协议，代码完全透明
* **完全自托管**：运行在你自己的机器或服务器上

### 智能代理能力

* **工具调用**：原生支持工具调用和代码执行
* **多代理路由**：支持多代理协同工作
* **会话隔离**：按代理/工作区/发送者隔离会话
* **计划任务**：支持 cron 定时任务
* **持续运行**：支持后台常驻运行，拥有持久记忆

## 📦 接入前准备

<CardGroup cols={1}>
  <Card title="准备信息" icon="list-check">
    * Node.js 22 或更高版本
    * 一个可用的 MixRoute API 地址（通常以 `/v1` 结尾）
    * 一个可用的 MixRoute API Key
  </Card>
</CardGroup>

在开始接入 MixRoute API 之前，建议先按 OpenClaw 官方当前推荐流程把 Gateway 和 Control UI 跑起来。这样后续排查问题时，更容易区分是 OpenClaw 本身未启动，还是模型提供商配置有误。

### 1. 安装 OpenClaw（macOS/Linux）

```bash theme={null}
curl -fsSL https://openclaw.ai/install.sh | bash
```

其他安装方式可参考 OpenClaw 官方文档：[Getting Started](https://docs.openclaw.ai/start/getting-started)。

### 2. 运行引导向导

```bash theme={null}
openclaw onboard --install-daemon
```

该向导会完成基础认证、Gateway 设置，以及可选的渠道初始化。这里的目标是先把 OpenClaw 跑起来，后面再把默认模型切到 MixRoute API。

### 3. 检查 Gateway 与 Control UI

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

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

如果浏览器能打开 Control UI，说明 OpenClaw 基础运行已经正常。这个阶段不需要先配置 Telegram、Discord、飞书等消息渠道。

### 4. 定位配置文件

OpenClaw 的配置文件通常位于 `~/.openclaw/openclaw.json`，你可以在引导向导生成的基础上继续修改。

<Tip>
  如果你把 OpenClaw 跑在专用服务账号下，或希望自定义配置/状态目录，可以使用环境变量 `OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、`OPENCLAW_HOME`。详细说明见官方文档：[Environment Variables](https://docs.openclaw.ai/help/environment)。
</Tip>

## 🚀 使用 MixRoute API 作为模型提供商

OpenClaw 支持通过 `models.providers` 接入自定义或兼容 OpenAI 接口的模型网关。对于 MixRoute API，最常见的做法是把它作为一个自定义 provider 加进配置里，再把默认模型指向 `mixroute/模型ID`。

### 接入思路

1. 在 `models.providers` 下声明一个 `mixroute` provider
2. 将 `baseUrl` 指向你的 MixRoute API 地址，并确保包含 `/v1`
3. 将 `api` 设为 `openai-completions`
4. 在 `models` 中列出你希望 OpenClaw 使用的模型 ID
5. 在 `agents.defaults.model.primary` 中把默认模型切到 `mixroute/...`

### 推荐做法：用环境变量保存密钥

先在当前 shell、服务环境，或 OpenClaw 可读取的 `.env` 中提供你的 MixRoute API 密钥：

```bash theme={null}
export MIXROUTE_API_KEY="sk-your-mixroute-key"
```

然后在 `openclaw.json` 里补充或修改以下片段：

```json theme={null}
{
  "models": {
    "mode": "merge",
    "providers": {
      "mixroute": {
        "baseUrl": "https://api.mixroute.ai/v1",
        "apiKey": "${MIXROUTE_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "gemini-3.5-flash", "name": "Gemini 3.5 Flash" },
          { "id": "kimi-k2.7-code", "name": "Kimi K2.7 Code" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "mixroute/gemini-3.5-flash",
        "fallbacks": ["mixroute/kimi-k2.7-code"]
      },
      "models": {
        "mixroute/gemini-3.5-flash": { "alias": "flash" },
        "mixroute/kimi-k2.7-code": { "alias": "kimi" }
      }
    }
  }
}
```

这不是一份必须原样照抄的完整配置，而是接入 MixRoute API 最关键的部分。只要 `provider`、模型 ID 和默认模型引用对应正确，OpenClaw 就能通过 MixRoute API 调用你暴露出来的模型资源。

### 关键配置说明

| 配置项                                 | 说明                                                            |
| ----------------------------------- | ------------------------------------------------------------- |
| `models.mode`                       | 建议设为 `merge`，在保留 OpenClaw 内置 provider 的同时追加 `mixroute`        |
| `models.providers.mixroute.baseUrl` | 你的 MixRoute API 地址，通常为 `https://api.mixroute.ai/v1`，需包含 `/v1` |
| `models.providers.mixroute.apiKey`  | MixRoute API 密钥，推荐通过 `${MIXROUTE_API_KEY}` 注入                 |
| `models.providers.mixroute.api`     | 对于 MixRoute API 这类 OpenAI 兼容网关，使用 `openai-completions`        |
| `models.providers.mixroute.models`  | 这里列出的模型 ID 必须与 MixRoute API 实际暴露的模型名称一致                       |
| `agents.defaults.model.primary`     | 默认主模型，格式必须是 `provider/model-id`                               |
| `agents.defaults.model.fallbacks`   | 备选模型列表，主模型失败时自动切换                                             |
| `agents.defaults.models`            | 可选，用来给模型起别名，方便在 UI 或会话里引用                                     |

### 验证是否接入成功

完成配置后，回到 Control UI 或重新打开：

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

如果你能在 OpenClaw 中正常发起对话，并且默认模型已经变成 `mixroute/...`，说明接入成功。你也可以使用：

```bash theme={null}
openclaw models list
```

确认 `mixroute/` 前缀的模型已经出现在可选列表中。

### 常见问题

* **`baseUrl` 没带 `/v1`**：这是最常见的接入错误之一。
* **模型 ID 填错**：`primary` 和 `fallbacks` 必须与 `models.providers.mixroute.models` 里的 `id` 对应。
* **密钥只在当前终端生效**：如果 Gateway 以后台服务运行，请确保服务进程也能读取 `MIXROUTE_API_KEY`。
* **想前台排障**：可使用官方前台运行方式 `openclaw gateway --port 18789` 观察日志与报错。