Clawdbot：企业级个人 AI 助手平台

[Pines-Cheng]

核心定位

Clawdbot 是一个私有化部署的个人 AI 助手平台，可在企业自有设备上运行。它通过统一的 Gateway 控制平面，整合多个通讯渠道（WhatsApp、Telegram、Slack、Discord、飞书、Microsoft Teams、WebChat 等）与用户交互，支持 macOS/iOS/Android 上的语音交互和实时 Canvas 可视化工作区。该平台强调数据隐私和本地运行，采用分布式架构设计，支持多智能体协同和跨设备执行。

---

六大核心能力

1. 多端多入口，无缝会话连续

特点： 跨渠道会话聚合，真正的全渠道统一体验

介绍： 你可以在一个渠道开始任务，在另一个渠道继续。如手机或飞书上布置任务，Web 端或者定制的网站小助手或者其他地方可以继续问。所有对话上下文自动同步，无需重复说明背景。

典型场景：

• 手机端发起：在飞书上发送"帮我准备明天的会议资料"
• Web 端接续：打开 WebChat 查看完整对话历史
• 补充细节：在 WebChat 中添加"会议在下午3点，需要准备产品演示"
• 任意渠道同步：回到手机飞书，自动同步完整上下文

技术实现：

• 所有直接消息自动聚合到统一会话（agent:<agentId>:main）
• 会话数据存储在 Gateway 主机（~/.clawdbot/agents/<agentId>/sessions/）
• 跨渠道对话历史完整保留在 .jsonl 文件中
• 支持自定义网站小助手、IDE 插件、Chrome 插件等任意入口
• WebChat 作为统一查看入口，可查看该 Agent 的所有跨渠道对话

---

2. 灵活的渠道扩展能力

特点： 插件化架构，快速集成任意消息渠道

介绍： 通过插件系统可以添加新的消息渠道，无需修改核心代码。支持企业内部平台、中后台站点、IDE 插件、浏览器插件等任意入口的快速接入。

典型场景：

• 企业内部集成：接入企业内部工单系统、OA 平台
• 开发工具集成：VSCode 插件、JetBrains IDE 插件
• 浏览器扩展：Chrome/Edge 侧边栏助手
• 移动端集成：企业 App 内嵌 AI 助手

技术实现：

• 核心渠道（内置）：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、BlueBubbles
• 企业渠道（插件）：飞书、Microsoft Teams、Nextcloud Talk
• 开放协议（插件）：Matrix、Nostr、Zalo、Tlon
• 插件通过 api.registerChannel() 注册新渠道
• 配置文件中 channels.<id> 管理渠道配置
• 支持自定义 outbound.sendText、inbound 等接口实现
• 插件扫描路径：配置路径 → 工作区扩展 → 全局扩展 → 捆绑扩展

---

3. 分布式执行架构

特点： Gateway 集中控制，节点分布执行

介绍： Agent 的核心逻辑始终运行在 Gateway 进程内（7×24 小时在线），但工具执行可以根据配置分布在主机、Docker 容器或节点设备（macOS/iOS/Android/Headless Linux）上。这种设计允许一个 Agent 控制多个设备，同时保持安全隔离。

典型场景：

• 远程办公：Gateway 部署在云端 VPS，本地 Mac/手机作为节点连接
• 多设备协同：一个 Agent 同时控制办公电脑、家庭服务器、手机
• 安全隔离：敏感操作（如代码编译）在 Docker 容器中执行
• 硬件集成：控制 3D 打印机、智能家居设备、摄像头

技术实现：

• Gateway 进程：运行在 ws://127.0.0.1:18789，作为单一控制平面
• 执行层分布：
  • sandbox.mode: "off"：所有工具在主机运行
  • sandbox.mode: "non-main"：非主会话在 Docker 容器执行
  • sandbox.mode: "all"：所有会话在 Docker 容器执行
• 节点设备能力：
  • macOS 节点：Canvas、Camera、Screen Recording、system.run
  • iOS/Android 节点：Canvas、Camera、Voice Wake、Location
  • Headless 节点：system.run、system.which（Linux/Windows）
• 节点通过 Gateway WebSocket 连接（role: "node"）
• 设备配对认证机制（clawdbot devices approve）

---

4. 企业级定时任务系统

特点： Cron + Heartbeat 双机制，覆盖精确调度和智能监控

介绍： 提供两种互补的定时机制：Cron Jobs 用于精确时间调度和一次性任务，Heartbeat 用于批量监控检查和上下文感知任务。两种机制可结合使用，满足不同业务场景需求。

典型场景：

• 精确调度：每天 9:00 生成日报并发送到 Telegram
• 一次性提醒：20 分钟后提醒查看 PR 审查结果
• 批量监控：每 30 分钟检查邮箱、日历、项目通知
• 智能决策：根据上下文判断是否需要提醒（无事则静默）

技术实现：

• Cron Jobs：
  • 支持三种调度：at（一次性时间戳）、every（固定间隔）、cron（标准表达式）
  • 作业持久化存储在 ~/.clawdbot/cron/jobs.json
  • 支持隔离会话执行（session: "isolated"）
  • 可直接输出到指定渠道（deliver: "telegram:123"）
  • 支持自动删除（deleteAfterRun: true）
• Heartbeat：
  • 默认每 30 分钟运行（heartbeat.every: "30m"）
  • 读取 HEARTBEAT.md 作为任务清单
  • 共享主会话上下文，支持连续对话
  • 智能抑制：无事时回复 HEARTBEAT_OK，不发送消息
  • 支持活跃时段限制（activeHours: {start: "08:00", end: "22:00"}）

---

5. 后台任务管理

特点： 多种后台运行模式，支持长时任务和异步执行

介绍： 支持命令后台执行、进程会话管理、子智能体后台任务等多种机制。长时任务可以在后台运行，完成后自动通知主 Agent，避免阻塞主对话流程。

典型场景：

• 长时编译：后台运行 npm run build，完成后通知结果
• 代码生成：使用 Codex 后台生成完整项目，实时查看进度
• 数据处理：后台运行数据分析脚本，定期轮询状态
• 自动化测试：后台运行测试套件，失败时立即通知

技术实现：

• Background Exec：
  • background: true：立即后台运行
  • yieldMs: 10000：超过 10 秒自动后台化
  • timeout: 1800：超时自动终止（默认 30 分钟）
  • 返回 sessionId 用于后续跟踪
• Process Tool：
  • list：列出运行中和已完成的会话
  • poll：检查会话状态并获取新输出
  • log：读取聚合输出（支持 offset 和 limit）
  • write/submit：发送 stdin 数据
  • kill：终止后台会话
• 子智能体后台任务：
  • 使用 sessions_spawn 创建后台子 Agent
  • 子 Agent 完成后自动通知主 Agent（subagent-announce）
  • 支持任务标签（label: "my-task"）和超时控制
• 完成通知机制：
  • 配置 tools.exec.notifyOnExit: true
  • 任务完成时自动触发 clawdbot gateway wake

---

6. 跨设备操作能力

特点： 一个 Agent 控制多个设备，支持远程命令执行

介绍： Agent 可通过节点系统远程操作手机和电脑，执行系统命令、控制摄像头、屏幕录制、发送通知等操作。所有操作都需要经过设备配对和权限验证，确保安全性。

典型场景：

• 远程监控：通过手机摄像头查看家中情况
• 自动化部署：在远程服务器上执行部署脚本
• 屏幕录制：录制电脑屏幕用于教程制作
• 智能通知：根据任务状态在手机上推送通知
• 硬件控制：控制 3D 打印机、空气净化器等智能设备

技术实现：

• 支持的操作：
  • 系统命令：system.run（执行 Shell 命令）、system.which（查找命令路径）
  • 摄像头控制：camera.snap（拍照）、camera.clip（录像）
  • 屏幕操作：screen.record（屏幕录制）
  • 通知推送：system.notify（系统通知）
  • Canvas 操作：canvas.present、canvas.navigate、canvas.eval、canvas.snapshot
• 安全机制：
  • 设备配对认证（clawdbot devices approve）
  • 执行批准机制：安全模式（deny）、询问模式（ask）、允许列表（allowlist）
  • TCC 权限控制（macOS）：屏幕录制、通知、辅助功能等
  • 节点权限映射（permissions map）
• CLI 操作示例：

  # 在 Mac 节点上执行命令
  clawdbot nodes run --node <mac-node> -- echo "Hello"
  
  # 在 Android 节点上拍照
  clawdbot nodes invoke --node <android-node> --command camera.snap

---

部署架构建议

方案一：本地部署（适合个人/小团队）

Gateway（Mac/Linux） + 本地节点设备

方案二：云端部署（适合远程办公）

Gateway（VPS/云服务器，7×24在线） + 本地设备作为节点

方案三：混合部署（适合企业）

Gateway（企业私有云） + Docker 沙箱 + 多节点设备

---

技术优势总结

1. 隐私优先：数据本地存储，支持私有化部署
2. 架构灵活：从单机到分布式都能支持
3. 扩展性强：插件系统支持任意渠道和工具集成
4. 生产就绪：支持定时任务、后台执行、多智能体协同
5. 跨平台：macOS/iOS/Android/Linux/Windows 全覆盖
6. 安全可控：设备配对、权限控制、沙箱隔离多重保障

---

适用场景： 需要统一 AI 助手入口、重视数据隐私、有多设备协同需求的企业或团队。

[Pines-Cheng]

Clawdbot 采用中心化网关架构，以 Gateway 作为单一控制平面协调所有组件。

核心架构概览

1. Gateway - 中央控制平面

Gateway 是单一长期运行的进程，拥有所有通道连接和控制平面 1 ：

graph TB
    subgraph "用户界面"
        CLI["CLI 命令"]
        WebUI["控制 UI<br/>http://127.0.0.1:18789"]
        macOSApp["macOS 应用"]
    end
    
    subgraph "Gateway (ws://127.0.0.1:18789)"
        GatewayCore["Gateway 进程<br/>src/gateway/index.ts"]
        WSServer["WebSocket 服务器"]
        HTTPServer["HTTP 服务器"]
        BridgeServer["Bridge 服务器<br/>tcp://0.0.0.0:18790"]
        ConfigMgr["配置管理器"]
        SessionStore["会话存储"]
    end
    
    CLI --> GatewayCore
    WebUI --> WSServer
    macOSApp --> WSServer

Loading

2. Agent 运行时

Agent 作为嵌入式运行时运行在 Gateway 进程内 2 ，基于 p-mono 架构：

• 工作区管理：每个 Agent 有独立的工作区（~/clawd 或 ~/clawd-<agentId>） 3
• 引导文件：AGENTS.md、SOUL.md、USER.md 等定义 Agent 行为 4
• 工具系统：核心工具（read/exec/edit/write）+ Clawdbot 特有工具 5

3. 会话管理

会话采用双层持久化架构 6 ：

1. 会话存储 (sessions.json)：元数据映射 sessionKey -> SessionEntry
2. 转录文件 (<sessionId>.jsonl)：完整的对话历史

会话键规则 7 ：

• 直接消息：agent:<agentId>:<mainKey>（跨渠道共享）
• 群组：agent:<agentId>:<channel>:group:<id>

4. 消息路由流程

sequenceDiagram
    participant Channel as 消息渠道
    participant Gateway as Gateway
    participant Agent as Agent
    participant Tools as 工具系统
    
    Channel->>Gateway: 入站消息
    Gateway->>Gateway: 路由到会话
    Gateway->>Agent: 执行 Agent 运行
    Agent->>Tools: 调用工具
    Tools-->>Agent: 工具结果
    Agent-->>Gateway: 流式响应
    Gateway-->>Channel: 发送回复

Loading

5. 多代理路由

支持多个隔离的 Agent 在一个 Gateway 中运行 8 ：

• 独立工作区：每个 Agent 有自己的文件、配置和会话
• 认证隔离：每个 Agent 有独立的 auth-profiles.json
• 绑定规则：通过 bindings 配置将消息路由到特定 Agent

6. 节点系统

通过 node.invoke 机制在配对设备上执行操作 9 ：

• macOS 节点：Canvas、Camera、Screen Recording、system.run
• 移动节点：iOS/Android 提供设备特定能力
• 安全机制：设备配对 + 执行批准 + 权限控制

技术实现细节

Gateway 协议

Gateway 通过 WebSocket 暴露 RPC 方法 10 ：

• agent - 运行 Agent 轮次
• send - 发送消息
• node.* - 节点管理
• sessions.* - 会话操作

Agent 生命周期

Agent 运行遵循循环 11 ：

1. 消息接收 → 上下文组装 → 模型推理
2. 工具执行 → 流式回复 → 持久化

配置系统

使用 JSON5 配置 + Zod 验证 12 ：

• 支持环境变量替换
• $include 指令分割配置
• 热重载安全变更

Notes

Clawdbot 的核心设计理念是单一 Gateway + 多端接入。所有状态管理、会话存储和消息路由都在 Gateway 中集中处理，确保了数据一致性和系统可靠性。这种架构既支持本地部署，也支持远程 Gateway + 本地节点的分布式模式。