社区投稿 | Clawdbot：技术架构与国产软件生态适配分析

文章首先介绍了 2026 年初爆火的开源项目 Clawdbot，这是一个主打“本地优先”和“隐私受控”的个人 AI 网关。其核心架构由控制平面（Gateway）、执行平面（Pi Agent）、接入层（多渠道集成）和知识扩展层（Skills）组成，支持将 AI 能力无缝嵌入 WhatsApp、Telegram 等通信工具。随后，文章重点分析了该架构在国产生态下的适配潜力：认为飞书、企业微信和钉钉由于具备完善的官方 API，是适配价值最高且技术难度较低的通道；而个人微信因合规和封号风险，不建议协议级接入。此外，文章还探讨了将 WPS、腾讯会议及国产 AI 搜索（如博查、U 深搜）集成到工具层的方案，为构建适配国内环境的私人 AI 助理提供了清晰的技术路径。

---

PSPDFKit/Nutrient 创始人 Peter Steinberger 开源了个人 AI 网关项目 Clawdbot，核心致力于打造可自托管、跨平台交互的本地优先型 AI 助理，实现“AI能力嵌入现有通信场景、数据完全自主掌控”的核心目标。该项目自2026年1月推出后迅速引爆开发者社区，短短数周内 GitHub 星标量突破40K+，单日最高涨星9000+，同时斩获4.6K+ forks，成为年初最热门的开源 AI 项目之一，其“单网关+多渠道”架构为本地 AI 助理落地提供了全新范式。

作为开源个人 AI 网关，Clawdbot 的核心价值在于打破传统 Chatbot 的平台依附性，通过内置的多渠道适配器与 WebSocket 控制平面，实现 WhatsApp、Telegram、Discord 等海外通信工具与本地 AI 大脑的统一对接。其架构核心为单进程网关服务，集成平台连接器、AI Agent RPC 通信模块、Web UI 配置面板三大核心组件，支持持久化会话管理、主动消息推送与跨平台媒体处理，所有数据均运行于个人基础设施，从根源保障隐私安全。

尽管架构设计极具创新性，但原版 Clawdbot 深度绑定海外生态，对国内开发者落地形成显著壁垒。基于其开源架构的可扩展性，本文聚焦两大核心方向展开国产适配分析：一是技术架构层面的改造，基于现有插件化渠道适配器，开发飞书、钉钉的专属适配模块，通过对接企业级 API 实现组织架构同步、审批流联动与消息回调，同时优化本地模型接入配置，解决 Ollama/LMStudio 与国产模型的兼容性问题；二是合规与场景适配，针对个人微信的第三方接入规范，设计基于官方开放能力的间接交互方案，规避合规风险，同时适配国产化操作系统与硬件环境，优化资源占用以适配个人终端部署。

依托 Clawdbot 的开源基础，国产化适配的核心价值在于保留“本地数据主权”的核心优势，同时打通国内主流办公与社交场景。后续将进一步拆解渠道适配器的接口规范、本地模型的配置优化细节，以及企业级平台适配的权限管控方案，为构建适配国产生态的私人 AI 助理提供完整技术参考。

Clawdbot 完整技术架构梳理 

Clawdbot 是一个运行在你个人设备上的私人 AI 助手，设计目标为随时可用、注重隐私，并集成到现有的沟通工作流中。与需要专用应用程序或 Web 界面的基于云端的助手不同，Clawdbot 在你日常使用的渠道上为你提供服务——包括 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams 等——同时保持对数据和配置的本地控制。

图1：Clawdbot交互演示：通过WhatsApp实现的本地AI助手对话

从设计思路上，Clawdbot 本质是一个本地优先的 AI 网关（AI Gateway）+ 多端助手，而不是单纯的一个机器人程序。该系统基于一个简单的原则运行：单用户、个人基础设施、多渠道访问。这意味着你在 macOS、Linux 或通过 WSL2 运行的 Windows 上部署一次 Clawdbot，将其连接到你选择的消息平台，并通过熟悉的界面与你的 AI 助手交互。无论你是在手机上向 WhatsApp 发送消息，在桌面上使用 Discord 聊天，还是通过浏览器使用 Web 仪表板，所有交互都通过你的个人 Gateway 实例流转——将对话、上下文和配置完全保留在你的控制之下。

Clawdbot 的架构围绕一个 Gateway 守护进程 展开，它是所有渠道连接和 AI 交互的唯一真实来源。该设计确保了所有连接平台的状态管理、配置集中和日志记录的一致性。Gateway 提供两个主要接口：用于与移动应用和扩展进行实时通信的 WebSocket 控制平面，以及用于基于浏览器的 Control UI 和 Canvas 主机的 HTTP 服务器。

该架构遵循消息路由模式，来自不同渠道的传入通信被标准化为通用格式，通过 Agent 系统处理，然后将响应传回原始渠道。这一抽象层使 Clawdbot 能够支持多样的消息协议，同时保持所有平台上一致的 Agent 行为和会话管理。

可以概括为四个层次：

• 控制平面（Control Plane） ：Gateway WebSocket 控制平面

• 执行平面（Execution Runtime） ：Pi agent 本地运行时 + 各类工具（Browser、Canvas、Nodes…）

• 接入层（Channels & Apps） ：各类消息通道（WhatsApp/Telegram/Slack/Discord…）和客户端（macOS/iOS/Android）

• 知识与扩展层（Workspace & Skills） ：本地工作区、技能系统、ClawdHub 插件生态

整体消息/任务流可以抽象为：

通道消息 → Gateway（会话路由 & 策略） → Agent（调用模型+工具）→ 工具执行（浏览器/系统/第三方） → 返回结果 → Gateway → 原通道回复

Gateway 是 Clawdbot 的“大脑中枢” ，负责：

统一的 WebSocket 控制平面 ：

• 管理所有客户端、通道、工具与事件

• 对外暴露统一的 WS 接口，作为“单一来源的真相（single control plane）”

会话与路由：

• 多会话模型（main 会话、群组隔离、激活模式、排队模式等）

• Multi-agent routing：可以把不同通道/群/联系人路由到不同的 Agent（不同工作区和人格）

状态与调度：

• presence / typing / usage tracking

• cron 任务与 wakeups

• Webhook 事件转发

运维：

• Control UI / WebDashboard

• Doctor（迁移/健康检查）、日志

• 支持 Tailscale Serve/Funnel、SSH 隧道，实现远程访问本地 Gateway 的 Dashboard

技术栈 ：

• Node.js ≥ 22，TypeScript 实现

• 通过 pnpm/npm/bun 安装和运行

• 默认运行为守护进程（daemon），长期在线

3.1 Pi Agent Runtime（“执行节点”）

通过 RPC 模式 与 Gateway 通信：

• 支持工具流（tools streaming）和块流（chunk streaming）

负责 实际执行任务 ，包括：

• 调用 LLM（云模型或本地模型）

• 执行系统命令（system.run）

• 操控浏览器（Browser control）

• 调用节点能力（摄像头、屏幕录制、通知等）

可以理解为：Gateway 负责“指挥和调度”，Pi Agent 负责“干活”。

3.2 工具体系（Tools & Automation）

核心工具类型包括：

Browser control :

• 管理本地的 Chrome/Chromium 实例

• 通过 CDP（Chrome DevTools Protocol）控制页面导航、点击、表单填写、截图等

Canvas / A2UI / Live Canvas :

• AI 双向驱动的可视化工作区

• 可以让 Agent 在“画布”上规划任务、展示结构化数据、做可视化操作

Nodes :

• 本地节点能力：摄像头快照/录制、屏幕录制、地理位置、系统通知

• macOS 特有能力：system.run/system.notify 等

Cron + Wakeups :

• 定时任务调度，周期性执行脚本或检查

Webhooks & Gmail Pub/Sub 等 ：

• 外部事件源订阅，触发内部工作流

Skills 平台 ：

• 将 CLI 工具、脚本、甚至第三方 API 封装成统一的“技能”接口

4.1 多渠道消息集成 Channels（消息通道）

Clawdbot 的优势在于其广泛的渠道支持，使你能够通过适合你工作流或设备偏好的任何消息平台与 AI 助手交互。核心渠道直接内置在主应用程序中，而其他平台则通过模块化插件系统提供，允许社区贡献和自定义集成。

当前官方主要支持 海外生态 ：

特点：

Multi-channel inbox ：统一收件箱

Group routing & Channel rules ：按群/通道配置策略：

• 哪些群允许机器人响应

• @ mention 触发 vs。 全量监听

• 私信（DM）策略：默认需要 pairing approve

4.2 Apps + Nodes（平台客户端）

macOS app :

• 菜单栏控制

• Voice Wake / Talk Mode（语音唤醒与对话悬浮窗）

• WebChat / 调试工具

• 作为 node 暴露 system.run/system.notify 等能力

iOS node :

• Canvas、Voice Wake、Talk、摄像头、屏幕录制等

Android node :

• Canvas、Talk、摄像头、屏幕录制，可选短信能力

Web UI :

• WebChat、Canvas/A2UI、控制台等

这些都通过 Gateway 的 WS 网络统一管理。

除了基本的聊天之外，Clawdbot 还包含一个丰富的技能系统，通过特定领域的能力扩展功能。Skills 是模块化包，添加新功能，如与外部服务的集成、专用工具或增强的命令处理。Skills 可以通过受控接口访问系统资源，并且可以按工作区启用或禁用，以实现细粒度控制。

Skills 生态系统包括：

• 生产力 Skill：与笔记集成（Notion、Obsidian、Apple Notes）、任务管理、日历系统

• 媒体 Skill：语音转录、图像生成、视频帧提取、音频处理

• 实用 Skill：天气信息、本地商家搜索、GitHub 集成、密码管理 （1Password）

• 开发 Skill：编码 Agent、git 操作、shell 命令执行、包管理

5.1 Workspace（工作区）

• 默认路径： ~/clawd （可配置）

• 每个 Agent 有自己的 workspace root

• 注入提示文件（Injected prompts）：

• AGENTS.md 、 SOUL.md 、 TOOLS.md 等

• 会话/记忆/配置多使用 Markdown 文件存储，类似 Obsidian 结构

5.2 Skills & ClawdHub

• 技能目录结构： ~/clawd/skills//SKILL.md

• 技能可以是：

• 本地脚本/CLI

• 外部 API

• 某类云服务集成

• ClawdHub：技能 registry，支持自动发现和拉取新技能

安全模型 ：

• DM policy：默认只对配对过的用户开放

• allowlist/denylist 策略

• 会话隔离（main vs。 non-main），Docker 沙箱等

部署 ：

• 本地安装：npm/pnpm/bun 全局安装 clawdbot

• Nix 模式、Docker 镜像

• 结合 Tailscale Serve/Funnel 暴露 Gateway dashboard 和 WS 访问

 国产软件生态适配可行性分析 

从 技术架构匹配度 看： Clawdbot 采用的是“通道插件化 + 工具插件化 + 技能插件化”，非常适合扩展国产生态， 不需要重写核心框架 。

真正的难点不在“能不能做”，而在于：

• 各家平台的 合规和账号策略

• 频率限制、权限申请

• 以及个人微信这类 没有官方开放 API 的场景。

下面分点逐一分析和给出可行路线。

1.1 个人微信

官方不提供个人号的公开 API（自建客服、自动回复等大多基于公众号/小程序、对话开放平台等）

市场上存在的方案：

• Windows API Hook / Xposed / PC 客户端模拟点击/键盘

• 第三方库：itchat、WeChatPYAPI 等，通过协议模拟

主要问题：

• 高封号风险 ：批量自动化、群发、高频操作容易被检测

• 法律与合规风险 ：未获微信官方授权

不建议在官方发行分支直接支持个人微信协议级接入

若一定要做，适合放在：

• 私有分支 / 本地脚本级 Skill

• 通过“本地浏览器自动化 + Web 微信/多开客户端”实现弱耦合控制，而非直接协议 Hook

1.2 企业微信（Work WeChat）

企业微信是 适配价值最高，也是风险最可控 的一类微信生态入口：

提供官方开放平台：

• Webhook 机器人：支持文本、Markdown、图片、卡片等消息类型

• 应用消息发送 API：可向指定用户/群发送消息，支持双向交互

• 事件订阅（接收消息 & 事件）：新消息、客户消息等通过回调 URL 推送

技术接入方式与 Clawdbot 当前海外通道非常类似：

企业微信 → 回调 URL → 本地 Gateway HTTP 入口 → Gateway → Agent

Gateway → 企业微信 API/Webhook → 群/用户

可行方案 ：

实现一个 WeComChannel （类似 TelegramChannel）：

• 入站：配置企业微信“接收消息服务器 URL”，指向 Gateway 的 HTTP/WS 入口，将消息转换为 Clawdbot 的统一消息结构

• 出站：使用企业微信应用消息 API 或群机器人 Webhook 发送响应

会话模型：

• 使用 userid / chatid 作为通道内用户/会话标识，映射到 Gateway sessionId

安全：

• 默认只对指定部门/群开放

• 使用企业微信的权限控制进行初级筛选，再配合 Clawdbot 自身的 pairing 机制

个人微信 不推荐 在官方架构中适配；企业微信适配 技术可行性高，合规性好，建议优先做 。

2.1 能力概览

官方开放平台非常完善：

• 机器人接收消息：当用户@机器人或发单聊消息时，钉钉推送 JSON 事件到你的服务端

• 发送群消息、单聊消息

• 获取用户、群信息等

• 自定义机器人（Webhook）单向推送

• 企业内部机器人（双向，支持接收@消息和单聊）

• 机器人：

• 服务端 API：

• 事件订阅：

2.2 与 Clawdbot 架构的契合

可以直接比照 Telegram/Slack 通道：

• 入站消息 ：

钉钉 → 机器人回调 URL（HTTP POST JSON）→ Clawdbot Gateway HTTP 入口 → 统一消息对象

• 出站消息 ：

Gateway → 钉钉机器人 Webhook / API → 群或个人

实现要点 ：

需要实现 DingTalkChannel ：

• 解析钉钉消息回调格式，转换为统一 MessageType（text/image/file 等）

• 维护 openConversationId / senderStaffId 等与 Clawdbot session 的映射

频率与权限：

• 注意钉钉的调用频率、并发限制

• 需要在企业/ISV 维度申请相应接口权限

技术适配几乎是“模板化工作”，只要参考已有海外通道实现； 综合可行性：高，建议作为企业场景的第一优先级通道之一（与企业微信/ 飞书 并列）。

飞书是 目前国内在开放平台友好度上最接近 Slack/Discord 的产品 ，对 Clawdbot 这种网关架构极其友好。

3.1 飞书能力

企业自建应用：

• 机器人能力（Bot），消息发送/接收

• 事件订阅： im.message.receive_v1 等

• Webhook：自定义机器人单向推送

• 丰富的服务端 API：群管理、多维表格、日程等

3.2 与 Clawdbot 的集成方式

基本等价于实现一个 FeishuChannel ：

• 入站：

飞书应用配置“事件订阅 URL”→ 指向 Gateway 的 HTTP 服务

消息事件统一转成内部 Message 对象（content、sender、chatType、chatId 等）

• 出站：

使用 sendasbot 的消息 API 回复消息（文本/富文本/卡片）

优势 ：

• 官方 SDK 和文档完善

• 消息模型清晰，适合构建复杂的自动化和卡片交互

• 飞书本身已经大规模支持 AI 场景（与 MCP、AI Agent 集成），生态心智匹配

适配难度低、体验潜力最大，强烈建议作为首选国产通道进行 POC 和第一版支持。

WPS 分两层：

• WebOffice 开放平台 （云端文档预览/编辑/转换）

• 本地 WPS 客户端二次开发 / 插件 / JSAPI

4.1 WebOffice 场景

适合这种模式：

Clawdbot 作为“文档助手”，通过 WebOffice 开放平台：

• 获取文档内容（API 调用）

• 分析、总结、重写

• 写回文档，或生成新版本

实现方式：

定义 WpsWebOfficeSkill （Skill 层）：

• 获取文件元数据

• 获取/更新文件内容

• 触发格式转换（如 Word → PDF）

• 封装 WebOffice SDK 的 HTTP API：

4.2 本地 WPS 客户端

面向在用户 PC 上安装的 WPS：

有 JS API/SDK 可供二次开发

可以通过：

• WPS 插件（VBA/JS）

• 或通过本地 HTTP 服务 + 外部进程控制

在 Clawdbot 架构中：

建议把本地 WPS 调用封装为一个 Node 工具 或 本地 Skill ，由 Pi Agent 触发：

如 wps.open(filePath) / wps.saveAsPdf(filePath, outputPath)

WPS 更偏工具集成层（Tools/Skills），与通道适配解耦； 技术可行性高，主要工作量在封装 SDK 和做权限确认界面。

腾讯会议的适配，本质上是把它当做一个“会议控制技能”。

5.1 能力

REST API:

• 创建/预定会议

• 修改/取消会议

• 查询会议信息、参会者

• SDK:

• 深度集成到自有客户端（适合企业产品）

5.2 在 Clawdbot 中的位置

适合实现为一个 Skill 而不是“通道”：

用户在任何通道（飞书/钉钉/企业微信）里对 Clawdbot 说：

“帮我创建一个今天下午 3 点的评审会议，参会人是 A/B/C”

Gateway → Agent → TencentMeetingSkill.createMeeting() :

• 通过 REST API 创建会议

• 返回会议链接/会议号/密码

再由 Agent 决定：

• 在当前通道发送会议卡片

• 或发邮件/日程邀请（可接入其他邮件工具）

作为“工具层 Skill”，技术上非常简单、边界清晰； 唯一成本在于企业版权限申请和运维， 可行性高 。

这块 Clawdbot 已经有成熟能力（Browser control via CDP），在国内环境主要考虑的是：

• 目标网站多为国产站点，需要处理中文界面和复杂交互

• 某些场景可以考虑直接集成像 browser-use 这类开源 AI 浏览器自动化工具，以获得更高层的抽象

可行方案 ：

• 复用现有 Browser Tool（Chromium + CDP）

• 对于高阶自动化场景：

在 Clawdbot 的 Tool 层接入 browser-use 或 Playwright 封装

对 LLM 暴露“浏览器动作工具”，比如： open_url ， click(selector) ， fill(selector, text)

浏览器控制是 Clawdbot 原生强项，迁移到国内环境主要是“网站变化”和“人机验证”问题， 技术上高度可行 。

国外 Clawdbot 常用的是 Google/Bing 等搜索。国内适配可以选：

• U 深搜是由深度搜索厂商 UniFuncs 推出的深度搜索产品，采用深度推理技术，基于国产模型底座驱动。只需要 3 分钟，给您一个精准、全面、可靠的答案！

• 博查 AI Web Search API：专门为 AI / RAG 场景设计的国内搜索 API

• 百度 AI 搜索：需额外企业认证，且策略可能更严格

在 Clawdbot 中的实现 ：

定义 SearchSkill ：

• 入参：query / 时间范围 / 数量等

• 调用U 深搜，博查等搜索引擎API，返回列表（标题、链接、snippet、内容摘要）

• Agent 再基于这些结果做进一步总结或决策

搜索是纯后端 HTTP API 调用， 几乎没有架构性风险 ；关键在内容质量、费用控制与合规性。国内首选博查 AI 这类“AI 友好型搜索 API”。

建议的国产生态适配优先级与实施路线

综合“技术难度 × 使用价值 × 合规风险”，可以给出一个推荐顺序：

通道适配优先级 1）飞书 2）企业微信 3）钉钉 —— 三者都可以依照现有海外通道模式开发 Channel 插件

工具/Skill 适配优先级 1）浏览器控制（复用现有 Browser Tool，增加国产站点测试） 2）搜索引擎（U 深搜/博查 API） 3）腾讯会议 Skill 4）WPS（WebOffice + 本地客户端操作）

不建议在官方分支深度集成的方向

• 个人微信协议级自动化（封号 & 法务风险高）

• 各类非官方 Hook/注入方案（Xposed 等） —— 可以由个人/团队在自身私有 Skill 中使用，但不宜做成默认能力

建议的迭代路径（目标是 “Clawdbot-CN” 版）

Phase 1：通道打通 + 最小可用

• 实现 FeishuChannel （只支持文字、基本卡片）

• 复用 Browser Tool、本地文件操作，配合搜索 API

• 目标：用户在飞书里对 Clawdbot 发消息，就能：

• 搜索资料

• 打开网页抓取信息

• 在本机跑简单脚本

Phase 2：企业覆盖 + 常用办公工具

• 新增 WeComChannel 和 DingTalkChannel

• 接入腾讯会议 Skill

• 接入 WPS WebOffice（文档分析、自动生成/润色）

Phase 3：深度自动化与安全治理

• 针对浏览器自动化和系统命令，增加更细粒度的权限控制 & 审计

• 对大规模企业部署，优化：

• 日志、监控、告警

• 多 Agent 协作（不同部门、不同角色）

Clawdbot 的本质是 本地优先、通道插件化、工具插件化的 AI 网关 ，架构上对“在国内生态重做一套通道+工具适配层”非常友好，无需推翻重来。

国产生态里， 飞书 / 企业微信 / 钉钉 在通道能力上与 Telegram/Slack/Discord 非常类似，只要按照现有 Channel 抽象写适配器即可， 技术可行性高，主要工作是 API 对接与会话映射。

WPS、腾讯会议、更换搜索引擎（如U 深搜等 AI 优化的搜索引擎接口服务）更适合作为 Skill / Tool 层集成 ，对现有框架几乎无侵入，开发投入可控。

真正需要谨慎的是 个人微信 这类没有官方开放接口、严重依赖非官方协议或注入的场景，不适合作为 Clawdbot 官方面向大众的能力，但可以留出 Skill 插槽让用户自行扩展。