OpenClaw概述

作者：CSDN博客
前言

OpenClaw 是一个通过Gateway，连接即时通讯平台（Channel, 如 Telegram、Discord、Slack 等）与本地AI Agent ，能24×7 运行的个人助手。它不仅仅是一个简单的消息转发器，而是一个具备完整会话管理、并发控制、记忆检索以及丰富工具支持的复杂 Agent 运行时环境。

个人评价：OpenClaw的完成度非常高，尽管因为各种安全问题被质疑，但其产品思想和围绕这个核心思想设计的各种代码组件和交互，值得开发者反复学习。

整体架构概览

从架构上来看，你可以把 openClaw 想象成一间智能平台，有五个重要功能区：

Gateway（大门）：管理会话、路由请求、做鉴权。它通常在本地运行，默认将控制面板绑定到 loopback（只允许本机访问），并支持通过 Tailscale 等私有网络扩展远程访问。Agent（大脑）：有专门的人设，负责理解上下文意图、制定分步计划、决定要调用哪些工具或技能。Skills（工具箱）：一组插件/技能（以 Markdown 与脚本描述），让 Agent 可以“开门、倒咖啡、发邮件、跑脚本”。Channels（通道）：连接 各种app，如WhatsApp、Telegram、Discord、Slack、SMS 等，让 AI 与用户的日常通信无缝对接。Nodes（传感器/终端）：运行在用户端设备（手机、笔记本、Raspberry Pi，台式机）的小智能体，可以提供摄像头、地理位置或系统通知等本地能力。

这样的分层设计方式让 openClaw 既能快速扩展社区技能skill和mcp等，也能够在不同设备间弹性部署和执行任务。
Gateway 组件：中央控制平面

Gateway 是openclawd系统的核心枢纽——负责长期运行的守护进程，负责管理所有消息通道并作为 WebSocket 控制平面。openClaw支持多 Agent 创建和运行。一个 Gateway 可以托管多个独立的 Agent。
Gateway 主要做三件事：

接收消息：从各个渠道收集用户指令路由分发：决定这条消息应该交给哪个 Agent 处理回复投递：把 Agent 的回复发送回对应的渠道

Agent：推理引擎

Agent在接收到消息与任务后，动用自己的脑袋（LLM/大模型）、手脚（Tools）、专业知识（Skills），尽可能的完成任务，其中可能会访问Web、运行命令、读写文件、编写代码，甚至调用其他Nodes能力（比如摄像头）。
openClaw 的核心运行的核心是Agent Loop。Agent Loop 的核心是一个 “思考-行动”循环：

提问 → 思考 → 规划 → 行动 → 观察 → 思考 → 行动 → 等待 → 检查 → 纠错 … → 完成

LLM 负责”思考”（决定做什么），Tools 负责”行动”（执行操作），执行结果作为”观察”反馈给 LLM，然后继续下一轮循环

Agent的四个核心阶段

阶段 1：上下文组装（Context Assembly）,Agent 需要告诉 LLM “你是谁、你能做什么、你有什么工具，用户说了什么”。这包括：

系统提示：Agent 的身份、规则、工具列表会话历史：之前的对话记录或者记忆Bootstrap 文件：AGENTS.md、SOUL.md、TOOLS.md 等工作区文件openClawd 会把这些文本内容拼接成一个完整的 Prompt，然后发送给 LLM。

阶段 2：模型推理（Model Inference）,LLM 收到 Prompt 后，思考决定下一步行动。它可能：

直接回复用户文字生成调用一个工具（Tool Call）的代码其他，如请求更多信息

阶段 3：工具执行（Tool Execution）,如果 LLM 决定调用工具，Agent 会：

解析 Tool Call 参数执行对应的工具（exec、read、write、browser…）把执行结果（状态、内容)返回给 LLM

阶段 4：回复分发（Reply Dispatch）,当 LLM 生成最终回复后，Agent 会：

格式化回复内容，变成用户语言通过 Gateway 发送回对应的消息渠道支持流式输出（边生成边发送）

OpenClaw支持多Agent模式，可以互不干扰，也可以相互协作。每个Agent有自己的工作区，放置专属配置与记忆，甚至自己的技能。其内核Pi Agent 是一个精简高效的编程智能体，核心特点包括：

Agent Loop（智能体循环）：处理用户消息、执行工具调用、将结果反馈给 LLM，循环直到模型生成无工具调用的响应事件驱动架构：循环过程发射生命周期事件，支持响应式 UI消息队列：支持两种模式（逐条处理或批量处理）工具流式传输：支持块流式传输和增量流式传输，实现实时输出

• 核心工具仅用如下 4 个，即可实现有效智能体：
  bash - 执行 shell 命令read - 读取文件内容write - 写入文件内容edit - 编辑文本文件
  
  系统提示词也极为精简，仅约 1000 tokens（包含工具定义），大模型可以理解编程智能体上下文。
  

多 LLM 提供商支持

openClaw 内置 pi-ai 目录，支持多种提供商：

1. // Anthropic Claude{"agent":{"model":"anthropic/claude-opus-4-5"}}// GLM zai{"agent":{"model":"zai/GLM-4.7"}}// Ollama 本地模型{"models":{"providers":{"ollama":{"baseUrl":"http://127.0.0.1:11434/v1"}}}}// LM Studio 本地{"models":{"providers":{"lmstudio":{"baseUrl":"http://localhost:1234/v1","apiKey":"LMSTUDIO_KEY","api":"openai-completions","models":[{"id":"minimax-m2.1-gs32","name":"MiniMax M2.1","contextWindow":200000},{...}]},"openai":{...}}}}

复制代码

模型选择使用 provider/model 格式（如 zai/GLM系列），Agent中可绑定支持模型，并可以故障转移。
Channels 系统：多平台消息集成

Channels 负责连接各消息平台到中央 Gateway。根据配置与不同的渠道（比如飞书）建立安全链接，完成消息收发（通常是WebSocket 协议）以及格式转换 — 即翻译成 Clawdbot 能听懂的格式。

Channel	协议/库	特性
WhatsApp	Baileys（WhatsApp Web 协议）	QR 登录、媒体支持、群组提及网关
Telegram	grammY（Bot API）	流式传输、Webhook 支持
Discord	discord.js	原生命令、DM 策略
Slack	Bolt	DM 配对策略、频道白名单
Signal	signal-cli	需本地安装 signal-cli
iMessage	imsg CLI	仅 macOS
Google	Chat Chat API	扩展渠道
Matrix、Teams	扩展插件	社区支持

WhatsApp 配置示例：

1. {"channels":{"whatsapp":{"allowFrom":["+15555550123"],"groups":{"*":{"requireMention":true}}}},"messages":{"groupChat":{"mentionPatterns":["@clawd"]}}}

复制代码

Nodes 系统：移动/桌面扩展

Nodes 就是在主机之外的其他“能力”节点，连接到 Gateway 的子设备（iOS、Android、macOS），提供设备本地功能：
旧手机、闲置电脑都可以作为 Node 加入网络，以提供更多的能力，比如摄像头、屏幕录制、系统控制、屏幕共享、显示可交互式的UI界面等。Nodes 需要在远程设备上运行相应的Node 客户端 App。Node 支持的类型：

平台	功能
iOS Node	Canvas、语音唤醒、摄像头拍照/录像、屏幕录制、语音触发
Android Node	Canvas、语音交互、摄像头、屏幕截图、短信集成（可选）
macOS Node	system.run（执行命令）、system.notify（通知）、Canvas/摄像头

这实现了"远程大脑，本地双手"的架构——Gateway 可运行在远程 Linux 实例，而 Nodes 通过 Tailscale 连接，执行操作运行在设备本地。
Plugins 体系

plugin 是 OpenClaw 的扩展包，它提供了

tool（给模型调用的函数能力）skill（给模型的指令/流程知识）hook（事件触发逻辑）channel/provider（渠道或模型提供方接入）CLI 命令、gateway 方法、后台服务 等

安装方式主要有两种

从 npm 安装：openclaw-cli plugins install <npm包名>从本地路径安装：openclaw-cli plugins install <容器内可见路径>

1. ## openclaw文件
2. {"plugins":{
3.     ## 允许加载的插件白名单
4.     "allow":["demo-tool","wa_message_enable"],
5.     ## 允许加载的黑名单（优先级高于白名单）
6.     "deny":[]
7.     ## 加载extensions目录以外的目录
8.     "load":{"paths":[
9.         ## 这个可以省略不写
10.         "/home/node/.openclaw/extensions/wa_message_enable"]},
11.     ## 各插件运行配置
12.     "entries":{"demo-tool":{"enabled":true},"wa_message_enable":{"enabled":true,"config":{"allowDirect":true,"allowGroup":false}}},
13.     ## 它主要给 openclaw plugins update 这类管理动作，告诉怎么更新插件
14.     ## 不想被管理的插件可以不写，如wa_message_enable
15.     "installs":{"demo-tool":{"source":"path","sourcePath":"/home/node/.openclaw/extensions/demo-tool","installPath":"/home/node/.openclaw/extensions/demo-tool","version":"0.0.1","installedAt":"2026-03-13T09:43:09.322Z"}}}}

复制代码

最小插件结构是：

1. my-plugin/
2.   ├─ openclaw.plugin.json  ## 插件的manifest
3.   └─ index.ts   ## 代码入口

复制代码

Tool

plugins tool 是“模型可调用的函数能力”，分成两大类

系统内置 tool自定义的 tool， 通过发现plugin，再使用registerTool方式注册 tool

内置tool主要目录

工具实现目录：src/agents/tools/工具总装配入口：src/agents/openclaw-tools.ts

openclaw的tool是通过插件的方式注入的，即在index.ts中调用registerTool进行注入

1. import{ Type } from "@sinclair/typebox";export default function register(api){
2.     api.registerTool({
3.       name: "my_tool",
4.       description: "最小示例工具",
5.       parameters: Type.Object({
6.         input: Type.String(),
7.       }),
8.       async execute(_toolCallId, params){return{
9.           content: [{ type: "text", text: params.input }],
10.         };},
11.     });}

复制代码

即my_tool是tool名字，openclaw.plugin.json里面记的是插件名

1. {"agents":{"list":[{"id":"main",
2.         "tools":{"deny":[## 禁用的tool"my_tool"## 这表表示 main这个agent禁用my_tool]}}]}}

复制代码

Hook

hook：系统事件触发的自动化监听器,适合审计、落盘、转发、启动任务这类逻辑.同tool一样可以通过插件registerHook方法注入

1. importtype{ OpenClawPluginApi } from "openclaw/plugin-sdk";export default function register(api: OpenClawPluginApi){
2.     api.registerHook("command:new",
3.       async (event)=>{
4.         event.messages.push("hook-demo 已触发");
5.         api.logger.info(`hook-demo fired: ${event.sessionKey}`);},
6.       {
7.         name: "hook-demo.command-new",
8.         description: "在 /new 时触发",
9.       },
10.     );}

复制代码

通这独立的标识去启用hooks机制

1. {
2.     hooks: {
3.       internal: {
4.         enabled: true## 启用hook机制"hook-demo":{## 启用hook-demo"enabled":true}}},
5.     plugins: {
6.       entries: {"hook-demo":{
7.           enabled: true}}}}

复制代码

在 OpenClaw 里又给了hook一套独立子系统：有自己的发现规则、目录结构、元数据、启停方式；
[code]my-hook/
  ├─ HOOK.md
  └─ handler.js


  - HOOK.md
  
  ---
  name: my-hook
  description: "在 /new 时回一条提示"
  metadata:
    {"openclaw":{"emoji":"