OpenClaw 不是"另一个 ChatGPT 桌面端"，也不是 LangChain 的竞品。它的本质是"AI-Native 消息网关 + 本地 Agent Runtime" ------单进程 Node.js 22+ / TypeScript 跑一个长期守护（默认 127.0.0.1:18789WebSocket），把所有 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 沙箱 + 上下文预算 三件事。
yaml
# ~/.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: trueSkill 的 metadata.openclaw.requires声明能力依赖 ：
yaml
# skills/downloads-cleaner/SKILL.md 头部
---
name: downloads-cleaner
description: 每周扫描 Downloads，按扩展名+语义分类 PDF/Papers、dmg zip/Setups、图片/Img，超 30d 移 Trash
metadata:
openclaw:
requires:
capabilities: ["filesystem"]
---三个开发者会踩的坑：
- 路径白名单 ：OC 默认禁止访问桌面/下载，需要在
scanPath或extraDirs显式声明，否则报Local media path is not under an allowed directory。 - sandbox 不继承 host 的
process.env------上面SCAN_DIR这类变量要么写agents.defaults.sandbox.docker.env，要么打到 sandbox 镜像里 。 - 上下文预算 ：Memory hybrid search 默认上限 2000 tokens，Skills 按"名片"级注入（每 skill <100 字），所以这个归类 Skill 的 description 写烂了也不会炸上下文，但如果你一次性
enabled: true五十个 skill 又不分层，token 预占直接爆------三级渐进披露就是为解这个的 。
🦞 场景二：代码巡检 Skill ------ Agent Loop + config 结构拆给你看
这是 OC 比"Cursor + 终端"更适合做团队机器人的地方：多 repo、多模型、多 channel 共享同一个 Agent 上下文。
yaml
# 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 是生产级用法 ：
yaml
channels:
feishu:
groups:
"-100123456": # 公开群
tools:
profile: "minimal"
allow: ["web_search"]
"-100987654": # 内部开发群
tools:
profile: "coding" # 允许 exec / file write
users:
"admin_user":
tools:
profile: "full" # 全权限三层安全防线 ：
- Tool Policy Engine 前置过滤（上面的 profile 就是这层）
- Docker 沙箱 隔离 exec（尤其是
system-exec这种高危 skill 默认关掉） - 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 假死。
调试顺序（按命中率排）：
- **
openclaw doctor --fix** ------ 自动修 config schema 不兼容、坏路径、card 状态。它本质是读~/.openclaw/credentials/+ config.json 做一致性校验，不是玄学。 - skill 热加载坑 ：
~/.openclaw/skills/下放 symlink 指向/Projects/manager/skills会被拒，log 出Skipping escaped skill path outside its configured root------必须在skills.load.allowSymlinkTargets显式白名单 。这是开发者把 skill 仓库放 git 根目录时的经典踩坑。 extraDirs的 containment 边界 ：每个 skill root 是 containment boundary，symlink escape 会被 skip，设计意图是防止~/Projects下随便一个目录被当成 skill 加载造成路径泄漏------安全设计不是 bug。npm error 128（git+ssh 连 GitHub 22 端口超时）------国内装 OC 或 clawhub 拉 skill 时高发，git 全局切url."https://github.com/".insteadOf "git@github.com:"能解。web_search默认不可用 提示"缺 Brave API key"------这里要再拆一次产品角色，Brave Search API 不是 OC 内置能力，是web-searchskill 的外部依赖 ，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-searchskill 的外部依赖，不在 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 被截。