02 - 技术原理核心

OpenClaw 架构解析

核心组件

OpenClaw 采用网关架构（Gateway Architecture），核心是一个持续运行的 Node.js 进程，协调各个子系统之间的交互。

graph TB
    A[用户消息] --> B[Channel Adapter]
    B --> C[Gateway Core]
    C --> D[LLM Router]
    D --> E[Claude/GPT/本地模型]
    E --> F[Tool Executor]
    F --> G[文件系统/Shell/浏览器]
    C --> H[Memory Manager]
    H --> I[Markdown 存储]
    C --> J[Control UI]
    J --> K[Web Dashboard :18789]

1. Gateway Core（网关核心）

Gateway 是 OpenClaw 的中央协调器，负责：

• 会话管理：维护用户会话状态，支持多用户、多平台同时交互
• 消息路由：将来自不同渠道的消息路由到适当的处理流程
• 工具调用：解析 LLM 返回的工具调用指令并执行
• 心跳调度：默认每 30 分钟执行一次自检任务（checklist）

Gateway 以守护进程形式运行（Linux 使用 systemd，macOS 使用 LaunchAgent），确保 24/7 在线。

2. Channel Adapter（渠道适配器）

OpenClaw 支持多种通讯渠道，每种渠道有专门的适配器：

Telegram 适配器使用 grammY 框架，支持：

• Webhook 模式：实时接收消息，延迟 < 100ms
• 长轮询模式：适用于无公网 IP 的环境
• 富媒体处理：图片、文档、音频、视频
• 交互式组件：按钮、内联键盘、命令菜单

3. Memory Manager（记忆管理器）

OpenClaw 的记忆系统是其区别于普通聊天机器人的核心特性：

• 持久化存储：所有记忆以 Markdown 文件存储在 ~/.openclaw/ 目录
• 层级结构：
  • workspace/ - 用户工作空间，可自定义
  • memory/ - 长期记忆（用户偏好、项目背景）
  • sessions/ - 会话历史（按日期组织）
  • skills/ - 已安装的 Skill 定义
• 全文检索：使用 grep 或 ripgrep 快速搜索历史记录
• 版本控制友好：纯文本格式，可用 Git 管理

4. Skill System（技能系统）

Skills 是 OpenClaw 的能力扩展单元，每个 Skill 是一个 SKILL.md 文件，包含：

---
name: example-skill
description: 示例技能说明
author: your-name
version: 1.0.0
---

# Example Skill

## 可用工具
- read_file: 读取文件内容
- write_file: 写入文件内容
- execute_command: 执行 Shell 命令

## 使用示例
用户: "读取我的 todo.txt 文件"
Agent: 调用 read_file 工具，路径为 ~/todo.txt

Skill 可以从多个来源安装：

• ClawHub：官方技能市场，3000+ 社区贡献
• GitHub 仓库：直接安装远程仓库中的 Skill
• 本地文件：手动创建和编辑

技术栈

OpenClaw 的技术选型体现了现代 Node.js 生态的最佳实践：

自举机制原理

什么是自举（Bootstrapping）？

在计算机科学中，自举指系统能够使用自身来改进或扩展自身的能力。对于 AI Agent，自举包含三个层次：

1. 元认知层：Agent 能够分析自身行为、识别改进点
2. 代码生成层：Agent 能够生成改进自身的代码
3. 执行验证层：Agent 能够安全地测试和应用改进

OpenClaw 的自举路径

路径一：Skill 自进化（推荐）

这是最安全的自举方式，Agent 通过编写新的 Skill 文件来扩展能力：

用户请求 → LLM 分析需求 → 生成 SKILL.md → 保存到 skills/ → 激活新能力

技术实现：

1. 需求分析：LLM 分析用户请求，判断是否需要新 Skill
2. Skill 生成：生成符合规范的 SKILL.md 文件
3. 工具定义：在 Skill 中声明需要的工具（如 write_file、execute_command）
4. 自动注册：保存到 ~/.openclaw/skills/ 后自动生效
5. 版本控制：通过 Git 管理 Skill 版本，支持回滚

示例场景：

用户："帮我创建一个能自动整理下载文件夹的 Skill"
Agent 分析需求 → 生成 organize-downloads Skill → 包含文件分类逻辑
→ 保存到 skills/organize-downloads/SKILL.md → 立即可用

路径二：配置自优化

Agent 分析使用模式，自动调整系统配置：

使用数据分析 → 识别低效模式 → 生成配置调整 → 应用到 settings.json

可优化的配置项包括：

• 模型选择：根据任务复杂度自动切换 Claude/GPT/本地模型
• 心跳频率：根据活跃时段调整 checklist 执行间隔
• 内存清理：自动归档旧会话，优化存储空间
• 工具权限：根据使用频率动态调整可用工具集

路径三：代码自修改（高风险）

这是最高级的自举形式，Agent 直接修改自身源代码。需要严格的安全沙箱：

改进需求 → 生成代码补丁 → 沙箱测试 → 代码审查 → 应用更新

安全机制：

1. 容器隔离：在 Docker 容器中测试修改后的代码
2. Git 分支：所有修改在独立分支进行，不影响主分支
3. 自动化测试：修改后自动运行测试套件
4. 人工审核：关键修改需要人工确认后才合并

递归自改进的理论基础

OpenClaw 的自举能力与学术界的**递归自改进（RSI）**研究密切相关：

Gödel Agent 框架

来自论文《Gödel Agent: A Self-Referential Agent Framework for Recursive Self-Improvement》，核心思想是：

Agent 将自身代码作为环境的一部分，通过元认知能力识别改进机会，生成更优的实现并替换旧代码。

关键技术：

• 自指（Self-Referential）：Agent 能够读取和分析自身代码
• 证明导向优化：不仅生成代码，还能证明新代码优于旧代码
• 安全约束：所有自修改必须在安全沙箱内验证

Darwin Gödel Machine

Sakana AI 的研究项目，实现了基于进化算法的代码自改进：

通过多轮迭代，AI 系统生成、测试、选择更优的代码版本，类似于生物进化。

核心机制：

1. 变异（Mutation）：对现有代码进行随机修改
2. 评估（Evaluation）：测试修改后代码的性能
3. 选择（Selection）：保留表现更好的代码版本
4. 遗传（Inheritance）：将优秀代码传递给下一代

STOP (Self-Taught Optimizer)

论文《Self-Taught Optimizer: Recursively Self-Improving Code Generation》提出：

从一个简单的种子程序开始，AI 逐步生成更优的代码优化器，形成递归改进循环。

适用于 OpenClaw 的场景：

• 优化 Skill 生成流程
• 改进工具调用效率
• 优化提示词工程

Telegram 集成技术

Telegram Bot API 架构

Telegram Bot 通过 HTTP 接口与 Telegram 服务器通信：

OpenClaw Gateway → HTTP POST → Telegram API Server → Telegram 服务器 → 用户客户端

两种通信模式：

模式一：长轮询（Long Polling）

// 持续请求 getUpdates，有新消息时立即返回
while (true) {
  const updates = await bot.api.getUpdates({ offset: lastUpdateId + 1 });
  for (const update of updates) {
    processUpdate(update); // 处理消息
  }
}

优点：

• 无需公网 IP 和域名
• 实现简单，适合开发和测试
• 不依赖 webhook 服务器稳定性

缺点：

• 延迟较高（取决于轮询间隔）
• 资源消耗较大（持续 HTTP 请求）

模式二：Webhook（推荐）

// 设置 webhook URL，Telegram 主动推送消息
await bot.api.setWebhook({ 
  url: 'https://your-domain.com/webhook',
  allowed_updates: ['message', 'callback_query']
});

// Fastify 路由处理 webhook 请求
fastify.post('/webhook', async (request, reply) => {
  const update = request.body;
  await processUpdate(update);
  return { ok: true };
});

优点：

• 实时推送，延迟 < 100ms
• 资源效率高（按需响应）
• 支持更多功能（如内联查询）

缺点：

• 需要 HTTPS 公网地址
• 需要配置 webhook 服务器

OpenClaw 的 Telegram 集成

OpenClaw 的 Telegram 适配器封装了上述复杂性，提供简洁的 CLI 命令：

# 添加 Telegram 渠道
openclaw channel add telegram

# 交互式配置：输入 Bot Token、选择模式（webhook/polling）
# 自动完成 webhook 设置（如果使用 webhook 模式）

配置存储：

Telegram 配置存储在 ~/.openclaw/openclaw.json：

{
  "channels": {
    "telegram": {
      "bot_token": "YOUR_BOT_TOKEN",
      "mode": "webhook",
      "webhook_url": "https://your-domain.com/webhook/telegram",
      "allowed_updates": ["message", "edited_message", "callback_query"]
    }
  }
}

环境变量方式（推荐用于生产）：

export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_WEBHOOK_URL="https://your-domain.com/webhook"

消息类型与处理

Telegram Bot API 支持丰富的消息类型：

自举与 Telegram 同步结合

将自举能力与 Telegram 集成，可以构建双向实时同步系统：

场景一：更新通知

当 OpenClaw 完成自举迭代（如生成了新 Skill），自动向 Telegram 推送通知：

// 自举完成后触发
async function onSelfBootstrapComplete(skillName, changes) {
  const message = `✅ 自举迭代完成\n\n` +
    `新增 Skill: ${skillName}\n` +
    `改进内容: ${changes.summary}\n` +
    `版本: ${changes.version}`;
  
  await telegramBot.api.sendMessage({
    chat_id: ADMIN_CHAT_ID,
    text: message,
    parse_mode: 'Markdown'
  });
}

场景二：远程触发自举

通过 Telegram 消息远程触发自举流程：

用户 Telegram 消息: "/bootstrap 优化文件搜索性能"

Agent 解析命令 → 进入自举模式 → 分析当前搜索实现
→ 生成优化方案 → 创建新 Skill → 测试验证
→ 推送结果到 Telegram

场景三：人工审核工作流

对于高风险自举操作（如修改核心代码），通过 Telegram 实现人工确认：

// 发送确认请求
const confirmMessage = await telegramBot.api.sendMessage({
  chat_id: ADMIN_CHAT_ID,
  text: '⚠️ 检测到代码自修改请求\n\n修改内容: ...',
  reply_markup: {
    inline_keyboard: [[
      { text: '✅ 确认应用', callback_data: 'approve' },
      { text: '❌ 拒绝', callback_data: 'reject' }
    ]]
  }
});

// 等待用户点击按钮
bot.on('callback_query', async (ctx) => {
  if (ctx.callbackQuery.data === 'approve') {
    await applyCodeChanges();
  }
});

参考资料

• OpenClaw Architecture Docs - 官方架构文档
• Telegram Bot API Documentation - Telegram Bot API 官方文档
• Gödel Agent Paper - 递归自改进代理框架
• Darwin Gödel Machine - Sakana AI 的自举研究
• STOP Paper - 递归自改进代码生成
• OpenClaw and RSI Analysis - OpenClaw 与 RSI 分析