Clawdbot 助手

Clawdbot 不仅仅是一个命令行工具；它被设计为一个运行在您的硬件上、连接到您的私人聊天频道的 全天候个人助手。

⚠️ 安全警告

Clawdbot 拥有执行代码、读写文件以及与您的真实账户交互的能力。

切勿在不受信任的输入或公开频道中启用 Clawdbot。
始终使用私信 (DM) 并保持配对 (Pairing) 开启。
定期查看您的安全设置。

先决条件

为了获得最佳体验，我们推荐以下设置：

一台常开的服务器: Raspberry Pi、Mac Mini 或旧笔记本电脑都可以。
两个手机号码:
- 一个用于您的日常使用。
- 一个专用于您的 Clawdbot 智能体。
Tailscale: 用于在任何地方安全地访问您的网关。

npm install -g clawdbot@latest
# 或: pnpm add -g clawdbot@latest

从源码安装 (开发版):

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build
pnpm link --global

双手机设置 (推荐)

您需要这样：

您的手机 (个人)                 第二部手机 (助手)
┌─────────────────┐           ┌─────────────────┐
│  您的 WhatsApp   │  ──────▶  │  助手 WhatsApp   │
│  +1-555-YOU     │   发消息   │  +1-555-CLAWD   │
└─────────────────┘           └────────┬────────┘
                                       │ 通过二维码连接
                                       ▼
                              ┌─────────────────┐
                              │  您的 Mac        │
                              │  (clawdbot)      │
                              │    Pi 智能体     │
                              └─────────────────┘

如果您将个人 WhatsApp 连接到 Clawdbot，发给您的每条消息都会变成“智能体输入”。这通常不是您想要的。

5 分钟快速入门

配对 WhatsApp Web (显示二维码；用助手手机扫描):

clawdbot channels login

启动网关 (保持运行):

clawdbot gateway --port 18789

在 ~/.clawdbot/clawdbot.json 中放入最简配置：

{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

现在从您白名单中的手机向助手的号码发送消息。

当入职完成时，我们会自动打开带有网关令牌的仪表板并打印带有令牌的链接。稍后重新打开：clawdbot dashboard。

给智能体一个工作区 (AGENTS)

Clawd 从其工作区目录读取操作说明和“记忆”。

默认情况下，Clawdbot 使用 ~/clawd 作为智能体工作区，并将在设置/首次运行智能体时自动创建它 (加上初始的 AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md)。BOOTSTRAP.md 仅在工作区全新时创建 (删除后不应再次出现)。

提示：将此文件夹视为 Clawd 的“记忆”，并将其设为 git 仓库 (最好是私有的)，以便备份您的 AGENTS.md + 记忆文件。如果安装了 git，全新的工作区将自动初始化。

clawdbot setup

完整的工作区布局 + 备份指南：智能体工作区记忆工作流：记忆

可选：通过 agents.defaults.workspace 选择不同的工作区 (支持 ~)。

{
  agent: {
    workspace: "~/clawd"
  }
}

如果您已经从仓库同步了自己的工作区文件，可以完全禁用引导文件的创建：

{
  agent: {
    skipBootstrap: true
  }
}

将其转变为“助手”的配置

Clawdbot 默认配置了一个很好的助手设置，但您通常会想要进行微调：

SOUL.md 中的人设/指令
思考默认设置 (如果需要)
心跳 (一旦您信任它)

示例：

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    workspace: "~/clawd",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // 初始设置为 0；稍后启用。
    heartbeat: { every: "0m" }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }
      }
    }
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@clawd", "clawd"]
    }
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080
    }
  }
}

会话和记忆

会话文件：~/.clawdbot/agents/<agentId>/sessions/{{SessionId}}.jsonl
会话元数据 (令牌使用情况、最后路由等): ~/.clawdbot/agents/<agentId>/sessions/sessions.json (旧版: ~/.clawdbot/sessions/sessions.json)
/new 或 /reset 会为该聊天开启一个新会话 (可通过 resetTriggers 配置)。如果单独发送，智能体会回复一个简短的问候以确认重置。
/compact [instructions] 压缩会话上下文并报告剩余的上下文配额。

心跳 (主动模式)

默认情况下，Clawdbot 每 30 分钟运行一次心跳，提示词如下： 如果 HEARTBEAT.md 存在 (工作区上下文)，请阅读它。严格遵守。不要推断或重复先前聊天中的旧任务。如果不需要关注，请回复 HEARTBEAT_OK。 设置 agents.defaults.heartbeat.every: "0m" 以禁用。

如果 HEARTBEAT.md 存在但实际上是空的 (只有空行和像 # Heading 这样的 markdown 标题)，Clawdbot 会跳过心跳运行以节省 API 调用。
如果文件丢失，心跳仍然运行，由模型决定做什么。
如果智能体回复 HEARTBEAT_OK (可选带简短填充；参见 agents.defaults.heartbeat.ackMaxChars)，Clawdbot 会抑制该心跳的出站交付。
心跳运行完整的智能体轮次 —— 较短的间隔会消耗更多令牌。

{
  agent: {
    heartbeat: { every: "30m" }
  }
}

媒体输入和输出

入站附件 (图片/音频/文档) 可以通过模板展示给您的命令：

{{MediaPath}} (本地临时文件路径)
{{MediaUrl}} (伪 URL)
{{Transcript}} (如果启用了音频转录)

来自智能体的出站附件：在单独的一行包含 MEDIA:<path-or-url> (不要有空格)。示例：

这是屏幕截图。
MEDIA:/tmp/screenshot.png

Clawdbot 会提取这些内容并将其作为媒体与文本一起发送。

操作清单

clawdbot status          # 本地状态 (凭证、会话、排队的事件)
clawdbot status --all    # 完整诊断 (只读，可粘贴)
clawdbot status --deep   # 增加网关健康探测 (Telegram + Discord)
clawdbot health --json   # 网关健康快照 (WS)

日志保存在 /tmp/clawdbot/ (默认：clawdbot-YYYY-MM-DD.log)。

下一步

Web 聊天：Web 聊天
网关操作：网关运行手册
Cron + 唤醒：Cron 任务
macOS 菜单栏助手：Clawdbot macOS 应用
iOS 节点应用：iOS 应用
Android 节点应用：Android 应用
Windows 状态：Windows (WSL2)
Linux 状态：Linux 应用
安全：安全

⚠️ 安全警告​

先决条件​

双手机设置 (推荐)​

5 分钟快速入门​

给智能体一个工作区 (AGENTS)​

将其转变为“助手”的配置​

会话和记忆​

心跳 (主动模式)​

媒体输入和输出​

操作清单​

下一步​