QClaw：本地化 AI 个人助手平台完全指南

Agent（智能体）

实际执行 AI 推理和工具调用的实体。支持 Pi Agent（默认）及多 Agent 路由。不同渠道可配置不同的 Agent 实例，拥有独立的工作空间和会话记忆。

配置示例：

{
  "agents": {
    "list": [
      { "id": "home", "default": true, "workspace": "~/.openclaw/workspace-home" },
      { "id": "work", "workspace": "~/.openclaw/workspace-work" }
    ]
  },
  "bindings": [
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "telegram", "accountId": "work-bot" } }
  ]
}

Skills（技能系统）

插件式功能扩展单元。每个 Skill 是一个独立的功能包，例如 arxiv-reader（论文阅读）、weather-advisor（天气查询）、habit-tracker（习惯追踪）。用户也可通过 skill-creator 从零编写自己的技能。

Channels（渠道接入）

原生支持多种聊天渠道，包括 WhatsApp、Telegram、Discord、iMessage、Signal、Slack 等。所有渠道共享统一的 DM 策略模型（配对/白名单/开放/禁用），方便统一管理访问权限。

三、主要功能特性

3.1 跨平台消息接入

最大的亮点是多渠道统一接入。用户可在多个聊天平台上与同一个 AI 助手对话，AI 拥有统一的记忆和上下文。以 WhatsApp 为例，只需在控制台扫描二维码绑定，后续私信自动路由到 AI Agent；Telegram 则需创建 Bot 并配置 Token。

3.2 Web 控制台（Control UI）

内置完整的 Web 控制台，默认地址 http://127.0.0.1:18789/。提供聊天界面、会话管理、配置编辑器（支持表单与 JSON 切换）、节点管理、Cron 任务管理及日志查看。采用热加载设计，修改配置后大多数设置立即生效。

3.3 移动端节点配对

支持将 iOS 和 Android 设备配对为'节点'，解锁设备级操作能力：

• iOS：Canvas 协同、相机控制、语音对话、屏幕录制、位置获取、推送通知。
• Android：除 iOS 能力外，还支持设备状态查询、通知列表读取、通讯录/日历读写、短信收发、运动数据等。

配对过程采用设备身份验证机制，需用户在手机上确认授权。

3.4 云端文件存储与分享

深度集成腾讯云对象存储（COS）服务：

• 文件上传：一键上传生成短链接，支持微信小程序内预览。
• 大小限制：小文件直接上传，大文件分片传输。
• 批量管理：支持批量上传、重命名、移动及 30 天自动清理策略。

3.5 定时任务与自动化（Cron）

内置 Cron 任务调度系统，支持定时触发、Agent 自动化（如每日天气简报）、Webhook 集成及任务历史记录。

3.6 多模型支持与灵活配置

不绑定特定大模型提供商，支持 Anthropic（Claude）、OpenAI（GPT）及其他兼容 OpenAI API 格式的模型。可定义多个模型形成模型降级链，主模型不可用时自动切换备用模型。

3.7 安全与隐私控制

作为本地部署方案，提供多层保障：DM 访问策略（仅配对/白名单）、群组提及门控（@才响应）、执行审批（系统命令需确认）、会话隔离及配置严格校验。

四、安装与配置

4.1 环境要求

• 操作系统：Windows 10/11、macOS 10.14+
• Node.js：推荐 Node 24 或 Node 22 LTS (22.16+)
• 网络：需能访问所选 AI 模型提供商 API
• 账号：根据渠道准备相应账号（WhatsApp 个人号 / Telegram Bot Token 等）

4.2 安装步骤

macOS / Linux：

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

Windows（PowerShell）：

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

或通过 npm 全局安装：

npm install -g openclaw@latest

4.3 初始化与启动

运行引导向导完成认证、网关设置和渠道配置：

openclaw onboard --install-daemon

向导会引导配置 AI API 密钥、选择聊天渠道、配置访问控制策略并启动 Gateway 服务。

安装完成后，Gateway 会自动作为后台服务运行。也可手动管理：

openclaw gateway status # 查看状态
openclaw gateway start  # 启动
openclaw gateway stop   # 停止
openclaw gateway restart# 重启

打开控制台：

openclaw dashboard

或直接访问 http://127.0.0.1:18789/。

4.4 配置文件

配置文件位于 ~/.openclaw/openclaw.json（JSON5 格式，支持注释）。典型基础配置示例：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-4o"]
      },
      "workspace": "~/.openclaw/workspace"
    }
  },
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+86138xxxxxxxx"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "gateway": {
    "port": 18789
  },
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "whatsapp"
      }
    }
  }
}

修改后 Gateway 会自动检测并热加载变更。

五、日常使用场景

5.1 随身 AI 助手

将 WhatsApp 或 Telegram 与 QClaw 绑定后，随时随地发消息即可获得帮助。查询资料、翻译文本、起草邮件、生成代码片段，均在熟悉界面中完成。

5.2 定时新闻摘要

配置 Cron 任务，让 QClaw 每天早上 8 点自动搜索科技新闻、提取摘要并推送到聊天软件。同样适用于股市行情、天气预报等自动化推送。

5.3 旅行规划助手

告诉 QClaw：'帮我规划一个 5 天 4 晚的东京自由行'，AI 可搜索景点美食、推荐路线、生成详细安排，并将行程整理为文档上传云端分享。

5.4 论文研究与文献管理

使用 arxiv-reader Skill，直接在聊天窗口搜索 arXiv 论文，让 AI 总结核心观点和研究方法。配合 Cron 任务可实现每周自动推送领域最新论文摘要。

5.5 移动端设备管理

Android 手机配对后，可通过自然语言操控：

• '帮我拍一张照片'：手机自动拍照传回。
• '查看手机通知'：AI 读取并汇总通知内容。
• '给 [联系人] 发一条短信'：AI 代为发送。
• '查看手机当前位置'：AI 获取 GPS 坐标并显示。

5.6 代码开发助手

内置 Pi Agent 专为代码场景优化，支持代码生成、审查、重构、Git 操作辅助及终端命令执行（需审批）。配合 Node 模式，还可在远程服务器上直接执行开发任务。

六、进阶玩法

6.1 自定义 Skill 开发

基于标准化接口设计专属 Skill：

1. 创建目录，编写 SKILL.md 描述文件。
2. 定义工具函数和调用方式。
3. 放入 ~/.openclaw/skills/ 目录。
4. 在配置中启用 Skill 并配置 API Key。 社区 Skill 可在 ClaWHub 上发现和安装。

6.2 Webhook 与第三方服务集成

接收外部 HTTP 请求触发 Agent 响应：

• Gmail 集成：新邮件到达时自动推送给 AI。
• GitHub 集成：Issue/PR 事件触发 AI 处理。
• 监控系统集成：告警到达时 AI 自动分析。

配置示例：

{
  "hooks": {
    "enabled": true,
    "token": "your-shared-secret",
    "path": "/hooks",
    "mappings": [
      {
        "match": { "path": "gmail" },
        "action": "agent",
        "agentId": "main",
        "deliver": true
      }
    ]
  }
}

6.3 多 Agent 分工协作

为不同任务线配置不同 Agent：

• 主 Agent：日常对话和轻量任务。
• 研究 Agent：论文搜索、信息整理。
• 编码 Agent：代码开发任务。
• 数据 Agent：数据分析、报告生成。 通过 bindings 配置实现自动路由。

6.4 沙箱执行环境

支持 Docker 沙箱模式，Agent 在隔离容器中执行代码和命令，杜绝影响宿主机风险。

6.5 远程访问配置

支持通过 Tailscale 或 SSH 反向隧道实现远程访问，即使不在本地网络也能通过手机操控家中 AI 助手。

七、总结

QClaw 的核心价值体现在三个方面：

1. 真正的'随身 AI'体验：将 AI 嵌入日常聊天软件，交互自然，降低使用门槛。
2. 隐私与控制的平衡：数据保留在本地，网关运行在自有机器上，配合细致的访问控制机制，处理敏感信息更安心。
3. 扩展性的设计哲学：Skill 系统、插件化渠道、多 Agent 路由预留了大量空间，适合从个人用户到企业定制的不同需求。

尽管作为相对年轻的开源项目，部分渠道接入文档和高级功能的上手门槛仍有优化空间，但总体而言，它已是一个非常成熟、功能完整的解决方案。

AI 助手正从'新鲜玩意儿'变成日常工作离不开的工具。QClaw 给出了一个值得尝试的答案：本地部署、自主控制、无缝集成。它专注于把'让 AI 在你身边'这件事做到极致。

项目资源：

• OpenClaw 主仓库：https://github.com/openclaw/openclaw
• 官方文档：https://docs.openclaw.ai
• 社区 Skill 市场：https://clawhub.com