蓝迪哥玩转Ai(4)---openclaw结构，算法及代码解析（文件即真理，流程即文件）

landyjzlai

607人浏览 · 2026-03-15 08:16:46

landyjzlai · 2026-03-15 08:16:46 发布

前言：还是那句话，懂软件和AI算力芯片设计的人，每次都可以顺利的发现他们OPEN-SOURCE玩的把戏。
分享的都是可以公开的通用知识。多学习，多创新。

1. 项目概述

1. 项目名称与定位

项目名称：OpenClaw（曾用名：Clawdbot/Moltbot）

定位：个人AI助手，用户可在自有设备上运行
口号：Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

2. GitHub 统计数据

Stars：308,000+

Forks：58,300+
Contributors：1,175+
Commits：18,204+
我们可以通过下面下载：
https://github.com/openclaw/openclaw

OpenClaw 遵循“文件即真理”（Files are the source of truth）
这意味着AI的记忆、人格和规则，不再是黑盒，而是全部物理存储在你本地的 Markdown 文件中，不仅数据绝对安全，还能跨会话持续自我进化
。
OpenClaw 的 8个核心 Markdown 文件
： 1️⃣ SOUL.md：注入灵魂——定义AI的核心性格、语气与道德边界
。 2️⃣ AGENTS.md：最高宪法——设定工作流、协作机制与安全红线
。 3️⃣ IDENTITY.md：角色卡片——明确AI当天的具体职位与专业技能
。 4️⃣ USER.md：主人档案——记住“你是谁”，让AI完全适应你的工作偏好
。 5️⃣ MEMORY.md：长期记忆库——提炼高价值决策与经验，彻底告别“失忆”
。 6️⃣ HEARTBEAT.md：主动脉搏——让AI无需指令，也能定时帮你收发邮件、监控任务 30分钟一次
。 7️⃣ TOOLS.md：能力清单——教会AI如何使用本地工具和外部系统
。 8️⃣ BOOTSTRAP.md：出生证明——引导完成首次初始化仪式后即销毁
文件即真理：文件是智能体认知的最终真理来源。
外布化了，思想。
OPENCLAW智能体：有状态，持久性。记忆和身份在重启后依然存在。

文件驱动架构的关键优势

持久性：智能体的记忆和规则在重启后依然存在。
透明性：所有指令都是人类可读的文本文件。
可审计性：可使用 Git 等工具追踪每一次变更。
本地控制：智能体的 “大脑” 存于本地机器，而非云端。
智能体的工作空间：
文件驱动架构核心配置表
暂时无法在飞书文档外展示此内容

HEARTBEAT.md：
主动自主性的引擎。此文件包含一个简短的任务清单，智能体按时（如每 30 分钟）检查，以便在没有用户直接提示的情况下采取行动。
辅助文件

USER.md：描述你这位人类操作员，以提供个性化体验。
IDENTITY.md：定义智能体的具体角色、名称和专长。
TOOLS.md：提供关于如何使用可用工具和本地惯例的指南。
BOOTSTRAP.md：用于一次性设置仪式的 “出生证明”。

流程概述：提示词组装流程：
收到消息(用户发送消息或心跳机制被触发)–> 扫描工作空间（运行环境工作空间中的核心Markdown文件） —> 注入上下文（文件内容注入到系统提示词的”项目上下文“部分）–>调用LLM（包含规则，个性和用户消息的完整提示词被发送给语言模型，比如智谱GLM-5或是QWEN）.
在这里插入图片描述

上下文最大：15万
[图片]

黄金法则
不要在聊天中 “训练” 你的智能体。永久的配置和学习都发生在 Markdown 文件中。
[图片]

核心文件最佳实践
明确：在AGENTS.md中清晰定义规则，约束和优先级。
简洁：为遵守Token限制，保持文件简短扼要。
定义清晰人设：使用SOUL.md建立一致的个性和语调
使用结构：用标题和列表组织信息，以便模型更好的解析。

解锁主动性与记忆
安排任务：使用HEARTBEAT.md定义主动任务，如发送晨报。
提炼智慧：定期从日常日志中提炼重要经验到MEMORY.md。

记录工具：使用TOOLS.md解释本地惯例和特定工具的“注意事项”
像对待代码库一样对待你的智能体工作区。使用Git进行版本控制，以审查其历史记录并
从错误中恢复。
(GIT原来是可以自己管理代码的，我们以前都是团队一起用，这个重要的邪修用法。)
“将思想、偏好和判断清晰地表述到Markdown文件中的能力，将在未来成为一项
极具价值的技能。

2. 核心特性

2.1 本地优先架构

本地Gateway控制平面：单个控制平面管理会话、通道、工具和事件

数据自控：用户数据、模型密钥和执行环境完全由用户控制
隐私保护：避免数据上传到第三方云服务

2.2 多通道支持

支持的即时通讯平台：

WhatsApp (Baileys)
Telegram (grammY)
Slack (Bolt)
Discord (discord.js)
Google Chat (Chat API)
Signal (signal-cli)
BlueBubbles (iMessage, 推荐)
iMessage (legacy imsg)
IRC
Microsoft Teams
Matrix
Feishu (飞书)
LINE
Mattermost
Nextcloud Talk
Nostr
Synology Chat
Tlon
Twitch
Zalo / Zalo Personal
WebChat

2.3 多代理路由

将入站通道/账户/对等体路由到隔离的代理（工作区+每代理会话）

支持代理间通信：sessions_list, sessions_history, sessions_send
会话管理：主会话、群组隔离、激活模式、队列模式

2.4 语音交互功能

语音唤醒：macOS/iOS上支持唤醒词（Wake Words）

连续语音：Android上支持连续语音识别
Talk Mode：语音对话模式，支持按住说话（PTT）
TTS集成：ElevenLabs + 系统TTS回退

2.5 Live Canvas

A2UI代理驱动的可视化工作空间

支持Canvas push/reset, eval, snapshot操作
实时可视化控制界面

2.6 工具生态系统

Browser控制：专用openclaw Chrome/Chromium浏览器，CDP控制

Canvas工具：A2UI操作、快照、评估
Node工具：相机拍照/剪辑、屏幕录制、位置获取、通知
Cron任务：定时任务、唤醒、Webhooks、Gmail Pub/Sub
会话工具：sessions_系列工具用于代理间协调

2.7 配套应用

macOS应用：菜单栏控制平面、语音唤醒/PTT、Talk Mode覆盖、WebChat、调试工具

iOS节点：Canvas、语音唤醒、Talk Mode、相机、屏幕录制、Bonjour+设备配对
Android节点：连接标签页、聊天会话、语音标签页、Canvas、相机/屏幕录制、Android设备命令（通知/位置/SMS/照片/联系人/日历/运动/应用更新）

3. 技术架构

3.1 编程语言分布

编程语言
占比
TypeScript
87.2%
Swift
8.4%
Kotlin
1.9%
Shell
1.0%
JavaScript
0.6%
CSS + 其他
0.9%

3.2 核心架构组件

Gateway（网关）

WebSocket控制平面：单一WS控制平面管理客户端、工具和事件
默认绑定：ws://127.0.0.1:18789
功能：会话管理、在线状态、配置、Cron任务、Webhooks、Control UI、Canvas主机

Agent Runtime（代理运行时）

基于pi-mono的代理运行时
RPC模式运行
支持工具流式传输和块流式传输

CLI Surface（命令行界面）

gateway：网关控制
agent：与代理对话
send：发送消息
wizard：向导配置
doctor：诊断工具

3.3 通信流程

各即时通讯平台 → Gateway (控制平面 ws://127.0.0.1:18789)

→ Pi agent (RPC)
→ CLI (openclaw …)
→ WebChat UI
→ macOS app
→ iOS / Android nodes

4. 项目结构

4.1 目录组织

目录
说明
apps
配套应用程序（macOS, iOS, Android）
src
核心源代码
packages
包管理目录
ui
Web UI界面
skills
技能插件
docs
项目文档
extensions
扩展功能
test
测试文件
scripts
构建和部署脚本
.agents
代理配置
vendor/a2ui
A2UI组件库

4.2 关键配置文件

package.json：项目依赖和脚本配置

tsconfig.json：TypeScript编译配置
Dockerfile：容器化部署配置
docker-compose.yml：多容器编排
fly.toml：Fly.io部署配置
pyproject.toml：Python项目配置

5. 安装与配置

5.1 系统要求

运行时：Node.js ≥ 22

支持平台：macOS, Linux, Windows（WSL2强烈推荐）
包管理器：npm, pnpm, bun

5.2 安装方式

NPM全局安装（推荐）
npm install -g openclaw@latest
或：pnpm add -g openclaw@latest
openclaw onboard --install-daemon
从源代码安装（开发）
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
pnpm openclaw onboard --install-daemon

5.3 基础配置

最小配置 ~/.openclaw/openclaw.json：
{
agent: {
model: “anthropic/claude-opus-4-6”,
},
}

6. 安全特性

6.1 DM访问控制

默认配对策略（dmPolicy=“pairing”）：未知发送者收到配对码，机器人不处理消息
配对命令：openclaw pairing approve
开放DM需要显式选择：设置dmPolicy=“open"并在白名单中包含”*"
6.2 沙箱模式
非主会话沙箱：设置agents.defaults.sandbox.mode="non-main"在Docker沙箱中运行
默认沙箱策略：
允许列表：bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn
拒绝列表：browser, canvas, nodes, cron, discord, gateway
6.3 远程访问
Tailscale Serve：tailnet-only HTTPS访问（默认使用Tailscale身份头）
Tailscale Funnel：公共HTTPS访问（需要密码认证）
SSH隧道：备用远程访问方案
6.4 macOS权限
TCC权限管理：屏幕录制、通知、相机等
Node模式：macOS应用作为节点运行，通过Gateway WebSocket广播能力
权限检查：system.run, system.notify等操作需要相应权限