OpenClaw - 自托管 AI 智能助手平台
OpenClaw 教程 — 安装 OpenClaw、对接 88API,快速搭建自托管 AI 助手。开源项目,支持 Telegram、Discord、WhatsApp 等多渠道集成。
项目介绍
OpenClaw 是一个开源、自托管的个人 AI 助手平台,将消息应用连接到运行在你自己硬件上的 AI 代理。专为开发者和高级用户设计,无需交出数据控制权即可拥有自主 AI 助手。
OpenClaw 完全开源,你可以在 OpenClaw 的 GitHub 仓库 浏览源码、提交 Issue 或参与贡献。本教程涵盖安装、配置,以及将 OpenClaw 对接 88API 的完整步骤。
🌟 核心特性
多渠道集成
- 多渠道集成:支持 Telegram、Discord、WhatsApp、iMessage 等多种消息渠道,也可通过插件扩展更多平台
- 单一网关:通过一个 Gateway 进程统一管理所有渠道
- 语音支持:支持 macOS/iOS/Android 语音交互
- Canvas 界面:可渲染交互式 Canvas 界面
自托管与数据安全
- 完全自托管:运行在你自己的机器或服务器上
- 开源透明:MIT 开源协议,代码完全透明
- 数据本地化:上下文和技能存储在你的本地计算机,而非云端
智能代理能力
- 持续运行:支持后台常驻运行,拥有持久记忆
- 计划任务:支持 cron 定时任务
- 会话隔离:按代理/工作区/发送者隔离会话
- 多代理路由:支持多代理协同工作
- 工具调用:原生支持工具调用和代码执行
📦 接入前准备
准备信息
- Node.js 24.16+ 或 26.1+(官方推荐 Node 26;Node 22、23、25 不受支持。官方一键安装脚本会自动处理 Node 环境)
- 88API 接口地址:
https://api.88api.ai/v1 - 在 88API 控制台创建的 API Key
- API Key 请妥善保管,不要粘贴到来源不明的应用或页面。
在开始接入 88API 之前,建议先按 OpenClaw 官方当前推荐流程把 Gateway 和 Control UI 跑起来。这样后续排查问题时,更容易区分是 OpenClaw 本身未启动,还是模型提供商配置有误。
1. 安装 OpenClaw
macOS/Linux:
curl -fsSL https://openclaw.ai/install.sh | bashWindows(PowerShell):
iwr -useb https://openclaw.ai/install.ps1 | iex其他安装方式可参考 OpenClaw 官方文档:Getting Started。
2. 运行引导向导
openclaw onboard --install-daemon该向导会完成基础认证、Gateway 设置,以及可选的渠道初始化。这里的目标是先把 OpenClaw 跑起来,后面再把默认模型切到 88API。
官方安装脚本结束后会自动启动这个向导;如果你已经在安装时完成了向导,可以跳过本步。向导要求先接通一个可用的模型才能完成。只有 88API 密钥时,在模型提供商列表中选择 More… → Custom Provider:Base URL 填 https://api.88api.ai/v1(必须带 /v1),兼容类型(Compatibility)保持默认 openai,Model ID 填 gpt-6.1-sol,再粘贴 88API 密钥。向导会实际请求一次,验证通过后才保存。向导创建的 provider 名称类似 custom-api-88api-ai,与后文手动添加的 api88 可以并存。
不要选 Skip for now:它会直接退出,不启动 Gateway,下一步的检查会失败。
3. 检查 Gateway 与 Control UI
openclaw gateway statusopenclaw dashboard如果浏览器能打开 Control UI,说明 OpenClaw 基础运行已经正常。这个阶段不需要先配置 Telegram、Discord、飞书等消息渠道。
4. 定位配置文件
OpenClaw 的配置文件通常位于 ~/.openclaw/openclaw.json,你可以在引导向导生成的基础上继续修改。
路径相关环境变量
如果你把 OpenClaw 跑在专用服务账号下,或希望自定义配置/状态目录,可以使用:
OPENCLAW_HOMEOPENCLAW_STATE_DIROPENCLAW_CONFIG_PATH
详细说明见官方环境变量文档:Environment Variables。
🚀 使用 88API 作为模型提供商
OpenClaw 支持通过 models.providers 接入自定义或兼容 OpenAI 接口的模型网关。对于 88API,最常见的做法是把它作为一个自定义 provider 加进配置里,再把默认模型指向 api88/模型ID。
接入思路
- 在
models.providers下声明一个api88provider - 将
baseUrl设为https://api.88api.ai/v1(必须包含/v1) - 将
api设为openai-completions - 在
models中列出你希望 OpenClaw 使用的模型 ID - 在
agents.defaults.model.primary中把默认模型切到api88/...
推荐做法:用环境变量保存密钥
Gateway 以后台服务运行(第 2 步 --install-daemon)时,读不到你在终端里 export 的变量。请把密钥写入 OpenClaw 官方推荐的全局环境文件 ~/.openclaw/.env(设置了 OPENCLAW_STATE_DIR 时为该目录下的 .env),然后重启 Gateway:
macOS/Linux:
echo 'API88_API_KEY=sk-your-88api-key' >> ~/.openclaw/.env
openclaw gateway restartWindows(PowerShell):
Add-Content -Path "$HOME\.openclaw\.env" -Value 'API88_API_KEY=sk-your-88api-key' -Encoding ascii
openclaw gateway restart然后在 openclaw.json 里补充或修改以下片段:
{
models: {
mode: "merge",
providers: {
api88: {
baseUrl: "https://api.88api.ai/v1",
apiKey: "${API88_API_KEY}",
api: "openai-completions",
models: [
{ id: "gemini-3.5-flash", name: "Gemini 3.5 Flash" },
{ id: "kimi-k3", name: "Kimi K3" },
],
},
},
},
agents: {
defaults: {
model: {
primary: "api88/gemini-3.5-flash",
fallbacks: ["api88/kimi-k3"],
},
models: {
"api88/gemini-3.5-flash": { alias: "flash" },
"api88/kimi-k3": { alias: "kimi" },
},
},
},
}这不是一份必须原样照抄的完整配置,而是接入 88API 最关键的部分。只要 provider、模型 ID 和默认模型引用对应正确,OpenClaw 就能通过 88API 调用对应模型。
关键配置说明
| 配置项 | 说明 |
|---|---|
models.mode | 建议设为 merge,在保留 OpenClaw 内置 provider 的同时追加 api88 |
models.providers.api88.baseUrl | 88API 接口地址 https://api.88api.ai/v1,必须带上 /v1 |
models.providers.api88.apiKey | 88API 密钥,推荐通过 ${API88_API_KEY} 注入 |
models.providers.api88.api | 对于 88API 这类 OpenAI 兼容网关,使用 openai-completions |
models.providers.api88.models | 这里列出的模型 ID 必须与 88API 实际提供的模型名称一致 |
agents.defaults.model.primary | 默认主模型,格式必须是 provider/model-id |
agents.defaults.model.fallbacks | 备选模型列表,主模型失败时自动切换 |
agents.defaults.models | 可选,用来给模型起别名,方便在 UI 或会话里引用 |
验证是否接入成功
完成配置后,回到 Control UI 或重新打开:
openclaw dashboard如果你能在 OpenClaw 中正常发起对话,并且默认模型已经变成 api88/...,说明接入成功。你也可以使用:
openclaw models list确认 api88/ 前缀的模型已经出现在可选列表中。
常见问题
baseUrl没带/v1:这是最常见的接入错误之一。- 模型 ID 填错:
primary和fallbacks必须与models.providers.api88.models里的id对应。 - 密钥只在当前终端生效:后台服务不会继承终端里 export 的变量,请写入
~/.openclaw/.env后执行openclaw gateway restart。 - 想前台排障:可使用官方前台运行方式
openclaw gateway --port 18789观察日志与报错。