【GitHub】OpenClaw：开源个人AI助手的新标杆

码流怪侠2026-05-02 17:55

一、项目概述

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聊天界面，而是一个完整的技术基础设施：

scss 复制代码 
┌─────────────────────────────────────────────────────────────┐
│                      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为核心枢纽，所有组件围绕其运转。这种设计的优势在于：

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

2.2 技术栈选择

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

2.3 核心子系统

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

bash 复制代码 
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（代理）

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

核心特性：

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

配置层次结构：

json5 复制代码 
{
  "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决策 → 工具清单解析 → 策略过滤 → 模型适配 → 执行处理 → 结果处理

核心代码流程（简化）：

typescript 复制代码 
// 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）的浏览器自动化能力：

核心功能：

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

使用示例：

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

4.3 执行批准机制

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

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

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

// 或通过控制台UI批准

安全边界：

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

4.4 工具策略层级

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

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

配置示例：

json5 复制代码 
{
  "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 渠道插件开发

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

typescript 复制代码 
// 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 插件发现机制

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

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

5.5 插件清单规范

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

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 沙箱隔离机制

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

json5 复制代码 
{
  "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引用模式：

json5 复制代码 
{
  "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 安装方式

推荐安装（生产环境）：

bash 复制代码 
# 使用npm
npm install -g openclaw@latest

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

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

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

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

# 首次运行设置
pnpm openclaw setup

# 开发模式
pnpm gateway:watch

7.2 最小配置

~/.openclaw/openclaw.json：

json5 复制代码 
{
  "agent": {
    "model": "openai/gpt-4o"
  }
}

7.3 完整配置示例

json5 复制代码 
{
  "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 快速使用

bash 复制代码 
# 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集成到开发工作流：

bash 复制代码 
# 终端集成
openclaw agent --message "帮我review这个PR"

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

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

九、项目亮点与未来展望

9.1 核心优势

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

9.2 技术创新

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

9.3 生态建设

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

十、总结

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

关键要点回顾：

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

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

相关资源：

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

相关推荐
user29876982706541 小时前
九、深入 Claude Code CLI 源码：Bridge/Remote Control 远程执行
人工智能
码农小白AI1 小时前
AI报告审核 IACheck：质量证明文件从“看得懂”走向“说得准”，术语一致性成为合规关键
人工智能
qq_283720051 小时前
Vibe Coding 氛围编程入门教程：AI 时代的全新开发范式（零基础到实战）
大数据·人工智能
wjcroom1 小时前
流体微元宇宙与伊辛拓扑体系的假象模型及实现路径
人工智能·物理学
zfh200506281 小时前
Open Claw Windows 一键部署教程（新手友好）
人工智能·open claw·小龙虾·open claw安装
kjmkq1 小时前
2026佛山鼎钻不锈钢一站式定制服务产业研究
人工智能
逻辑君1 小时前
认知神经科学研究报告【20260018】
人工智能·神经网络
AI医影跨模态组学1 小时前
如何将纵向CT影像组学特征与局部晚期胃癌化疗时空异质性及耐药演化建立关联，并进一步解释其与化疗响应、淋巴结转移及生存预后的机制联系
人工智能·深度学习·论文·医学·医学影像·影像组学
AI木马人2 小时前
9.人工智能实战：GPU 服务如何上 Kubernetes？从单机部署到 K8s + NVIDIA Device Plugin + HPA 的生产级改造
人工智能·容器·kubernetes
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03裂开！ChatGPT 居然开始要手机号验证，附详细解决方法04【AI】2026 年具身智能模型和世界模型总结05Codex 接入 DeepSeek API 完整配置文档062026年4月AI大事件深度解读：大模型竞争进入“深水区“07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲08零基础教你claude code 接入 deepseek V409在Windows 11上安装Docker的踩坑记录102026年AI前瞻：量子AI、具身智能与科学发现的新纪元