Gateway + Agent Loop + Skills 渐进披露：OpenClaw 工程化笔记

OpenClaw 不是"另一个 ChatGPT 桌面端"，也不是 LangChain 的竞品。它的本质是"AI-Native 消息网关 + 本地 Agent Runtime"——单进程 Node.js 22+ / TypeScript 跑一个长期守护（默认 127.0.0.1:18789 WebSocket），把所有 IM 渠道（WhatsApp / Telegram / 飞书 / Discord / Slack…）的消息抽象成统一事件，路由到 Agent Loop，Agent 再调模型 + Skills + Memory 闭环 。Peter Steinberger 做它的出发点，是解决"LangChain 能拼 LLM 调用链但不解决消息渠道接入、会话持久化、多用户隔离、执行审批"这套老问题 。

📌 顺手纠一个常见误解：Cherry Studio 是 OpenClaw 的宿主之一（Electron 模型聚合前端，里面能嵌 OC Gateway），但不是 OC 本体。OC 本体是那个 Node22+TS 单进程守护，Gateway / Agent / Skills / Memory 四个模块都在这里面跑 。

🧬 四层架构速读

层 角色 技术点
Gateway 单例守护，WS localhost:18789，持所有 channel 连接 TypeBox schema 校验、req/res/event 三种消息、Tailscale 隧道可选
Agent (Brain) 每个 agent 独立 SOUL.md 人格 + 上下文组装 Prompt = SOUL + AGENTS + TOOLS + Memory(hybrid search) + Skills(渐进) + History，送 LLM
Skills (Hands 的工具箱) YAML frontmatter + SKILL.md，三级渐进披露 名片→说明书→执行逻辑，按 数据 token 开销降 30-50%
Memory ~/.openclaw/memory/ 下 Markdown，混合检索 MEMORY.md 长期 + YYYY-MM-DD.md 日志

一次消息的生命周期：Channel → Gateway(Router 按 channel/peer 绑 agent) → Orchestrator 加载 Memory(hybrid search) → 拼 Prompt → LLM → tool calls → Hands(exec/file/browser/http) → 结果喂回 Brain（可能多轮 loop）→ 最终回复写 Memory → 原 channel 回包 。

🦞 场景一：Downloads 目录语义归类 —— Skill + sandbox 的工程化写法

别让龙虾裸奔。这个场景的技术关键点不在"归类逻辑"，而在 ACL 白名单 + Docker 沙箱 + 上下文预算 三件事。

# ~/.openclaw/config.yaml 相关片段
skills:
  entries:
    downloads-cleaner:
      enabled: true
      env:
        SCAN_DIR: "${HOME}/Downloads"
        TARGET_PAPERS: "${HOME}/Papers"
        TARGET_SETUPS: "${HOME}/Setups"
        STALE_DAYS: "30"
security:
  sandboxMode: true
  sensitiveDataFilter: true

Skill 的 metadata.openclaw.requires 声明能力依赖 ：

# skills/downloads-cleaner/SKILL.md 头部
---
name: downloads-cleaner
description: 每周扫描 Downloads，按扩展名+语义分类 PDF/Papers、dmg zip/Setups、图片/Img，超 30d 移 Trash
metadata:
  openclaw:
    requires:
      capabilities: ["filesystem"]
---

三个开发者会踩的坑：

  1. 路径白名单：OC 默认禁止访问桌面/下载，需要在 scanPath 或 extraDirs 显式声明，否则报 Local media path is not under an allowed directory 。
  2. sandbox 不继承 host 的 process.env——上面 SCAN_DIR 这类变量要么写 agents.defaults.sandbox.docker.env，要么打到 sandbox 镜像里 。
  3. 上下文预算：Memory hybrid search 默认上限 2000 tokens，Skills 按"名片"级注入（每 skill <100 字），所以这个归类 Skill 的 description 写烂了也不会炸上下文，但如果你一次性 enabled: true 五十个 skill 又不分层，token 预占直接爆——三级渐进披露就是为解这个的 。

🦞 场景二：代码巡检 Skill —— Agent Loop + config 结构拆给你看

这是 OC 比"Cursor + 终端"更适合做团队机器人的地方：多 repo、多模型、多 channel 共享同一个 Agent 上下文。

# config.yaml 片段
model:
  provider: openrouter
  apiKey: "${OPENROUTER_KEY}"
  defaultModel: "anthropic/claude-sonnet-4"
  parameters:
    maxTokens: 16384
    reserveTokensFloor: 20000   # 留 20k 给多轮 tool loop

skills:
  entries:
    code-review:
      enabled: true
      env:
        GITHUB_TOKEN: "${GH_TOKEN}"
    git-diff-summary:
      enabled: true
  load:
    extraDirs: ["/opt/team-skills"]   # 团队共享 skill 仓库 

agents:
  defaults:
    bootstrap: "AGENTS.md"     # 注入"你是团队代码 reviewer"人设
    tools: ["TOOLS.md"]        # 可用 tool 清单

AGENTS.md / SOUL.md / TOOLS.md 的注入顺序在 的 Prompt Assembly 表里写得明明白白：SOUL(200-1k) → AGENTS/TOOLS(100-500) → Memory hybrid search(上限 2k) → 活跃 Skills(每 skill 100-500) → History。所以 reserveTokensFloor 要算清楚：上面这组如果开了 5 个活跃 Skill + 2k Memory + 长 diff，不预留 20k 就会在 tool loop 中途被截断。

⚠️ 上一轮我提到"OpenRouter Auto 路由 3.22 无限递归刷定价"——更正归属：那是 OpenRouter 上层路由层的 bug，不是 OC 本体问题，OC 只是 consumer。OC 3.23+ 升了下兼容。

🦞 场景三：飞书 / Discord 当"社畜替身" —— Channel Adapter 解耦是关键

OC 的漂亮设计在这：渠道适配层和 Agent 执行层是切开的。Telegram / 飞书 / Discord / Slack / WhatsApp 协议各不一样（Baileys、grammY、飞书 WS 模拟…），但进了 Gateway 全变成统一消息结构，Agent 完全不感知"对面是哪个 IM" 。

按 sender / group 下发 tool profile 是生产级用法 ：

channels:
  feishu:
    groups:
      "-100123456":   # 公开群
        tools:
          profile: "minimal"
          allow: ["web_search"]
      "-100987654":   # 内部开发群
        tools:
          profile: "coding"   # 允许 exec / file write
    users:
      "admin_user":
        tools:
          profile: "full"     # 全权限

三层安全防线 ：

  1. Tool Policy Engine 前置过滤（上面的 profile 就是这层）
  2. Docker 沙箱 隔离 exec（尤其是 system-exec 这种高危 skill 默认关掉）
  3. Human-in-the-Loop 高危操作弹确认

飞书带附件 3.22 那个 bug 确实是 OC 侧（channel 插件走错路径），3.23 修了——所以生产跑 channel 插件先看 openclaw --version，低于 0.9.x 的飞书媒体先别上 。

🦞 场景四：龙虾"自救" —— 调试与运维的开发者笔记

OC 单进程模型的好处是部署简单（一个 binary 一个 config），坏处是所有蛋在一个 Node event loop 里——liveness warning 35s 通常是某个 tool call（比如 browser 或 exec 卡死）阻塞了 loop，不是 Gateway 假死。

调试顺序（按命中率排）：

  1. openclaw doctor --fix —— 自动修 config schema 不兼容、坏路径、card 状态。它本质是读 ~/.openclaw/credentials/ + config.json 做一致性校验，不是玄学。
  2. skill 热加载坑：~/.openclaw/skills/ 下放 symlink 指向 /Projects/manager/skills 会被拒，log 出 Skipping escaped skill path outside its configured root——必须在 skills.load.allowSymlinkTargets 显式白名单 。这是开发者把 skill 仓库放 git 根目录时的经典踩坑。
  3. extraDirs 的 containment 边界：每个 skill root 是 containment boundary，symlink escape 会被 skip，设计意图是防止 ~/Projects 下随便一个目录被当成 skill 加载造成路径泄漏——安全设计不是 bug。
  4. npm error 128（git+ssh 连 GitHub 22 端口超时）——国内装 OC 或 clawhub 拉 skill 时高发，git 全局切 url."https://github.com/".insteadOf "git@github.com:" 能解。
  5. web_search 默认不可用提示"缺 Brave API key"——这里要再拆一次产品角色，Brave Search API 不是 OC 内置能力，是 web-search skill 的外部依赖，API key 通过 skills.entries.web-search.env 或 .env 注入 。OC 本体只负责持 WS + 调模型 + 跑 Skill，联网搜这个能力在 skill 层。

🔍 逐个从技术栈角度拆一下

避免上篇那种"混着讲"的问题，这一轮出现的几个东西角色分明：

  • OpenClaw 本体：Node22+TS 单进程 Gateway + Agent Runtime + Skills + Memory，本地优先，模型无关（provider 抽象层后面可以挂 Anthropic/OpenAI/Ollama/OpenRouter/Bailian 任一个）。
  • Cherry Studio：Electron 套壳的"模型聚合前端"，其中一个用法是宿主 OC Gateway 给你一个 GUI 控制面 + 聊天窗口。它不是 OC 的必要组件，OC 可以 headless 跑（openclaw gateway --port 18789）只接 CLI / WS 客户端 。
  • OpenRouter：挂在 OC model.provider: openrouter 后面的模型路由层，负责把 "anthropic/claude-sonnet-4" 这类 slug 路由到真实 endpoint、做 fallback、计费。OC 侧只是一个 consumer，路由层 bug（比如前面说的 Auto 递归）OC 控制不了。
  • Brave Search API：web-search skill 的外部依赖，不在 OC 本体里，key 走 env 注入 。
  • ClawHub：Skill 注册中心，5700+ 社区 skill，clawhub install / outdated / update 是包管理器语义 。

几个判断

💡 OC 的真正竞争壁垒不是"能接 26 个 IM 渠道"（那是体力活），是 Gateway 单例 + Agent Loop + Skill 三级渐进披露 + Memory hybrid search 这套"让 LLM 住进消息流"的中间件范式 。对比 LangChain（问"怎么用代码调 LLM"）和 AutoGPT（问"怎么让 LLM 自主执行"），OC 问的是"怎么让 LLM 进 IM 且可控可信"——这是三类问题。

Token 消耗是真的大户，三个原因叠加：Agent Loop 多轮 tool call 每轮都重拼 Prompt（SOUL+AGENTS+Memory+Skills+History 全重算）、Memory hybrid search 每次都查、Skills 虽然渐进披露但"名片级"50 个也要占几百 token。所以 reserveTokensFloor + maxTokens + 模型选 128k 上下文是必调三件套，否则复杂任务跑到半路 Brain 被截。

posted @ 2026-06-25 13:31  睡不醒的技术人  阅读(2)  评论(0)    收藏  举报