【笔记】OpenClaw 架构浅析

一篇面向开发者的 OpenClaw 技术浅析

目标读者：有一定技术基础，想了解 AI Agent 架构设计的开发者

1. OpenClaw 是什么

1.1 官方定义

bash 复制代码

OpenClaw = 开源、可自托管的 AI 智能体平台
          (Open-source, Self-hostable AI Agent Platform)

Slogan: "The AI that actually does things"
        (真正能做事的 AI)

1.2 核心特性

特性	说明
本地运行	数据不出本地，隐私安全
多渠道接入	支持 WhatsApp、Telegram、Slack、Discord、飞书等
3000+ 技能	内置丰富的自动化技能插件
工具调用	能执行文件操作、浏览器控制、Shell 命令等
多模型支持	支持 Claude、GPT、本地模型及中国模型（DeepSeek、GLM 等）

1.3 与传统 Chatbot 的本质区别

yaml 复制代码

传统 Chatbot:
  用户 → 聊天 → 返回文本 → 结束
  ❌ 只能被动回答
  ❌ 无法执行操作
  ❌ 无状态对话


OpenClaw AI Agent:
  用户 → 理解意图 → 规划任务 → 调用工具 → 执行操作 → 反馈结果
  ✅ 主动执行任务
  ✅ 操作真实系统
  ✅ 维护会话状态

2. 为什么需要 OpenClaw

2.1 解决的问题

问题一：AI 只会聊天，不会做事

makefile 复制代码

场景: 你想让 AI 帮你创建一个 React 项目

传统 ChatGPT:
  你: "帮我创建一个 React 项目"
  AI: "好的，你可以运行 npx create-react-app myapp..."

OpenClaw:
  你: "帮我创建一个 React 项目"
  AI: [直接执行命令]
      > npx create-react-app myapp
      > cd myapp
      > npm install
      ✅ 项目已创建完成，可以直接运行

问题二：多个聊天工具，来回切换很麻烦

markdown 复制代码

OpenClaw 统一接入:
  ┌────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │WhatsApp│  │ Telegram │  │  Slack   │  │ Discord  │
  └────┬───┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
       └───────────┼─────────────┼─────────────┘
                   ↓
            ┌─────────────────┐
            │  OpenClaw       │
            │  统一 AI 助手    │
            └─────────────────┘

问题三：隐私和安全顾虑

对比项	云端 AI 服务	OpenClaw 本地运行
数据流程	对话内容 → 上传云端 → AI 处理 → 返回结果	对话内容 → 本地 AI 处理 → 本地执行
隐私保护	⚠️ 数据可能被用于训练 ⚠️ 敏感信息泄露风险	✅ 数据完全在本地 ✅ 可以使用本地模型（Ollama）

2.2 适用场景

场景	OpenClaw 如何帮助
办公自动化	自动处理邮件、日历、文档
开发辅助	代码生成、调试、Git 操作
系统管理	服务器监控、日志分析
学习辅助	问答解释、资料整理
个人助理	提醒、搜索、信息汇总

3. 核心架构设计

3.1 整体架构图

3.2 Gateway（网关）的核心职责

Gateway 是 OpenClaw 的"中枢神经"，负责协调所有组件，主要职责包括四个层面：

1️⃣ 消息接入层（作为"门"）

接收各平台的用户消息（WhatsApp、Telegram、Slack、Discord 等）
转换为统一的消息格式
验证用户身份和权限

2️⃣ 智能调度层（作为"大脑"）

选择合适的 AI 模型
决定调用哪些工具
协调多 Agent 协作

3️⃣ 执行协调层（作为"指挥官"）

调用 pi-mono 执行工具
管理技能插件
监控执行状态

4️⃣ 状态管理层（作为"记忆库"）

保存对话历史
维护会话状态
本地向量数据库（RAG 检索）

3.3 数据流向图

4. 技术栈深度分析

4.1 整体技术栈

4.2 pi-mono 核心包详解

pi-ai: LLM 抽象层

pi-ai 提供统一的 LLM 调用接口，支持 20+ 模型供应商，核心能力包括：

支持的模型供应商：

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude 3.5 Sonnet)
Google (Gemini)
AWS Bedrock
DeepSeek (通过兼容 API)
GLM/智谱 (通过兼容 API)
MiniMax (原生支持)
Ollama (本地模型)

核心功能：

统一的消息格式
Tool/Function Calling 支持
流式输出
跨供应商上下文切换
成本和 Token 统计

代码示例：pi-ai 基础用法

typescript 复制代码

import { getModel, stream, Context, Tool, Type } from '@mariozechner/pi-ai';

// 1. 选择模型
const model = getModel('anthropic', 'claude-sonnet-4-5');

// 2. 定义工具
const tools: Tool[] = [{
  name: 'get_time',
  description: '获取当前时间',
  parameters: Type.Object({
    timezone: Type.Optional(Type.String())
  })
}];

// 3. 构建对话上下文
const context: Context = {
  systemPrompt: '你是一个有帮助的助手',
  messages: [{ role: 'user', content: '现在几点了？' }],
  tools
};

// 4. 流式调用
for await (const event of stream(model, context)) {
  switch (event.type) {
    case 'text_delta':
      process.stdout.write(event.delta);  // 流式输出
      break;
    case 'toolcall_end':
      console.log('调用了工具:', event.toolCall.name);
      break;
  }
}

pi-agent-core: Agent 核心

pi-agent-core 是 Agent 执行引擎，核心职责包括：

核心职责：

工具注册和执行
事件流管理
错误处理和重试
会话状态管理

内置工具：

Read - 读取文件（支持图片）
Write - 创建/覆盖文件
Edit - 精确文本替换
Bash - 执行 Shell 命令

pi-coding-agent: CLI 工具

pi-coding-agent 提供命令行交互界面：

功能：

会话管理（新建/恢复/分支）
模型切换
主题支持
上下文文件加载
快捷键支持

扩展机制：

Skills - 可复用的技能包
Extensions - 自定义扩展
Prompts - 提示词模板
Themes - 主题样式

4.3 为什么选择 TypeScript/Node.js

优势	说明
生态丰富	npm 有 200万+ 包，任何功能都能找到现成库
异步 I/O	事件驱动，适合处理大量并发消息
JSON 原生支持	与 AI API 交互非常方便
跨平台	一套代码跑 Windows/Mac/Linux
开发效率高	类型安全 + 热重载，开发体验好
社区活跃	遇到问题容易找到解决方案

5. 运行原理详解

5.1 Agent 循环（Agentic Loop）

这是 AI Agent 的核心运行机制：

typescript 复制代码

// 伪代码：Agent 循环
async function agenticLoop(userMessage: string) {
  let context = loadUserSession();  // 加载用户会话历史

  while (true) {
    // 步骤 1: 调用 AI
    const response = await callAI(context);

    // 步骤 2: 检查是否需要调用工具
    if (response.stopReason === 'tool_use') {
      for (const toolCall of response.toolCalls) {
        // 步骤 3: 执行工具
        const result = await executeTool(toolCall);

        // 步骤 4: 将结果添加到上下文
        context.messages.push({
          role: 'assistant',
          content: response.content
        });
        context.messages.push({
          role: 'user',
          content: [{
            type: 'tool_result',
            tool_use_id: toolCall.id,
            content: result
          }]
        });
      }
      // 继续循环，让 AI 分析工具执行结果
    } else {
      // 步骤 5: 没有更多工具调用，返回最终答案
      saveUserSession(context);
      return response.content;
    }
  }
}

5.2 实际运行示例

示例：创建目录

arduino 复制代码

用户: "帮我创建一个名为 hello-world 的目录"

第 1 轮: AI 理解意图
  └─ 调用 bash: "mkdir hello-world"
      └─ ✅ 成功

第 2 轮: AI 分析结果
  └─ 返回: "已成功创建 hello-world 目录"

5.3 多轮工具调用示例

示例：创建并启动 React 项目

arduino 复制代码

用户: "帮我创建一个 React 项目并启动开发服务器"

第 1 轮 → 调用 bash: "npx create-react-app myapp"
第 2 轮 → 调用 bash: "cd myapp && npm install" → ✅ 成功
第 3 轮 → 调用 bash: "cd myapp && npm start" → ✅ 已启动
第 4 轮 → 返回: "React 项目已创建并启动，访问 http://localhost:3000"

6. 依赖关系解析

6.1 核心依赖图

erlang 复制代码

openclaw (主项目)
    │
    ├── @mariozechner/pi-coding-agent
    │       │
    │       ├── @mariozechner/pi-agent-core
    │       │       │
    │       │       └── @mariozechner/pi-ai
    │       │               │
    │       │               ├── @anthropic-ai/sdk (Claude)
    │       │               ├── openai (GPT)
    │       │               ├── @google/genai (Gemini)
    │       │               ├── @aws-sdk/client-bedrock (AWS)
    │       │               └── undici (HTTP 客户端)
    │       │
    │       └── @mariozechner/pi-tui
    │               │
    │               └── @silvia-odwyer/photon-node (Rust+Wasm)
    │
    ├── @slack/bolt (Slack 接入)
    ├── grammy (Telegram 接入)
    ├── @whiskeysockets/baileys (WhatsApp 接入)
    ├── discord-api-types (Discord 接入)
    │
    ├── @lydell/node-pty (伪终端)
    ├── playwright-core (浏览器)
    ├── sharp (图片处理)
    └── pdfjs-dist (PDF 处理)

6.2 依赖类型分析

依赖类型	包名	用途	是否需要编译
核心引擎	@mariozechner/pi-*	Agent 核心能力	❌ 纯 TS
消息平台	@slack/bolt, grammy	多渠道接入	❌ 纯 JS
AI 模型	@anthropic-ai/sdk, openai	调用 AI API	❌ 纯 JS
浏览器	playwright-core	浏览器自动化	❌ 纯 JS
图片处理	sharp	C++ 原生模块	⚠️ 需要编译
图片处理	@silvia-odwyer/photon-node	Rust+Wasm	✅ 预编译
终端	@lydell/node-pty	C++ 原生模块	⚠️ 需要编译

注意 : photon-node 使用 WebAssembly，不需要用户端编译，是更现代化的方案。

7. 快速开始

7.1 安装

bash 复制代码

# 克隆项目
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

# 启动 Gateway
npm run gateway:start

7.2 配置 AI 模型

bash 复制代码

# 方式一：使用 API Key
export ANTHROPIC_API_KEY=sk-ant-xxx
export OPENAI_API_KEY=sk-xxx

# 方式二：使用订阅登录
npm run login
# 选择 Anthropic Claude Pro/Max

7.3 连接消息平台

bash 复制代码

# 配置 Slack
npm run config:slack

# 配置 Telegram
npm run config:telegram

# 配置 Discord
npm run config:discord

7.4 开始使用

bash 复制代码

# 启动 OpenClaw
npm start

# 在配置的消息平台中发送消息：
# "帮我查看当前目录的文件"
# "创建一个名为 test.txt 的文件，内容是 Hello World"
# "分析这个项目的 package.json"

8. 总结

8.1 OpenClaw 的核心价值

OpenClaw 的核心价值体现在四个方面：

1️⃣ 从"聊天"到"做事"

传统 AI 只能回答问题
OpenClaw 能执行实际操作

2️⃣ 从"单一渠道"到"全平台统一"

一个 AI 助手，覆盖所有聊天平台

3️⃣ 从"云端"到"本地可控"

数据隐私安全，完全可控

4️⃣ 从"固定功能"到"可扩展插件"

3000+ 技能插件，无限可能

8.2 架构设计的关键启示

设计原则	OpenClaw 的实现	启示
分层架构	Gateway → Engine → Execution	职责清晰，易于扩展
抽象统一	pi-ai 统一多个 LLM API	切换模型无需改代码
工具化	一切皆工具（Read/Write/Edit/Bash）	简单而强大
可扩展	Skills/Extensions 机制	用户可以自定义功能
本地优先	数据存储在本地，支持本地模型	隐私安全，离线可用

8.3 学习路径建议

第一步：理解基础
- 什么是 AI Agent？
- Tool Use / Function Calling 是什么？
- Agent 循环如何工作？
第二步：深入架构
- Gateway 的设计理念
- pi-mono 的模块化设计
- 消息流和执行流
第三步：动手实践
- 安装运行 OpenClaw
- 配置自己的 AI 模型
- 创建自定义技能
第四步：进阶探索
- 阅读源码
- 开发自己的 Extension
- 参考其他实现（ZeroClaw/PicoClaw）

8.4 下一步

读完本文后，你可以：

实际使用：安装 OpenClaw，体验 AI Agent 的能力
阅读源码：深入理解实现细节
参考对比：阅读《xxxClaw 版本对比浅析》，了解不同技术栈的选择
动手实现：构建自己的轻量版 AI Agent

参考资料

作者注: 本文基于 2026 年 2 月的 OpenClaw 架构编写，如有更新请以官方文档为准。

最后更新: 2026-02-28

文章使用了 GLM 5.0 润色

版权声明：

本文版权属于作者林小帅，未经授权不得转载及二次修改。

转载或合作请在下方留言及联系方式。