OpenClaw (开源个人 AI Agent 框架 / “小龙虾”)

1. 定义

OpenClaw 是 2026 年爆火的开源、自托管、IM 优先的个人 AI Agent 框架；它的能力边界由”模型 + Skill”共同定义。前身 Clawdbot → Moltbot → OpenClaw，由 Peter Steinberger 于 2025 年末创建；2026 年 2 月其加入 OpenAI 后，项目移交开源基金会、转为社区驱动。

记忆钩子：把 OpenClaw 想成一家”公司”——Gateway 是总机门禁，内置工具是自家设备，Skills 是员工才艺，MCP 是租来的外部设备，模型是大脑。模型负责”想”，其余负责”干”。

2. OpenClaw vs Hermes：大脑与机器人（核心辨析）

这是最容易混的一对——它们是互补关系，不是竞品。一句话：Hermes 是被塞进 OpenClaw 的”大脑”，OpenClaw 是包住大脑的”身体 + 神经系统”。

维度	Hermes	OpenClaw
是什么	开源 LLM 系列（基座经 SFT 训出来的 Instruct 模型）	开源 Agent 框架 / harness（运行时 + 渠道 + 权限）
含不含模型	它就是模型	不含模型，模型是外接的”大脑”
负责什么	”想”：推理、决策、产出 function-calling	”干”：接消息、跑循环、调工具、管权限、回发
能否独立干活	不能——单独一个 Hermes 只会回答，不会自己收发 IM、跑脚本	不能——没有模型它不知道”想”什么
关系	作为后端引擎被 OpenClaw 调用	把任意 OpenAI 兼容模型（含本地 Hermes）当大脑
类比	发动机	整车底盘 + 方向盘 + 轮子 + 仪表盘

为什么这样分：OpenClaw 的 Agent Runtime 支持多种模型 provider，也能把自定义 OpenAI-compatible API 配成模型后端——今天用 Claude，明天换 DeepSeek，Gateway 和渠道层不用重装（见 §5.1）。反过来，Hermes 再强也只是模型权重，必须靠 OpenClaw 这类 harness 包一层，才变成微信/Telegram 里那个会接消息、调用工具的助理。

注意不要把两个方向混淆：

OpenClaw → 模型 API：OpenClaw 是客户端，主动调用 Claude/GPT/DeepSeek/vLLM；
外部客户端 → OpenClaw：Gateway 可选暴露 /v1/chat/completions 等兼容端点，让 Open WebUI 等客户端调用 OpenClaw Agent；该能力默认关闭，不是“模型能接进来”的原因。

对应 hermes.md §7.4「大脑 vs 机器人」；Gateway 兼容端点见 OpenClaw 官方说明。

3. 核心概念 / 能做什么

Gateway（网关）：中央神经系统，所有渠道消息的统一入口与调度中心。本质是 WebSocket 控制平面（默认 ws://127.0.0.1:18789，使用 JSON 消息），同一端口还承载 Control UI 和可选、默认关闭的兼容 HTTP endpoints。
Tools（工具）三类来源：内置工具（本地 TS 函数）、Skills（Markdown 指导 Agent 组合工具）、MCP（远程外部服务）。三者并列，按”是否涉敏感数据/是否复杂编排”选型。
Skills + ClawHub：Skill 是能力的”手脚”（按需加载，省 Token），ClawHub 是 Skill 应用商店（clawhub install）。
MCP 集成：接 Anthropic 开放标准 Model Context Protocol，把内部系统当”USB 外设”挂上，内部逻辑对 Agent 不可见。
ReAct 执行引擎：增强型 ReAct 循环驱动”思考→行动→观察”。

4. 工作原理（架构与消息流）

IM 渠道 (WhatsApp/Telegram/Slack…)
        │  消息进入
        ▼
   ┌─────────────── Gateway ───────────────┐
   │ · 多渠道聚合 · 路由 · 认证/权限          │
   │ · 会话管理 · 事件广播 · 资源协调        │
   └───────────────┬───────────────────────┘
                   │  RPC: agent / chat / channels / cron / config …
                   ▼
            AgentRunner
   System Prompt = AGENTS.md + SOUL.md + TOOLS.md + Skills段
                   │
                   ▼
             ReAct 循环 (pi-mono 引擎)
   思考 → ToolCall(内置工具/Skills/MCP) → 执行 → 观察 → 再思考
                   │
                   ▼
   Gateway 广播 agent.event → 渠道回发用户

工具执行生命周期：before_tool_call Hook（拦截/改参）→ 权限校验（allow/deny/ask）→ tool.execute() → after_tool_call Hook。
三层权限：AGENTS.md（员工手册）→ Tool Policies（部门权限 JSON）→ Runtime Permissions（现场审批）；Tool Profile 分 minimal / coding / messaging / full。
Skills 加载：6 级优先级（Extra Dirs → Bundled → Managed → Personal Agents → Project Agents → Workspace），仅把”名称+描述”注入 System Prompt，用到时才 read 完整内容，chokidar 热更新（250ms 防抖）省 Token。
MCP：JSON-RPC 的”发现→调用→返回”，内部机密不暴露给 Agent。

4.1 为什么放在 VPS 上就能 7×24 实时交互

VPS 是一台一直联网、一直开机的远程 Linux 电脑。安装 daemon 后，Linux 的 systemd 会在开机时启动 Gateway，并在配置允许时管理其重启；本地 Mac、SSH 窗口或浏览器关掉，不会结束 VPS 上的进程。

你在手机上发消息
        │
        ▼
Telegram / 飞书 / Discord 平台
        │
        │  long polling 或持久 WebSocket
        ▼
VPS：Channel Plugin
        │  标准化事件、校验 pairing/allowlist
        ▼
Gateway：路由到对应 Agent 和 Session
        │
        ▼
Agent Runtime
  ├── 主动 HTTPS 调用外部模型 API
  ├── 或调用 VPS 本地的 Ollama/vLLM
  └── 按策略调用文件、Shell、浏览器、MCP 等工具
        │
        ▼
Channel Plugin 调用平台 API 回发
        │
        ▼
你在聊天 App 中收到回复

所谓“实时”不是手机与 VPS 直接建立神秘连接，而是渠道插件长期等待消息事件，收到后立即触发 Agent。整体延迟由渠道传输、模型首 token、工具执行和回发时间共同组成。

4.2 为什么通常不需要开放入站端口

Linux 默认允许普通进程主动建立出站 socket；聊天渠道和模型调用大多也是 VPS 主动向外连接。因此“不弹网络授权”不等于没有权限，而是权限由 Linux 用户、Bot Token、API Key、pairing、Tool Policy、防火墙等层共同控制。

不同渠道的事件进入方式：

渠道/入口	默认或常见方式	谁先发起网络连接	是否要求 VPS 公网回调
Telegram	Long polling	VPS 主动请求 Telegram `getUpdates`	否
飞书/Lark	WebSocket	VPS 主动连接飞书	否
Discord 等	持久连接或平台特定 Gateway	VPS 主动连接平台	通常否
HTTP Webhook	平台向 VPS 发送 HTTPS 请求	平台主动访问 VPS	是，需要域名/TLS/反向代理
Control UI	浏览器连接 Gateway	用户设备主动连接 VPS	需要 SSH tunnel、Tailscale 或受保护反代

以 Telegram long polling 为例：

VPS ──“有新消息吗？没有就保持等待”──▶ Telegram
VPS ◀──────── 有消息时立即返回 ──────── Telegram
VPS ───────── 调用 API 回发 ──────────▶ Telegram

这三步都是 VPS 发起的出站 HTTPS，不需要开放 18789。飞书当前默认使用 WebSocket 长连接，同样不需要公网 URL；webhook mode 才需要公网入口。参见 Telegram channel 与 Feishu channel 官方文档。

5. 两个关键设计（原理层面）

5.1 模型无关 —— 为什么能”换国产模型”

Agent Runtime 通过 provider adapter 调用不同模型；自定义 provider 还可以指向 OpenAI-compatible baseUrl。配置的实质是提供认证信息、API 类型与模型目录，再把默认模型写成 provider/model（如 deepseek/deepseek-chat）。

推论：换”大脑”不用重装框架。今天 Claude、明天 DeepSeek/Qwen/GLM，只改 agents.defaults.model.primary 一处即可。国产模型（DeepSeek/Qwen/GLM）多为 OpenAI 兼容，国内直连、无需代理。

// 把默认模型换成 DeepSeek（最小示例：概念如此，具体字段以版本文档为准）
{ "models": { "providers": { "deepseek": { "apiKey": "sk-xxxxx" } } },
  "agents": { "defaults": { "model": { "primary": "deepseek/deepseek-chat" } } } }

还可设 fallback（主模型挂了自动切，如 Claude 额度用完切免费 Qwen）和 modelRouting（按 simple/complex/code 任务复杂度自动选模型）。

5.2 网络两个方向 —— 渠道连接不等于暴露 Gateway

出方向（egress）：Gateway 主动连接聊天平台、模型 API、MCP 或网页。海外 API 无法直连时，才考虑为进程设置 HTTP_PROXY/HTTPS_PROXY。
入方向（ingress）：浏览器、移动节点或 webhook 要主动连接 VPS。应使用 SSH tunnel、Tailscale，或带 TLS 与身份验证的反向代理。

从本机安全访问 VPS 上只绑定 loopback 的 Control UI：

ssh -N -L 18789:127.0.0.1:18789 user@vps

然后在本机打开：

http://127.0.0.1:18789

本机的 127.0.0.1:18789 经 SSH 加密通道连接 VPS 的 127.0.0.1:18789。Gateway 无需改绑 0.0.0.0。SSH 隧道原理见 ../networking/ssh.md。

安全原则：聊天渠道能收到消息，不代表 Gateway 端口必须公开。Gateway 默认 loopback-first；非 loopback 绑定需要有效认证，但仍应优先使用 SSH/Tailscale/私网入口。官方 Network 文档

6. 典型工作流（高层，不是命令清单）

起 Gateway + 接一个模型后端（任意 OpenAI 兼容，可走 api_relay.md）。
clawhub install 装基础 Skill，把领域 Skill 丢进 Skills 目录。
写 AGENTS.md 定规范、配 Tool Policy 最小权限（呼应 agent_security.md）。
接 IM 渠道（Telegram 默认 long polling；飞书默认 WebSocket，二者均无需公网回调；选择 webhook 时才配置公网 HTTPS 入口）。
在 IM 里发指令 → Gateway 路由 → ReAct 循环调工具 → 结果回发；用 cron Skill 让它”主动干活”。

7. 常见误区

❌ “OpenClaw 自带模型” → 错。它是框架/脚手架，模型是外接的”大脑”（见 §2）。
❌ “没装 Skill 也能干活” → 默认只会对聊/生成文本；联网、跑命令、定时都要靠 Skill 或 MCP。
❌ “装越多 Skill 越好” → 上下文膨胀 + 安全风险；按场景装、配最小权限。
❌ “MCP 和内置工具二选一” → 二者并列，按”是否涉敏感数据”选型：敏感用 MCP，简单用内置，复杂编排用 Skills。
❌ “飞书一定要开放公网 webhook” → 当前官方插件默认用 WebSocket，由 Gateway 主动连飞书；只有显式选择 webhook mode 才需要公网回调。
❌ “前台终端跑 Gateway 就行” → VPS 自用要 7×24，应安装为 systemd daemon；nohup 只适合临时测试，macOS 本机才使用 launchd。
❌ “换模型要重装 OpenClaw” → 只改配置一处，重启 Gateway 即可（见 §5.1）。
❌ “模型名写成 deepseek-chat” → 必须 deepseek/deepseek-chat（提供商/模型），否则 Unknown model。
❌ “国产模型也要翻墙” → DeepSeek/Qwen/GLM 国内直连，配 Forward Proxy 反而绕路。
❌ “网关直接 0.0.0.0 暴露公网” → 裸端口等于把执行系统送上门；始终绑 127.0.0.1，靠 VPN/反代进（见 §5.2）。
❌ “OpenClaw 能直接当多客户 SaaS 底座” → 缺多租户/用户管理/计费/限流，需自建一层。
❌ “自动化发帖能规模化代运营” → 管自己号 OK；批量代发必踩平台风控/封号（见 xiaohongshu_agent.md §7）。
❌ “部署完就高可用” → 单 Gateway 本地进程，无内置 HA/监控；自用够，当生产不够。

8. 定位：自用 MVP，不是生产后端

一句话：OpenClaw 最适合 = 自用运营工具 / 需求验证 MVP，不是直接当多租户生产后端。

维度	自用运营（本场景）	多客户生产后端
隔离	单用户，无需租户隔离	需多租户隔离 + 用户管理
扩缩	单 Gateway 够用	需横向扩展 + 负载均衡
计费	自己付模型/服务器费	需计量计费体系
合规	管自己号，风控自己扛	代发必踩平台风控 / 封号
高可用	进程挂了重启即可	需 HA + 监控 + 告警

场景举例：运营你自己的号（如小红书，见 xiaohongshu_agent.md），用 OpenClaw + Skills 把发帖/互动/数据回收自动化。验证需求后，若要做成产品，再把核心逻辑抽成自己的服务。

9. 延伸阅读 / 关联概念

hermes.md：关系（大脑 vs 机器人）——OpenClaw 是”整机”，Hermes 是被塞进去的”大脑”。Agent Runtime 可通过本地推理服务调用 Hermes；单独一个模型不会自己收发 IM 或跑脚本，必须靠 OpenClaw 这类 harness 包一层。
agent_harness.md：框架负责执行/权限/渠道，模型只负责决策
tool_calling.md：Tool Call = 模型的 function calling，OpenClaw 用它统一抹平各厂商差异
skills.md：Skill 作为 Agent 能力扩展的通用机制
mcp.md：Model Context Protocol，“AI 世界的 USB 接口”
foundation_model.md：模型是怎么从基座变成能用的 Instruct 模型的
agent_security.md：提示词注入 = 注入漏洞的 AI 版；最小权限
api_relay.md：中转站/网关，把兼容端点做成服务端；OpenClaw 的 base_url 可指过来
../networking/ssh.md：从本机安全进入 VPS、建立 Control UI 本地端口转发
OpenClaw Gateway / Network 官方文档：loopback、远程访问与 Gateway 网络边界
xiaohongshu_agent.md：把 xiaohongshu-mcp-skills 挂进 OpenClaw，运营你自己的小红书号（§8 自用 MVP 的落地例子）

第二大脑 / Knowledge Bank

探索

openclaw