OpenClaw on Last Stand

OpenClaw 源码导读（三）：Agent Harness — 为"每一家 LLM 都能兜住"而生的执行管线

Sat, 02 May 2026 22:32:27 +0800

系列第一篇把 OpenClaw 的架构地图摊开，第二篇深入 Gateway 控制平面。这一篇，我们钻进整个项目的心脏——src/agents/，看 OpenClaw 怎么处理最复杂的一件事：当 Gateway 接到一条用户消息之后，怎么把它变成一轮真正的 LLM turn + Tool 循环。

这一层代码的体量和复杂度非常惊人：

src/agents/pi-embedded-runner/run.ts 单文件 2160 行，是整个 agent 循环的驱动器。

src/agents/pi-embedded-runner/compact.ts 1148 行，专门处理上下文压缩。

整个 src/agents/ 目录有 830+ 个文件，光 anthropic-*.ts 就有近 20 个（为了 Messages API 的各种 edge case）。

同时支持 Anthropic、OpenAI、Google Gemini、Bedrock、Vertex、OpenRouter、Z.AI/GLM、MiniMax、Qwen、Ollama、Kilocode 等十多个 provider。

但这些"量"的背后，是一个只有一个接口的核心抽象：AgentHarness。本文就从这个抽象出发，一路看到 2160 行循环如何处置真实世界里十几类失败。

一、Harness 抽象：只有一个 `runAttempt`

1. 为什么不用 LangChain 风格的"Agent Framework"

读过 LangChain 或 CrewAI 的人第一眼会期望看到 AgentExecutor、AgentChain、Memory、Callback、Tool 这些类。OpenClaw 里一个都没有。

它的选择是：把整个 agent 循环当成一个黑盒，对外只暴露一个接口：

export type AgentHarness = {
 id: string;
 label: string;
 pluginId?: string;
 supports(ctx: AgentHarnessSupportContext): AgentHarnessSupport;
 runAttempt(params: AgentHarnessAttemptParams): Promise<AgentHarnessAttemptResult>;
 compact?(params: AgentHarnessCompactParams): Promise<AgentHarnessCompactResult | undefined>;
 reset?(params: AgentHarnessResetParams): Promise<void> | void;
 dispose?(): Promise<void> | void;
};

五个方法，其中三个可选：

OpenClaw 源码导读（四）：Channels、Nodes 与扩展生态

Sat, 02 May 2026 22:32:27 +0800

前三篇我们看清了 OpenClaw 的三副骨架：架构全景、Gateway 控制平面、Agent Harness 执行管线。这一篇是压轴篇，我们看它的"血肉"——channels/、node-host/、canvas-host/、plugins/、skills/、sandbox/。OpenClaw 真正"好用"的感觉，是从这一层来的：一条消息从 WhatsApp 进来、触发 iOS 上的摄像头、在 Android 上渲染一张 Canvas、最后把结果发回 Slack 线程——整个过程中 Gateway 本身一行代码都不需要改。

本文涵盖 118 个 channel/provider extension、53 个 skill、iOS/macOS/Android node 客户端、A2UI Canvas 协议、以及 Docker sandbox 的整套隔离模型。

一、Channels：118 个 extension 是怎么"插"进来的

1. ChannelPlugin 接口

OpenClaw 所有 channel（微信、Telegram、Slack、iMessage、IRC、Discord……）本质上都是实现同一个接口 ChannelPlugin：

export type ChannelPlugin<ResolvedAccount = any, Probe = unknown, Audit = unknown> = {
 id: ChannelId;
 meta: ChannelMeta;
 capabilities: ChannelCapabilities;
 defaults?: {
 queue?: {
 debounceMs?: number;
 };
 };
 reload?: { configPrefixes: string[]; noopPrefixes?: string[] };
 setupWizard?: ChannelPluginSetupWizard;
 config: ChannelConfigAdapter<ResolvedAccount>;
 configSchema?: ChannelConfigSchema;
 setup?: ChannelSetupAdapter;
 pairing?: ChannelPairingAdapter;
 security?: ChannelSecurityAdapter<ResolvedAccount>;
 groups?: ChannelGroupAdapter;
 mentions?: ChannelMentionAdapter;
 outbound?: ChannelOutboundAdapter;
 status?: ChannelStatusAdapter<ResolvedAccount, Probe, Audit>;
 gatewayMethods?: string[];
 gateway?: ChannelGatewayAdapter<ResolvedAccount>;
 auth?: ChannelAuthAdapter;
 approvalCapability?: ChannelApprovalCapability;
 elevated?: ChannelElevatedAdapter;
 commands?: ChannelCommandAdapter;
 lifecycle?: ChannelLifecycleAdapter;
 secrets?: ChannelSecretsAdapter;
 allowlist?: ChannelAllowlistAdapter;
 doctor?: ChannelDoctorAdapter;
 bindings?: ChannelConfiguredBindingProvider;
 conversationBindings?: ChannelConversationBindingSupport;
 streaming?: ChannelStreamingAdapter;
 threading?: ChannelThreadingAdapter;
 messaging?: ChannelMessagingAdapter;
 agentPrompt?: ChannelAgentPromptAdapter;
 directory?: ChannelDirectoryAdapter;
 resolver?: ChannelResolverAdapter;
 actions?: ChannelMessageActionAdapter;
 heartbeat?: ChannelHeartbeatAdapter;
 agentTools?: ChannelAgentToolFactory | ChannelAgentTool[];
};

这个接口一共有 40 多个可选的 adapter，每个对应一种能力：

OpenClaw 源码导读（二）：Gateway 控制平面 — 一条 WebSocket 连上所有人

Sat, 02 May 2026 22:32:27 +0800

在系列第一篇里我们看到，OpenClaw 的核心隐喻是 “Gateway 是控制平面”。它不存转储消息、不排队、不持久化事件流，而是一个长在 127.0.0.1:18789 上的状态化 RPC 服务器，所有客户端（CLI、macOS.app、iOS/Android Node、WebChat 浏览器、Canvas iframe）都靠一条 WebSocket 接入。

这一篇拆开控制平面的五个层面：

进程入口：CLI 怎么从 openclaw gateway 走到 Node 进程常驻

WebSocket 协议：握手帧、RPC 帧、Event 帧、状态快照与版本号

鉴权矩阵：Token / Password / Device Token / Bootstrap Token / Tailscale Whois / Trusted Proxy

Pairing：陌生客户端怎么合法加入（setup code、pairing store、allowFrom）

Session 模型：Session Key 组成规则、多 Agent 路由、Session ID 模糊匹配

注：下文所有 src/ 路径都指 openclaw/openclaw 仓库根下。

一、CLI 到 Gateway 的六段路径

第一篇概览过 src/entry.ts 和 src/cli/run-main.ts，这里按调用序重新画一遍，把每个关键函数在 graph 上标出来：

flowchart TD
A0["openclaw gateway --port 18789"] --> A1
A1["entry.ts
main guard + process.title"] --> A2
A2["normalizeEnv + enableCompileCache()"] --> A3
A3["ensureCliRespawnReady()
按需 spawn 子 Node"] --> A4
A4["parseCliContainerArgs
parseCliProfileArgs"] --> A5
A5["tryHandleRootVersionFastPath
tryHandleRootHelpFastPath"] -->|miss| A6
A6["runMainOrRootHelp → runCli(argv)"] --> B0
B0["run-main.ts
container? container in progress"] --> B1
B1["loadCliDotEnv (~/.openclaw/.env)"] --> B2
B2["assertSupportedRuntime (Node≥22.16)"] --> B3
B3["tryRouteCli（fast-path 子命令路由）"] -->|miss| B4
B4["buildProgram() + commander 注册"] --> B5
B5["installUnhandledRejectionHandler"] --> B6
B6["registerPluginCliCommandsFromValidatedConfig (lazy)"] --> B7
B7["program.parseAsync"] --> C0
C0["gateway 命令匹配 → gatewayCommandAction"] --> C1
C1["lock 文件 + 端口 acquire"] --> C2
C2["HTTP/WS server 启动"] --> C3
C3["channels/plugins/cron/canvas-host 启动"] --> C4["Ready"]

1. 为什么要自己 `spawn` 自己

ensureCliRespawnReady() 是 src/entry.ts 里最容易被忽视但非常重要的段落：

OpenClaw 源码导读（一）：架构总览 — 为"单个主人"而设计的 AI Gateway

Sat, 02 May 2026 22:32:27 +0800

2025 年 11 月，Peter Steinberger（PSPDFKit 创始人、前著名 iOS 社区人物）把自己折腾出来的个人 AI 助手 Molty 开源为 OpenClaw。短短几个月，仓库吃到 35 万+ star、93 个 release、360 多个 contributor，核心代码量在 TypeScript/Swift/Kotlin/Go/Python 之间横跨 40 多万行。它和 Claude Code、Codex CLI 乍看都是"跑在本地的 CLI Agent"，但设计哲学完全不同——Claude Code 是一个编程助手，OpenClaw 是一个长在你设备上的私人秘书：它挂在 WhatsApp/Telegram/iMessage/微信的 IM 客户端后面，能自己发消息、自己开浏览器、自己调用 iOS/Android 上的摄像头和麦克风。

本文是 OpenClaw 源码导读系列的第一篇，目标是把整个项目的"地图"摊开。先讲清楚它要解决什么问题、在怎样的信任模型下运行，再把仓库 100 多个顶层模块拎出来分类，最后给出后续系列文章的导航。

一、它到底是什么

1. 一句话定义

OpenClaw 官方给自己的定位是 “Personal AI Assistant. Any OS. Any Platform. The lobster way.” 翻译过来就是：一个在你自己设备上运行、从你自己现有的聊天工具里和你对话的个人 AI 助手。

这个定位里藏着三个关键差异：

Personal：它不是多租户 SaaS，也不是团队协作工具，而是单一主人的私人助手。整个信任模型就是为"只有一个 operator"优化的。
Any OS / Any Platform：Gateway 是 Node 进程，可以跑在 macOS/Linux/Windows(WSL2)、甚至 Fly.io/Docker/NAS 上；客户端包含 iOS/Android/macOS 原生 App，还有 Web Dashboard。
The lobster way：作者把它拟人化成一只太空龙虾 Molty，这是一个品牌/吉祥物层面的设计，但也反映了项目的"玩心"。

2. 和 Claude Code 对比：两个相似却完全不同的 CLI Agent

由于作者 Steipete 本身是 Claude Code 的重度用户和 Anthropic 的合作者，社区最常问的问题就是"和 Claude Code 有啥区别"。这里先画一张对比表：

OpenClaw on Last Stand

OpenClaw 源码导读（三）：Agent Harness — 为"每一家 LLM 都能兜住"而生的执行管线

一、Harness 抽象：只有一个 runAttempt

1. 为什么不用 LangChain 风格的"Agent Framework"

OpenClaw 源码导读（四）：Channels、Nodes 与扩展生态

一、Channels：118 个 extension 是怎么"插"进来的

1. ChannelPlugin 接口

OpenClaw 源码导读（二）：Gateway 控制平面 — 一条 WebSocket 连上所有人

一、CLI 到 Gateway 的六段路径

1. 为什么要自己 spawn 自己

OpenClaw 源码导读（一）：架构总览 — 为"单个主人"而设计的 AI Gateway

一、它到底是什么

1. 一句话定义

2. 和 Claude Code 对比：两个相似却完全不同的 CLI Agent

一、Harness 抽象：只有一个 `runAttempt`

1. 为什么要自己 `spawn` 自己