1. 本期目标这一系列博客准备从源码角度学习 OpenClaw。在正式进入代码之前第一期先不急着逐文件分析而是先回答几个基础问题1. OpenClaw 是什么 2. 它和普通 AI 聊天机器人有什么区别 3. 为什么它强调 local-first 和 personal assistant 4. Gateway、Channel、Agent、Tools、Skills、Sandbox 分别是什么 5. 这个项目的源码应该按照什么顺序阅读 6. 后续博客可以分成哪些模块继续分析OpenClaw 的官方 README 将其定义为一个运行在用户自己设备上的个人 AI 助手。它可以通过用户已经在使用的消息渠道进行回复也支持 macOS、iOS、Android 上的语音输入输出并能渲染用户可控制的 Live Canvas。官方 README 还特别强调Gateway 只是控制平面真正的产品形态是 assistant 本身。(GitHub)所以本系列的核心不是简单看一个聊天应用怎么写而是理解一个本地优先、多渠道、可调用工具、可扩展技能、带安全隔离机制的个人 AI Agent 系统是如何组织源码和运行链路的。2. OpenClaw 是什么简单来说OpenClaw 是一个开源的个人 AI 助手系统。它不是只能在网页里聊天的普通 Chatbot而是希望成为一个常驻在你设备附近的个人助手。它可以接入不同消息平台可以运行工具可以使用技能可以处理会话可以在本地 Gateway 的控制下协调多个入口和能力。官方 README 对它的描述很直接OpenClaw is a personal AI assistant you run on your own devices.也就是说它强调的是“你自己的设备”“你的个人助手”“你常用的沟通渠道”。它支持的渠道也比较多包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、Matrix、飞书、LINE、Mattermost、微信、QQ、WebChat 等。(GitHub)因此可以先用一句话理解 OpenClawOpenClaw 是一个以本地 Gateway 为控制中心、以多渠道消息入口为交互方式、以工具和技能为执行能力的个人 AI Agent 系统。3. 它和普通 AI Chatbot 有什么区别普通 AI Chatbot 的结构通常比较简单用户输入 ↓ 后端调用大模型 ↓ 模型返回文本 ↓ 前端展示回答它的核心能力是“对话”。而 OpenClaw 的目标更接近“个人助手系统”。它不仅要回答问题还要处理多渠道消息、管理会话、调用工具、加载技能、接入移动端节点、处理语音和 Canvas并且要考虑安全隔离。可以这样对比普通 Chatbot 重点是一次问答或多轮对话。 OpenClaw 重点是本地常驻、多渠道接入、任务执行、个人工作流和安全边界。OpenClaw 官方 README 中列出的 Highlights 也说明了这一点它包含 Local-first Gateway、多渠道收件箱、多 Agent 路由、语音唤醒与连续语音、Live Canvas、First-class tools、伴随应用和 skills 等能力。(GitHub)所以如果用源码学习的视角来看OpenClaw 的重点不是某一个模型调用函数而是整个 Agent 系统如何被拆分成多个模块并在 Gateway 的协调下工作。4. 为什么 OpenClaw 强调 local-firstlocal-first 可以理解为系统的核心控制能力尽量运行在用户自己的环境中 而不是完全依赖远程平台。OpenClaw 的官方 README 把 Local-first Gateway 放在 Highlights 的第一项说明 Gateway 是整个系统中非常关键的控制平面。Gateway 负责管理 sessions、channels、tools 和 events。(GitHub)这带来两个直接影响。第一用户的数据和工作区更接近本地环境。OpenClaw 更像一个围绕个人设备和个人渠道运行的助手而不是一个单纯的云端聊天服务。第二安全问题会变得更加重要。因为 Agent 一旦能够操作本地工具、读取写入文件、处理真实消息入口就必须考虑权限、沙箱、远程暴露、DM 来源、工具访问边界等问题。官方 README 也明确提醒OpenClaw 会连接真实消息入口入站私信应该被视为不可信输入。(GitHub)所以local-first 不是单纯的部署方式而是影响 OpenClaw 架构设计的核心理念。5. 从整体上看 OpenClaw 的架构如果先不看具体代码OpenClaw 可以抽象成下面这条链路用户消息入口 ↓ Channel Adapter ↓ Gateway ↓ Session / Routing ↓ Agent Runtime ↓ Model / Tools / Skills ↓ 结果返回 ↓ Channel Adapter ↓ 用户收到回复其中每一层大概可以这样理解Channel 负责接入不同消息平台例如 Telegram、Slack、Discord、微信、QQ、WebChat 等。 Gateway 负责统一管理消息、会话、工具、事件和系统控制是整个系统的控制中心。 Session 负责区分不同会话、不同用户、不同上下文。 Agent Runtime 负责真正组织模型调用、工具调用、技能加载和任务执行。 Tools 让 Agent 可以执行具体动作例如浏览器、Canvas、节点、定时任务、会话工具、Discord / Slack 动作等。 Skills 通过技能文件扩展 Agent 的行为和知识。 Sandbox 为非 main session 或高风险上下文提供隔离运行环境。官方 README 中提到OpenClaw 的 First-class tools 包括 browser、canvas、nodes、cron、sessions 以及 Discord / Slack actionsskills 则通过 onboarding 和 bundled / managed / workspace skills 等方式进入系统。(GitHub)这说明 OpenClaw 的 Agent 能力不是写死在一个对话函数里而是通过工具、技能、会话和配置不断扩展。6. Gateway 是什么Gateway 是理解 OpenClaw 的第一个关键词。官方 README 明确说The Gateway is just the control plane — the product is the assistant.也就是说Gateway 本身不是最终产品形态而是整个助手系统背后的控制平面。它负责把不同渠道、不同会话、不同工具和不同事件连接起来。(GitHub)可以把 Gateway 想象成一个“中枢”Telegram 发来的消息 Slack 发来的消息 WebChat 发来的消息 移动端节点发来的事件 本地 CLI 发来的命令 ↓ Gateway ↓ 统一路由到 Agent / Session / Tools如果没有 Gateway系统中的各个能力会变得很分散。每个渠道都要自己处理模型调用、会话、工具、鉴权和安全控制系统会很难维护。有了 Gateway 之后不同入口都可以统一进入控制平面再由 Gateway 进行分发和管理。所以源码阅读时Gateway 应该是后续重点分析对象之一。7. Channel 是什么Channel 可以理解为 OpenClaw 和外部消息平台之间的适配层。用户可能不想打开一个专门的网页聊天界面而是希望直接在自己熟悉的平台上和助手交互。例如 Telegram、Slack、Discord、微信、QQ 或 WebChat。OpenClaw 支持多种渠道官方 README 列出了 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、微信、QQ、WebChat 等。(GitHub)所以 Channel 的价值是把不同平台的消息格式转换成 OpenClaw 内部可以统一处理的消息事件 再把 Agent 的回复转换成对应平台可以发送的消息。可以写成外部平台消息 ↓ Channel Adapter ↓ OpenClaw 内部消息格式 ↓ Gateway / Agent 处理 ↓ OpenClaw 内部回复 ↓ Channel Adapter ↓ 外部平台展示后续源码解析时Channel 接入机制会是一个单独的大模块。8. Agent 是什么Agent 是 OpenClaw 中真正执行智能任务的部分。如果 Gateway 是控制平面Channel 是消息入口那么 Agent 就是负责理解用户请求、组织上下文、调用模型、使用工具和技能完成任务的核心执行者。从功能上看Agent 至少要处理几个问题1. 当前用户说了什么 2. 这属于哪个 session 3. 是否需要读取历史上下文 4. 是否需要使用某个 skill 5. 是否需要调用 tool 6. 应该调用哪个模型 7. 模型输出应该如何返回给用户也就是说Agent 并不只是“调用一次大模型 API”。它更像一个调度器用户请求 ↓ 上下文组织 ↓ 技能加载 ↓ 工具选择 ↓ 模型调用 ↓ 结果整理 ↓ 回复用户这也是 OpenClaw 和普通聊天应用最大的区别之一。9. Tools 是什么Tools 是让 Agent 从“会说话”变成“能做事”的关键。如果没有工具模型最多只能生成文本回答。有了工具之后Agent 可以进行更多动作例如浏览网页、操作 Canvas、调用节点、处理定时任务、管理 sessions或者执行 Discord / Slack 相关动作。官方 README 将这些称为 First-class tools。(GitHub)可以这样理解模型本身负责判断和规划 Tools 负责真正执行外部动作。这和我们之前分析ai_agent项目中的 Tool Calling 很像但 OpenClaw 的工具系统更复杂因为它面向的是一个本地优先、多渠道、多会话的个人助手系统。后续源码阅读时Tools 系统要重点关注几个问题1. Tool 在源码中如何定义 2. Tool schema 如何暴露给模型 3. 模型如何选择工具 4. 工具结果如何返回模型 5. 高风险工具如何限制权限 6. Sandbox 如何影响工具执行10. Skills 是什么Skills 可以理解为 OpenClaw 的能力扩展机制。工具更偏“动作”例如打开浏览器、操作 Canvas、管理 session。而技能更偏“知识、行为规则和任务模板”通常通过文件组织起来让 Agent 在特定任务中获得额外指令或能力。官方 README 提到 OpenClaw 支持 bundled / managed / workspace skills并且 onboarding 流程也会涉及 skills。(GitHub)可以先这样区分Tool 让 Agent 能执行某个动作。 Skill 让 Agent 知道如何处理某类任务。举个例子Tool 像是“浏览器”“文件编辑器”“会话管理器”。 Skill 像是“如何写周报”“如何整理邮件”“如何处理某个工作流”。后续源码阅读时需要重点关注1. skills 目录如何组织 2. SKILL.md 如何被加载 3. skill 内容如何进入 prompt 4. workspace skills 和 bundled skills 有什么区别 5. skill 是否会带来 prompt injection 或权限风险11. Sandbox 为什么重要OpenClaw 这种系统必须重视安全。因为它不是一个只生成文本的聊天机器人。它可能连接真实消息入口可能调用工具可能读写文件可能接入设备节点甚至可能处理用户的私人渠道消息。官方 README 中的安全模型部分说明默认情况下main session 的工具运行在宿主机上对于 group / channel safety可以设置agents.defaults.sandbox.mode: non-main让非 main sessions 在 sandbox 中运行。Docker 是默认 sandbox backend同时也支持 SSH 和 OpenShell backends。(GitHub)这段信息非常关键。它说明 OpenClaw 并不是简单地“所有东西都在同一个权限下运行”而是区分 main session 和 non-main session并为更高风险的会话提供沙箱机制。可以这样理解main session 更像用户本人直接使用助手默认工具运行在宿主机上。 non-main session 更像来自群聊、频道或外部入口的会话更适合放入 sandbox 中隔离。官方 README 还列出了典型 sandbox 默认允许和拒绝的工具类型。例如允许 bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn拒绝 browser、canvas、nodes、cron、discord、gateway 等。(GitHub)这说明 Sandbox 是后续源码解析中非常重要的一期尤其适合结合安全角度展开。12. 从仓库结构看项目复杂度OpenClaw 仓库不是一个简单的单目录项目。从 GitHub 页面可以看到它包含多个顶层目录例如apps config deploy docs extensions packages qa scripts security skills src test ui这些目录说明 OpenClaw 至少包含应用端、配置、部署、文档、扩展、共享包、质量保障、安全、技能、核心源码、测试和 UI 等多个部分。(GitHub)从源码阅读角度可以先这样理解src 核心运行时代码后续重点分析。 extensions 不同渠道或插件扩展相关代码。 skills 内置或示例技能相关内容。 packages 共享包或内部模块。 apps 桌面端、移动端或伴随应用相关代码。 ui 控制台、Canvas 或可视化界面相关代码。 security 安全策略、扫描或安全配置相关内容。 docs 官方文档和架构说明。 test / qa 测试和质量保障。第一期先建立这个目录地图后续阅读源码时才不会迷路。13. 推荐的源码阅读顺序这个项目不适合一开始就从某个文件开始逐行读。更合理的顺序是先看主链路再看模块细节。我建议按照下面顺序阅读第一步README 和文档 先搞清楚项目定位、安装方式、核心概念和安全提醒。 第二步package.json 和 openclaw.mjs 理解 CLI 命令入口在哪里openclaw 命令如何启动。 第三步Gateway 相关源码 理解控制平面如何启动、如何管理 session、channel、tools 和 events。 第四步Channel 相关源码 理解不同消息平台如何接入外部消息如何转换成内部事件。 第五步Agent Runtime 理解用户消息进入后Agent 如何组织上下文、调用模型、使用工具和技能。 第六步Tools 系统 理解工具如何定义、注册、执行以及结果如何返回模型。 第七步Skills 系统 理解技能文件如何被发现、加载并影响 Agent 行为。 第八步Sandbox 与安全 理解 main / non-main session 的权限差异以及工具隔离机制。 第九步UI / Canvas / Apps / Nodes 理解可视化界面、Canvas、移动端节点和伴随应用如何接入 Gateway。这个顺序的好处是先看系统主干再看能力扩展最后看安全和多端形态。14. 本系列建议分期整个 OpenClaw 源码解析可以分成下面这些期第一期项目总览与源码阅读路线 第二期源码运行与开发环境 第三期仓库目录结构解析 第四期CLI 入口与 openclaw 命令 第五期Gateway 核心机制 第六期配置系统解析 第七期Session 会话模型 第八期模型调用链路 第九期Channel 接入机制 第十期消息处理主链路 第十一期Tools 系统源码解析 第十二期Skills 系统源码解析 第十三期Sandbox 安全模型 第十四期Canvas 与 UI 第十五期移动端与 Nodes如果后续还想继续深入可以扩展为第十六期多 Agent 路由机制 第十七期语音唤醒与 Talk Mode 第十八期安全风险与加固建议 第十九期如何开发一个自己的 Skill 第二十期如何开发一个自己的 Channel这样整个系列既能覆盖源码也能覆盖扩展开发和安全分析。15. 本期重点理解这一期最重要的是先建立 OpenClaw 的整体认识。可以总结为五点第一OpenClaw 是一个运行在用户自己设备上的个人 AI 助手系统而不是普通网页聊天机器人。 第二Gateway 是控制平面负责统一管理 sessions、channels、tools 和 events。 第三Channel 负责连接外部消息平台让用户可以通过 Telegram、Slack、Discord、微信、QQ、WebChat 等入口与助手交互。 第四Tools 和 Skills 是 Agent 能力扩展的两个关键机制Tools 更偏动作执行Skills 更偏任务能力和行为规则。 第五Sandbox 是 OpenClaw 安全模型的重要组成部分尤其适合隔离来自非 main session 的高风险任务。一句话概括OpenClaw 的核心价值是把大模型从“聊天窗口里的回答者”扩展成“运行在个人设备上、接入多渠道、具备工具和技能、需要安全边界的本地优先 AI 助手”。16. 本期小结本期主要对 OpenClaw 项目做了整体介绍。OpenClaw 是一个运行在用户自己设备上的个人 AI 助手能够通过多种消息渠道与用户交互并通过 Gateway 统一管理会话、渠道、工具和事件。与普通 Chatbot 相比OpenClaw 更强调 local-first、多渠道入口、任务执行能力、技能扩展和安全隔离。源码层面上它包含src、extensions、skills、packages、apps、ui、security、docs等多个目录说明它是一个完整的 Agent 系统工程而不是一个简单模型调用 Demo。这一期可以用一句话总结阅读 OpenClaw 源码不能只看模型调用函数而要从 Gateway、Channel、Agent、Tools、Skills 和 Sandbox 这几个核心模块出发理解一个个人 AI 助手系统是如何被组织起来的。下一期可以继续分析OpenClaw 源码解析二源码运行与开发环境下一期重点讲如何准备 Node / pnpm 环境如何安装和启动 OpenClaw如何使用openclaw onboard、openclaw gateway status、openclaw gateway --port 18789 --verbose和openclaw agent --message跑通最小链路并为后续源码调试做准备。
OpenClaw 源码解析（一）：项目总览与源码阅读路线
发布时间：2026/5/24 3:27:00
1. 本期目标这一系列博客准备从源码角度学习 OpenClaw。在正式进入代码之前第一期先不急着逐文件分析而是先回答几个基础问题1. OpenClaw 是什么 2. 它和普通 AI 聊天机器人有什么区别 3. 为什么它强调 local-first 和 personal assistant 4. Gateway、Channel、Agent、Tools、Skills、Sandbox 分别是什么 5. 这个项目的源码应该按照什么顺序阅读 6. 后续博客可以分成哪些模块继续分析OpenClaw 的官方 README 将其定义为一个运行在用户自己设备上的个人 AI 助手。它可以通过用户已经在使用的消息渠道进行回复也支持 macOS、iOS、Android 上的语音输入输出并能渲染用户可控制的 Live Canvas。官方 README 还特别强调Gateway 只是控制平面真正的产品形态是 assistant 本身。(GitHub)所以本系列的核心不是简单看一个聊天应用怎么写而是理解一个本地优先、多渠道、可调用工具、可扩展技能、带安全隔离机制的个人 AI Agent 系统是如何组织源码和运行链路的。2. OpenClaw 是什么简单来说OpenClaw 是一个开源的个人 AI 助手系统。它不是只能在网页里聊天的普通 Chatbot而是希望成为一个常驻在你设备附近的个人助手。它可以接入不同消息平台可以运行工具可以使用技能可以处理会话可以在本地 Gateway 的控制下协调多个入口和能力。官方 README 对它的描述很直接OpenClaw is a personal AI assistant you run on your own devices.也就是说它强调的是“你自己的设备”“你的个人助手”“你常用的沟通渠道”。它支持的渠道也比较多包括 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、Matrix、飞书、LINE、Mattermost、微信、QQ、WebChat 等。(GitHub)因此可以先用一句话理解 OpenClawOpenClaw 是一个以本地 Gateway 为控制中心、以多渠道消息入口为交互方式、以工具和技能为执行能力的个人 AI Agent 系统。3. 它和普通 AI Chatbot 有什么区别普通 AI Chatbot 的结构通常比较简单用户输入 ↓ 后端调用大模型 ↓ 模型返回文本 ↓ 前端展示回答它的核心能力是“对话”。而 OpenClaw 的目标更接近“个人助手系统”。它不仅要回答问题还要处理多渠道消息、管理会话、调用工具、加载技能、接入移动端节点、处理语音和 Canvas并且要考虑安全隔离。可以这样对比普通 Chatbot 重点是一次问答或多轮对话。 OpenClaw 重点是本地常驻、多渠道接入、任务执行、个人工作流和安全边界。OpenClaw 官方 README 中列出的 Highlights 也说明了这一点它包含 Local-first Gateway、多渠道收件箱、多 Agent 路由、语音唤醒与连续语音、Live Canvas、First-class tools、伴随应用和 skills 等能力。(GitHub)所以如果用源码学习的视角来看OpenClaw 的重点不是某一个模型调用函数而是整个 Agent 系统如何被拆分成多个模块并在 Gateway 的协调下工作。4. 为什么 OpenClaw 强调 local-firstlocal-first 可以理解为系统的核心控制能力尽量运行在用户自己的环境中 而不是完全依赖远程平台。OpenClaw 的官方 README 把 Local-first Gateway 放在 Highlights 的第一项说明 Gateway 是整个系统中非常关键的控制平面。Gateway 负责管理 sessions、channels、tools 和 events。(GitHub)这带来两个直接影响。第一用户的数据和工作区更接近本地环境。OpenClaw 更像一个围绕个人设备和个人渠道运行的助手而不是一个单纯的云端聊天服务。第二安全问题会变得更加重要。因为 Agent 一旦能够操作本地工具、读取写入文件、处理真实消息入口就必须考虑权限、沙箱、远程暴露、DM 来源、工具访问边界等问题。官方 README 也明确提醒OpenClaw 会连接真实消息入口入站私信应该被视为不可信输入。(GitHub)所以local-first 不是单纯的部署方式而是影响 OpenClaw 架构设计的核心理念。5. 从整体上看 OpenClaw 的架构如果先不看具体代码OpenClaw 可以抽象成下面这条链路用户消息入口 ↓ Channel Adapter ↓ Gateway ↓ Session / Routing ↓ Agent Runtime ↓ Model / Tools / Skills ↓ 结果返回 ↓ Channel Adapter ↓ 用户收到回复其中每一层大概可以这样理解Channel 负责接入不同消息平台例如 Telegram、Slack、Discord、微信、QQ、WebChat 等。 Gateway 负责统一管理消息、会话、工具、事件和系统控制是整个系统的控制中心。 Session 负责区分不同会话、不同用户、不同上下文。 Agent Runtime 负责真正组织模型调用、工具调用、技能加载和任务执行。 Tools 让 Agent 可以执行具体动作例如浏览器、Canvas、节点、定时任务、会话工具、Discord / Slack 动作等。 Skills 通过技能文件扩展 Agent 的行为和知识。 Sandbox 为非 main session 或高风险上下文提供隔离运行环境。官方 README 中提到OpenClaw 的 First-class tools 包括 browser、canvas、nodes、cron、sessions 以及 Discord / Slack actionsskills 则通过 onboarding 和 bundled / managed / workspace skills 等方式进入系统。(GitHub)这说明 OpenClaw 的 Agent 能力不是写死在一个对话函数里而是通过工具、技能、会话和配置不断扩展。6. Gateway 是什么Gateway 是理解 OpenClaw 的第一个关键词。官方 README 明确说The Gateway is just the control plane — the product is the assistant.也就是说Gateway 本身不是最终产品形态而是整个助手系统背后的控制平面。它负责把不同渠道、不同会话、不同工具和不同事件连接起来。(GitHub)可以把 Gateway 想象成一个“中枢”Telegram 发来的消息 Slack 发来的消息 WebChat 发来的消息 移动端节点发来的事件 本地 CLI 发来的命令 ↓ Gateway ↓ 统一路由到 Agent / Session / Tools如果没有 Gateway系统中的各个能力会变得很分散。每个渠道都要自己处理模型调用、会话、工具、鉴权和安全控制系统会很难维护。有了 Gateway 之后不同入口都可以统一进入控制平面再由 Gateway 进行分发和管理。所以源码阅读时Gateway 应该是后续重点分析对象之一。7. Channel 是什么Channel 可以理解为 OpenClaw 和外部消息平台之间的适配层。用户可能不想打开一个专门的网页聊天界面而是希望直接在自己熟悉的平台上和助手交互。例如 Telegram、Slack、Discord、微信、QQ 或 WebChat。OpenClaw 支持多种渠道官方 README 列出了 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、微信、QQ、WebChat 等。(GitHub)所以 Channel 的价值是把不同平台的消息格式转换成 OpenClaw 内部可以统一处理的消息事件 再把 Agent 的回复转换成对应平台可以发送的消息。可以写成外部平台消息 ↓ Channel Adapter ↓ OpenClaw 内部消息格式 ↓ Gateway / Agent 处理 ↓ OpenClaw 内部回复 ↓ Channel Adapter ↓ 外部平台展示后续源码解析时Channel 接入机制会是一个单独的大模块。8. Agent 是什么Agent 是 OpenClaw 中真正执行智能任务的部分。如果 Gateway 是控制平面Channel 是消息入口那么 Agent 就是负责理解用户请求、组织上下文、调用模型、使用工具和技能完成任务的核心执行者。从功能上看Agent 至少要处理几个问题1. 当前用户说了什么 2. 这属于哪个 session 3. 是否需要读取历史上下文 4. 是否需要使用某个 skill 5. 是否需要调用 tool 6. 应该调用哪个模型 7. 模型输出应该如何返回给用户也就是说Agent 并不只是“调用一次大模型 API”。它更像一个调度器用户请求 ↓ 上下文组织 ↓ 技能加载 ↓ 工具选择 ↓ 模型调用 ↓ 结果整理 ↓ 回复用户这也是 OpenClaw 和普通聊天应用最大的区别之一。9. Tools 是什么Tools 是让 Agent 从“会说话”变成“能做事”的关键。如果没有工具模型最多只能生成文本回答。有了工具之后Agent 可以进行更多动作例如浏览网页、操作 Canvas、调用节点、处理定时任务、管理 sessions或者执行 Discord / Slack 相关动作。官方 README 将这些称为 First-class tools。(GitHub)可以这样理解模型本身负责判断和规划 Tools 负责真正执行外部动作。这和我们之前分析ai_agent项目中的 Tool Calling 很像但 OpenClaw 的工具系统更复杂因为它面向的是一个本地优先、多渠道、多会话的个人助手系统。后续源码阅读时Tools 系统要重点关注几个问题1. Tool 在源码中如何定义 2. Tool schema 如何暴露给模型 3. 模型如何选择工具 4. 工具结果如何返回模型 5. 高风险工具如何限制权限 6. Sandbox 如何影响工具执行10. Skills 是什么Skills 可以理解为 OpenClaw 的能力扩展机制。工具更偏“动作”例如打开浏览器、操作 Canvas、管理 session。而技能更偏“知识、行为规则和任务模板”通常通过文件组织起来让 Agent 在特定任务中获得额外指令或能力。官方 README 提到 OpenClaw 支持 bundled / managed / workspace skills并且 onboarding 流程也会涉及 skills。(GitHub)可以先这样区分Tool 让 Agent 能执行某个动作。 Skill 让 Agent 知道如何处理某类任务。举个例子Tool 像是“浏览器”“文件编辑器”“会话管理器”。 Skill 像是“如何写周报”“如何整理邮件”“如何处理某个工作流”。后续源码阅读时需要重点关注1. skills 目录如何组织 2. SKILL.md 如何被加载 3. skill 内容如何进入 prompt 4. workspace skills 和 bundled skills 有什么区别 5. skill 是否会带来 prompt injection 或权限风险11. Sandbox 为什么重要OpenClaw 这种系统必须重视安全。因为它不是一个只生成文本的聊天机器人。它可能连接真实消息入口可能调用工具可能读写文件可能接入设备节点甚至可能处理用户的私人渠道消息。官方 README 中的安全模型部分说明默认情况下main session 的工具运行在宿主机上对于 group / channel safety可以设置agents.defaults.sandbox.mode: non-main让非 main sessions 在 sandbox 中运行。Docker 是默认 sandbox backend同时也支持 SSH 和 OpenShell backends。(GitHub)这段信息非常关键。它说明 OpenClaw 并不是简单地“所有东西都在同一个权限下运行”而是区分 main session 和 non-main session并为更高风险的会话提供沙箱机制。可以这样理解main session 更像用户本人直接使用助手默认工具运行在宿主机上。 non-main session 更像来自群聊、频道或外部入口的会话更适合放入 sandbox 中隔离。官方 README 还列出了典型 sandbox 默认允许和拒绝的工具类型。例如允许 bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn拒绝 browser、canvas、nodes、cron、discord、gateway 等。(GitHub)这说明 Sandbox 是后续源码解析中非常重要的一期尤其适合结合安全角度展开。12. 从仓库结构看项目复杂度OpenClaw 仓库不是一个简单的单目录项目。从 GitHub 页面可以看到它包含多个顶层目录例如apps config deploy docs extensions packages qa scripts security skills src test ui这些目录说明 OpenClaw 至少包含应用端、配置、部署、文档、扩展、共享包、质量保障、安全、技能、核心源码、测试和 UI 等多个部分。(GitHub)从源码阅读角度可以先这样理解src 核心运行时代码后续重点分析。 extensions 不同渠道或插件扩展相关代码。 skills 内置或示例技能相关内容。 packages 共享包或内部模块。 apps 桌面端、移动端或伴随应用相关代码。 ui 控制台、Canvas 或可视化界面相关代码。 security 安全策略、扫描或安全配置相关内容。 docs 官方文档和架构说明。 test / qa 测试和质量保障。第一期先建立这个目录地图后续阅读源码时才不会迷路。13. 推荐的源码阅读顺序这个项目不适合一开始就从某个文件开始逐行读。更合理的顺序是先看主链路再看模块细节。我建议按照下面顺序阅读第一步README 和文档 先搞清楚项目定位、安装方式、核心概念和安全提醒。 第二步package.json 和 openclaw.mjs 理解 CLI 命令入口在哪里openclaw 命令如何启动。 第三步Gateway 相关源码 理解控制平面如何启动、如何管理 session、channel、tools 和 events。 第四步Channel 相关源码 理解不同消息平台如何接入外部消息如何转换成内部事件。 第五步Agent Runtime 理解用户消息进入后Agent 如何组织上下文、调用模型、使用工具和技能。 第六步Tools 系统 理解工具如何定义、注册、执行以及结果如何返回模型。 第七步Skills 系统 理解技能文件如何被发现、加载并影响 Agent 行为。 第八步Sandbox 与安全 理解 main / non-main session 的权限差异以及工具隔离机制。 第九步UI / Canvas / Apps / Nodes 理解可视化界面、Canvas、移动端节点和伴随应用如何接入 Gateway。这个顺序的好处是先看系统主干再看能力扩展最后看安全和多端形态。14. 本系列建议分期整个 OpenClaw 源码解析可以分成下面这些期第一期项目总览与源码阅读路线 第二期源码运行与开发环境 第三期仓库目录结构解析 第四期CLI 入口与 openclaw 命令 第五期Gateway 核心机制 第六期配置系统解析 第七期Session 会话模型 第八期模型调用链路 第九期Channel 接入机制 第十期消息处理主链路 第十一期Tools 系统源码解析 第十二期Skills 系统源码解析 第十三期Sandbox 安全模型 第十四期Canvas 与 UI 第十五期移动端与 Nodes如果后续还想继续深入可以扩展为第十六期多 Agent 路由机制 第十七期语音唤醒与 Talk Mode 第十八期安全风险与加固建议 第十九期如何开发一个自己的 Skill 第二十期如何开发一个自己的 Channel这样整个系列既能覆盖源码也能覆盖扩展开发和安全分析。15. 本期重点理解这一期最重要的是先建立 OpenClaw 的整体认识。可以总结为五点第一OpenClaw 是一个运行在用户自己设备上的个人 AI 助手系统而不是普通网页聊天机器人。 第二Gateway 是控制平面负责统一管理 sessions、channels、tools 和 events。 第三Channel 负责连接外部消息平台让用户可以通过 Telegram、Slack、Discord、微信、QQ、WebChat 等入口与助手交互。 第四Tools 和 Skills 是 Agent 能力扩展的两个关键机制Tools 更偏动作执行Skills 更偏任务能力和行为规则。 第五Sandbox 是 OpenClaw 安全模型的重要组成部分尤其适合隔离来自非 main session 的高风险任务。一句话概括OpenClaw 的核心价值是把大模型从“聊天窗口里的回答者”扩展成“运行在个人设备上、接入多渠道、具备工具和技能、需要安全边界的本地优先 AI 助手”。16. 本期小结本期主要对 OpenClaw 项目做了整体介绍。OpenClaw 是一个运行在用户自己设备上的个人 AI 助手能够通过多种消息渠道与用户交互并通过 Gateway 统一管理会话、渠道、工具和事件。与普通 Chatbot 相比OpenClaw 更强调 local-first、多渠道入口、任务执行能力、技能扩展和安全隔离。源码层面上它包含src、extensions、skills、packages、apps、ui、security、docs等多个目录说明它是一个完整的 Agent 系统工程而不是一个简单模型调用 Demo。这一期可以用一句话总结阅读 OpenClaw 源码不能只看模型调用函数而要从 Gateway、Channel、Agent、Tools、Skills 和 Sandbox 这几个核心模块出发理解一个个人 AI 助手系统是如何被组织起来的。下一期可以继续分析OpenClaw 源码解析二源码运行与开发环境下一期重点讲如何准备 Node / pnpm 环境如何安装和启动 OpenClaw如何使用openclaw onboard、openclaw gateway status、openclaw gateway --port 18789 --verbose和openclaw agent --message跑通最小链路并为后续源码调试做准备。
