从零到精通
玩转 OpenClaw

API Key

一串像 sk-ant-xxx... 的密码。大模型公司靠它认人、计费。OpenClaw 用它替你调用模型。别泄露、别上传 GitHub。

终端 / 命令行

一个"打字让电脑干活"的黑窗口。Win 叫 PowerShell，Mac/Linux 叫 Terminal。OpenClaw 的命令都在这里敲。

Node.js

一个能跑 JavaScript 的运行时。OpenClaw 是用它写的，所以你得先装它（免费、开源）。

端口（如 18789）

电脑上程序的"门牌号"。OpenClaw Gateway 默认开在 18789 号门，控制台从这门进出。

守护进程 / daemon

一直在后台跑的程序。Gateway 就是个守护进程——开机自启、默默常驻。

WebSocket

一种"长连接"网络协议。控制台、手机节点和 Gateway 之间靠它实时通信。

1. 1
   按章节顺序学

   入门 → 进阶 → 高手 → 自测。每章开头有"学完你能"，结尾有"动手实验室"。
2. 2
   动手做，别只看

   每章实验室的任务都真的去做一遍，看到"预期结果"才算过关。
3. 3
   跟着主线项目走

   每章末尾的"主线进度"会告诉你，你的私人助手 Molty 现在会什么了。
4. 4
   每章做完点"本章小测"

   巩固检验；全部学完做最后的总测，80% 以上算通关。

Node.js

22.22.3+ / 24.15+ / 25.9+（推荐 24）。node --version 检查

API Key

任一模型提供商（Anthropic / OpenAI / Google / DeepSeek …），onboard 时会问

内存

最低 4GB，推荐 8GB；跑本地大模型需 16GB+ / GPU

端口

18789（Gateway 默认，仅本机）

1. 1
   运行 onboard 向导

   bash📋 复制

   openclaw onboard --install-daemon

   向导带你：选模型提供商 → 填 API Key → 配 Gateway → 装守护进程。可选步骤可跳过，之后用 openclaw configure 回来补。
2. 2
   确认 Gateway 在跑

   bash📋 复制

   openclaw gateway status   # 应看到监听 18789

3. 3
   打开控制台发消息

   bash📋 复制

   openclaw dashboard   # 浏览器打开 http://127.0.0.1:18789

   在 WebChat 里打一句话，收到 AI 回复 = 成功！🎉

核心内置 3 个：iMessage、Telegram、WebChat。其余 30+ 都是官方插件，一行命令装：openclaw plugins install @openclaw/<id>，或在 openclaw onboard / openclaw channels add 时按需装。

1. 1
   找 @BotFather 创建机器人

   Telegram 里搜 BotFather → /newbot → 起名 → 拿到 123456:ABC-DEF... 形式的 token。
2. 2
   写进配置

   ~/.openclaw/openclaw.json📋 复制

   {
     "channels": {
       "telegram": {
         "enabled": true,
         "botToken": "123456:ABC-DEF...",
         "dmPolicy": "pairing"
       }
     }
   }

3. 3
   重启 & 私聊

   bash📋 复制

   openclaw gateway restart

   去 Telegram 找你的 bot 发消息。首次会收到配对码（因为 dmPolicy=pairing），在终端 openclaw pairing approve 批准后即可对话。

支持多账号的渠道（WhatsApp/Discord/Telegram/Slack…）用 accountId 区分。每个号可路由到不同 Agent：

openclaw channels login --channel whatsapp --account biz

OpenClaw 把每条入站消息路由到一个会话。会话是上下文 + 历史 + 并发控制的容器。默认 DM 都汇入一个 main 会话，群按群隔离，cron 每次新建。

{
  "session": { "dmScope": "per-channel-peer" }
}

dmScope 取值：main(默认共享) / per-peer(按人) / per-channel-peer(按渠道+人，推荐) / per-account-channel-peer(再加账号)。

每个 Agent 一个工作区（默认 ~/.openclaw/workspace/）。首次会话时这些用户可编辑文件被注入系统提示：

这是最该认真写的文件。它决定 Agent 听起来像不像个真人。原则：短 > 长，锋利 > 含糊；放语气/态度/边界，别放流水账/安全政策堆砌。

# 我的灵魂

你叫 Molty，一只话痨但靠谱的太空龙虾。直球、不啰嗦、有主见。

## 语气
- 永远别用"很好的问题"、"我很乐意帮忙"、"绝对"开头。直接答。
- 一句话能说清就一句话。该详细时才详细。
- 允许自然幽默，别硬抖机灵。事情搞砸了会说"卧槽"。
- 我要做蠢事时直接喊停，有魅力地，但别粉饰。

## 边界
- 涉及花钱、删数据、发外部消息前先问我。
- 不确定就说不确定，别瞎编。
- 用中文回我，除非我用别的语言。

做那个凌晨两点你还愿意聊两句的助手。不是企业客服，不是马屁精，就是……靠谱。

USER.md

"我叫 XX，前端工程师，偏好 TypeScript，作息晚睡晚起。"——让 Agent 认识你

IDENTITY.md

名字/emoji/一句话定位，比 SOUL 更轻

AGENTS.md

操作规则："每次改代码前先跑测试"、"提交用 conventional commits"

TOOLS.md

工具使用偏好，不是工具开关（开关在 openclaw.json）

memory_search

混合检索（向量语义 + 关键词）。措辞不同也能找到

memory_get

读指定记忆文件或行范围

配了 embedding provider 即可用。默认用 OpenAI embeddings，也支持 Gemini/Voyage/Mistral/Bedrock/Ollama 等。
后端：内置 SQLite（默认，开箱即用）/ QMD（本地+重排）/ Honcho（跨会话用户建模）/ LanceDB。

openclaw memory status            # 看索引状态和 provider
openclaw memory search "部署相关"  # 命令行检索
openclaw memory index --force     # 重建索引

模型引用统一写 provider/model，例如 anthropic/claude-sonnet-4-6、openai/gpt-5、ollama/qwen3:8b。模型名带斜杠（如 OpenRouter 风格）要带 provider 前缀：openrouter/moonshotai/kimi-k2。

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["openai/gpt-5.4", "ollama/qwen3:8b"]
      }
    }
  }
}

配了 fallbacks 后，主模型请求失败（限流/宕机/超时）会自动按序试备用。还能做鉴权轮转。

1. 1
   装 Ollama 并拉模型

   bash📋 复制

   ollama pull qwen3:8b   # 或 llama3.3 / deepseek-r1 等

2. 2
   配 provider（Ollama 默认跑在 11434）

   ~/.openclaw/openclaw.json📋 复制

   {
     "models": { "providers": { "ollama": { "baseUrl": "http://127.0.0.1:11434" } } }
   }

3. 3
   混合策略（推荐）

   日常用云端快模型省钱，深度任务用大模型，离线兜底用本地。靠 failover 串起来。

openclaw skills search 日历        # 搜技能
openclaw skills install @oc/daily  # 装
openclaw plugins list              # 看已装插件
openclaw plugins install @openclaw/discord

Skills 加载层级（高优先在前）：工作区 skills/ → 项目 .agents/skills → 个人 ~/.agents/skills → 托管 ~/.openclaw/skills → 内置。Skill 用 frontmatter 的 flat name 暴露，放嵌套目录只是组织。

agentId

一个"大脑"——独立工作区 + agentDir + 会话库 + 人格

accountId

一个渠道账号实例（如 WhatsApp 的 personal / biz 两个号）

binding

把 (渠道, 账号, peer) 路由到某个 agentId

同 tier 内按配置顺序，第一个匹配的赢。binding 里写了多个 match 字段要全部满足（AND）。

配置在 ~/.openclaw/openclaw.json（JSON5，支持注释）。严格校验——未知键/类型错 Gateway 直接拒启，只有诊断命令可用。

改配置

openclaw onboard / openclaw configure / openclaw config get|set|unset / 网页 Config 标签 / 直接编辑

热重载

改文件自动生效；校验失败则保留旧配置，错误存 .rejected.<ts>

修复

openclaw doctor --fix 诊断+修复，保留 last-known-good

两桶规则

根级放基础设施，agents.defaults 放 Agent 行为

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

或用 Tailscale 组私有网络，更省心。远程仍需握手 + auth token。

Skill 就是一个 SKILL.md 指令包：frontmatter（名字、描述、触发场景）+ 正文步骤。Agent 在匹配场景时按需 read 它，照着干。

---
name: code-review
description: 审查 Git 改动，给出可执行的改进建议。在用户提交 PR 或说"review 一下"时使用。
---

# 代码审查流程
1. 先跑 git diff 看全部改动
2. 按风险排序：安全 > 数据丢失 > 逻辑 > 风格
3. 每条问题给：文件:行号 + 问题 + 具体改法
4. 别啰嗦风格问题，除非会引发 bug
5. 最后一句总评：能不能合并

一个大任务拆成几个独立子任务并行干（如：调研 + 实现 + 验证），用 sessions_spawn 派子 agent——它是推式完成，干完自动回来汇报，不用你轮询。

帮我调研 3 个竞品的功能、同时实现一个 demo 页面、再写测试。
三个子任务并行，完成后汇总结果给我。

插件能加工具 / 渠道 / 模型 provider / Hook。比 Skill 更底层——Skill 是提示词，插件是真代码。

openclaw plugins init my-plugin     # 生成脚手架
# 在 src/index.ts 里：
#   api.registerTool("hello", { ...schema }, async (params) => {
#     return { text: "你好，" + params.name };
#   });
openclaw plugins build
openclaw plugins install ./dist       # 装本地包

想写自己的客户端、做深度集成，得懂协议底层：

传输

WebSocket（默认 127.0.0.1:18789），文本帧 + JSON

握手

第一帧必须是 connect，含设备身份 + auth；否则直接断

三类帧

req→res（请求响应）、event（服务端推送：agent/chat/presence/health…）

校验

TypeBox 定义 schema → 生成 JSON Schema → 生成 Swift 模型

幂等

send/agent 需带幂等 key，便于安全重试

覆盖入门 / 进阶 / 精通三档，答完看总分。题库可持续扩充（改 QUIZ 数组即可）。