【GitHub】OpenClaw：开源个人AI助手的新标杆一、项目概述 OpenClaw（官网：https://open

一、项目概述

OpenClaw（官网：openclaw.ai）是一个功能强大的开源个人AI助手项目，其Slogan为"Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞"。截至目前，该项目在GitHub上已获得超过 367,000 Stars，成为全球排名第6的热门开源项目，Fork数超过75,000，拥有来自全球2,000多位贡献者的参与。

1.1 项目诞生背景

在AI助手日益普及的今天，用户面临着诸多困境：数据隐私无法保障、服务依赖云端、AI助手与日常通讯工具割裂等。OpenClaw的出现正是为了解决这些痛点——它允许用户在自有设备上运行完整的AI助手系统，通过用户已经习惯的通讯渠道（如微信、WhatsApp、Telegram等）进行交互，真正实现数据自主、渠道统一、体验无缝的AI助手体验。

1.2 项目定位

OpenClaw的定位是自托管（Self-hosted）多渠道路由网关。它不是又一个AI聊天界面，而是一个完整的技术基础设施：

┌─────────────────────────────────────────────────────────────┐
│                      OpenClaw Gateway                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │ Discord │  │Telegram │  │WhatsApp │  │ Slack   │  ...  │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │             │
│  ┌────▼────────────▼────────────▼────────────▼────┐       │
│  │              统一消息路由层                      │       │
│  │         (Channel Router & Session Manager)       │       │
│  └─────────────────────┬───────────────────────────┘       │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────┐       │
│  │            AI Agent Runtime                      │       │
│  │     (多代理路由 · 工具系统 · 技能系统)          │       │
│  └─────────────────────┬───────────────────────────┘       │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────┐       │
│  │         Tools & Plugins System                  │       │
│  │  (浏览器 · 文件系统 · 媒体生成 · MCP扩展)      │       │
│  └────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────┘

1.3 核心数据一览

指标	数值	说明
GitHub Stars	367,000+	全球第6大热门项目
Forks	75,000+	社区参与度极高
贡献者	2,000+	活跃的开源社区
提交数	39,499	持续的代码迭代
支持渠道	20+	覆盖主流通讯平台
许可协议	MIT	完全开源免费

二、核心架构设计

2.1 Hub-and-Spoke架构

OpenClaw采用中心辐射型（Hub-and-Spoke）架构，以Gateway为核心枢纽，所有组件围绕其运转。这种设计的优势在于：

单一事实来源：Gateway作为中央控制平面，统一管理所有会话、配置和路由逻辑
单进程多渠道：一个Gateway实例可同时服务所有绑定的通讯渠道，无需为每个平台单独部署服务
易于扩展：新增渠道只需开发对应插件，无需改变核心架构

2.2 技术栈选择

组件	技术选型	选型理由
运行时	Node.js 22+ (推荐24)	高性能、广泛的生态系统
语言	TypeScript	类型安全、支持现代ES特性
包管理	pnpm workspaces	高效的monorepo管理
容器化	Docker	沙箱隔离、跨平台部署
通信协议	WebSocket RPC (v3)	实时双向通信

2.3 核心子系统

OpenClaw的代码库按功能划分为以下核心子系统：

openclaw/
├── apps/              # 应用程序入口
├── packages/          # 核心包
├── src/               # 源代码
│   ├── agents/        # 代理运行时
│   ├── config/        # 配置系统
│   ├── routing/       # 路由与会话
│   └── ...
├── extensions/       # 扩展插件
├── ui/               # 控制台界面
└── vendor/           # 第三方代码

三、核心概念详解

3.1 Gateway（网关）

Gateway是OpenClaw的中央控制平面，是一个Node.js服务器，协调所有客户端、渠道、代理和工具之间的通信。

主要职责：

职责	实现方式	说明
WebSocket RPC	Protocol v3 协议	处理实时双向通信
插件加载	动态加载扩展	支持运行时扩展
钩子执行	全局事件系统	拦截生命周期事件
能力注册	提供者能力管理	协调系统资源
多代理路由	映射到代理实例	实现智能路由

Gateway的核心价值在于它始终运行，作为系统的不变核心。即使UI客户端断开连接，Gateway也会保持运行，维护所有活跃会话的状态。

3.2 Agent（代理）

代理是一个隔离的运行时上下文，由代理核心执行管道驱动。它管理自己的工作空间、模型提供者和工具执行逻辑。

核心特性：

多代理隔离：不同的通道或发送者可以绑定到不同的代理实例
独立配置：每个代理可拥有独立的模型选择、系统提示和工具集
工作空间隔离：每个代理拥有独立的文件系统工作空间

配置层次结构：

{
  "agents": {
    "defaults": {          // 所有代理的共享设置
      "model": "openai/gpt-4o",
      "tools": { "allow": ["browser", "exec"] }
    },
    "list": [
      {
        "id": "coding-agent",      // 编程专用代理
        "model": "anthropic/claude-3-5-sonnet",
        "systemPrompt": "你是一个专业的编程助手..."
      },
      {
        "id": "research-agent",    // 研究专用代理
        "model": "openai/gpt-4-turbo"
      }
    ]
  }
}

3.3 Session（会话）

会话是对话状态边界，用于管理对话的上下文和状态。

会话范围模式：

模式	说明	使用场景
`main`	单个全局会话	单一用户环境
`per-peer`	按用户ID隔离	多用户共享网关
`per-channel-peer`	按渠道+用户双重隔离	完全隔离的对话体验

会话生命周期管理：

上下文压缩：当会话过大时自动压缩历史
自动修复：会话文件损坏时自动修复
持久化存储：JSONL格式转录本

3.4 Channel（通道）

通道是连接到网关的消息表面，每个通道作为插件实现，负责消息的发送和接收。

支持的通道类型：

内置渠道	捆绑插件	外部插件
Discord	Matrix	自定义开发
Telegram	Nostr
WhatsApp	Twitch
Slack	Zalo
Signal	Feishu
iMessage	LINE
Microsoft Teams	Mattermost
Google Chat	IRC
WeChat	QQ
WebChat	Nostalgia

3.5 Tools（工具）

工具是代理能力的核心机制，允许代理与主机系统或外部API交互。

工具分类：

类别	工具示例	功能描述
系统工具	`exec`, `bash`, `process`	shell命令执行、进程管理
浏览器工具	`browser`	CDP-based浏览器自动化
内存工具	`memory_search`	长期记忆搜索和更新
媒体工具	`image_gen`, `tts`	图像生成、语音合成
网络工具	`web_search`, `fetch`	网络搜索和内容获取
会话工具	`sessions_list`, `sessions_spawn`	会话管理和子代理创建

3.6 Skills（技能）

技能是模块化的能力定义，通常以markdown文件（SKILL.md）形式存在，教导代理如何使用工具组合完成特定任务。

技能存储位置：

捆绑技能：~/.openclaw/skills/<skill>/SKILL.md
插件技能：打包在插件目录中
覆盖技能：优先于捆绑技能生效

运行时注入：技能在每次运行时被解析并注入到系统提示中，实现动态能力扩展。

四、工具系统深度解析

4.1 工具执行流程

OpenClaw的工具系统采用管道式设计，确保每个工具调用都经过安全检查：

Agent决策 → 工具清单解析 → 策略过滤 → 模型适配 → 执行处理 → 结果处理

核心代码流程（简化）：

// 1. 清单解析：根据有效策略确定代理允许使用的工具
const allowedTools = resolveEffectiveToolPolicy(session, agentConfig);

// 2. 模式规范化：为特定模型提供商适配工具定义
const normalizedTools = normalizeToolSchemas(allowedTools, providerId);

// 3. 执行处理：路由到适当的内部处理程序
const result = await handleToolExecution(toolName, params, context);

// 4. 结果处理：捕获输出和媒体工件
const processedResult = processToolResult(result);

4.2 浏览器自动化

OpenClaw提供基于CDP（Chrome DevTools Protocol）的浏览器自动化能力：

核心功能：

页面导航：自动访问网页
元素交互：点击、输入、滚动
内容提取：获取页面文本、截图
表单处理：自动填充和提交

使用示例：

用户：帮我搜索GitHub上最热的AI项目
     ↓
Agent调用 browser.search("site:github.com trending AI projects")
     ↓
返回搜索结果列表
     ↓
Agent可进一步调用 browser.click() 访问详情页

4.3 执行批准机制

对于敏感的exec工具，OpenClaw提供批准状态机制：

// 工具执行请求（需要批准）
{
  tool: "exec",
  command: "rm -rf /tmp/build",
  requireApproval: true
}

// 等待用户通过CLI确认
// openclaw approve <approval-id>

// 或通过控制台UI批准

安全边界：

沙箱模式默认禁止exec工具
主会话可完全访问主机
批准状态确保用户知晓并同意危险操作

4.4 工具策略层级

工具访问受多层策略控制（拒绝优先原则）：

全局策略 → 代理级策略 → 配置文件级策略 → 组级策略

配置示例：

{
  "agents": {
    "defaults": {
      "tools": {
        "allow": ["browser", "read", "write"],
        "deny": ["exec"]  // 拒绝exec，即使在上面allow列表中
      }
    }
  },
  "sandbox": {
    "tools": {
      "allow": ["read", "web_search"]
    }
  }
}

五、插件架构详解

5.1 插件系统设计

OpenClaw采用模块化可扩展的插件架构，核心是PluginRegistry，支持多种扩展点：

扩展点	说明
消息渠道	新增通讯平台支持
模型提供商	AI推理引擎集成
工具	功能能力扩展
钩子	生命周期事件拦截
内存后端	持久化存储方案

5.2 插件类型

类型	说明	典型用例
`plain-capability`	纯功能型	新工具、新渠道
`hybrid-capability`	混合功能型	包含多个扩展点
`hook-only`	仅钩子型	事件处理、日志
`non-capability`	非功能型	配置辅助

5.3 渠道插件开发

开发一个新的消息渠道插件只需以下步骤：

// 1. 定义插件入口
import { defineChannelPluginEntry } from 'openclaw/plugin-sdk/channel-core';

export default defineChannelPluginEntry({
  id: 'my-custom-channel',
  label: 'My Custom Channel',
  
  // 2. 实现注册逻辑
  register(api) {
    api.registerChannel({
      id: 'my-channel',
      capabilities: ['send', 'receive', 'media'],
      
      // 3. 实现消息处理
      onMessage: async (message, context) => {
        // 处理收到的消息
        return context.sendToAgent(message);
      },
      
      // 4. 实现消息发送
      sendMessage: async (target, content) => {
        // 发送消息到目标用户
      }
    });
  }
});

5.4 插件发现机制

插件按以下优先级被发现和加载：

1. 显式配置路径 (plugins.load.paths)
2. 工作区扩展 (.openclaw/extensions/)
3. 全局扩展 (~/.openclaw/extensions/)
4. 内置插件 (OPENCLAW_BUNDLED_PLUGINS_DIR)

5.5 插件清单规范

每个插件需要包含openclaw.plugin.json清单文件：

{
  "id": "my-awesome-plugin",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": { "type": "string" }
    }
  },
  "kind": "channel",
  "contracts": {
    "capabilities": ["send", "receive"]
  }
}

六、安全模型与信任边界

6.1 信任模型设计

OpenClaw采用个人助手信任模型（Personal Assistant Trust Model），核心假设是：

每个Gateway实例有一个单一可信操作者边界
系统不适用于不可信用户共享网关的场景
认证后提供操作者级访问，网关内部无用户隔离

6.2 信任边界矩阵

边界	信任级别	说明
Gateway配置/状态	✅ 可信	能修改配置即控制网关
Gateway认证调用者	✅ 可信	认证提供操作者级权限
会话密钥	🔄 路由上下文	不是授权令牌，仅用于路由
通道消息	⚠️ 不可信	可能包含提示注入
插件/扩展	✅ 可信	在网关进程内运行
主机环境	⚠️ 部分不可信	子代理需环境清理

6.3 沙箱隔离机制

沙箱模式为非信任代理提供隔离执行环境：

{
  "sandbox": {
    "enabled": true,
    "backend": "docker",  // 或 "ssh", "openshell"
    "filesystem": {
      "mounts": ["/tmp/workspace"],
      "readonly": ["/usr/bin", "/lib"]
    },
    "network": {
      "isolated": true,
      "allowedHosts": ["api.openai.com"]
    },
    "tools": {
      "allow": ["read", "web_search"],
      "deny": ["exec", "browser", "nodes"]
    }
  }
}

隔离效果：

文件系统：仅能访问绑定挂载
网络：限制在Docker内部网络
工具：默认禁用所有敏感工具

6.4 密钥管理

OpenClaw的敏感配置支持SecretRef引用模式：

{
  "agent": {
    "model": "openai/gpt-4o",
    "authProfile": "my-openai-key"
  },
  "authProfiles": {
    "my-openai-key": {
      "provider": "openai",
      "credentials": {
        // 方式1：从环境变量加载
        "apiKey": { "from": "env", "var": "OPENAI_API_KEY" },
        // 方式2：从文件读取
        "token": { "from": "file", "path": "/secrets/token.txt" },
        // 方式3：执行命令获取
        "secret": { "from": "exec", "command": "security find-generic-password..." }
      }
    }
  }
}

6.5 安全审计

openclaw security audit命令自动检查配置风险：

检查项	说明
Gateway暴露检测	检查是否在无认证情况下暴露到互联网
浏览器控制检查	检查是否为不可信发送者启用浏览器自动化
文件系统权限	验证`~/.openclaw`和配置文件的权限
执行批准标志	标记`exec`工具设置为`ask="off"`的情况

七、安装与配置

7.1 安装方式

推荐安装（生产环境）：

# 使用npm
npm install -g openclaw@latest

# 或使用pnpm
pnpm add -g openclaw@latest

# 启动引导安装
openclaw onboard --install-daemon

从源码安装（开发环境）：

# 克隆仓库（必须使用pnpm）
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install

# 首次运行设置
pnpm openclaw setup

# 开发模式
pnpm gateway:watch

7.2 最小配置

~/.openclaw/openclaw.json：

{
  "agent": {
    "model": "openai/gpt-4o"
  }
}

7.3 完整配置示例

{
  "gateway": {
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  },
  
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": { "from": "env", "var": "TELEGRAM_BOT_TOKEN" },
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "whatsapp": {
      "enabled": true
    }
  },
  
  "agents": {
    "defaults": {
      "model": "openai/gpt-4o",
      "tools": {
        "allow": ["browser", "exec", "read", "write"]
      }
    },
    "list": [
      {
        "id": "coding",
        "model": "anthropic/claude-3-5-sonnet",
        "systemPrompt": "你是一个专业的编程助手..."
      }
    ]
  },
  
  "sandbox": {
    "enabled": true,
    "backend": "docker"
  }
}

7.4 快速使用

# 1. 安装守护进程
openclaw onboard --install-daemon

# 2. 启动Gateway
openclaw gateway --port 18789 --verbose

# 3. 打开控制台
openclaw dashboard

# 4. 发送消息
openclaw agent --message "帮我写一个Hello World"

# 5. 安全检查
openclaw security audit

八、使用场景与案例

8.1 个人AI助手

OpenClaw可以作为完全私密的个人AI助手：

┌────────────────────────────────────────────────────────┐
│  个人使用场景                                            │
│                                                        │
│  • 通过Telegram/WhatsApp与AI对话                      │
│  • 设置定时任务自动执行                                 │
│  • 浏览器自动化完成网页操作                             │
│  • 本地知识库问答                                      │
│  • 代码编写和调试助手                                  │
│                                                        │
│  优势：数据完全本地存储，无需担心隐私泄露               │
└────────────────────────────────────────────────────────┘

8.2 团队协作助手

团队可以部署OpenClaw作为共享助手：

┌────────────────────────────────────────────────────────┐
│  团队使用场景                                           │
│                                                        │
│  • Slack/Discord频道集成                               │
│  • 按团队成员隔离会话                                  │
│  • 共享代码片段和文档                                  │
│  • 自动化工作流程                                      │
│                                                        │
│  优势：统一管理、可审计、完全控制                       │
└────────────────────────────────────────────────────────┘

8.3 开发者工具链

开发者可以将OpenClaw集成到开发工作流：

# 终端集成
openclaw agent --message "帮我review这个PR"

# IDE集成（通过LSP）
# 使用OpenClaw作为代码助手后端

# CI/CD集成
openclaw agent --message "分析构建失败原因"

九、项目亮点与未来展望

9.1 核心优势

特性	说明
完全开源	MIT协议，代码完全透明
自托管	数据完全在用户手中
多渠道	支持20+主流通讯平台
可扩展	完整的插件系统和技能机制
安全	沙箱隔离、密钥管理、审计工具
跨平台	支持桌面、移动、服务器

9.2 技术创新

Agent Control Protocol (ACP)：标准化的子代理通信协议
多代理路由：智能地将请求路由到最合适的代理
实时Canvas：代理驱动的可视化工作区
设备节点协议：与原生客户端的安全通信机制

9.3 生态建设

ClawHub技能市场：用户分享和发现技能的社区
DeepWiki文档：AI驱动的项目文档解读
Discord社区：活跃的开发者交流频道
赞助商支持：OpenAI、GitHub、NVIDIA等科技巨头背书

十、总结

OpenClaw代表了开源AI助手的新方向——它不是简单地对接AI模型，而是构建了一个完整的个人AI基础设施。通过Gateway统一管理、多渠道无缝接入、强大的工具系统和安全隔离机制，OpenClaw让每个用户都能拥有真正属于自己的AI助手。

关键要点回顾：

架构设计：Hub-and-Spoke架构，Gateway作为单一事实来源
核心概念：Agent、Session、Channel、Tools、Skills五大支柱
工具系统：管道式执行、策略过滤、CDP浏览器自动化
插件架构：模块化设计，支持渠道、提供商、工具、钩子扩展
安全模型：个人助手信任模型 + Docker沙箱隔离
配置系统：Zod Schema验证、SecretRef密钥管理、热重载

如果你正在寻找一个功能完整、安全可靠、易于扩展的开源AI助手解决方案，OpenClaw绝对值得一试。

相关资源：

GitHub仓库：github.com/openclaw/op…
官方网站：openclaw.ai
官方文档：docs.openclaw.ai
DeepWiki：deepwiki.com/openclaw/op…
Discord社区：discord.gg/clawd

本文档基于OpenClaw项目最新代码和官方文档编写，如有疏漏欢迎指正。