Clawdbot 使用文档

介绍 #

Clawdbot是一个开源的个人AI助手，运行在您自己的设备上，通过WhatsApp、Telegram、Discord等聊天平台与您交互。与传统的云端AI服务不同，Clawdbot让您完全掌控自己的数据和隐私。

什么是Clawdbot？

Clawdbot不仅仅是一个简单的聊天机器人，它是一个完整的AI助手平台，具备以下核心能力：

• 多平台聊天集成 - 支持WhatsApp、Telegram、Discord、Slack、Signal、iMessage等10+主流聊天平台
• 浏览器控制 - 可以控制专用Chrome浏览器，自动浏览网页、填写表单、提取数据
• 系统级访问 - 读写文件、运行Shell命令、执行脚本，完全访问或沙盒模式可选
• 技能扩展 - 通过ClawdHub安装社区技能，或让Clawdbot自己编写新技能
• 持久化记忆 - 记住您的所有对话和偏好，24小时上下文持续
• 语音交互 - macOS/iOS/Android支持语音唤醒和对话模式

Clawdbot能做什么？

系统要求 #

最低配置

推荐配置

• AI模型订阅 - Anthropic Claude Pro/Max 或 OpenAI ChatGPT Plus
• 内存 - 16GB+ RAM（用于浏览器控制等高级功能）
• Docker - 用于沙盒模式和安全隔离（可选）

安装指南 #

一键安装（推荐）

Clawdbot提供一键安装脚本，自动安装所有依赖：

# 一键安装脚本（自动安装Node.js和所有依赖）
curl -fsSL https://molt.bot/install.sh | bash

# PowerShell 一键安装
iwr -useb https://molt.bot/install.ps1 | iex

使用npm安装

如果您已经安装了Node.js 22+，可以直接使用npm安装：

# 使用 npm 全局安装
npm install -g clawdbot@latest

# 或使用 pnpm
pnpm add -g clawdbot@latest

# 或使用 bun
bun add -g clawdbot@latest

从源码安装

开发者可以从GitHub克隆源码进行安装：

# 克隆仓库
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 安装依赖
pnpm install

# 构建UI
pnpm ui:build

# 构建项目
pnpm build

# 运行安装向导
pnpm clawdbot onboard --install-daemon

验证安装

安装完成后，运行以下命令验证：

# 检查版本
clawdbot --version

# 运行诊断
clawdbot doctor

快速入门 #

按照以下步骤，5分钟内让Clawdbot运行起来：

clawdbot onboard --install-daemon

# 登录聊天平台（如WhatsApp）
clawdbot channels login

clawdbot gateway --port 18789 --verbose

# 或者通过CLI发送消息
clawdbot agent --message "你好，Clawdbot！"

基础配置 #

Clawdbot的配置文件位于 ~/.clawdbot/clawdbot.json。以下是基础配置示例：

{
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "thinkingLevel": "medium"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "agents": {
    "defaults": {
      "workspace": "~/clawd"
    }
  }
}

配置文件结构

工作空间配置

Clawdbot的工作空间默认位于 ~/clawd，包含以下重要文件：

• AGENTS.md - 代理配置和行为定义
• SOUL.md - AI助手的个性和身份设定
• TOOLS.md - 可用工具的配置
• skills/ - 技能扩展目录

AI模型设置 #

支持的模型

Clawdbot支持多种AI模型提供商：

配置Anthropic Claude

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  },
  "auth": {
    "anthropic": {
      "type": "oauth"  // 或 "apiKey"
    }
  }
}

配置OpenAI

{
  "agent": {
    "model": "openai/gpt-5.2"
  },
  "auth": {
    "openai": {
      "apiKey": "sk-..."
    }
  }
}

模型故障转移

Clawdbot支持配置多个模型，当主模型不可用时自动切换：

{
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "fallbackModels": [
      "anthropic/claude-sonnet-4-5",
      "openai/gpt-5.2"
    ]
  }
}

聊天平台配置 #

WhatsApp

通过扫描二维码连接WhatsApp：

# 登录WhatsApp
clawdbot channels login whatsapp

配置文件设置：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+86138********"],  // 允许的手机号
      "groups": ["*"]  // 允许的群组，"*"表示全部
    }
  }
}

Telegram

创建Telegram Bot并获取Token：

1. 在Telegram中找到 @BotFather
2. 发送 /newbot 创建新机器人
3. 复制获得的Bot Token

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF..."
    }
  }
}

Discord

创建Discord Bot应用：

1. 访问 Discord Developer Portal
2. 创建新应用并添加Bot
3. 复制Bot Token
4. 邀请Bot到您的服务器

{
  "channels": {
    "discord": {
      "token": "your-bot-token"
    }
  }
}

Slack

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-..."
    }
  }
}

iMessage (仅macOS)

iMessage集成需要在macOS上运行，并且Messages应用已登录：

{
  "channels": {
    "imessage": {
      "enabled": true,
      "groups": ["*"]
    }
  }
}

网关配置 #

Gateway是Clawdbot的控制中心，管理所有会话、工具和事件。

基本配置

{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "verbose": true
  }
}

启动选项

作为系统服务运行

# 安装为系统服务
clawdbot onboard --install-daemon

# 手动启动/停止服务
clawdbot gateway start
clawdbot gateway stop
clawdbot gateway restart

Web控制台

Gateway运行后，可以通过Web浏览器访问控制台：

http://localhost:18789

控制台提供会话管理、配置编辑、日志查看等功能。

核心功能 #

会话管理

Clawdbot为每个对话创建独立的会话，支持：

• 主会话 - 您的私人对话，拥有完整权限
• 群组会话 - 群聊中的对话，可配置触发方式
• 会话隔离 - 不同会话之间的上下文完全隔离

聊天命令

在聊天中可以使用以下命令控制Clawdbot：

记忆系统

Clawdbot具备强大的记忆能力：

• 对话记忆 - 记住您的所有对话内容
• 偏好学习 - 学习您的习惯和偏好
• 跨会话同步 - 不同平台间的记忆同步

浏览器控制 #

Clawdbot可以控制专用的Chrome/Chromium浏览器，执行各种网页操作。

启用浏览器控制

{
  "browser": {
    "enabled": true,
    "color": "#FF4500",
    "headless": false
  }
}

浏览器功能

• 网页浏览 - 访问任意网站，提取内容
• 表单填写 - 自动填写和提交表单
• 截图 - 对网页进行截图
• 文件上传 - 上传文件到网站
• 多配置文件 - 支持多个浏览器配置文件

技能系统 #

技能是Clawdbot的扩展能力，可以添加新的功能和行为。

技能类型

• 内置技能 - Clawdbot自带的核心技能
• 托管技能 - 从ClawdHub安装的社区技能
• 工作空间技能 - 本地自定义的技能

安装技能

# 从ClawdHub搜索技能
clawdbot skills search calendar

# 安装技能
clawdbot skills install calendar-sync

# 列出已安装技能
clawdbot skills list

创建自定义技能

技能是一个包含 SKILL.md 文件的目录：

# ~/clawd/skills/my-skill/SKILL.md

# My Custom Skill

## Description
这是我的自定义技能，用于...

## Tools
- tool_name: 工具描述

## Examples
用户: 执行某个任务
助手: 好的，我来帮您...

ClawdHub技能库

访问 ClawdHub 浏览和发布技能。热门技能包括：

• 日历同步 - 与Google Calendar、Outlook同步
• 邮件管理 - Gmail、Outlook邮件处理
• 任务管理 - Todoist、Notion集成
• 代码助手 - GitHub、GitLab操作
• 智能家居 - HomeKit、Google Home控制

自动化 #

定时任务 (Cron)

设置定时任务让Clawdbot主动工作：

{
  "cron": {
    "jobs": [
      {
        "name": "daily-briefing",
        "schedule": "0 8 * * *",
        "message": "给我生成今天的日程摘要"
      },
      {
        "name": "weekly-report",
        "schedule": "0 18 * * 5",
        "message": "总结本周的工作进展"
      }
    ]
  }
}

Webhook触发

通过Webhook接收外部事件触发：

# Webhook端点
POST http://localhost:18789/webhook

# 请求体
{
  "event": "github_pr",
  "data": {...}
}

Gmail Pub/Sub

实时接收Gmail通知：

{
  "automation": {
    "gmail": {
      "enabled": true,
      "watchLabels": ["INBOX"],
      "actions": {
        "newEmail": "处理新邮件并通知我重要的内容"
      }
    }
  }
}

语音功能 #

语音唤醒 (Voice Wake)

在macOS、iOS和Android上支持语音唤醒：

{
  "voice": {
    "wakeWord": "Hey Clawd",
    "enabled": true
  }
}

对话模式 (Talk Mode)

持续的语音对话体验，无需每次唤醒：

• macOS菜单栏应用中启用
• iOS/Android节点应用中使用
• 配合ElevenLabs获得自然语音合成

语音合成

配置ElevenLabs语音合成：

{
  "voice": {
    "tts": {
      "provider": "elevenlabs",
      "voiceId": "your-voice-id"
    }
  }
}

macOS #

macOS应用

Clawdbot提供原生macOS菜单栏应用：

• 菜单栏快速访问和控制
• 语音唤醒和对话模式
• WebChat内置界面
• 系统通知集成

权限设置

macOS需要授予以下权限：

• 辅助功能 - 用于系统控制
• 麦克风 - 用于语音输入
• 屏幕录制 - 用于截图功能
• 通知 - 用于系统通知

Windows #

WSL2（推荐）

在Windows上，强烈建议使用WSL2运行Clawdbot：

# 安装WSL2
wsl --install

# 在WSL2中安装Clawdbot
curl -fsSL https://molt.bot/install.sh | bash

原生Windows（Beta）

也可以在原生Windows PowerShell中运行：

iwr -useb https://molt.bot/install.ps1 | iex

Linux #

支持的发行版

• Ubuntu 20.04+
• Debian 11+
• Fedora 35+
• Arch Linux

安装

# 一键安装
curl -fsSL https://molt.bot/install.sh | bash

# 或使用Nix
nix-shell -p clawdbot

作为systemd服务

# 安装服务
clawdbot onboard --install-daemon

# 管理服务
systemctl --user start clawdbot
systemctl --user enable clawdbot

移动端 #

iOS节点

iOS应用作为节点连接到Gateway：

• Canvas可视化工作空间
• 语音唤醒和对话模式
• 相机和屏幕录制
• Bonjour自动配对

Android节点

Android应用功能类似：

• Canvas和对话模式
• 相机和屏幕捕获
• 可选SMS集成

配对方式

# 列出可用节点
clawdbot nodes list

# 配对新节点
clawdbot nodes pair

安全设置 #

访问控制

配置白名单限制访问：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+86138********"],
      "dmPolicy": "pairing"
    }
  }
}

DM配对模式

未知发送者需要配对码才能使用：

# 审批配对请求
clawdbot pairing approve telegram abc123

沙盒模式

为群聊启用Docker沙盒：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

工具权限

配置允许和禁止的工具：

{
  "tools": {
    "allow": ["bash", "read", "write"],
    "deny": ["browser", "nodes"]
  }
}

远程访问 #

Tailscale（推荐）

使用Tailscale安全地远程访问Gateway：

{
  "gateway": {
    "tailscale": {
      "mode": "serve"  // 或 "funnel"
    }
  }
}

SSH隧道

# 创建SSH隧道
ssh -L 18789:localhost:18789 user@remote-host

远程Gateway模式

在Linux服务器上运行Gateway，从其他设备连接：

• Gateway运行在服务器上，执行工具调用
• macOS/iOS/Android作为节点连接
• 设备特定操作通过节点执行

命令参考 #

常见问题 #

安装问题

Q: 安装时提示Node.js版本过低？

Clawdbot需要Node.js 22或更高版本。使用nvm或直接从nodejs.org下载最新版本：

# 使用nvm安装Node.js 22
nvm install 22
nvm use 22

Q: Windows上安装失败？

建议使用WSL2环境运行Clawdbot：

wsl --install
# 然后在WSL2中运行安装脚本

连接问题

Q: WhatsApp扫码后无法连接？

确保您的手机和电脑在同一网络，并且手机上的WhatsApp是最新版本。尝试重新运行 clawdbot channels login whatsapp。

Q: Telegram Bot无响应？

检查Bot Token是否正确，并确保已向Bot发送过 /start 命令。查看Gateway日志获取详细错误信息。

使用问题

Q: 如何重置会话？

在聊天中发送 /reset 或 /new 命令即可重置当前会话。

Q: 如何查看Token使用量？

发送 /status 命令查看当前会话的Token使用情况和成本估算。

Q: Clawdbot可以访问我的文件吗？

默认情况下，主会话的Clawdbot有完整的文件系统访问权限。您可以在配置中限制访问范围或启用沙盒模式。

更多帮助

如果您遇到其他问题：

• 运行 clawdbot doctor 进行自动诊断
• 查看 官方文档
• 加入 Discord社区 获取帮助
• 在 GitHub 提交Issue