Clawdbot - 开源本地 AI 助手完全指南

前言

根据公开仓库信息，Clawdbot 由 Peter Steinberger（PSPDFKit 创始人）发起，是一款开源个人 AI 助手。与传统的 ChatGPT 或 Claude 网页版不同，Clawdbot 运行在本地设备，通过常用消息应用（如 Telegram、Discord、WhatsApp）进行交互。

系统要求：macOS 14+、Windows、Linux（以官方文档为准）

GitHub stars 等热度数据以仓库实时统计为准，社区讨论观点仅供参考。

核心特性

本地优先设计

  • 所有数据存储在本地，不上传云端
  • 对话记录以 Markdown 格式保存在 ~/clawd/memories/
  • Gateway 默认仅绑定 localhost，保护隐私

持久记忆

  • 24/7 保持上下文，跨会话记忆
  • 支持语义检索历史对话
  • 按日期和主题分类存储

多平台集成

支持 50+ 集成，核心消息平台包括（以官方文档为准）：

  • WhatsApp、Telegram、Discord、Slack
  • Signal、iMessage
  • 其他平台通过开放协议（Matrix、WebChat）支持
  • 支持私聊和群聊

自扩展能力

  • 可以编写和修改自己的 Skills
  • 社区插件生态
  • 支持 Cron 定时任务

技术架构

Clawdbot 采用三层架构设计：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
┌─────────────────────────────────────────┐
│           Channel Layer                  │
│  (Telegram/Discord/WhatsApp/iMessage)   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           Gateway Layer                  │
│         (localhost:18789)               │
│  - 消息路由                              │
│  - 会话管理                              │
│  - Skills 执行                           │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│            LLM Layer                     │
│  (Claude / GPT / MiniMax / 本地模型)    │
└─────────────────────────────────────────┘

Gateway Layer

核心控制层，默认运行在 localhost:18789：

  • 管理消息会话
  • 路由跨渠道消息
  • 处理工具调用和 Skills 执行
  • 维护对话历史

Channel Layer

连接各消息平台：

  • Bot APIs（Discord、Telegram、Slack）
  • Web 协议（WhatsApp、Signal）
  • 原生集成（iMessage 通过 imsg CLI）
  • 开放协议（Matrix、WebChat）

LLM Layer

支持多种大语言模型后端（以官方文档为准）：

  • Anthropic Claude（原生优化）
  • OpenAI GPT
  • MiniMax M2.1
  • 第三方 API 代理（OpenAI 兼容格式）
  • 本地自托管模型

安装部署

安装前准备

建议准备好 Node.js（推荐 18+，以官方文档为准）与 Git。以下命令用于确认环境：

1
2
3
node -v
npm -v
git --version

如需使用 pnpm，可通过 Corepack 启用：

1
2
corepack enable
corepack prepare pnpm@latest --activate

方式一：一键安装

1
curl -fsSL https://clawd.bot/install.sh | bash -s --

安全提示：建议先下载脚本并审阅内容，确认来源可信后再执行：
curl -fsSL https://clawd.bot/install.sh -o install.sh && sed -n '1,160p' install.sh

方式二：npm 安装

1
2
npm install -g clawdbot@latest
clawdbot onboard

方式三：开发者安装

1
2
3
4
5
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm run build
pnpm run clawdbot onboard

安装后检查

1
2
3
4
5
6
7
8
9
10
11
# 版本信息
clawdbot version

# 检查状态
clawdbot status

# 健康检查
clawdbot health

# 诊断问题
clawdbot doctor

配置指南

配置文件位于 ~/clawd/config.yaml

安全提示：API Key 建议通过环境变量注入，避免明文写入配置文件或提交到版本控制。

可先在 shell 中导出密钥（也可以写入 ~/.zshrc 或使用 dotenv 工具管理）：

1
2
export ANTHROPIC_API_KEY="your_anthropic_key"
export OPENAI_API_KEY="your_openai_key"

使用 Anthropic 官方 API

模型名称请参考 Anthropic 官方文档：

1
2
3
4
llm:
  provider: anthropic
  model: claude-sonnet-4-20250514  # 以官方文档为准
  apiKey: ${ANTHROPIC_API_KEY}     # 使用环境变量

使用 OpenAI 兼容代理

模型名称以代理服务实际支持为准：

1
2
3
4
5
llm:
  provider: openai-compatible
  model: gpt-4o-mini               # 根据代理支持的模型填写
  apiKey: ${OPENAI_API_KEY}
  baseUrl: https://api.example.com/v1  # 替换为你的代理地址

OAuth 订阅配置

1
clawdbot configure --section llm.oauth

Skills 系统

Skills 是 Clawdbot 的扩展能力核心，存放在 ~/clawd/skills/ 目录。

Markdown 格式定义

1
2
3
4
5
6
7
8
9
10
11
12
13
# skill: web-search
使用 Brave Search API 搜索网络内容

## 触发条件
当用户询问需要实时信息的问题时

## 环境变量
- BRAVE_API_KEY

## 执行步骤
1. 使用 BRAVE_API_KEY 调用 Brave Search API
2. 解析搜索结果
3. 生成摘要回复

内置能力

  • 浏览器控制：网页浏览、表单填写、数据提取
  • 系统访问：文件读写、Shell 命令执行（沙箱或完全访问）
  • 日历集成：事件管理、提醒设置
  • 代码执行：运行脚本、自动化任务
  • 智能家居：通过 Home Assistant/MQTT 控制设备

实战：Discord 集成

1. 创建 Discord Bot

访问 Discord Developer Portal 创建应用。

2. 配置权限

需要的权限：

  • Send Messages
  • Read Message History
  • Embed Links

3. 配置 Clawdbot

1
clawdbot configure --section channels.discord

按提示输入 Bot Token 即可完成配置。注意妥善保管 Token，避免写入公开仓库或命令行历史。

记忆系统

Clawdbot 的记忆以 Markdown 文件形式本地存储：

1
2
3
4
5
6
7
~/clawd/memories/
├── 2026-01-26.md          # 按日期存储
├── 2026-01-25.md
└── topics/                # 按主题分类
    ├── coding.md
    ├── schedule.md
    └── research.md

特点：

  • 纯文本格式，可直接编辑
  • 支持语义检索
  • 完全本地，无云端上传

安全与隐私

  • Gateway 仅运行在 localhost，不对外暴露
  • 远程访问可通过 SSH 隧道或 Tailscale
  • 仅 LLM API 调用需要网络连接
  • 所有对话数据本地存储

如需通过 SSH 进行安全访问，可参考：

1
ssh -L 18789:localhost:18789 user@your-server

常见集成

Clawdbot 提供 50+ 集成，常用服务包括（以官方文档为准）：

服务 用途
Gmail 邮件读取、回复、分类
GitHub 代码审查、Issue 管理
Spotify 音乐控制
Obsidian 笔记管理
Notion/Todoist 任务管理
Philips Hue 智能灯光控制
Twitter/X 社交媒体
WHOOP 健身数据追踪

总结

Clawdbot 代表了个人 AI 助手的新方向：

  • 本地优先：数据隐私有保障
  • 消息驱动：通过熟悉的聊天应用交互
  • 可扩展：Skills 系统支持持续扩展
  • 开源免费：社区驱动持续改进

如果你想要一个 24/7 运行的私人 AI 助手，Clawdbot 是目前值得关注的开源选择之一。

参考链接