OpenClaw 核心功能解析：一文让你彻底搞懂 OpenClaw

导读

如果你和我一样对OpenClaw怀有以下疑问：

直接让 OpenClaw 操控我的电脑工作，存在哪些安全风险
OpenClaw 是怎么配置到各种聊天软件中的，原理是什么
会不会出现还没开始工作，AI 理解上下文就已经消耗了大量token
openclaw有没有优化上下文过长导致 AI 无法理解核心导致幻觉严重的问题
openclaw怎么更好的使用skills，在众多skills中怎么做到更好的按需分配
openclaw解决了哪些难点，怎么解决的

那么我建议你阅读本文章，最开始我也有这些问题，在AI的辅助下阅读了源码现已解决，故分享。

有错误或者补充欢迎指正

1. OpenClaw 是什么？

1.1 用一句话理解

OpenClaw 是一个运行在你自己电脑上的 AI 助手平台，它可以：

通过 20+ 种聊天软件（微信、Telegram、Discord 等）与你交互
自动操作浏览器、执行命令、管理文件
跨设备协同（电脑、手机、平板）
所有数据存储在本地，隐私可控

1.2 与其他 AI 产品的区别

特性	OpenClaw	ChatGPT/Claude 网页版	AutoGPT/LangChain
部署方式	本地运行	云端服务	本地/云端
数据隐私	如果自己配，那么完全本地	上传云端	取决于配置
多渠道接入	✅ 20+ 平台	❌ 仅网页	❌ 需自行开发
跨设备协同	✅ macOS/iOS/Android	❌	❌
浏览器控制	✅ 完整自动化	❌	⚠️ 基础支持
权限管理	✅ 多层安全机制	N/A	⚠️ 较弱

2. 核心架构一图看懂

2.1 整体架构（30秒理解）

核心理念：

Gateway（网关） ：像一个"总机"，接收所有消息并分发
Agent（智能体） ：真正的"大脑"，理解你的需求并决定怎么做
Tools（工具） ：Agent 的"手"，执行具体操作
本地存储：所有数据都在你的电脑上，不上传云端

2.2 消息处理流程（3分钟理解）

3. 四大技术难点及解决方案

难点 1：安全与权限的平衡

3.1.1 问题描述

类比理解：给 AI 助手权限，就像给保姆家里钥匙。

给太多权限：保姆可能乱翻东西、破坏财物
给太少权限：保姆无法打扫卫生、做饭

具体风险：

提示词注入：黑客通过聊天消息欺骗 AI 执行危险命令
记忆投毒：在 AI 的记忆中植入恶意指令
未授权访问：陌生人冒充你发送消息

3.1.2 OpenClaw 的解决方案

OpenClaw 采用多层防御体系，源码证据如下：

第一层：DM Pairing（私聊配对）

原理：陌生人第一次给你发消息时，必须先通过配对验证。

源码位置 ：src/infra/device-pairing.ts:14-100

typescript 复制代码

// 配对请求结构
export type DevicePairingPendingRequest = {
  requestId: string;
  deviceId: string;
  publicKey: string;        // 设备公钥（加密通信）
  displayName?: string;
  platform?: string;
  role?: string;            // 角色：operator/admin/device
  scopes?: string[];        // 权限范围
  ts: number;
};

实际效果：

陌生人发消息 → OpenClaw 生成 6 位配对码
你在电脑上执行 openclaw pairing approve telegram <code>
配对成功后，该联系人才能与 AI 对话

第二层：命令执行审批（Exec Approvals）

原理：AI 想执行危险命令时，必须先征得你的同意。

源码位置 ：src/infra/exec-approvals.ts:10-36

typescript 复制代码

// 三种安全等级
export type ExecSecurity = "deny" | "allowlist" | "full";

// deny：完全禁止执行命令
// allowlist：只允许白名单命令（如 ls、cat）
// full：允许所有命令（危险！）

// 询问模式
export type ExecAsk = "off" | "on-miss" | "always";
// off：不询问（仅限白名单）
// on-miss：白名单外的命令询问
// always：所有命令都询问

配置示例：

json 复制代码

{
  "agents": {
    "defaults": {
      "exec": {
        "security": "allowlist",  // 只允许白名单命令
        "ask": "on-miss"          // 白名单外的命令询问
      }
    }
  }
}

第三层：Docker 沙箱隔离

原理：在群组聊天中，AI 在隔离的 Docker 容器中执行命令，无法访问你的真实文件。

源码位置：src/agents/sandbox/config.ts

json 复制代码

// 沙箱配置
{
  "sandbox": {
    "mode": "non-main",  // 仅非个人 DM 使用沙箱
    "allowTools": ["bash", "read", "write"],  // 允许的工具
    "denyTools": ["browser", "canvas", "nodes"]  // 禁止的工具
  }
}

实际效果：

个人 DM：AI 可以访问你的真实文件
群组聊天：AI 在 Docker 容器中运行，无法破坏你的系统

第四层：安全审计系统

原理：OpenClaw 内置安全扫描工具，自动检测配置风险。

源码位置 ：src/security/audit.ts:32-61

typescript 复制代码

// 安全审计报告结构
export type SecurityAuditFinding = {
  checkId: string;
  severity: "info" | "warn" | "critical";  // 严重程度
  title: string;
  detail: string;
  remediation?: string;  // 修复建议
};

使用方法：

csharp 复制代码

openclaw doctor  # 运行安全检查

# 输出示例
[CRITICAL] DM policy not enabled
  未启用私聊配对，陌生人可直接与 AI 对话
  修复：设置 channels.telegram.dmPolicy: "pairing"

[WARN] Sandbox disabled for groups
  群组聊天未启用沙箱，存在安全风险
  修复：设置 sandbox.mode: "non-main"

3.1.3 安全机制总结

防御层	防御对象	源码位置	配置项
DM Pairing	未授权访问	src/infra/device-pairing.ts	`channels.*.dmPolicy: "pairing"`
Exec Approvals	危险命令执行	src/infra/exec-approvals.ts	`agents.defaults.exec.security`
Docker Sandbox	群组恶意操作	`src/agents/sandbox/`	`agents.defaults.sandbox.mode`
Security Audit	配置漏洞	src/security/audit.ts	`openclaw doctor`
认证系统	网关访问控制	src/gateway/auth.ts	`gateway.auth.mode`

安全架构图：

难点 2：多渠道统一适配

3.2.1 问题描述

类比理解：就像一个翻译官，要同时听懂 20 种语言（Telegram、Discord、Slack...），并且每种语言的语法、格式都不一样。

具体挑战：

Telegram 用 grammY 库，Discord 用 discord.js
消息格式差异：Telegram 支持 Markdown，Discord 支持 Embed
附件类型不同：图片、视频、文件的处理方式各异
API 变更：平台更新 API，适配代码需要跟着改

3.2.2 OpenClaw 的解决方案

插件化架构

原理：每个聊天平台都是一个独立的"插件"，通过统一的接口与 Gateway 通信。

源码位置：src/channels/plugins/

bash 复制代码

src/channels/plugins/
├── telegram/        # Telegram 插件
│   ├── index.ts     # 插件入口
│   ├── send.ts      # 发送消息
│   └── receive.ts   # 接收消息
├── discord/         # Discord 插件
├── slack/           # Slack 插件
└── whatsapp/        # WhatsApp 插件

统一接口定义：src/channels/plugins/types.ts

typescript 复制代码

// 所有渠道插件必须实现这个接口
interface ChannelPlugin {
  start(): Promise<void>;           // 启动插件
  stop(): Promise<void>;            // 停止插件
  sendMessage(params: {             // 发送消息
    to: string;
    text: string;
    mediaUrls?: string[];
  }): Promise<void>;
}

实际效果：

新增一个聊天平台？只需开发一个插件
平台 API 变更？只需修改对应插件，不影响其他部分
Agent 无需关心底层细节，只处理标准格式

消息归一化

原理：将不同平台的消息转换为统一格式。

源码位置：src/channels/session.ts

难点 3：本地执行与资源管控

3.3.1 问题描述

类比理解：在你的电脑上运行 AI，就像在家里养宠物。

宠物（AI）需要吃饭（CPU/内存）
宠物可能乱跑（孤儿进程）
宠物需要训练（模型推理）

具体挑战：

浏览器自动化（Playwright）占用大量内存
长时间运行可能内存泄漏
本地模型推理卡顿
进程管理不当导致系统卡死

3.3.2 OpenClaw 的解决方案

Runtime 池化（进程复用）

原理：不是每次都创建新进程，而是复用已有的进程。

源码位置：src/acp/control-plane/runtime-cache.ts

json 复制代码

// Runtime 缓存配置
{
  "agents": {
    "defaults": {
      "runtimeIdleTtlMs": 300000  // 5分钟无活动自动回收
    }
  }
}

实际效果：

第一次请求：创建 Runtime（慢，约 2-3 秒）
后续请求：复用 Runtime（快，约 100ms）
空闲 5 分钟后自动回收，释放内存

并发控制（Actor 模型）

原理：同一个会话的请求排队执行，避免冲突。

源码位置 ：src/acp/control-plane/session-actor-queue.ts

kotlin 复制代码

  async run<T>(actorKey: string, op: () => Promise<T>): Promise<T> {
    return this.queue.enqueue(actorKey, op, {
      onEnqueue: () => {
        this.pendingBySession.set(actorKey, (this.pendingBySession.get(actorKey) ?? 0) + 1);
      },
      onSettle: () => {
        const pending = (this.pendingBySession.get(actorKey) ?? 1) - 1;
        if (pending <= 0) {
          this.pendingBySession.delete(actorKey);
        } else {
          this.pendingBySession.set(actorKey, pending);
        }
      },
    });
  }

实际效果：

避免同一会话的请求互相干扰
保证消息顺序处理
防止资源竞争

难点 4：长期记忆与上下文管理

3.4.1 问题描述

类比理解：AI 的记忆就像人的大脑，但容量有限。

短期记忆：最近几轮对话（上下文窗口）
长期记忆：历史对话、知识库（需要持久化）

具体挑战：

LLM 上下文窗口有限（如 GPT-4 最多 128K tokens）
长对话后，早期信息会被遗忘
记忆数据无加密，设备故障可能丢失

3.4.2 OpenClaw 的解决方案

Session Compaction（上下文压缩）

原理：将历史对话压缩为摘要，保留关键信息。

源码位置：

src/agents/pi-embedded-runner/compact.ts

使用方法：

bash 复制代码

# 手动压缩
/compact
 
# 自动压缩（配置）
{
  "agents": {
    "defaults": {
      "autoCompact": true
    }
  }
}

Memory Search（语义检索）

原理：不是把所有记忆都加载，而是按需检索相关内容。

源码位置：src/memory/

工具调用：

php 复制代码

// Agent 调用 memory_search
memory_search({
  query: "项目进展",
  maxResults: 5
})
 
// 返回相关记忆片段
// 然后用 memory_get 获取详细内容

4. 为什么 OpenClaw 能脱颖而出

4.1 核心竞争力对比

4.2 十大核心功能点

功能	说明	源码位置	竞品对比
1. Gateway 控制平面	单一 WebSocket 管理所有连接	src/gateway/	✅ 独有
2. Multi-Agent 路由	7 层优先级智能路由	src/routing/resolve-route.ts	✅ 独有
3. 跨渠道消息	20+ 平台统一接入	src/channels/plugins/	⚠️ 部分竞品支持
4. 浏览器控制	Playwright + CDP 完整自动化	src/browser/	⚠️ 功能较弱
5. Canvas + A2UI	Agent 驱动的可视化界面	src/canvas-host/	✅ 独有
6. Nodes 系统	跨设备能力调用（相机/屏幕/位置）	src/node-host/	✅ 独有
7. Docker 沙箱	群组聊天环境隔离	`src/agents/sandbox/`	❌ 少见
8. DM Pairing	私聊配对防未授权访问	src/infra/device-pairing.ts	❌ 少见
9. Skills 平台	按需加载技能插件	src/agents/skills/	⚠️ 部分支持
10. 心跳机制	主动式后台任务执行	src/infra/heartbeat-runner.ts	✅ 独有

5. 上下文优化：如何避免 Token 浪费

5.1 问题：会不会还没开始工作就消耗大量 Token？

答案：OpenClaw 已经做了很好的优化，但仍有改进空间。

5.2 优化机制详解

5.2.1 Bootstrap 文件截断

问题：

AGENTS.md、TOOLS.md 等配置文件可能很大（几十 KB），全部加载会浪费 Token。

解决方案：设置字符数上限，超出部分截断。

源码位置 ：src/agents/bootstrap-budget.ts:164-221

json 复制代码

// 配置示例
{
  "agents": {
    "defaults": {
      "bootstrapMaxChars": 50000,        // 单文件最大 50K 字符
      "bootstrapTotalMaxChars": 200000,  // 所有文件总和最大 200K
      "bootstrapWarningMode": "once"     // 截断警告模式
    }
  }
}

警告机制：

csharp 复制代码

[Bootstrap truncation warning]
Some workspace bootstrap files were truncated before injection.
Treat Project Context as partial and read the relevant files directly if details seem missing.
- AGENTS.md: 80000 raw -> 50000 injected (~37% removed; max/file).

实际效果：

空 session 启动：~5K-10K tokens（系统提示 + 工具定义 + bootstrap）
避免了无限制加载导致的 Token 爆炸

5.2.2 Skills 按需加载

问题：如果一次性加载所有 skills（可能有 20 个），每个 5KB，就是 100KB 的上下文开销。

解决方案：只注入 skills 列表，Agent 需要时再加载具体内容。

源码位置 ：src/agents/system-prompt.ts:20-36

arduino 复制代码

// 系统提示中的 Skills 指令
"## Skills (mandatory)",
"Before replying: scan <available_skills> <description> entries.",
"- If exactly one skill clearly applies: read its SKILL.md at <location> with `read`, then follow it.",
"- If multiple could apply: choose the most specific one, then read/follow it.",
"- If none clearly apply: do not read any SKILL.md.",
"Constraints: never read more than one skill up front; only read after selecting."

对比：

❌ 传统方式：20 个 skills × 5KB = 100KB 上下文
✅ OpenClaw：skills 列表 1KB + 按需加载 5KB = 6KB 上下文

5.2.3 Memory 语义检索

问题：将整个 MEMORY.md（可能 50KB+）注入上下文，浪费 Token。

解决方案：先搜索，再按需拉取相关片段。

源码位置 ：src/agents/system-prompt.ts:38-64

arduino 复制代码

// 系统提示中的 Memory 指令
"## Memory Recall",
"Before answering anything about prior work, decisions, dates, people, preferences, or todos: 
 run memory_search on MEMORY.md + memory/*.md; 
 then use memory_get to pull only the needed lines."

5.2.4 Subagent 精简上下文

问题：子任务也加载完整系统提示，浪费 Token。

解决方案 ：Subagent 使用 minimal 模式，跳过不必要的部分。

源码位置 ：src/agents/system-prompt.ts:11-17

typescript 复制代码

export type PromptMode = "full" | "minimal" | "none";
 
// minimal 模式跳过：
// - Skills section
// - Memory section
// - User identity section
// - Reply tags section

5.3 上下文优化总结

优化机制	节省效果	源码位置
Bootstrap 截断	单文件 50K → 总量 200K 限制	src/agents/bootstrap-budget.ts
Skills 按需加载	100KB → 6KB	src/agents/system-prompt.ts
Memory 检索	50KB → 2KB	src/memory/
Subagent 精简	10K → 3K tokens	src/agents/system-prompt.ts
Session Compaction	20K → 5K tokens	src/agents/pi-embedded-runner/compact.ts

实测数据（基于代码推测）：

空 session 启动：~5K-10K tokens
10 轮对话后：~15K-25K tokens
触发 compaction 后：降回 ~8K-12K tokens

6. Skills 智能分配机制

6.1 问题：在众多 skills 中怎么做到按需分配？

OpenClaw 采用两阶段加载 + 强制约束的策略。

6.2 工作流程

6.3 强制约束机制

源码位置 ：src/agents/system-prompt.ts:20-36

arduino 复制代码

// 系统提示中的强制约束
"## Skills (mandatory)",
"Before replying: scan <available_skills> <description> entries.",
"- If exactly one skill clearly applies: read its SKILL.md at <location> with `read`, then follow it.",
"- If multiple could apply: choose the most specific one, then read/follow it.",
"- If none clearly apply: do not read any SKILL.md.",
"Constraints: never read more than one skill up front; only read after selecting.",

关键约束：

必须先扫描：不能跳过扫描直接加载
只加载一个：禁止贪婪加载多个 skills
先判断再加载：避免盲目加载

6.4 Skills 类型

6.5 Skill 结构

bash 复制代码

skills/deployment/
├── SKILL.md          # Skill 说明（注入到 agent）
├── package.json      # 依赖（可选）
└── tools/            # 自定义工具（可选）
    └── deploy.ts

SKILL.md 示例：

markdown 复制代码

# Deployment Skill

## 适用场景
- 部署静态网站到 Netlify/Vercel
- 部署 Node.js 应用到云服务器

## 使用步骤
1. 检查项目类型（静态/动态）
2. 选择部署平台
3. 执行部署命令
4. 验证部署结果

## 工具调用
- `exec("npm run build")`
- `exec("netlify deploy --prod")`

7. 完整技术栈总览

7.1 技术架构分层

7.2 核心依赖库

类别	库名	用途	源码位置
运行时	Node.js 22+	JavaScript 运行环境	-
语言	TypeScript	类型安全	全项目
开发工具	Bun	快速开发/测试	-
AI 引擎	pi-mono	LLM 推理	`src/acp/runtime/`
浏览器	Playwright	浏览器自动化	src/browser/
消息平台	grammY, discord.js, Bolt	渠道集成	src/channels/plugins/
沙箱	Docker	环境隔离	`src/agents/sandbox/`
存储	JSON/JSONL	配置和历史	`~/.openclaw/`

8. 总结：OpenClaw 的核心价值

8.1 技术创新点

单一控制平面：Gateway WebSocket 统一管理
智能路由：7 层优先级匹配
Runtime 池化：自动缓存和回收
上下文优化：Bootstrap 截断 + Session 压缩
安全优先：多层防御体系

8.2 适用场景

✅ 适合使用 OpenClaw 的场景：

需要 AI 跨多个聊天平台工作
需要 AI 使用浏览器自动化工作
需要 AI 跨设备协同
需要 AI 通过聊天就能为你工作，读取本地文件成为你的专属助手

❌ 不适合使用 OpenClaw 的场景：

只需要简单聊天（用 ChatGPT 网页版即可）
没有本地运行环境（需要云服务）
不希望 AI 直接自主操控我的本地文件

8.3 学习路径建议

复制代码

编辑

9. 常见问题 FAQ

Q1: OpenClaw 安全吗？会不会被黑客利用？

A : OpenClaw 提供了多层安全机制，但安全性取决于你的配置。

推荐安全配置：

json 复制代码

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing"  // 启用私聊配对
    }
  },
  "agents": {
    "defaults": {
      "exec": {
        "security": "allowlist",  // 只允许白名单命令
        "ask": "on-miss"          // 白名单外的命令询问
      },
      "sandbox": {
        "mode": "non-main"  // 群组聊天使用沙箱
      }
    }
  },
  "gateway": {
    "auth": {
      "mode": "password"  // 启用密码认证
    }
  }
}

定期检查：

bash 复制代码

openclaw doctor  # 运行安全审计

Q2: 会不会消耗大量 Token？

A: OpenClaw 已经做了很好的优化，但一定的 Token 消耗是难免的：

Bootstrap 截断：单文件 50K/总量 200K 限制
Skills 按需加载：只加载需要的 skill
Memory 检索：语义搜索而非全量加载
Session 压缩：定期压缩历史对话

实测数据：

空 session 启动：~5K-10K tokens
10 轮对话后：~15K-25K tokens
压缩后：降回 ~8K-12K tokens

Q3: 如何开始使用 OpenClaw？

A: 三步快速上手：

bash 复制代码

# 1. 安装
curl -fsSL https://openclaw.ai/install.sh | bash
 
# 2. 启动 Gateway
openclaw gateway run
 
# 3. 配置渠道（以 Telegram 为例）
openclaw onboard

详细教程：docs.openclaw.ai/start/wizar...

Q4: OpenClaw 与 ChatGPT/Claude 有什么区别？

特性	OpenClaw	ChatGPT/Claude
部署	本地运行	云端服务
隐私	完全本地	上传云端
渠道	20+ 平台	仅网页/App
工具	完整自动化	受限
成本	用户自配 API Key，可选便宜API	订阅费用

10. 参考资源

官方文档 ：docs.openclaw.ai
GitHub 仓库 ：github.com/openclaw/op...
Discord 社区 ：discord.gg/openclaw
源码导读：
- Gateway: src/gateway/server/ws-server.ts
- 路由: src/routing/resolve-route.ts
- ACP: src/acp/control-plane/manager.core.ts
- 安全: src/security/audit.ts
- 浏览器: src/browser/