🤖 Clawdbot 代码架构深度解析

一、概述

Clawdbot 是一个 AI 助手框架，它就像一个「智能中转站」，连接着你（通过 Telegram、Discord 等渠道）和 AI 大脑（Claude、GPT 等模型）。它不仅能理解你的消息，还能调用各种工具来完成任务。

用通俗的话说：

> Clawdbot 就像一个全能管家，你通过微信/Telegram 发消息给他，他会调动各种资源（执行命令、读写文件、搜索网页）来帮你完成任务，然后把结果告诉你。

二、整体架构图

┌─────────────────────────────────────────────────────────────────────┐
│                          用户交互层                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │ Telegram │  │ Discord  │  │  Signal  │  │ WhatsApp │   ...      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘            │
│       │             │             │             │                   │
│       └─────────────┴──────┬──────┴─────────────┘                   │
└────────────────────────────┼────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Gateway 网关层                               │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  HTTP/WebSocket 服务器 (默认端口 18789)                       │    │
│  │  • 消息路由 • 会话管理 • 健康检查 • 配置重载                    │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                             │                                       │
│      ┌──────────────────────┼──────────────────────┐               │
│      ▼                      ▼                      ▼               │
│  ┌────────┐           ┌──────────┐           ┌──────────┐          │
│  │ Channel│           │ Sessions │           │   Cron   │          │
│  │ Manager│           │ Manager  │           │ Scheduler│          │
│  └────────┘           └──────────┘           └──────────┘          │
└─────────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          Agent 智能体层                              │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  PI (Provider Interface) - AI 模型交互引擎                    │    │
│  │  • 构建提示词 (System Prompt)                                 │    │
│  │  • 流式响应处理                                               │    │
│  │  • 工具调用编排                                               │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                             │                                       │
│      ┌──────────────────────┼──────────────────────┐               │
│      ▼                      ▼                      ▼               │
│  ┌────────┐           ┌──────────┐           ┌──────────┐          │
│  │ Tools  │           │ Subagent │           │  Skills  │          │
│  │ System │           │ Registry │           │ Loader   │          │
│  └────────┘           └──────────┘           └──────────┘          │
└─────────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         AI 模型层                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │ Claude   │  │ GPT-4    │  │ Gemini   │  │ 本地模型  │   ...      │
│  │(Anthropic)│ │ (OpenAI) │  │ (Google) │  │ (Ollama) │            │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │
└─────────────────────────────────────────────────────────────────────┘

三、核心组件详解

1. 🚪 Gateway（网关）- 系统的大门

文件位置： /dist/gateway/

Gateway 是整个系统的「指挥中心」，负责：

• 接收来自各个渠道的消息
• 管理所有会话（Session）
• 分发任务给 Agent
• 返回 AI 的回复

核心代码示例（server.impl.js）：

// Gateway 启动时做的事情
export async function startGatewayServer(port = 18789, opts = {}) {
    // 1. 加载配置
    let configSnapshot = await readConfigFileSnapshot();
    
    // 2. 初始化子 Agent 注册表
    initSubagentRegistry();
    
    // 3. 加载插件（各种渠道、工具）
    const { pluginRegistry, gatewayMethods } = loadGatewayPlugins({
        cfg: cfgAtStart,
        workspaceDir: defaultWorkspaceDir,
        // ...
    });
    
    // 4. 创建 Channel 管理器
    const channelManager = createChannelManager({ /* ... */ });
    
    // 5. 启动 HTTP/WebSocket 服务器
    // ...
}

通俗理解：

> Gateway 就像酒店的前台，所有客人（消息）都要先经过前台登记，然后前台决定把你分配到哪个房间（会话），再叫服务员（Agent）来服务你。

2. 📱 Channel（渠道）- 消息的入口

文件位置： /dist/channels/ 和 /dist/telegram/

Channel 是消息进入系统的入口，每种聊天平台都有对应的 Channel 插件：

channels/
├── plugins/
│   ├── telegram.js    # Telegram 插件
│   ├── discord.js     # Discord 插件
│   ├── signal.js      # Signal 插件
│   ├── whatsapp.js    # WhatsApp 插件
│   └── slack.js       # Slack 插件

以 Telegram 为例（telegram/bot.js）：

export function createTelegramBot(opts) {
    // 使用 grammy 库创建 Telegram Bot
    const bot = new Bot(opts.token);
    
    // 配置消息限流
    bot.api.config.use(apiThrottler());
    
    // 按聊天 ID 顺序处理消息
    bot.use(sequentialize(getTelegramSequentialKey));
    
    // 注册消息处理器
    registerTelegramHandlers({
        bot,
        processMessage,  // 核心处理函数
        // ...
    });
    
    return bot;
}

消息处理流程（bot-handlers.js）：

// 当收到 Telegram 消息时
bot.on("message", async (ctx) => {
    // 1. 检查是否重复消息
    if (shouldSkipUpdate(ctx)) return;
    
    // 2. 检查发送者是否有权限
    if (!isSenderAllowed(senderId, allowFrom)) return;
    
    // 3. 处理媒体（图片、文件等）
    const media = await resolveMedia(ctx, mediaMaxBytes);
    
    // 4. 交给消息处理器
    await processMessage(ctx, media);
});

通俗理解：

> Channel 就像不同的门（Telegram 门、Discord 门），每个门都有自己的门卫，但进来之后都走同一条路去见 AI 管家。

3. 🧠 Agent（智能体）- AI 的大脑

文件位置： /dist/agents/

Agent 是实际与 AI 模型对话的组件，核心职责：

• 构建 System Prompt（告诉 AI 它是谁、能做什么）
• 发送消息给 AI 模型
• 处理 AI 的流式响应
• 执行 AI 请求的工具调用

System Prompt 构建（system-prompt.js）：

// AI 的「身份证」和「能力说明书」
function buildSystemPrompt(params) {
    const sections = [
        // 1. 基础身份
        buildUserIdentitySection(ownerLine),
        
        // 2. 可用技能
        buildSkillsSection(params),
        
        // 3. 消息发送能力
        buildMessagingSection(params),
        
        // 4. 工具使用说明
        buildToolsSection(params),
        
        // 5. 当前时间
        buildTimeSection(params),
    ];
    
    return sections.flat().join('\n');
}

流式响应订阅（pi-embedded-subscribe.js）：

export function subscribeEmbeddedPiSession(params) {
    const state = {
        assistantTexts: [],      // AI 的回复文本
        toolMetas: [],           // 工具调用信息
        deltaBuffer: "",         // 流式文本缓冲
        // ...
    };
    
    // 处理 AI 返回的每个文本片段
    const pushAssistantText = (text) => {
        if (!text) return;
        assistantTexts.push(text);
    };
    
    // 处理工具调用
    const handleToolCall = (toolCall) => {
        toolMetas.push({
            name: toolCall.name,
            input: toolCall.input,
            // ...
        });
    };
    
    // ...
}

通俗理解：

> Agent 就像 AI 的「翻译官」，把你的消息翻译成 AI 能理解的格式，再把 AI 的回复翻译成你能看懂的消息。

4. 🔧 Tools（工具）- AI 的双手

文件位置： /dist/agents/pi-tools.js 和 /dist/agents/bash-tools.exec.js

Tools 是 AI 能够调用的各种功能，包括：

• exec - 执行 Shell 命令
• read / write / edit - 文件操作
• web_search - 网页搜索
• browser - 浏览器控制
• message - 发送消息

工具定义示例（bash-tools.exec.js）：

const execSchema = Type.Object({
    command: Type.String({ 
        description: "Shell command to execute" 
    }),
    workdir: Type.Optional(Type.String({ 
        description: "Working directory" 
    })),
    timeout: Type.Optional(Type.Number({
        description: "Timeout in seconds"
    })),
    // ...
});

// 执行命令的核心逻辑
async function runExecTool(params) {
    const { command, workdir, timeout } = params;
    
    // 1. 安全检查
    if (requiresExecApproval(command, security)) {
        await requestApproval(command);
    }
    
    // 2. 执行命令
    const result = await spawnWithFallback({
        command,
        cwd: workdir,
        timeout: timeout * 1000,
    });
    
    // 3. 返回输出
    return {
        output: result.stdout,
        exitCode: result.exitCode,
    };
}

工具策略控制（pi-tools.policy.js）：

// 根据配置决定哪些工具可用
export function filterToolsByPolicy(tools, policies) {
    return tools.filter(tool => {
        // 检查全局策略
        if (!isToolAllowedByPolicies(tool.name, policies)) {
            return false;
        }
        return true;
    });
}

通俗理解：

> Tools 就像管家的各种技能——会做饭（exec）、会整理文件（read/write）、会上网查资料（web_search）。AI 决定要做什么，然后调用对应的技能来完成。

5. 📋 Session（会话）- 对话的记忆

文件位置： /dist/sessions/ 和 /dist/gateway/session-utils.js

Session 管理对话的上下文和历史：

Session Key 的组成（session-key.js）：

// Session Key 的格式示例：
// - agent:main:main          → 主 Agent 的主会话
// - agent:main:telegram:dm:123456  → Telegram 私聊会话
// - agent:main:subagent:abc123     → 子 Agent 会话

export function buildAgentMainSessionKey(params) {
    const agentId = normalizeAgentId(params.agentId);  // "main"
    const mainKey = normalizeMainKey(params.mainKey);  // "main"
    return `agent:${agentId}:${mainKey}`;              // "agent:main:main"
}

export function buildAgentPeerSessionKey(params) {
    // 为每个聊天对象创建独立会话
    return `agent:${agentId}:${channel}:dm:${peerId}`;
}

通俗理解：

> Session 就像你和管家的对话记录本，管家知道你上次聊了什么，能接着之前的话题继续聊。

6. 👶 Subagent（子智能体）- 分身术

文件位置： /dist/agents/subagent-registry.js

当任务复杂时，主 Agent 可以派生子 Agent 来并行处理：

// 子 Agent 注册表
const subagentRuns = new Map();

// 注册新的子 Agent
export function registerSubagentRun(params) {
    const runId = generateRunId();
    
    subagentRuns.set(runId, {
        runId,
        childSessionKey: params.childSessionKey,
        requesterSessionKey: params.requesterSessionKey,
        task: params.task,                    // 子 Agent 的任务描述
        startedAt: Date.now(),
        outcome: null,                        // 完成后的结果
    });
    
    return runId;
}

// 等待子 Agent 完成
async function waitForSubagentCompletion(runId, timeoutMs) {
    const entry = subagentRuns.get(runId);
    if (!entry) return;
    
    // 监听 Agent 事件
    onAgentEvent((evt) => {
        if (evt.runId === runId && evt.data?.phase === 'done') {
            // 子 Agent 完成，通知主 Agent
            announceSubagentCompletion(entry);
        }
    });
}

通俗理解：

> Subagent 就像主管家叫来的帮手，主管家说"你去调查这个问题"，帮手完成后再向主管家汇报。

四、关键流程详解

流程1：一条 Telegram 消息的完整旅程

┌─────────────────────────────────────────────────────────────────────────┐
│ 用户在 Telegram 发送: "帮我看看当前目录有什么文件"                          │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. Telegram Bot 接收消息                                                │
│    bot.on("message", async (ctx) => { ... })                           │
│    • 提取消息文本、发送者ID、聊天ID                                       │
│    • 检查发送者权限                                                      │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. 构建 Session Key                                                     │
│    sessionKey = "agent:main:telegram:dm:123456"                        │
│    • 加载该会话的历史消息                                                 │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. 发送到 Gateway                                                       │
│    gateway.call("chat.send", {                                         │
│        sessionKey: "agent:main:telegram:dm:123456",                    │
│        message: "帮我看看当前目录有什么文件",                              │
│        channel: "telegram"                                              │
│    })                                                                   │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 4. Agent 构建请求                                                       │
│    • 生成 System Prompt（包含可用工具列表）                               │
│    • 拼接历史消息                                                        │
│    • 添加用户新消息                                                      │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 5. 调用 AI 模型（如 Claude）                                             │
│    API 请求包含:                                                        │
│    • system: "You are Claude Code, Anthropic's CLI..."                 │
│    • messages: [之前的对话 + 新消息]                                     │
│    • tools: [exec, read, write, ...]                                   │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 6. AI 返回工具调用请求                                                   │
│    {                                                                    │
│      "type": "tool_use",                                               │
│      "name": "exec",                                                   │
│      "input": { "command": "ls -la" }                                  │
│    }                                                                    │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 7. 执行工具调用                                                         │
│    const result = await execTool({ command: "ls -la" });               │
│    // 返回: "total 32\ndrwxr-xr-x 5 user user 4096..."                 │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 8. 把工具结果返回给 AI                                                   │
│    AI 看到目录列表后，生成自然语言回复:                                    │
│    "当前目录有以下文件和文件夹：..."                                       │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 9. 回复发送到 Telegram                                                  │
│    await sendMessageTelegram(chatId, "当前目录有以下文件...");           │
└─────────────────────────────────────────────────────────────────────────┘

流程2：工具调用的实现机制

// 1. AI 在回复中包含工具调用
// AI Response:
{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01XYZ",
      "name": "exec",
      "input": { "command": "ls -la" }
    }
  ]
}

// 2. 系统解析工具调用
const toolCall = response.content.find(c => c.type === "tool_use");
const { name, input, id } = toolCall;

// 3. 找到对应的工具实现
const tool = tools.find(t => t.name === name);

// 4. 执行工具
const result = await tool.execute(input);

// 5. 构造工具结果
const toolResult = {
  type: "tool_result",
  tool_use_id: id,
  content: result.output
};

// 6. 把结果发回给 AI 继续对话
messages.push({ role: "user", content: [toolResult] });
// 再次调用 AI API...

流程3：子 Agent 的派发与回收

// 主 Agent 决定派发子任务
// System Prompt 中的指导：
// "If a task is complex, spawn a sub-agent to handle it..."

// 1. 主 Agent 调用 sessions_spawn 工具派发子 Agent
await sessions_spawn({
  task: "分析这个代码库的架构",
  label: "code-analysis"
});

// 2. 系统创建新的 Session
const childSessionKey = `agent:main:subagent:${generateId()}`;

// 3. 注册子 Agent
registerSubagentRun({
  runId,
  childSessionKey,
  requesterSessionKey: parentSessionKey,
  task: "分析这个代码库的架构",
  startedAt: Date.now()
});

// 4. 子 Agent 独立运行
// 有自己的对话历史，有自己的工具访问权限

// 5. 子 Agent 完成后，系统通知主 Agent
onAgentEvent((evt) => {
  if (evt.data?.phase === 'done') {
    // 发送完成通知给主 Agent
    notifyParentAgent({
      message: `子任务「${label}」已完成，结果：...`
    });
  }
});

五、数据流总结

用户消息
    │
    ▼
[Channel Plugin] ──解析消息──▶ [Gateway] ──路由──▶ [Session Manager]
                                   │                      │
                                   │                      ▼
                                   │              加载对话历史
                                   │                      │
                                   ▼                      │
                              [Agent] ◀───────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              构建 System    准备 Messages   加载 Tools
                Prompt           │              │
                    │            │              │
                    └──────────────┬──────────────┘
                                   │
                                   ▼
                            [AI Model API]
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              纯文本回复      工具调用请求     思考过程
                    │              │              │
                    │              ▼              │
                    │        [Tool Executor]      │
                    │              │              │
                    │              ▼              │
                    │        工具执行结果         │
                    │              │              │
                    └──────────────┼──────────────┘
                                   │
                                   ▼
                           [Response Handler]
                                   │
                                   ▼
                           发送到用户渠道

六、目录结构速查表

/usr/lib/node_modules/clawdbot/dist/
│
├── gateway/          # 🚪 网关层 - 系统入口
│   ├── server.impl.js       # 网关服务器主实现
│   ├── server-chat.js       # 聊天处理
│   ├── server-channels.js   # 渠道管理
│   └── session-utils.js     # 会话工具
│
├── agents/           # 🧠 智能体层 - AI 交互
│   ├── system-prompt.js     # 系统提示词构建
│   ├── pi-embedded-subscribe.js  # AI 响应订阅
│   ├── pi-tools.js          # 工具定义
│   ├── bash-tools.exec.js   # exec 工具实现
│   └── subagent-registry.js # 子 Agent 管理
│
├── channels/         # 📱 渠道层 - 消息入口
│   └── plugins/
│       ├── telegram.js      # Telegram 插件
│       ├── discord.js       # Discord 插件
│       └── ...
│
├── telegram/         # Telegram 专用模块
│   ├── bot.js              # Bot 创建
│   ├── bot-handlers.js     # 消息处理器
│   └── send.js             # 消息发送
│
├── sessions/         # 📋 会话管理
│   └── session-key-utils.js
│
├── routing/          # 路由逻辑
│   └── session-key.js      # Session Key 构建
│
├── config/           # ⚙️ 配置管理
│   └── config.js
│
├── cli/              # 命令行界面
│   └── program/
│
├── cron/             # ⏰ 定时任务
│
└── skills/           # 🎯 技能系统

七、总结

Clawdbot 的架构可以用一句话概括：

> 「多入口、单核心、多工具」

• 多入口：支持 Telegram、Discord、Signal 等多种消息渠道
• 单核心：所有消息都通过 Gateway 路由到 Agent 处理
• 多工具：AI 可以调用各种工具（执行命令、读写文件、搜索网页等）来完成任务

这种架构的优点是：

1. 易扩展：新增一个渠道只需要写一个 Channel 插件

2. 统一管理：所有对话都通过 Session 统一管理

3. 能力丰富：通过 Tools 系统，AI 几乎可以做任何事

4. 安全可控：工具调用有策略控制，敏感操作需要审批

报告生成时间：2026-01-28