Clawdbot 本地优先 AI 助手：架构、部署与安全边界

大多数人使用 ChatGPT、Claude 这类大语言模型时，交互方式仍然是“打开网页或 App，然后输入问题”。这种方式适合问答、写作、代码解释，但它和真实工作环境之间隔了一层：文件在本地，命令在终端，通知在聊天软件，浏览器里还有登录状态和业务系统。

Clawdbot 的思路不一样。它不是再做一个聊天窗口，而是把 AI Agent 放到你的电脑或服务器上运行，再通过 Telegram、Slack、Teams、iMessage 等常用聊天工具接收指令。模型负责理解任务和规划步骤，本地进程负责调用文件系统、终端、浏览器等工具。

项目名称曾调整为 Moltbot；为避免概念混乱，后续统一使用 Clawdbot 指代这个本地优先的个人 AI 助手。

Clawdbot 解决的核心问题

Clawdbot 可以理解为一个“住在本地机器里的 AI 助手”。它的关键不在于重新训练了一个模型，而在于把三个东西组合到了一起：

1. 熟悉的聊天入口：用户不需要打开新的 AI 应用，可以直接在 Telegram、Slack、iMessage 等工具里发消息。
2. 本地执行能力：Clawdbot 运行在你的 Mac、Linux 或 WSL2 环境里，因此可以访问你允许它访问的文件、命令行和本机服务。
3. 可扩展技能系统：通过 MCP（Model Context Protocol，模型上下文协议）或技能包，把浏览器、文件系统、网络请求等能力挂到 Agent 上。

传统 AI 聊天工具和 Clawdbot 的差别可以用一张表概括：

这类工具的定位不是“替代聊天机器人”，而是把 AI 从问答系统推进到执行系统：它可以理解你的自然语言指令，然后通过本地工具完成任务。

整体架构：聊天入口、本地 Agent、技能系统

Clawdbot 的运行链路可以拆成几层：

flowchart LR
    U[用户] --> C[聊天入口<br/>Telegram / Slack / iMessage]
    C --> G[通信连接器<br/>Bot Token / Gateway]
    G --> A[Clawdbot 本地 Agent]

    A --> L[大语言模型 API<br/>Claude / OpenAI / Gemini]
    A --> M[本地记忆<br/>Markdown / 日志 / 配置]
    A --> S[技能系统 / MCP 工具]

    S --> F[文件系统]
    S --> T[终端命令]
    S --> B[浏览器]
    S --> N[网络请求]

各部分的职责比较明确：

一次典型调用流程如下：

sequenceDiagram
    participant User as 用户
    participant Chat as Telegram Bot
    participant Agent as Clawdbot
    participant LLM as 大语言模型
    participant Skill as Filesystem Skill
    participant FS as 本地文件系统

    User->>Chat: 帮我找出桌面上包含 Confidential 的文件
    Chat->>Agent: 转发消息
    Agent->>LLM: 提供上下文和可用工具列表
    LLM-->>Agent: 计划：调用文件搜索工具
    Agent->>Skill: 搜索 Desktop 目录
    Skill->>FS: 扫描文件名和内容
    FS-->>Skill: 返回匹配结果
    Skill-->>Agent: 工具执行结果
    Agent->>LLM: 汇总结果
    LLM-->>Agent: 生成回复
    Agent-->>Chat: 返回文件列表
    Chat-->>User: 展示结果

这里最重要的一点是：模型本身不会直接读你的磁盘，也不会直接敲命令。它只能通过 Clawdbot 暴露出来的工具间接执行动作。也就是说，工具权限怎么开，决定了 Agent 能做什么，也决定了风险有多大。

Local-first：为什么本地优先很关键

Local-first 指的是数据和执行尽量发生在用户自己的设备上，而不是完全托管在云端。Clawdbot 采用这种方式有几个直接影响。

数据路径更透明

Clawdbot 的记忆、日志、配置会保存在本地目录中，常见路径类似：

~/.clawd

如果记忆以 Markdown 等可读格式保存，用户可以直接打开查看，不需要通过某个云端后台导出数据。对于个人助手来说，这一点很重要，因为长期使用后，记忆里会包含工作习惯、常用路径、任务偏好，甚至敏感项目名称。

更容易接入本机资源

运行在本地意味着 Clawdbot 可以访问本机具备权限的资源，例如：

• 指定目录下的文件；
• Git 仓库状态；
• 本地命令行工具；
• 浏览器或自动化插件；
• 内网服务或开发环境。

这也是它区别于普通 Web AI 的地方。Web AI 可以告诉你“应该执行 git status”，但本地 Agent 可以真的执行 git status，并把结果带回上下文继续分析。

权限边界需要自己管理

本地优先不是天然安全。只要 Agent 拥有文件系统、终端或浏览器权限，它就已经接近一个高权限自动化脚本。区别在于：传统脚本的动作是确定的，而 AI Agent 的动作会受到提示词、上下文和工具返回结果影响。

所以，Clawdbot 更像一个“可对话的本地自动化进程”，不能当普通聊天机器人随便部署。

快速部署：用 Telegram 跑通最小闭环

Clawdbot 适合先从 Telegram 入口开始试用，因为 Telegram Bot 的配置流程相对简单，排查问题也比较直接。

环境准备

建议准备下面这些环境：

安装 Bun 可以参考官方方式，也可以先用 npm 跑通。核心目标是确保项目依赖能安装、启动脚本能执行。

克隆项目并安装依赖

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 推荐方式
bun install

# 如果不用 Bun，可根据项目支持情况使用 npm
# npm install

配置环境变量

在项目根目录创建 .env 文件。下面以 Claude 和 Telegram 为例：

# 大语言模型配置
ANTHROPIC_API_KEY=your_api_key_here

# Telegram Bot 配置
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

# 只允许指定用户访问，防止陌生人调用你的机器人
TELEGRAM_ALLOWED_USER_IDS=123456789

TELEGRAM_ALLOWED_USER_IDS 非常关键。它相当于第一道访问控制，如果不配置，别人一旦拿到你的机器人入口，就可能消耗你的模型额度，甚至通过已启用的工具访问你的机器。

启动本地 Agent

bun run dev

启动后，在 Telegram 中给机器人发送：

ping

如果机器人返回：

pong

说明 Telegram 入口、本地进程和基础消息链路已经连通。

通信网关：为什么手机能控制本地机器

Clawdbot 的体验很大一部分来自“手机发消息，本地机器执行任务”。这里需要理解通信入口的差异。

如果使用 Telegram 的长轮询模式，本地机器通常不需要暴露公网端口，只要能访问 Telegram Bot API 即可。
如果使用 webhook、Slack 事件回调或某些消息网关，就可能需要公网回调地址、反向代理或隧道服务。

消息链路可以理解为：

flowchart LR
    Phone[手机聊天软件] --> Platform[聊天平台服务器]
    Platform --> Connector[Bot / Gateway]
    Connector --> Local[本地 Clawdbot 进程]
    Local --> Tools[本地工具与文件]
    Tools --> Local
    Local --> Connector
    Connector --> Platform
    Platform --> Phone

这条链路里的薄弱点主要有三个：

1. 聊天账号被盗：攻击者可以冒充你向 Agent 发指令。
2. Bot Token 泄露：别人可能接管机器人通道。
3. Agent 权限过大：一旦入口失守，文件、终端、浏览器都可能被滥用。

技能系统：Clawdbot 的“手脚”从哪里来

Clawdbot 本体负责调度，真正让它执行任务的是技能系统。可以把技能理解成一组受控工具，例如：

• filesystem：读取目录、搜索文件、写入文件；
• fetch：访问网页或接口；
• shell：执行终端命令；
• browser：操作浏览器页面；
• 其他通过 MCP 暴露的外部工具。

MCP（Model Context Protocol，模型上下文协议）解决的是“模型如何安全、标准化地调用外部工具”的问题。Agent 会把可用工具列表、参数结构和上下文交给模型，模型选择要调用的工具，再由本地进程执行。

一个简化的技能配置可以写成类似下面的形式，实际字段以项目配置为准：

skills:
  - name: filesystem
    enabled: true
    options:
      allowedPaths:
        - /Users/yourname/Desktop
        - /Users/yourname/Documents/work

  - name: fetch
    enabled: true

  - name: shell
    enabled: false

这里有一个重要原则：能不开的工具就不开，能限制目录就限制目录。

例如，只想让 Clawdbot 整理桌面文件，就不要给它整个用户目录的读写权限；只想让它查询网页，就不要开启终端执行权限。

可以尝试的低风险指令：

列出桌面上最近 7 天修改过的 Markdown 文件。

更高风险的指令需要谨慎，例如：

帮我删除所有临时文件。

这类任务涉及写入或删除操作，最好让 Agent 先生成执行计划和候选文件列表，再由用户确认。

适合用 Clawdbot 的场景

Clawdbot 更适合“自然语言入口 + 本地执行”的任务，而不是所有 AI 场景。

判断是否该用 Clawdbot，可以看任务是否满足两个条件：

1. 任务需要访问本地环境或已有工作流；
2. 用聊天入口触发，比打开专门工具更自然。

如果只是问一个通用问题，普通 AI 聊天工具更简单。如果任务需要“看本地文件、跑命令、再把结果发回来”，Clawdbot 的形态就更合适。

作为 AI 入口，它的产品形态有什么特别

Clawdbot 的特殊之处不是模型能力本身，而是入口设计和执行方式。

AI 不再是一个单独目的地

很多 AI 产品要求用户进入一个新的 App 或网页，再把任务复制过去。Clawdbot 反过来，把 AI 放进用户已经使用的聊天工具里。

这会降低一个实际阻力：用户不需要切换工作流。
在手机上想让家里的 Mac 查一个文件，直接给机器人发消息即可；在 Slack 里想让 Agent 查询某个项目状态，也不需要再打开另一个 AI 页面。

从“回答问题”变成“交付结果”

普通 AI 聊天往往停在建议层面：

你可以运行 git status 查看当前仓库状态。

Clawdbot 更接近执行层面：

当前仓库有 3 个未提交文件：
- src/api/user.ts
- README.md
- package.json

其中 package.json 修改了依赖版本。

这背后的变化是，AI 的价值不只来自“说得对”，还来自“能把任务推进一步”。工具生态越丰富，Agent 能完成的任务边界就越大。

本地记忆让助手更像长期工作流组件

如果一个 AI 助手每次都从空白上下文开始，它很难真正融入日常工作。Clawdbot 把记忆和配置放在本地，意味着用户可以逐步沉淀自己的偏好、路径、任务模板和历史上下文。

这种设计也带来一个管理责任：记忆文件需要备份、清理和保护。
如果不希望保留历史，可以删除对应的本地目录，例如：

rm -rf ~/.clawd

执行前要确认路径，避免误删其他数据。

安全边界：必须把它当高权限代理来管理

Clawdbot 拥有的能力越强，风险越高。尤其是开启文件系统、终端、浏览器技能后，它已经不只是聊天机器人，而是一个可以代表你操作系统和账号的代理。

常见风险和防护方式如下：

推荐的最低安全配置：

TELEGRAM_ALLOWED_USER_IDS=123456789

推荐的运行方式：

• 使用单独的低权限系统用户运行 Clawdbot；
• 不要在生产服务器或核心内网机器上试验；
• 只开放必要技能；
• 文件系统技能只允许访问指定目录；
• 删除、写入、执行命令等动作必须先让 Agent 给出计划；
• API Key、Bot Token 不要写进聊天消息；
• 定期检查 ~/.clawd、日志和技能配置。

如果怀疑入口或密钥泄露，处理顺序应该是：

# 1. 停止 Clawdbot 进程
# 2. 重置 Telegram Bot Token
# 3. 轮换 LLM API Key
# 4. 检查本地日志和文件访问痕迹
# 5. 必要时清理本地记忆目录

Clawdbot 的边界和代价

Clawdbot 展示了 AI Agent 的一种重要方向：让 AI 进入已有沟通入口，并通过本地工具交付结果。它没有必要神化，真实使用时仍然有不少限制。

Clawdbot 更像一个高可塑性的个人 Agent 框架，而不是开箱即用的普通消费级应用。适合愿意管理配置、权限和工具链的人；如果只想获得一个稳定、低风险的聊天助手，独立 AI App 仍然更省心。

常用地址

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

Clawdbot 的价值在于把 AI、聊天入口和本地执行环境接在了一起。它让 AI 不再只是回答问题，而是开始参与文件、命令、浏览器和工作流操作。与此同时，它也把安全问题推到了前台：一旦 AI 拥有“键盘、文件和身份”，权限控制就不再是可选项，而是部署前必须完成的基础工作。