文章目录

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

1、前言

很多 AI Agent 框架让你感觉在用"黑箱"——Clawdbot 的开源架构让你能清晰看到每一层的设计决策。

本文带你从系统架构到核心模块，完整拆解 Clawdbot 的技术栈：Gateway 控制平面、记忆系统、技能系统、安全架构、以及如何进行二次开发。

2、整体架构概览

2.1 架构图

在这里插入图片描述

2.2 设计原则

Clawdbot 的架构设计遵循三个核心原则：

原则 描述 实现方式
本地优先 核心逻辑全部本地运行，数据不上传 SQLite 存储、本地向量索引
模块解耦 每个平台适配器独立，易于扩展 插件式架构、接口抽象
可扩展 技能系统支持热加载，无需重启 三层技能加载、ClawdHub 市场

2.3 数据流向

在这里插入图片描述

3、技术栈详解

3.1 核心运行时

组件 技术选型 选型理由
运行时 Node.js ≥ 22 异步 I/O，生态丰富，对 AI 工具链友好
语言 TypeScript (ESM) 类型安全，IDE 支持好，便于大型项目维护
包管理 pnpm monorepo 依赖隔离，磁盘高效，支持工作区
数据库 SQLite 零配置，本地优先，无需额外服务
测试框架 Vitest 快速，与 TypeScript 集成好

为什么选择 Node.js 22+？

// Node.js 22 原生支持的关键特性

// 1. 原生 ESM 模块
import { Gateway } from './gateway.js';

// 2. 原生 fetch API
const response = await fetch('https://api.anthropic.com/...');

// 3. 性能优化的 V8 引擎
// 对 AI 推理和大量文本处理有显著提升

3.2 消息平台适配

Clawdbot 支持 12+ 消息平台，每个平台都有独立的适配器：

平台 使用的库/协议 认证方式 特点
Telegram grammY Bot Token 最稳定，推荐新手
WhatsApp Baileys QR 码扫描 非官方库，功能完整
Discord discord.js Bot Token 支持 Guild 和 DM
iMessage BlueBubbles macOS 专属 需要 Mac 作为服务器
Signal signal-cli 手机号 隐私优先
Slack Slack SDK OAuth 企业场景
Google Chat Google API Service Account G Suite 集成
Mattermost Mattermost API Bot Token 自托管团队
Matrix Matrix Protocol Homeserver 去中心化

3.2.1 适配器架构

// 所有适配器实现统一接口
interface ChannelAdapter {
  // 初始化连接
  connect(): Promise<void>;

  // 发送消息
  sendMessage(chatId: string, content: string): Promise<void>;

  // 接收消息（事件驱动）
  onMessage(callback: (msg: IncomingMessage) => void): void;

  // 断开连接
  disconnect(): Promise<void>;
}

// Telegram 适配器示例
class TelegramAdapter implements ChannelAdapter {
  private bot: Bot;

  async connect() {
    this.bot = new Bot(process.env.TELEGRAM_BOT_TOKEN);
    await this.bot.start();
  }

  async sendMessage(chatId: string, content: string) {
    await this.bot.api.sendMessage(chatId, content);
  }

  onMessage(callback) {
    this.bot.on('message', (ctx) => {
      callback({
        platform: 'telegram',
        chatId: ctx.chat.id.toString(),
        senderId: ctx.from.id.toString(),
        content: ctx.message.text,
        timestamp: new Date(),
      });
    });
  }
}

3.3 AI 后端支持

Clawdbot 支持多种 AI 后端，可以根据场景灵活切换：

后端 推荐场景 配置方式
Claude Opus 4.5 生产环境首选 API Key 或 OAuth
Claude Sonnet 平衡成本和性能 API Key 或 OAuth
GPT-4o OpenAI 生态 API Key
本地模型（Ollama） 隐私敏感、离线 本地部署

3.3.1 模型配置

// ~/.clawdbot/clawdbot.json
{
  "agent": {
    // 主模型配置
    "model": "anthropic/claude-opus-4-5-20251101",

    // 备选模型（可选）
    "fallbackModel": "anthropic/claude-sonnet-4-20250514"
  },

  // 认证配置
  "auth": {
    "anthropic": {
      // 方式1：API Key（推荐生产环境）
      "apiKey": "sk-ant-..."

      // 方式2：OAuth（需要 Claude Pro/Max 订阅）
      // "useOAuth": true
    },
    "openai": {
      "apiKey": "sk-..."
    },
    "local": {
      "provider": "ollama",
      "baseUrl": "http://localhost:11434",
      "model": "llama3:latest"
    }
  }
}

4、记忆系统深度解析

这是 Clawdbot 最核心的技术亮点——让 AI 真正"记住"你。

4.1 记忆架构图

在这里插入图片描述

（详见上方架构图）

4.2 混合检索原理

Clawdbot 使用混合检索策略，结合了向量相似度和传统全文检索的优势：
在这里插入图片描述

4.2.1 为什么是 70:30？

检索方式 优势 劣势
向量检索 理解语义、支持意译 可能丢失精确匹配
BM25 全文 精确匹配、速度快 不理解同义词

70:30 的比例是经过大量测试得出的平衡点：

  • 向量检索能处理"那个投资的事"→"关于股票的讨论"这类语义映射
  • BM25 确保"Claude Code"这类专有名词不会被误检索

4.3 存储结构

4.3.1 SQLite 表结构

-- 核心记忆表
CREATE TABLE memories (
    id TEXT PRIMARY KEY,           -- UUID
    content TEXT NOT NULL,         -- 原始内容
    embedding BLOB,                -- 向量嵌入（浮点数组）
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    user_id TEXT,                  -- 关联用户
    session_id TEXT,               -- 关联会话
    metadata JSON                  -- 扩展元数据
);

-- BM25 全文索引（虚拟表）
CREATE VIRTUAL TABLE memories_fts USING fts5(
    content,
    content='memories',
    content_rowid='rowid'
);

-- 向量索引（使用 sqlite-vec 扩展）
CREATE VIRTUAL TABLE memories_vec USING vec0(
    id TEXT PRIMARY KEY,
    embedding FLOAT[1536]          -- OpenAI 嵌入维度
);

-- 索引
CREATE INDEX idx_memories_user ON memories(user_id);
CREATE INDEX idx_memories_session ON memories(session_id);
CREATE INDEX idx_memories_created ON memories(created_at);

4.3.2 每日日志格式

<!-- ~/.clawdbot/agents/<agentId>/memory/2026-01-25.md -->

# 2026-01-25 对话日志

## 09:15 早安问候
**用户**：早上好
**助手**：早上好！今天天气不错，有什么计划吗？

## 10:30 项目讨论
**用户**：帮我总结一下 Clawdbot 的架构
**助手**：Clawdbot 采用本地优先的架构...

## 14:00 投资想法
**用户**：我在考虑投资一些科技股
**助手**：好的，需要我帮你分析吗？

---

## 今日关键洞察
- 用户正在关注科技股投资
- 用户对 Clawdbot 架构感兴趣
- 明天有重要会议（用户提到）

## 待办事项
- [ ] 提醒用户明天的会议

4.4 嵌入提供商

Clawdbot 支持多种嵌入模型，按优先级自动选择：

本地嵌入 → OpenAI → Gemini
  (优先)    (备选)    (兜底)
提供商 模型 维度 特点
本地 embeddinggemma-300M-Q8_0.gguf 约600MB 无需网络，速度快
OpenAI text-embedding-3-small 1536 效果好，成本适中
Gemini gemini-embedding-001 - Google 生态

4.4.1 嵌入配置

// ~/.clawdbot/clawdbot.json
{
  "memorySearch": {
    "embedding": {
      // 优先使用本地
      "preferLocal": true,

      // OpenAI 配置
      "openai": {
        "model": "text-embedding-3-small"
      },

      // 批处理设置（降低成本）
      "batchSize": 100,

      // 缓存配置
      "cache": {
        "enabled": true,
        "ttl": 86400  // 24小时
      }
    },

    // 检索配置
    "retrieval": {
      "vectorWeight": 0.7,    // 向量权重
      "bm25Weight": 0.3,      // BM25 权重
      "topK": 10              // 返回数量
    }
  }
}

5、技能系统（Skills）

技能系统让 Clawdbot 的能力可以无限扩展，就像手机的 App Store。

5.1 三层加载机制

在这里插入图片描述

5.2 技能结构

一个典型的技能目录结构：

my-weather-skill/
├── SKILL.md              # 主指令文件（必须）
├── scripts/              # 可执行脚本（可选）
│   ├── get_weather.py
│   └── format_output.js
├── reference/            # 参考文档（可选）
│   └── api_docs.md
└── examples/             # 示例（可选）
    └── usage.md

5.2.1 SKILL.md 格式

---
# YAML Frontmatter（元数据）
name: weather-forecast
description: 获取天气预报并格式化输出
version: 1.0.0
author: xzl

# 触发条件
triggers:
  - "天气"
  - "weather"
  - "今天穿什么"

# 依赖检查
requires:
  binaries: ["python3", "curl"]
  env: ["WEATHER_API_KEY"]
  platform: ["darwin", "linux"]

# 工具权限
tools:
  - Bash
  - Read
---

# Weather Forecast Skill

当用户询问天气相关问题时，按以下步骤执行：

## 1. 获取位置
如果用户没有指定位置，使用默认位置（广东省）。

## 2. 调用天气 API
```bash
python3 scripts/get_weather.py --location "${LOCATION}"

3. 格式化输出

将天气数据格式化为用户友好的形式：

  • 当前温度和体感温度
  • 天气状况描述
  • 穿衣建议

4. 附加建议

根据天气状况给出额外建议：

  • 雨天：提醒带伞
  • 高温：提醒防晒
  • 低温：提醒添衣

## 5.3 技能热加载

Clawdbot 支持技能热加载，无需重启：

```bash
# 添加新技能后自动生效
cp -r my-new-skill ~/.clawdbot/skills/

# 或使用 CLI
clawdbot skills reload

热加载原理：

// Gateway 监听技能目录变化
const watcher = chokidar.watch([
  `${workspaceDir}/.claude/skills`,
  `${homeDir}/.clawdbot/skills`,
]);

watcher.on('change', async (path) => {
  console.log(`Skill changed: ${path}`);
  await skillManager.reload();
});

5.4 ClawdHub 技能市场

ClawdHub（https://clawdhub.com）是 Clawdbot 的官方技能市场：

# 搜索技能
clawdhub search "weather"

# 安装技能
clawdhub install weather-forecast

# 更新技能
clawdhub update weather-forecast

# 列出已安装
clawdhub list

热门技能：

技能名称 功能 安装量
browser-control 浏览器自动化 10k+
calendar-sync 日历同步 8k+
smart-home 智能家居控制 5k+
code-review 代码审查 4k+
email-summary 邮件摘要 3k+

6、安全架构

Clawdbot 采用多层安全策略，保护用户数据和系统安全。

6.1 访问控制：DM 策略

在这里插入图片描述

6.1.1 DM 策略配置

策略 行为 适用场景
pairing 未知发件人获得时间限制的配对码 默认推荐
allowlist 完全阻止未知发件人 高安全需求
open 允许任何人访问 公开服务
disabled 不接受任何 DM 仅群组使用 
// ~/.clawdbot/clawdbot.json
{
  "channels": {
    "telegram": {
      "dm": {
        "policy": "pairing",
        "pairingTimeout": 3600  // 配对码有效期（秒）
      }
    },
    "discord": {
      "dm": {
        "policy": "allowlist",
        "allowlist": ["user_id_1", "user_id_2"]
      }
    }
  }
}

6.2 Docker 沙箱隔离

Clawdbot 支持将非主会话在 Docker 容器中运行，实现安全隔离：

// ~/.clawdbot/clawdbot.json
{
  "agents": {
    "defaults": {
      "sandbox": {
        // 启用沙箱
        "mode": "non-main",  // off | non-main | all

        // 隔离作用域
        "scope": "session",   // session | agent | shared

        // Docker 配置
        "image": "debian:bookworm-slim",
        "network": "none",    // 网络隔离
        "user": "agent",      // 非 root 用户

        // 资源限制
        "pidsLimit": 100,
        "memory": "512m",
        "memorySwap": "1g",
        "cpus": "1"
      }
    }
  }
}

6.2.1 沙箱模式说明

模式 行为
"off" 禁用沙箱，所有会话直接在主机运行
"non-main" 主会话在主机，其他会话在 Docker
"all" 所有会话都在 Docker 中运行

6.2.2 工作区访问控制

访问级别 说明
"none" 使用隔离的沙箱工作区
"ro" 只读挂载代理工作区
"rw" 读写访问工作区

6.3 文件权限加固

# 推荐的权限设置
chmod 700 ~/.clawdbot/               # 只有本用户可访问
chmod 600 ~/.clawdbot/*.json         # 配置文件
chmod 600 ~/.clawdbot/credentials/*  # 凭证文件

# 运行安全审计
clawdbot security audit --fix

6.4 提示注入防护

Clawdbot 使用多种策略防止提示注入攻击：
在这里插入图片描述

7、WebSocket 控制平面

Gateway 暴露 WebSocket 端口，允许外部工具集成和监控。

7.1 协议设计

端口配置优先级：
--port > CLAWDBOT_GATEWAY_PORT > gateway.port > 默认 18789

额外端口：
├── base + 2 (18791): Browser control URL
├── base + 4 (18793): Canvas host
└── 18790: iOS 节点 TCP bridge

7.1.1 连接协议

// 客户端连接流程
const ws = new WebSocket('ws://localhost:18789');

// 1. 发送连接请求（必须是第一帧）
ws.send(JSON.stringify({
  type: 'req',
  method: 'connect',
  params: {
    minProtocol: 1,
    maxProtocol: 1,
    client: 'my-integration',
    caps: ['send_message', 'list_sessions'],
    auth: 'Bearer your-token'
  }
}));

// 2. 接收连接响应
ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'res' && msg.ok) {
    console.log('Connected!', msg.payload);
  }
});

7.2 API 示例

7.2.1 发送消息

// 向特定会话发送消息
ws.send(JSON.stringify({
  type: 'req',
  id: 'msg-001',
  method: 'send_message',
  params: {
    platform: 'telegram',
    chatId: '123456',
    content: 'Hello from external tool!'
  }
}));

7.2.2 查询记忆

// 搜索记忆
ws.send(JSON.stringify({
  type: 'req',
  id: 'mem-001',
  method: 'memory_search',
  params: {
    query: '上周的投资讨论',
    limit: 5
  }
}));

// 响应
// {
//   type: 'res',
//   id: 'mem-001',
//   ok: true,
//   payload: {
//     results: [
//       { content: '...', score: 0.92, timestamp: '...' },
//       ...
//     ]
//   }
// }

7.2.3 监听事件

// 监听所有消息事件
ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'event' && msg.event === 'message_received') {
    console.log('New message:', msg.payload);
  }
});

8、进阶配置

8.1 多模型路由

根据不同场景自动选择最合适的模型：

// ~/.clawdbot/clawdbot.json
{
  "agent": {
    "modelRouting": {
      "rules": [
        {
          // 代码相关使用 Opus
          "condition": {
            "contentContains": ["代码", "编程", "bug"]
          },
          "model": "anthropic/claude-opus-4-5-20251101"
        },
        {
          // 简单问答使用 Haiku（更快更便宜）
          "condition": {
            "messageLength": { "max": 50 }
          },
          "model": "anthropic/claude-haiku-4-20250514"
        },
        {
          // 默认使用 Sonnet
          "default": true,
          "model": "anthropic/claude-sonnet-4-20250514"
        }
      ]
    }
  }
}

8.2 自定义记忆策略

// ~/.clawdbot/clawdbot.json
{
  "memorySearch": {
    // 调整检索权重
    "retrieval": {
      "vectorWeight": 0.8,  // 更侧重语义
      "bm25Weight": 0.2
    },

    // 记忆压缩策略
    "compression": {
      "enabled": true,
      "threshold": 10000,   // 超过 10k tokens 时压缩
      "strategy": "summarize"  // summarize | truncate
    },

    // 自动遗忘
    "forgetting": {
      "enabled": false,     // 是否启用
      "maxAge": 365,        // 最大保留天数
      "minScore": 0.3       // 低于此分数的记忆可被遗忘
    }
  }
}

8.3 性能调优

// ~/.clawdbot/clawdbot.json
{
  "performance": {
    // 并发控制
    "maxConcurrentSessions": 10,
    "maxConcurrentTools": 5,

    // 缓存配置
    "cache": {
      "embedding": {
        "enabled": true,
        "maxSize": 10000
      },
      "response": {
        "enabled": false  // 响应缓存（谨慎使用）
      }
    },

    // 超时设置
    "timeout": {
      "llm": 120000,      // LLM 调用超时
      "tool": 60000,      // 工具调用超时
      "memory": 10000     // 记忆检索超时
    }
  }
}

9、二次开发指南

9.1 添加新的消息平台

// src/channels/my-platform/adapter.ts

import { ChannelAdapter, IncomingMessage } from '../types';

export class MyPlatformAdapter implements ChannelAdapter {
  private client: MyPlatformSDK;

  constructor(config: MyPlatformConfig) {
    this.client = new MyPlatformSDK(config);
  }

  async connect(): Promise<void> {
    await this.client.login();
    console.log('MyPlatform connected');
  }

  async sendMessage(chatId: string, content: string): Promise<void> {
    await this.client.sendMessage(chatId, content);
  }

  onMessage(callback: (msg: IncomingMessage) => void): void {
    this.client.on('message', (raw) => {
      callback({
        platform: 'my-platform',
        chatId: raw.conversationId,
        senderId: raw.senderId,
        content: raw.text,
        timestamp: new Date(raw.timestamp),
      });
    });
  }

  async disconnect(): Promise<void> {
    await this.client.logout();
  }
}

// 注册适配器
// src/channels/index.ts
import { MyPlatformAdapter } from './my-platform/adapter';

channelRegistry.register('my-platform', MyPlatformAdapter);

9.2 创建自定义技能

# 使用 CLI 创建技能模板
clawdbot skills create my-skill

# 生成的目录结构
# ~/.clawdbot/skills/my-skill/
# ├── SKILL.md
# └── scripts/
#     └── main.py

9.3 贡献代码

# 1. Fork 并克隆
git clone https://github.com/YOUR_USERNAME/clawdbot.git
cd clawdbot

# 2. 安装依赖
pnpm install

# 3. 开发模式
pnpm gateway:watch

# 4. 运行测试
pnpm test

# 5. 代码检查
pnpm lint

# 6. 提交 PR
# 确保测试通过，覆盖率 > 70%

10、总结

10.1 架构优势回顾

特性 亮点
本地优先 数据留在本地，保护隐私
模块化 便于扩展和维护
开源透明 可审计、可定制
记忆系统 70/30 混合检索，真正的长期记忆
技能系统 热加载、ClawdHub 生态
安全架构 多层防护、Docker 沙箱

10.2 关键配置文件速查

文件 用途
~/.clawdbot/clawdbot.json 主配置文件
~/.clawdbot/credentials/ 平台凭证
~/.clawdbot/skills/ 用户技能
~/.clawdbot/memory/ 向量数据库
~/.clawdbot/agents/<id>/ 代理数据

10.3 深入学习资源

  • 源码阅读：https://github.com/clawdbot/clawdbot
  • API 文档：https://docs.clawd.bot/api
  • 技能开发：https://docs.clawd.bot/skills
  • 贡献指南：https://github.com/clawdbot/clawdbot/blob/main/CONTRIBUTING.md

参考资源

官方资源

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

技术文档

# 架构
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

2026 MBA必看！10个降AI率工具测评榜单

avatar 2048 AI社区
cover

ChatGPT和Gemini导出pdf指令

avatar 2048 AI社区
cover

【Flutter for OpenHarmony】网络请求实战：Dio 封装与数据上云

avatar 2048 AI社区