OpenClaw 是一个 TypeScript ESM 项目，运行在 Node.js 22+ 之上，使用 pnpm 构建，可选 Bun 执行。整个系统是一个三层架构：

核心设计模式：Hub-and-Spoke（轮毂-辐条）。Gateway 是中心轮毂，所有 Channel Adapter 和工具执行都是辐条。

Gateway 是一个 单进程 WebSocket 服务器，默认绑定到 127.0.0.1:18789。使用 ws 库，所有 WebSocket frame 通过 JSON Schema（由 TypeBox 生成）验证。

关键约束：

Session Key 的格式是层级化的：

<rest> 的格式因会话类型和 scope 策略而异：

具体例子：

Session key 的段数不固定——DM 会话根据 dmScope（main/per-peer/per-channel-peer/per-account-channel-peer）生成不同层级的 key。

核心函数：

Session 状态以 append-only JSONL 格式持久化到 ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl，支持分支（branching），可用于恢复和对话树检查。

这是 OpenClaw 最精巧的设计之一。队列采用 lane-aware FIFO 架构，纯 TypeScript + Promises 实现，无外部依赖、无后台线程。

Lane 类型与默认并发上限：

核心保证："Only one agent run touches a given session at a time"——通过 per-session lane 实现。

消息处理模式（inbound message 如何与正在运行的 agent turn 交互）：

队列参数：

用户可通过 /queue <mode> 动态切换。

OpenClaw 内嵌了 @mariozechner/pi-agent-core（简称 Pi），通过 runEmbeddedPiAgent 函数驱动完整的 agentic loop。

循环的 4 个阶段：

循环终止条件：LLM 发送了纯文本响应（没有 tool_use block）= 任务完成。仓库层无 max-steps 限制，仍受 timeout 等运行时约束。

buildAgentSystemPrompt（src/agents/system-prompt.ts）组装多个 section，有三种模式：

Prompt 组件（按注入顺序）：

关键设计：空文件被跳过；大文件被裁剪并加截断标记。这种"文件即配置"模式让行为变更无需改源码——编辑 Markdown 文件即可。

resolveDefaultModelForAgent（src/agents/model-selection.ts）：

模型引用格式：provider/model（按第一个 / 分割）。

Failover 策略：

Auth Profile 轮换：resolveAuthProfileOrder 确定轮换顺序，isProfileInCooldown 检查冷却状态。

冷却参数（默认值）：

非 billing 错误的回退曲线：1min → 5min → 25min → 最大 1h（指数增长，5^n 分钟）。

当 session 接近 context window 上限时触发自动压缩。

触发阈值：contextWindow - reserveTokensFloor - softThresholdTokens

Memory Flush（压缩前的记忆冲刷）：

这是 OpenClaw 最巧妙的设计之一。在满足触发条件的情况下，compaction 发生前系统触发一个 silent agentic turn（对用户不可见），提醒模型将可持久信息写入 memory/YYYY-MM-DD.md（必要时再整理到 MEMORY.md）。模型通常以 NO_REPLY 开头回复，OpenClaw 的投递层会过滤掉这个前缀。

防重机制：session state 中跟踪 memoryFlushCompactionCount，防止同一 compaction 周期重复 flush。

核心函数：compactEmbeddedPiSession（src/agents/pi-embedded-runner/compact.ts）

createOpenClawCodingTools（src/agents/pi-tools.ts）将 Pi 核心工具与 OpenClaw 特有工具合并：

Pi 核心工具（来自 pi-agent-core）：

OpenClaw 扩展工具：

工具定义使用 TypeBox（JSON Schema with TypeScript types）声明。每个 tool result 携带 output（文本给 LLM）和 details（结构化数据给 UI 渲染）。

权限按 pipeline 顺序逐层过滤（每一层都可以收窄工具集）：

Tool 分组：

默认 Sandbox Policy（DEFAULT_TOOL_ALLOW）：允许 exec, process, read, write, edit, apply_patch, image, sessions_list, sessions_history, sessions_send, sessions_spawn, subagents, session_status；禁止 browser, canvas, nodes, cron, gateway 及各 channel 工具。注意：memory_search/memory_get 不在默认允许列表中。

Hook 是 TypeScript 模块，每个 Hook 目录包含 HOOK.md（文档）和 handler.ts（实现）。通过 jiti（运行时 TypeScript 加载器）加载，无需预编译。

生命周期 Hook：

内置 Hook 示例：

OpenClaw 的记忆哲学是 "文件即真理"——只有写入磁盘的内容才会被保留。

文件结构：

Session 日志：

索引存储：~/.openclaw/memory/<agentId>.sqlite（per-agent SQLite 数据库）

Chunking 策略：

同步触发器：

文件监听：MEMORY.md 和 memory/ 目录的 watcher，1.5s debounce。

如果 embedding provider/model/endpoint 指纹或 chunking 参数变化，整个索引重建。

这是记忆系统的核心引擎。两路搜索并行执行，结果合并。

Vector Search（searchVector() in src/memory/manager-search.ts:18-90）：

Keyword Search（searchKeyword() in src/memory/manager-search.ts:92-148）：

混合合并（mergeHybridResults() in src/memory/hybrid.ts:33-108）：

默认权重：vector 0.7, text 0.3。低于 minScore（0.35）的结果被过滤。最终返回 Top maxResults（默认 6）。

自动选择顺序：

超时设置：

Embedding 缓存：chunk embedding 缓存在 SQLite embedding_cache 表，最多 50,000 条，避免重索引时重复调用 API。

QMD Backend（memory.backend = "qmd"）：

Session Memory Indexing（实验性）：

每个 Skill 是一个目录，核心文件是 SKILL.md（Markdown + YAML frontmatter）：

必需 frontmatter 字段：

可选 frontmatter 字段：

metadata.openclaw 控制资格检查：

注意：parser 只支持 单行 frontmatter key，metadata 是 单行 JSON 对象。

三个加载位置，优先级从高到低：

额外路径通过 skills.load.extraDirs 加载，优先级最低。插件在 openclaw.plugin.json 中声明 skills 目录。

Session Snapshot：session 开始时快照 eligible skills，后续 turns 复用。Skills watcher（默认开启）监听 SKILL.md 文件变化，触发中途刷新。配置：skills.load.watch、watchDebounceMs。

环境变量 仅在未设置时注入，作用域是 per agent run，不是全局。运行结束后通过 applySkillEnvOverridesFromSnapshot() 的 restore 函数恢复 process.env。

每个 Channel Adapter 实现相同的接口：

WhatsApp 深入：Baileys 实现了 WhatsApp Web 协议的逆向工程——通过 WebSocket 直接与 WhatsApp 服务器通信，模拟网页端客户端。凭证存储在 ~/.openclaw/credentials/，使用多文件认证状态持久化。

iMessage 深入：需要 macOS，使用 AppleScript 与 Messages.app 交互。需要合适的签名权限。读取 Messages 数据库获取消息事件。

插件通过 openclaw.plugin.json 声明，Gateway 管理插件生命周期：

Plugin SDK（dist/plugin-sdk/）提供类型定义、验证工具和辅助函数。插件通过 api.registerTool(toolName, toolDefinition) 注册新工具。

配对审批：

审批数据存储在 ~/.openclaw/credentials/<channel>-allowFrom.json，与配置中的 allowlist 合并。

Per-agent 的 allow / deny 列表：

高风险工具（exec, browser, web_fetch, web_search）应限制给受信 agent。

openclaw security audit 命令检查：

--deep 启用实时 Gateway 探测；--fix 自动应用安全护栏。

沙箱针对的是 工具执行，而非 Gateway 本身。

Container 参数：

核心函数：

容器在 session 终止或 Gateway 重启时清理。Exec 工具通过 docker exec 将命令路由到容器。

沙箱化 session 无法访问：

底层使用 Chrome DevTools Protocol (CDP) 连接 Chromium 浏览器。Playwright 作为 CDP 之上的抽象层处理高级交互（click, type, snapshot, PDF）。

当 Playwright 不可用时：基本 screenshot 和 ARIA snapshot 仍然可用，但交互操作返回 501 错误。

Port 架构：

Agent 理解网页的方式——不是通过 CSS selector，而是通过 snapshot 生成的 numeric refs（数字引用）。

AI Snapshot（默认，需 Playwright）：

Agent 使用 openclaw browser click 12 操作元素。

Role Snapshot：

关键约束：refs 在页面导航后不稳定，必须重新生成 snapshot。

驱动你现有的 Chrome tabs：

支持组合等待条件：

执行模型：在 main session 中按固定间隔（默认 30 分钟）触发一次 agent turn。

HEARTBEAT.md：Agent 每次心跳时检查的 Markdown checklist。保持精简以减少 token 开销。

HEARTBEAT_OK 信号：如果没有需要注意的事项，agent 回复 HEARTBEAT_OK，Gateway 静默丢弃，不推送消息。

Rotating Heartbeat 模式：用单个心跳轮转检查（邮件、日历、任务对账、git 状态），根据每项的逾期程度决定优先级，替代多个独立 cron job。

使用 5-field cron 表达式 + timezone 支持，在精确时间触发。

Session 类型：

One-shot Reminder（--at）：

Cron（main session）通过 system events 集成——事件排队等待下次心跳投递，而非触发独立 run。这保持了 main session 的上下文连贯性。

Canvas 是 Gateway 直接服务的动态 Web 界面。通过 WebSocket 推送 UI 更新。

A2UI（Agent-to-UI）是开源格式，针对 agent 生成的可更新 UI 优化。当前版本 v0.8（Public Preview）。

渲染方式：

源码：src/canvas-host/a2ui/，bundle hash 由 pnpm canvas:a2ui:bundle 生成。

关键函数：

以下 3 个设计决策最能体现 OpenClaw 的工程取向。

OpenClaw 的设计刻意避免复杂的隐藏状态：

Session key 的拓扑结构（如 agent:main:main vs agent:main:telegram:dm:xxx）天然地编码了"谁在说话"和"它从哪里来"。实际权限由 sandbox mode 和工具策略（allow/deny 列表）共同决定，session key 提供的是会话拓扑信息，而非直接授权。这套设计让权限控制有了多层结构，而不需要一个独立的中心化 ACL 系统。

Markdown 是核心的行为接口，涵盖了大部分跟 LLM 直接交互的配置：

系统级配置（并发、沙箱、工具策略等）走 openclaw.json，系统提示词也包含代码层与配置层生成的内容。但 Markdown 的优势在于 LLM 天然擅长读写它，用它做行为配置比 JSON 或 YAML 对 Agent 更友好。

纯 TypeScript + Promise 实现的并发控制，没有 Redis，没有 RabbitMQ，没有 Worker Threads。通过 lane-aware FIFO 就解决了多 session 并发问题。这是工程品味的体现——能用简单方案解决的问题，不引入外部依赖。

OpenClaw 在 context window 快满时，会先触发一个 silent turn 让 agent 把可持久信息写入 memory 文件，然后再压缩。这个「先存档再遗忘」的思路值得了解，但需要说明：这不是 OpenClaw 的独创——Claude Code 和 Codex 都采用了类似的压缩前保存机制，这更像是行业趋同的工程实践。

同样，Markdown 文件（AGENTS.md、SOUL.md 等）作为 bootstrap context 一次性注入系统提示词，靠字符数上限截断——这个策略 Claude Code 对 MEMORY.md 的处理方式也基本相同（前 200 行注入，其余按需读取）。Skills 部分 OpenClaw 已经做了渐进式加载（元数据列表 + 按需读取 SKILL.md），与 Claude Code 的 Agent Skills 思路一致。