文章目录

🍃作者介绍：25届双非本科网络工程专业，阿里云专家博主，深耕 AI 原理 / 应用开发 / 产品设计。前几年深耕Java技术体系，现专注把 AI 能力落地到实际产品与业务场景。
🦅个人主页：@逐梦苍穹
🐼GitHub主页：https://github.com/XZL-CODE
✈ 您的一键三连，是我创作的最大动力🌹

1、前言

当你的 AI 助手不仅能回答问题，还能主动提醒你喝水、总结未读消息、甚至记住你三个月前提过的那个想法——这就是 Clawdbot 想要实现的愿景。

本文带你从零开始了解 Clawdbot：它是什么、能做什么、怎么安装、适合谁用。

直接放最终效果：

在这里插入图片描述

2、为什么需要"随时在线"的 AI 助手

2.1 现有 AI 工具的痛点

让我们诚实地面对现状：

ChatGPT / Claude 网页版：

  • 需要打开浏览器才能用
  • 用完关闭，下次重新开始
  • 不记得上周你聊了什么
  • 不会主动联系你

语音助手（Siri / Google Assistant）：

  • 只能做简单问答和控制
  • “金鱼记忆”——完全不记得之前的对话
  • 无法处理复杂任务
  • 跨平台能力弱

AI 编程工具（Cursor / Copilot）：

  • 专注于代码，其他场景无能为力
  • 嵌入在 IDE 中，离开就用不了
  • 不会主动帮你做事

痛点总结：

工具类型随时可用长期记忆主动提醒多入口
ChatGPT 网页❌ 需开浏览器❌ 会话级❌❌
Siri✅❌❌❌
Claude Code❌ 需开终端❌ 会话级❌❌
理想助手✅✅✅✅

2.2 理想的 AI 助手应该是什么样的？

想象一下这个场景：

周一早上 8:00
你还在通勤，手机 Telegram 弹出消息：
“早上好！今天的安排：9 点有产品评审会议，下午 3 点需要提交周报。对了，上周你说要研究的那个框架，我找到了几篇不错的文章，要我总结一下吗？”

周三下午 2:50
你正在写代码，WhatsApp 弹出提醒：
“3 点的会议还有 10 分钟开始，会议链接在这里。”

周五晚上 10:00
iMessage 收到消息：
“该写周记了。这周你完成了：用户认证模块、API 重构、修复了 3 个 bug。要我帮你整理成周报吗？”

这就是 Clawdbot 想要实现的——一个真正的个人 AI 助手：

  • 随时在线：不需要你打开任何应用，它一直在
  • 多入口：通过 Telegram、WhatsApp、iMessage、Discord 都能找到它
  • 长期记忆：记得你所有的偏好、历史对话、重要事项
  • 主动出击：会主动提醒你、帮你总结、给你建议

3、Clawdbot 是什么

3.1 一句话定义

Clawdbot = 本地优先的 AI 网关 + 多平台消息整合 + 长期记忆系统

更直白地说：它是一个你自己部署的 AI 助手服务，可以通过各种消息 App 随时和它对话，而且它会记住你们之间的所有历史。

3.2 核心设计理念

1. 本地优先（Local-First）

  • 所有数据存储在你自己的设备上
  • 对话记录不会上传到任何第三方服务器
  • 你完全控制你的数据
你的数据在哪里？

ChatGPT：OpenAI 服务器（美国）
Siri：Apple 服务器
Clawdbot：你的 Mac mini / 服务器 / 电脑

2. 消息入口统一

不需要安装新的 App，用你已有的消息应用就能和 AI 对话：

支持的平台实现方式
TelegramBot API
WhatsAppBaileys（非官方）
DiscordBot API
iMessageBlueBubbles（需 Mac）
Signalsignal-cli
SlackSlack API
Google ChatAPI
MattermostAPI
Matrix协议
…12+ 平台

3. 记忆永存

  • 不只是保存聊天记录
  • 会自动提取重要信息
  • 支持语义检索（“我上周说的那个想法”）
  • 每日自动生成对话摘要

3.3 它能做什么？（场景表格）

场景示例背后能力
日常对话“今天天气怎么样”LLM 对话
任务提醒“提醒我明天 9 点开会”主动推送 + Cron
知识管理“我上周提到的投资想法是什么”长期记忆检索
信息总结“帮我总结这个 PDF”多模态 + 工具调用
代码辅助“写一个 Python 爬虫脚本”Claude/GPT 集成
智能家居“关掉客厅的灯”技能系统扩展
习惯培养“每天晚上 10 点提醒我写日记”定时任务
浏览器操作“帮我在淘宝搜索并截图”CDP 浏览器控制
文件管理“整理下载文件夹”Shell 命令执行
日程管理“总结一下今天的安排”日历集成

3.4 背后的技术（简述）

在这里插入图片描述

  • 技术栈：Node.js 22+、TypeScript、pnpm monorepo
  • 数据存储：SQLite（轻量级，无需额外数据库）
  • AI 模型：支持 Claude、GPT、本地模型（Ollama）

4、安装实战：从零到对话全流程

本章节基于笔者在 macOS 上的真实安装经历编写，包含完整的命令输出和常见问题解决方案。

在这里插入图片描述

4.1 环境准备

# 检查 Node.js 版本（需要 >= 22）
node --version
# 如果版本不够，macOS 用 Homebrew 安装
brew install node@22

# 检查 pnpm（可选，npm 也行）
pnpm --version
# 如果没有，安装它
npm install -g pnpm

系统要求：

要求说明
Node.js>= 22（推荐 LTS）
操作系统macOS / Linux / Windows（WSL2）
内存>= 4GB（推荐 8GB）
磁盘>= 2GB 可用空间

4.2 安装部署

方式一：npm 安装（推荐）

npm install -g clawdbot

方式二：一键安装

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

方式三：从源码安装

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

# 2. 安装依赖
pnpm install

# 3. 构建
pnpm build

# 4. 链接 CLI（可选）
npm link

4.3 初始配置（Onboarding 向导详解）

运行以下命令启动配置向导：

clawdbot onboard

向导会显示一个有趣的 ASCII 龙虾 Logo：

░████░█░░░░░█████░█░░░█░███░░████░░████░░▀█▀
█░░░░░█░░░░░█░░░█░█░█░█░█░░█░█░░░█░█░░░█░░█░
█░░░░░█░░░░░█████░█░█░█░█░░█░████░░█░░░█░░█░
█░░░░░█░░░░░█░░░█░█░█░█░█░░█░█░░█░░█░░░█░░█░
░████░█████░█░░░█░░█░█░░███░░████░░░███░░░█░
              🦞 FRESH DAILY 🦞
步骤 1：安全确认
◇  Security ───────────────────────────────────────────────────────╮
│  Clawdbot agents can run commands, read/write files, and act     │
│  through any tools you enable.                                   │
│  Please read: https://docs.clawd.bot/security                    │
├──────────────────────────────────────────────────────────────────╯

◇  I understand this is powerful and inherently risky. Continue?
│  Yes
步骤 2：选择 AI 后端和认证方式
◇  Model/auth provider
│  Anthropic

◆  Anthropic auth method
│  ● Anthropic token (paste setup-token) ← 推荐 Claude Max 用户
│  ○ Anthropic token (Claude Code CLI)
│  ○ Anthropic API key

认证方式对比：

认证方式适用场景优点缺点
setup-tokenClaude Max/Pro 订阅用户无需额外付费需要额外步骤生成 token
Claude Code CLI已配置 Claude Code 的用户自动读取凭证可能找不到凭证文件
API KeyAPI 按量付费用户最直接需要独立付费
步骤 3：生成并粘贴 setup-token（Claude Max 用户）

如果你选择了 “Anthropic token (paste setup-token)”：

在另一个终端运行：

claude setup-token

这会生成一个有效期 1 年的 OAuth token：

✓ Long-lived authentication token created successfully!

Your OAuth token (valid for 1 year):

sk-ant-oat01-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...

Store this token securely. You won't be able to see it again.

复制这个 token，然后在 onboard 向导中粘贴：

◇  Paste Anthropic setup-token
│  sk-ant-oat01-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...

◇  Token name (blank = default)
│  default

◇  Default model
│  Keep current (default: anthropic/claude-opus-4-5)

重要提示：如果你是 Claude Max 订阅用户，不需要单独购买 API Key，使用 setup-token 即可复用你的订阅额度。

步骤 4：配置消息平台（以 Telegram 为例）
◇  Channel status ────────────────────────────╮
│  Telegram: not configured                   │
│  WhatsApp: not configured                   │
│  Discord: not configured                    │
│  ...共支持 12+ 平台                          │
├─────────────────────────────────────────────╯

◇  Select channel (QuickStart)
│  Telegram (Bot API)

配置 Telegram 需要 Bot Token，获取方式：

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot
  3. 按提示输入 Bot 名称和用户名
  4. 复制 Bot Token（类似 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ123456789）
◇  Telegram bot token ────────────────────────────╮
│  1) Open Telegram and chat with @BotFather      │
│  2) Run /newbot (or /mybots)                    │
│  3) Copy the token (looks like 123456:ABC...)   │
├─────────────────────────────────────────────────╯

◇  Enter Telegram bot token
│  123456789:ABCdefGHIjklMNOpqrSTUvwxYZ123456789
步骤 5：安装 Gateway 服务
◇  Gateway service runtime ────────────────────────────────────────────╮
│  QuickStart uses Node for the Gateway service (stable + supported).  │
├──────────────────────────────────────────────────────────────────────╯

◒  Installing Gateway service…
Installed LaunchAgent: /Users/your-username/Library/LaunchAgents/com.clawdbot.gateway.plist
Logs: /Users/your-username/.clawdbot/logs/gateway.log
◇  Gateway service installed
步骤 6：完成配置
◇
Telegram: ok (@YourBotName) (1416ms)  ← 你的 Bot 已连接
Agents: main (default)
Heartbeat interval: 1h (main)
Session store (main): /Users/your-username/.clawdbot/agents/main/sessions/sessions.json

◇  Control UI ─────────────────────────────────────────────────────────╮
│  Web UI: http://127.0.0.1:18789/                                     │
│  Web UI (with token): http://127.0.0.1:18789/?token=your-token...    │
│  Gateway WS: ws://127.0.0.1:18789                                    │
├──────────────────────────────────────────────────────────────────────╯

└  Onboarding complete.

4.4 首次对话与配对验证

去 Telegram 给你的 Bot 发消息，你会收到一个配对码：

Clawdbot: access not configured.

Your Telegram user id: 1234567890

Pairing code: ABC12345

Ask the bot owner to approve with:
clawdbot pairing approve telegram <code>

这是 Clawdbot 的安全机制——默认情况下，Bot 不会响应任何人的消息，需要你在终端批准配对：

clawdbot pairing approve telegram ABC12345

配对完成后，再次发消息就能正常对话了！

4.5 Gateway 服务管理（重要）

理解 Gateway 服务的命令是日常使用的关键。

命令速查表
命令作用说明
clawdbot gateway前台运行关闭终端会停止
clawdbot gateway install安装服务同时启动，开机自启
clawdbot gateway start启动服务需要先 install
clawdbot gateway stop停止服务会卸载服务
clawdbot gateway status查看状态检查服务是否运行
实战示例

查看服务状态：

clawdbot gateway status

输出（运行中）：

◇
Service: LaunchAgent (loaded)
Runtime: running (pid 14416, state active)
RPC probe: ok
Listening: 127.0.0.1:18789

输出（未运行）：

◇
Service: LaunchAgent (not loaded)
Runtime: unknown
RPC probe: failed
Service not installed. Run: clawdbot gateway install
常见问题：stop 后无法 start

问题现象：

clawdbot gateway stop
# Stopped LaunchAgent: gui/501/com.clawdbot.gateway

clawdbot gateway start
# Gateway service not loaded.
# Start with: clawdbot gateway install

原因：clawdbot gateway stop 会完全卸载 LaunchAgent，而不是只暂停它。

解决方案：

# 方法 1：重新安装（推荐）
clawdbot gateway install

# 方法 2：用 launchctl 手动加载
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist

# 方法 3：直接前台运行
clawdbot gateway

最佳实践：

  • 需要重启时，使用 clawdbot gateway install（会自动重启）
  • 想要前台调试时，使用 clawdbot gateway（看实时日志）
  • 不要轻易使用 stop，除非你确定要停止服务

4.6 TUI 模式：与 Bot “聊天培养感情”

Clawdbot 有一个独特的 TUI（终端 UI）模式，用于初始化你的 Bot 人格：

clawdbot tui

┌ clawdbot tui - ws://127.0.0.1:18789 - agent main - session main ┐
│                                                                  │
│  session agent:main:main                                         │
│                                                                  │
│  Wake up, my friend!                                             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
 ⠋ dillydallying… • 0s | gateway connected
 agent main | session main | anthropic/claude-opus-4-5 | tokens 0/200k

在 TUI 中，你可以：

  • 告诉它你的偏好和习惯
  • 设置它的性格和说话风格
  • 进行初始化对话，建立"记忆基础"

提示：Clawdbot 会记住你在 TUI 中说的所有内容，这就是它"认识你"的开始。

4.7 让它 24 小时运行

如果你希望 Clawdbot 一直在线（推荐）：

macOS（LaunchAgent 自动配置）：

# onboard 时选择安装 Gateway 服务即可
# 或者手动安装
clawdbot gateway install

服务文件位置：~/Library/LaunchAgents/com.clawdbot.gateway.plist

Linux（使用 systemd）：

# 创建 service 文件
sudo cat > /etc/systemd/system/clawdbot.service << 'EOF'
[Unit]
Description=Clawdbot Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/bin/node /usr/lib/node_modules/clawdbot/dist/entry.js gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 启用并启动
sudo systemctl enable clawdbot
sudo systemctl start clawdbot

4.8 配置文件位置速查

文件/目录作用
~/.clawdbot/clawdbot.json主配置文件
~/.clawdbot/agents/main/agent/auth-profiles.json认证配置
~/.clawdbot/agents/main/sessions/会话存储
~/.clawdbot/skills/用户技能目录
~/clawd/工作空间（Workspace）
/tmp/clawdbot/clawdbot-YYYY-MM-DD.log日志文件
~/Library/LaunchAgents/com.clawdbot.gateway.plistmacOS 服务配置

5、核心功能详解

5.1 长期记忆系统

这是 Clawdbot 最核心的差异化能力。

普通聊天机器人：用完就忘
Clawdbot：记住你的一切

记忆架构：

在这里插入图片描述

混合检索：

当你问"我上周说的那个投资想法"时，Clawdbot 会：

  1. 向量检索（70% 权重）：找到语义相近的内容
  2. BM25 全文检索（30% 权重）：找到关键词匹配的内容
  3. 融合排序：返回最相关的记忆

实际效果：

你（3 个月前）：我打算学习 Rust，主要是想写高性能的系统工具

你（今天）：我之前想学什么编程语言来着？

Clawdbot：你 3 个月前提到想学习 Rust，主要目的是写高性能的系统工具。

5.2 技能系统（Skills）与 ClawdHub

Clawdbot 通过"技能"来扩展能力，就像手机的 App Store。

技能是什么？

  • 一个 Markdown 文件（SKILL.md）+ 可选的脚本
  • 定义了特定场景下 AI 应该如何行动
  • 可以调用外部工具和 API

三层加载机制：

优先级从高到低：

1. Workspace Skills   <当前目录>/.claude/skills/
   └── 项目级别，只在该项目生效

2. User Skills        ~/.clawdbot/skills/
   └── 用户级别，所有项目共享

3. Bundled Skills     内置技能
   └── Clawdbot 自带的基础技能

安装技能：

# 从 ClawdHub 安装
clawdhub install weather-forecast

# 或手动创建
mkdir -p ~/.clawdbot/skills/my-skill
cat > ~/.clawdbot/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 我的自定义技能
triggers:
  - "帮我做XXX"
---

当用户请求 XXX 时，按以下步骤执行：
1. ...
2. ...
EOF

ClawdHub 技能市场：https://clawdhub.com

  • 社区贡献的技能
  • 一键安装
  • 定期更新

5.3 主动提醒能力（Cron 任务）

这是普通聊天机器人做不到的——Clawdbot 可以主动找你。

设置提醒：

你：每天早上 8 点提醒我看晨报
Clawdbot：好的，已设置每日 8:00 的提醒

→ 第二天早上 8:00，Clawdbot 发消息：
  "早上好！该看晨报了。"

技术实现：

Clawdbot 内置了 Cron 工具，支持：

  • 一次性提醒
  • 周期性提醒（每天/每周/每月）
  • 条件触发（当某事发生时）

配置示例（高级用户）：

// ~/.clawdbot/clawdbot.json
{
  "cron": {
    "tasks": [
      {
        "name": "morning-brief",
        "schedule": "0 8 * * *",
        "action": "send_message",
        "prompt": "生成今日简报，包括天气、日程、未读消息摘要"
      }
    ]
  }
}

5.4 语音支持（ElevenLabs）

Clawdbot 可以和你语音对话，就像真正的助手一样。

Talk Mode：

开启语音模式后：

你说话 → 语音转文字 → AI 处理 → 文字转语音 → 播放回复

配置方式：

// ~/.clawdbot/clawdbot.json
{
  "nodes": {
    "talk": {
      "voiceId": "XB0fDUnXU5LcNxj5cHcI",  // ElevenLabs 语音 ID
      "modelId": "eleven_v3",
      "apiKey": "your-elevenlabs-api-key"
    }
  }
}

支持的场景：

  • macOS App（原生支持）
  • iOS/Android App（通过节点）
  • 需要 ElevenLabs API Key

5.5 浏览器控制

Clawdbot 可以帮你操作浏览器，执行复杂的网页任务。

示例：

你：帮我在京东搜索"机械键盘"，找一个 500 元以下评价最好的

Clawdbot：
1. 打开京东
2. 搜索"机械键盘"
3. 筛选价格 < 500
4. 按评价排序
5. 返回前 3 个结果的截图和链接

技术实现：

  • 使用 Chrome DevTools Protocol (CDP)
  • 支持截图、点击、输入、滚动等操作
  • 可以处理登录态（需要手动授权一次）

6、适合谁使用

6.1 理想用户画像

技术人员：

  • 想要构建个人知识库
  • 喜欢自己掌控数据
  • 有一台可以 24 小时运行的设备（Mac mini/服务器）

效率爱好者：

  • 追求自动化工作流
  • 想要跨设备统一的 AI 入口
  • 愿意花时间配置以获得更好的体验

隐私敏感者：

  • 不想把对话数据上传到云端
  • 需要本地部署的解决方案
  • 企业/团队内部使用

场景举例：

用户类型典型使用场景
独立开发者项目管理、代码 Review、文档生成
自媒体创作者内容灵感记录、定时提醒发布、数据分析
小团队内部知识库、任务协调、会议纪要
研究人员文献管理、想法记录、写作辅助

6.2 不适合的场景

普通用户：

  • 如果你只是偶尔用用 ChatGPT，没必要部署 Clawdbot
  • 配置和维护需要一定的技术能力

没有运行设备：

  • Clawdbot 需要一台 24 小时运行的设备
  • 如果你没有服务器/Mac mini/NAS，可以考虑云服务器（但会增加成本）

追求开箱即用：

  • Clawdbot 需要配置才能发挥最大价值
  • 如果你想要"下载就能用"，ChatGPT App 可能更适合你

不想折腾：

  • 技能配置、记忆调优、平台对接都需要时间
  • 如果你只是想快速解决问题，Claude Code 可能更直接

6.3 成本预估

项目费用
Clawdbot 软件免费（开源）
运行设备$0（用现有电脑）- $599（Mac mini）
AI API$0.015/1K tokens（按量）或 $20-100/月（订阅）
电费（24h 运行）~$3/月（Mac mini）
总计$20-150/月（取决于使用量）

7、总结与下一步

7.1 核心价值回顾

Clawdbot 的核心价值可以总结为三点：

  1. 永久在线：不需要打开任何应用，它一直在等你
  2. 长期记忆：记住你的所有偏好和历史，真正的"个人"助手
  3. 主动出击：会主动提醒你、帮你总结、给你建议

7.2 快速开始检查清单

# 1. 检查环境
node --version  # >= 22

# 2. 安装 Clawdbot
curl -fsSL https://clawd.bot/install.sh | bash

# 3. 初始配置
clawdbot onboard

# 4. 启动
clawdbot gateway start

# 5. 测试
# 打开 Telegram，和你的 Bot 对话

7.3 系列预告

本系列共 3 篇文章：

篇目标题内容
第一篇Clawdbot 完全指南✅ 当前文章
第二篇技术架构深度解析→ 下一篇
第三篇Clawdbot vs Claude Code 对比已发布

下一篇将深入 Clawdbot 的技术架构：

  • 完整的系统架构图
  • 记忆系统的实现原理
  • 技能系统的设计
  • 安全架构
  • 二次开发指南

参考资源

官方资源

  • 官网：https://clawd.bot
  • GitHub：https://github.com/clawdbot/clawdbot
  • 文档：https://docs.clawd.bot
  • 技能市场：https://clawdhub.com

社区资源

  • Discord：https://discord.gg/clawdbot
  • Twitter/X：@clawdbot

相关文章

# 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

从想法到真机｜启元机器人开发者社区正式上线，面向所有具身智能创作者开放

avatar AtomGit开源社区
cover

最高赢取价值万元大奖！仓颉生态创新开发挑战赛等你来挑战

avatar AtomGit开源社区
cover

从创意画布到可编辑成片，开源 AI 正在重做视频工作流

avatar AtomGit开源社区