QClaw 本地化 AI 个人助手平台使用指南

QClaw 基于网关（Gateway）模式设计。整个系统的工作流程可以用以下简化的数据流来描述：

用户消息 → 聊天渠道 (WhatsApp/Telegram/Discord/…) → OpenClaw Gateway ↓ AI Agent (Pi / Claude / GPT) ↓ 工具调用 (搜索/代码/文件/…) ↓ AI 回复 → OpenClaw Gateway → 聊天渠道 → 用户 

所有渠道的接入、Agent 的调度、工具的执行，均由 Gateway 统一处理。这种架构的优势在于：

1. 单一入口：只需部署一个 Gateway，就能同时服务多个聊天渠道。
2. 会话隔离：不同渠道、不同用户可以拥有独立的 Agent 会话空间。
3. 工具扩展：工具系统以插件化方式加载，新增工具无需修改核心代码。

2.2 关键组件

2.2.1 Gateway（网关）

Gateway 是 QClaw 的核心进程，负责：

• 维护与各聊天渠道的连接（WhatsApp Web、Bot API、WebSocket 等）
• 管理 AI Agent 的会话状态
• 路由消息和工具调用
• 处理定时任务（Cron）和 Webhook
• 提供 Web 控制台（Control UI）

Gateway 支持热重载配置，修改配置文件后无需手动重启即可生效。

2.2.2 Agent（智能体）

Agent 是实际执行 AI 推理和工具调用的实体。OpenClaw 支持：

• Pi Agent（默认，基于 OpenClaw 内置的 Pi 编码智能体）
• 多 Agent 路由：可以为不同渠道、不同用途配置不同的 Agent 实例，每个 Agent 有独立的工作空间（Workspace）和会话记忆。

配置示例：

{
  "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" } }
  ]
}

2.2.3 Skills（技能系统）

Skills 是 OpenClaw 的插件式功能扩展单元。每个 Skill 是一个独立的功能包，可以向 Agent 提供特定能力，例如：

• arxiv-reader：arXiv 论文阅读助手
• weather-advisor：天气查询和建议
• habit-tracker：习惯追踪和打卡
• travel-planner：旅行规划
• content-factory：多代理内容生产线

用户也可以通过 skill-creator Skill 从零编写自己的技能。

2.2.4 Channels（渠道接入）

OpenClaw 原生支持多种聊天渠道：

所有渠道共享统一的 DM 策略模型（pairing / allowlist / open / disabled），方便统一管理访问权限。

三、主要功能特性

3.1 跨平台消息接入

QClaw 最大的亮点之一是多渠道统一接入。用户可以同时在多个聊天平台上与同一个 AI 助手对话，而 AI 助手拥有统一的记忆和上下文。

以 WhatsApp 为例，只需在 QClaw 控制台中扫描二维码完成绑定，后续在该账号下收到的所有私信都会自动路由到 AI Agent 进行处理。整个过程对对方来说，感觉就像在和一个真人聊天一样。

Telegram 则需要先在 BotFather 创建一个 Bot，将 Bot Token 配置到 OpenClaw 配置文件中，之后用户通过与 Bot 对话来使用 AI 助手。

3.2 Web 控制台（Control UI）

QClaw 内置了一个功能完整的 Web 控制台，通过浏览器即可访问。默认地址为 http://127.0.0.1:18789/。

控制台提供了以下功能模块：

• 聊天界面：直接在浏览器中与 AI 对话，无需任何渠道配置。
• 会话管理：查看、切换、归档不同的话题会话。
• 配置编辑器：图形化编辑 openclaw.json 配置文件，支持表单视图和原始 JSON 视图切换。
• 节点管理：查看和管理已配对的移动端节点。
• Cron 任务：管理定时任务和自动化工作流。
• 日志查看：实时查看 Gateway 运行日志，方便排查问题。

控制台采用热加载设计，修改配置后大多数设置可以立即生效，无需重启 Gateway。

3.3 移动端节点配对

QClaw 支持将 iOS 和 Android 设备配对为"节点"（Node），从而解锁丰富的设备级操作能力：

iOS 节点能力：

• Canvas 协同：在配对的 iOS 设备上展示 AI 生成的网页内容，AI 可以实时读取页面状态。
• 相机控制：通过 AI 指令触发手机摄像头拍照或录制视频。
• 语音对话：在手机端直接进行语音输入/输出。
• 屏幕录制：AI 可以发起屏幕录制并获取结果。
• 位置获取：获取设备当前位置信息。
• 推送通知：通过 APNs 推送消息到手机。

Android 节点能力（更丰富）：

除了上述 iOS 的能力外，Android 节点还额外支持：

• 设备状态查询：电池、存储、运行状态等。
• 通知列表读取：读取手机通知栏内容。
• 通讯录/日历读写：搜索和添加联系人、日历事件。
• 短信收发：在 AI 的控制下发送和接收短信。
• 运动数据：计步、运动状态等。

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

3.4 云端文件存储与分享

QClaw 深度集成了腾讯云对象存储（COS）服务，为用户提供便捷的文件管理能力：

• 文件上传：通过 @qclaw/cos-uploader 命令将本地文件一键上传至云端。上传后自动生成短链接，支持微信小程序内直接预览，PC 端扫码查看。
• 文件大小无限制：小文件（≤50 MB）直接上传；大文件采用分片（Multipart Upload）方式，自动分块传输，理论上支持任意大小的文件。
• 批量上传：支持一次性上传多个文件，云端文件名冲突时可选择覆盖或重命名。
• 文件管理：支持查询云端文件信息、列目录、重命名、移动等操作。
• 保留策略：上传文件默认保留 30 天后自动清理，短链接在有效期内可随时访问。

这意味着用户可以让 AI 助手帮忙生成报告、图片或代码文件，然后直接上传到云端并分享链接，整个过程无需打开任何云存储管理界面。

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

QClaw 内置了完整的 Cron 任务调度系统，支持：

• 定时触发：按 cron 表达式或固定间隔执行任务。
• Agent 自动化：让 AI 在特定时间自动执行操作，例如"每天早上 8 点给我发一条天气简报"或"每周一自动搜索并总结上周 AI 领域的最新论文"。
• Webhook 集成：接收外部 HTTP 请求并触发 Agent 响应，实现与第三方服务的集成。
• 任务历史记录：每次 Cron 执行的结果都被记录下来，方便回溯和调试。

3.6 多模型支持与灵活配置

OpenClaw 不绑定特定的大模型提供商，支持主流的 AI 模型：

• Anthropic 系列：Claude 3.5 Sonnet、Claude 3 Opus 等
• OpenAI 系列：GPT-4o、GPT-4 Turbo 等
• 其他兼容 OpenAI API 格式的模型（通过自定义 Provider 接入）

用户可以在配置文件中定义多个模型，设定主模型和备用模型，形成模型降级链（Model Failover）。当主模型不可用时，自动切换到备用模型，保证服务的高可用性。

3.7 安全与隐私控制

作为本地部署方案，QClaw 在数据安全方面提供了多层保障：

• DM 访问策略：可配置为仅接受配对用户（pairing）或仅允许名单用户（allowlist）的消息。
• 群组提及门控：在群组聊天中，AI 默认仅在被 @ 提及时响应，避免无关消息干扰。
• 执行审批：涉及系统命令执行的场景需要用户手动审批，防止 AI 误操作。
• 会话隔离：不同用户/渠道的会话数据完全隔离，互不干扰。
• 配置验证：OpenClaw 对配置文件进行严格校验，拒绝无效或存在安全风险的配置。

四、安装与配置

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 安装步骤

4.2.1 安装 OpenClaw（核心引擎）

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.2.2 初始化配置

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

openclaw onboard --install-daemon

向导会引导你：

1. 配置 AI API 密钥（Anthropic / OpenAI 等）
2. 选择要接入的聊天渠道并完成绑定
3. 配置访问控制策略
4. 启动 Gateway 服务

4.2.3 启动网关服务

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

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

4.2.4 打开控制台

openclaw dashboard

或直接在浏览器中访问 http://127.0.0.1:18789/。

4.3 配置文件

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

{
  // AI Agent 默认设置
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-4o"]
      },
      "workspace": "~/.openclaw/workspace"
    }
  },
  // 渠道配置：以 WhatsApp 为例
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+86138xxxxxxxx"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  // 网关设置
  "gateway": {
    "port": 18789
  },
  // 心跳检查（每 30 分钟自动唤醒检查）
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "whatsapp"
      }
    }
  }
}

修改配置文件后，Gateway 会自动检测并热加载大多数变更，无需手动重启。

4.4 常见渠道配置要点

WhatsApp：

• 通过控制台扫描二维码完成账号绑定
• 建议设置 allowFrom 为可信手机号列表，防止陌生人滥用

Telegram：

• 在 @BotFather 创建 Bot，获取 HTTP Bot Token
• 设置 dmPolicy: "pairing" 允许新用户申请配对

Discord：

• 创建 Discord Application，启用 Bot 功能
• 在 Bot 设置中开启 MESSAGE CONTENT INTENT
• 将 Bot 加入目标服务器，配置 allowFrom 为服务器 ID

五、日常使用场景

5.1 随身 AI 助手

最直接的使用方式：将 WhatsApp 或 Telegram 与 QClaw 绑定后，无论身在何处，只要掏出手机给 Bot 发一条消息，就能获得 AI 助手的帮助。查询资料、翻译文本、起草邮件、生成代码片段——所有操作都在熟悉的聊天界面中完成。

5.2 定时新闻摘要

通过 Cron 任务配置，让 QClaw 每天早上 8 点自动：

1. 搜索当天科技新闻
2. 提取摘要并格式化
3. 推送到你的 WhatsApp 或 Telegram

类似地，可以配置股市行情、天气预报、日程提醒等自动化推送任务。

5.3 旅行规划助手

告诉 QClaw：'帮我规划一个 5 天 4 晚的东京自由行'，AI 可以：

1. 搜索东京热门景点、美食、购物信息
2. 根据预算和偏好推荐行程路线
3. 生成详细的每日安排（包含交通、门票、时间）
4. 将行程整理为文档，上传到云端并分享链接

整个过程无需打开任何旅游网站，AI 帮你一站式搞定。

5.4 论文研究与文献管理

使用 arxiv-reader Skill，可以直接在聊天窗口中：

• 搜索指定主题的 arXiv 论文
• 让 AI 帮你总结论文核心观点和研究方法
• 追踪某个领域的最新发表动态

配合 Cron 任务，还能实现每周自动推送领域内最新论文摘要的功能。

5.5 移动端设备管理

当你的 Android 手机与 QClaw 完成配对后，可以实现以下操作：

• 发送"帮我拍一张照片"，手机自动拍照并传回
• 发送"查看手机通知"，AI 读取并汇总通知内容
• 发送"给 [联系人] 发一条短信：今晚 7 点见"，AI 帮你发送短信
• 发送"查看手机当前位置"，AI 获取 GPS 坐标并显示在地图上

这相当于为你的手机配备了一个可以用自然语言操控的 AI 管家。

5.6 代码开发助手

QClaw 内置的 Pi Agent 专为代码开发场景优化，支持：

• 代码生成、审查和重构
• 项目文件管理和批量操作
• Git 操作辅助
• 终端命令执行（需要用户审批）
• 复杂多文件任务的规划和执行

配合 Node 模式，还可以在远程服务器上直接执行代码开发任务。

六、进阶玩法

6.1 自定义 Skill 开发

OpenClaw 的 Skill 系统基于标准化接口设计。如果你有特定的业务需求，可以开发专属 Skill：

1. 创建 Skill 目录，编写 SKILL.md 描述文件
2. 定义 Skill 支持的工具函数和调用方式
3. 将 Skill 放入 ~/.openclaw/skills/ 目录
4. 在配置中启用 Skill：设置 skills.entries.<skill-name> 并配置 API Key（如需要）

已有的社区 Skill 可以在 ClaWHub（https://clawhub.com）上发现和安装。

6.2 Webhook 与第三方服务集成

通过 OpenClaw 的 Webhook 机制，可以接收来自外部服务的 HTTP 请求并触发 Agent 响应：

• Gmail 集成：新邮件到达时自动推送给 AI，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 配置，根据消息来源或关键词自动路由到对应的 Agent，实现专业分工。

6.4 沙箱执行环境

OpenClaw 支持 Docker 沙箱模式，Agent 可以在隔离的容器中执行代码和命令，杜绝了对宿主机造成意外影响的风险：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}

6.5 远程访问配置

OpenClaw 支持通过 Tailscale 或 SSH 反向隧道实现远程访问，让你即使不在本地网络环境中，也能通过手机远程操控家中的 AI 助手。具体配置方法可参考官方文档中关于 gateway.remote 和 gateway.bind 的说明。

七、QClaw 的使用感受与总结

经过实际使用，QClaw 给我留下最深刻印象的是以下三点：

第一，真正的"随身 AI"体验。 过去要使用 AI 助手，往往需要打开特定的 App 或网页，步骤繁琐且容易打断工作流。QClaw 将 AI 直接嵌入到日常的聊天软件中，让与 AI 交互变得和给朋友发消息一样自然。这种无感知的集成极大地降低了使用门槛。

第二，隐私与控制的平衡。 所有对话数据默认保留在本地，网关运行在自己的机器或服务器上，用户对数据拥有完全的控制权。相比纯 SaaS 方案，这在处理敏感信息时是一个巨大的心理保障。同时，OpenClaw 的访问控制机制也足够细致，可以精确控制谁能访问、能访问什么。

第三，扩展性的设计哲学。 Skill 系统、插件化渠道、多 Agent 路由、Webhook 集成——OpenClaw 从架构层面就为扩展预留了大量空间。无论你是个人用户只是想简单用一用，还是企业用户需要深度定制，都能找到适合自己的切入角度。

当然，作为一款相对年轻的开源项目，QClaw 在某些方面仍有成长空间。例如某些渠道的接入文档还不够详细，部分高级功能（如沙箱、Docker 集成）的上手门槛对非技术用户略高。但总体而言，它已经是一个非常成熟、功能完整的解决方案。

八、结语

AI 助手正在从"新鲜玩意儿"变成我们日常工作中离不开的工具。在这个过程中，如何让 AI 更好地融入我们的工作流、如何在享受 AI 便利的同时保护好个人隐私，是每个用户都需要思考的问题。

QClaw 给出了一个值得尝试的答案：本地部署、自主控制、无缝集成。它不追求最炫酷的功能，而是专注于把"让 AI 在你身边"这件事做到极致。

对于需要本地化 AI 助手的用户，QClaw 提供了完整的解决方案。

项目地址：

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