OpenClaw 完全指南

基于 docs.openclaw.ai 整理，2026-03-27 Content was rephrased for compliance with licensing restrictions

一、概览与快速入门

什么是 OpenClaw？

OpenClaw 是一个自托管的 AI 网关，将你常用的聊天应用（WhatsApp、Telegram、Discord、iMessage 等）连接到 AI 编程代理。你在自己的机器或服务器上运行一个 Gateway 进程，它就成为消息应用和 AI 助手之间的桥梁。

核心特点

自托管: 运行在你自己的硬件上，数据完全由你掌控
多通道: 一个 Gateway 同时服务 WhatsApp、Telegram、Discord 等多个平台
Agent 原生: 为编程代理设计，支持工具调用、会话管理、记忆和多代理路由
开源: MIT 许可证，社区驱动

适用人群

开发者和高级用户，希望拥有一个可以从任何地方发消息的个人 AI 助手，同时不放弃数据控制权。

快速入门

前置要求

Node.js: 推荐 Node 24，也支持 Node 22 LTS (22.14+)
API Key: 来自模型提供商（Anthropic、OpenAI、Google 等）
时间: 约 5 分钟

安装与启动

# 安装 OpenClaw（具体安装命令参见官方文档）
# 运行引导向导
openclaw onboard

# 或者使用配置向导
openclaw configure

启动后

Dashboard: 浏览器打开 http://127.0.0.1:18789/
远程访问: 可通过 Tailscale 或 SSH 隧道

环境变量（高级）

变量	用途
`OPENCLAW_HOME`	内部路径解析的主目录
`OPENCLAW_STATE_DIR`	覆盖状态目录
`OPENCLAW_CONFIG_PATH`	覆盖配置文件路径

工作原理

用户 → [WhatsApp/Telegram/Discord/...] → Gateway → AI Agent → 响应
                                            ↑
                                     Control UI (Web)
                                     CLI / macOS App

Gateway 是会话、路由和通道连接的唯一真实来源。

二、架构与协议

整体架构

OpenClaw 采用单一长驻 Gateway 架构，所有消息通道和控制面客户端都连接到这个 Gateway。

┌─────────────────────────────────────────────┐
│                  Gateway (守护进程)            │
│  - 维护 Provider 连接                         │
│  - 暴露 WebSocket API                        │
│  - JSON Schema 验证                          │
│  - 事件: agent, chat, presence, health, cron  │
├─────────────────────────────────────────────┤
│  Canvas Host:                                │
│  /__openclaw__/canvas/  (agent 可编辑 HTML)    │
│  /__openclaw__/a2ui/    (A2UI host)          │
└─────────────────────────────────────────────┘
         ↑ WebSocket          ↑ WebSocket
    ┌────┴────┐          ┌────┴────┐
    │ Clients │          │  Nodes  │
    │ (CLI/UI)│          │(设备端) │
    └─────────┘          └─────────┘

三类连接者

类型	说明	连接方式
Gateway	核心守护进程，每台主机一个	监听 `127.0.0.1:18789`
Clients	macOS App / CLI / Web Admin	WebSocket 连接
Nodes	macOS / iOS / Android / Headless 设备	WebSocket + `role: node`

通信协议

传输层

协议: WebSocket，文本帧 + JSON 载荷
握手: 第一帧必须是 connect
认证: 如果设置了 OPENCLAW_GATEWAY_TOKEN，connect 时必须携带匹配的 token

消息格式

请求: { type: "req", id, method, params }
响应: { type: "res", id, ok, payload | error }
事件: { type: "event", event, payload, seq?, stateVersion? }

幂等性

对有副作用的方法（send、agent）需要幂等键，Gateway 维护短期去重缓存，支持安全重试。

配对与本地信任

所有 WebSocket 客户端在 connect 时携带设备身份
新设备 ID 需要配对审批，Gateway 签发设备 token
本地连接（loopback）可自动审批
非本地连接需要显式审批
签名载荷 v3 绑定 platform + deviceFamily

远程访问

# 推荐: Tailscale 或 VPN

# 备选: SSH 隧道
ssh -N -L 18789:127.0.0.1:18789 user@host

同样的握手 + auth token 机制适用于隧道连接。可选启用 TLS + 证书固定。

运维要点

启动: openclaw gateway（前台运行，日志输出到 stdout）
健康检查: WebSocket health 方法
进程管理: 推荐 launchd (macOS) 或 systemd (Linux) 自动重启

关键不变量

每台主机只有一个 Gateway 控制一个 Baileys 会话
握手是强制的，非 JSON 或非 connect 的首帧会被硬关闭
事件不会重放，客户端需要在间隙时主动刷新

三、配置详解

配置文件位置

~/.openclaw/openclaw.json

如果文件不存在，OpenClaw 使用安全默认值。

最小配置示例

{
  "agents": { "defaults": { "workspace": "~/.openclaw/workspace" } },
  "channels": { "whatsapp": { "allowFrom": ["+15555550123"] } }
}

编辑配置的四种方式

方式	命令/操作
交互式向导	`openclaw onboard` / `openclaw configure`
CLI 单行命令	`openclaw config get/set/unset <path>`
Control UI	浏览器打开 `http://127.0.0.1:18789`，Config 标签页
直接编辑	编辑 `~/.openclaw/openclaw.json`，Gateway 自动监听变更

配置热重载

Gateway 监听配置文件变更，大多数设置无需重启即可生效。

重载模式

模式	行为
`hybrid`（默认）	安全变更即时热应用，关键变更自动重启
`hot`	仅热应用安全变更，需要重启时只记录警告
`restart`	任何变更都重启 Gateway
`off`	禁用文件监听，下次手动重启时生效

{
  "gateway": {
    "reload": { "mode": "hybrid", "debounceMs": 300 }
  }
}

哪些需要重启？

类别	需要重启？
Channels、Agent/Models、Automation、Sessions、Tools、UI	❌ 不需要
Gateway server (端口/绑定/TLS/HTTP)	✅ 需要
Infrastructure (discovery/plugins)	✅ 需要

环境变量

OpenClaw 读取环境变量的来源：

父进程环境变量
当前工作目录的 .env
~/.openclaw/.env（全局回退）

内联环境变量

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-...",
    "vars": { "GROQ_API_KEY": "gsk-..." }
  }
}

配置中引用环境变量

{
  "gateway": { "auth": { "token": "${OPENCLAW_GATEWAY_TOKEN}" } },
  "models": { "providers": { "custom": { "apiKey": "${CUSTOM_API_KEY}" } } }
}

规则：

仅匹配大写名称 [A-Z_][A-Z0-9_]*
缺失/空变量在加载时报错
用 $${VAR} 转义为字面量

Secret Refs（密钥引用）

支持三种来源：env、file、exec

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": { "source": "env", "provider": "default", "id": "OPENAI_API_KEY" }
      }
    }
  }
}

严格验证

配置验证失败时：

Gateway 不会启动
只有诊断命令可用：openclaw doctor、openclaw logs、openclaw health、openclaw status
运行 openclaw doctor --fix 自动修复

四、聊天通道

概述

OpenClaw 可以连接你已经在用的任何聊天应用。每个通道通过 Gateway 连接，文本在所有通道都支持，媒体和表情反应因通道而异。

内置通道

通道	说明	备注
WhatsApp	最流行，使用 Baileys 库	需要 QR 配对
Telegram	Bot API (grammY)	最快的设置方式，只需 bot token
Discord	Bot API + Gateway	支持服务器、频道和 DM
Signal	signal-cli	注重隐私
Slack	Bolt SDK	工作区应用
BlueBubbles	iMessage 推荐方案	macOS 服务器 REST API
iMessage (legacy)	旧版 macOS 集成	已弃用，新项目用 BlueBubbles
WebChat	Gateway 内置 Web UI	WebSocket 连接
IRC	经典 IRC 服务器	频道 + DM
Google Chat	HTTP webhook	企业应用

插件通道（需单独安装）

通道	说明
Feishu/飞书	WebSocket 连接
LINE	LINE Messaging API
Matrix	Matrix 协议
Mattermost	Bot API + WebSocket
Microsoft Teams	Bot Framework
Nextcloud Talk	自托管聊天
Nostr	去中心化 DM (NIP-04)
Synology Chat	NAS 聊天 webhook
Tlon	Urbit 消息
Twitch	IRC 连接
Voice Call	Plivo / Twilio 电话
WeChat/微信	iLink Bot 插件，QR 登录
Zalo	Zalo Bot API（越南）
Zalo Personal	Zalo 个人账号 QR 登录

关键要点

多个通道可以同时运行，OpenClaw 按聊天自动路由
最快上手：Telegram（简单 bot token）
WhatsApp 需要 QR 配对，磁盘状态较多
群组行为因通道而异
DM 配对和白名单出于安全考虑强制执行

配置示例

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } }
    },
    "telegram": {
      "botToken": "your-bot-token"
    }
  }
}

五、工具系统

概述

Agent 除了生成文本之外的所有操作都通过工具完成。工具让 Agent 能够读写文件、运行命令、浏览网页、发送消息和与设备交互。

内置工具

工具	功能
`exec` / `process`	运行 shell 命令，管理后台进程
`browser`	控制 Chromium 浏览器（导航、点击、截图）
`web_search` / `web_fetch`	搜索网页、获取页面内容
`read` / `write` / `edit`	工作区文件读写
`apply_patch`	多段文件补丁
`message`	跨所有通道发送消息
`canvas`	驱动 Node Canvas（展示、执行、快照）
`nodes`	发现和定位已配对设备
`cron` / `gateway`	管理定时任务、重启 Gateway
`image` / `image_generate`	图像分析 / 图像生成
`sessions_*` / `agents_list`	会话管理、子代理

工具权限控制

Allow / Deny 列表

{
  "tools": {
    "allow": ["group:fs", "browser", "web_search"],
    "deny": ["exec"]
  }
}

Deny 始终优先于 Allow。

工具配置文件（Profile）

Profile	包含工具
`full`	所有工具（默认）
`coding`	文件 I/O、运行时、会话、记忆、图像
`messaging`	消息、会话列表/历史/发送/状态
`minimal`	仅 `session_status`

工具分组

用 group:* 简写在 allow/deny 中引用：

分组	包含工具
`group:runtime`	exec, bash, process
`group:fs`	read, write, edit, apply_patch
`group:sessions`	sessions_list, sessions_history, sessions_send 等
`group:memory`	memory_search, memory_get
`group:web`	web_search, web_fetch
`group:ui`	browser, canvas
`group:automation`	cron, gateway
`group:messaging`	message
`group:nodes`	nodes
`group:openclaw`	所有内置工具（不含插件工具）

按 Provider 限制

{
  "tools": {
    "profile": "coding",
    "byProvider": {
      "google-antigravity": { "profile": "minimal" }
    }
  }
}

六、Skills 技能

概述

OpenClaw 使用 AgentSkills 兼容的技能文件夹来教 Agent 如何使用工具。每个技能是一个包含 SKILL.md（带 YAML frontmatter）的目录。

技能加载位置与优先级

<workspace>/skills        ← 最高优先级
~/.openclaw/skills        ← 中等优先级（本地/托管）
bundled skills            ← 最低优先级（随安装包附带）

同名技能按优先级覆盖。还可以通过 skills.load.extraDirs 配置额外目录。

多代理场景

每个 Agent 有自己的 workspace，因此 <workspace>/skills 是 per-agent 的
~/.openclaw/skills 是共享的，对同一机器上所有 Agent 可见
可通过 skills.load.extraDirs 添加共享技能包

SKILL.md 格式

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

（技能指令内容）

可选 frontmatter 字段

字段	说明
`homepage`	在 macOS Skills UI 中显示为 “Website”
`user-invocable`	`true/false`，是否暴露为用户斜杠命令（默认 true）
`disable-model-invocation`	`true/false`，是否从模型提示中排除（默认 false）
`command-dispatch`	设为 `tool` 时，斜杠命令绕过模型直接调用工具
`command-tool`	`command-dispatch: tool` 时要调用的工具名

在指令中使用 {baseDir} 引用技能文件夹路径。

ClawHub（技能注册中心）

ClawHub 是 OpenClaw 的公共技能注册中心，浏览地址：https://clawhub.com

# 安装技能到工作区
openclaw skills install <skill-slug>

# 更新所有已安装技能
openclaw skills update --all

# 扫描并发布更新（使用 clawhub CLI）
clawhub sync --all

openclaw skills install 安装到当前活跃 workspace 的 skills/ 目录。

安全注意事项

将第三方技能视为不受信任的代码，启用前先阅读
对不受信任的输入和高风险工具，优先使用沙箱运行
技能发现只接受 realpath 在配置根目录内的技能
skills.entries.*.env 和 skills.entries.*.apiKey 会注入到宿主进程（不是沙箱），注意保密

七、会话管理

会话模型

OpenClaw 为每个 Agent 维护一个主会话。DM（私聊）折叠到 agent:<agentId>:<mainKey>，群组/频道聊天有独立的 key。

DM 作用域（dmScope）

通过 session.dmScope 控制私聊消息的分组方式：

模式	行为
`main`（默认）	所有 DM 共享主会话，保持连续性
`per-peer`	按发送者 ID 隔离
`per-channel-peer`	按通道 + 发送者隔离（多用户推荐）
`per-account-channel-peer`	按账号 + 通道 + 发送者隔离（多账号推荐）

安全 DM 模式（多用户必读）

如果你的 Agent 可以接收多人的 DM，强烈建议启用隔离模式。否则所有用户共享同一对话上下文，可能泄露隐私。

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

何时启用：

配对审批了多个发送者
DM 白名单有多个条目
设置了 dmPolicy: "open"
多个号码/账号可以给你的 Agent 发消息

可用 openclaw security audit 验证 DM 设置。

身份链接

用 session.identityLinks 将不同通道的同一用户映射到统一身份，使其在 per-peer 等模式下共享 DM 会话。

状态存储位置

~/.openclaw/agents/<agentId>/sessions/sessions.json    ← 会话存储
~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl ← 对话记录

Gateway 是会话状态的唯一真实来源。UI 客户端必须查询 Gateway 获取会话列表和 token 计数。

会话维护

OpenClaw 自动维护会话存储，保持文件大小可控。

默认参数

参数	默认值
`mode`	`warn`
`pruneAfter`	30 天
`maxEntries`	500
`rotateBytes`	10MB
`maxDiskBytes`	未设置（禁用）

{
  "session": {
    "maintenance": {
      "mode": "warn",
      "pruneAfter": "30d",
      "maxEntries": 500
    }
  }
}

八、多代理路由

概述

多代理模式允许在一个 Gateway 中运行多个隔离的 Agent，每个 Agent 有独立的 workspace、状态目录和会话。通过 bindings 将入站消息路由到指定 Agent。

什么是”一个 Agent”？

每个 Agent 拥有完全独立的：

组件	路径
Workspace	`~/.openclaw/workspace-<agentId>`
State Dir	`~/.openclaw/agents/<agentId>/agent`
Sessions	`~/.openclaw/agents/<agentId>/sessions`
Auth Profiles	`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
Skills	`<workspace>/skills`（per-agent）+ `~/.openclaw/skills`（共享）

主 Agent 的凭证不会自动共享。不要跨 Agent 复用 agentDir（会导致认证/会话冲突）。

单代理模式（默认）

不做任何配置时，OpenClaw 运行单个 Agent：

agentId 默认为 main
会话键为 agent:main:<mainKey>
Workspace 默认 ~/.openclaw/workspace

多代理配置示例

{
  "agents": {
    "list": [
      { "id": "alex", "workspace": "~/.openclaw/workspace-alex" },
      { "id": "mia", "workspace": "~/.openclaw/workspace-mia" }
    ]
  },
  "bindings": [
    {
      "agentId": "alex",
      "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+15551230001" } }
    },
    {
      "agentId": "mia",
      "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+15551230002" } }
    }
  ],
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551230001", "+15551230002"]
    }
  }
}

路由规则（优先级从高到低）

peer 精确匹配（DM/群组/频道 ID）
parentPeer 匹配（线程继承）
guildId + roles（Discord 角色路由）
guildId（Discord）
teamId（Slack）
accountId 匹配
通道级匹配（accountId: "*"）
回退到默认 Agent（agents.list[].default，否则列表第一个，默认 main）

多代理 = 多人格

每个 agentId 是完全隔离的人格：

不同的手机号/账号（per channel accountId）
不同的个性（per-agent workspace 中的 AGENTS.md 和 SOUL.md）
独立的认证 + 会话（除非显式启用跨代理通信）

管理命令

# 添加新 Agent（交互式向导）
openclaw agents add

# 查看所有 Agent 及其 bindings
openclaw agents list --bindings

与 Auto-FDO v2 架构的关系

本项目的 Auto-FDO v2 架构正是基于 OpenClaw 多代理模式：

templates/scout/AGENTS.md     → ~/.openclaw/workspace-scout/AGENTS.md
templates/analyzer/AGENTS.md  → ~/.openclaw/workspace-analyzer/AGENTS.md
templates/profiler/AGENTS.md  → ~/.openclaw/workspace-profiler/AGENTS.md
templates/operator/AGENTS.md  → ~/.openclaw/workspace-operator/AGENTS.md

由 scripts/setup_multi_agent.sh 自动部署。

九、插件系统

概述

插件扩展 OpenClaw 的能力：新通道、模型提供商、工具、技能、语音、图像生成等。分为核心插件（随 OpenClaw 附带）和外部插件（社区发布在 npm）。

插件类型

格式	工作方式
Native	`openclaw.plugin.json` + 运行时模块，进程内执行
Bundle	Codex/Claude/Cursor 兼容布局，映射到 OpenClaw 功能

快速开始

# CLI 安装
openclaw plugins install clawhub:@openclaw/voice-call

# 或在聊天中使用斜杠命令
/plugin install clawhub:@openclaw/voice-call
/plugin show voice-call
/plugin enable voice-call

官方可安装插件

插件	包名
Matrix	`@openclaw/matrix`
Microsoft Teams	`@openclaw/msteams`
Nostr	`@openclaw/nostr`
Voice Call	`@openclaw/voice-call`
Zalo	`@openclaw/zalo`
Zalo Personal	`@openclaw/zalouser`

配置

{
  "plugins": {
    "enabled": true,
    "allow": ["voice-call"],
    "deny": ["untrusted-plugin"],
    "load": { "paths": ["~/Projects/oss/voice-call-extension"] },
    "entries": {
      "voice-call": { "enabled": true, "config": { "provider": "twilio" } }
    }
  }
}

字段	说明
`enabled`	总开关（默认 true）
`allow`	插件白名单
`deny`	插件黑名单（deny 优先于 allow）
`load.paths`	额外插件路径
`slots`	独占类别选择器
`entries.<id>`	每个插件的开关 + 配置

独占插槽（Slots）

某些类别只能有一个活跃插件：

{
  "plugins": {
    "slots": {
      "memory": "memory-core",
      "contextEngine": "legacy"
    }
  }
}

插槽	控制内容	默认值
`memory`	活跃记忆插件	`memory-core`
`contextEngine`	活跃上下文引擎	`legacy`

插件 API 概览

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({ /* 模型提供商 */ });
    api.registerTool({ /* Agent 工具 */ });
    api.registerChannel({ /* 聊天通道 */ });
    api.registerSpeechProvider({ /* TTS/STT */ });
    api.registerWebSearchProvider({ /* 网页搜索 */ });
    api.registerHttpRoute({ /* HTTP 端点 */ });
    // ...更多注册方法
  },
});

CLI 管理命令

openclaw plugins list                  # 列出所有插件
openclaw plugins inspect <id>          # 详细信息
openclaw plugins install <package>     # 安装
openclaw plugins update <id>           # 更新
openclaw plugins enable <id>           # 启用
openclaw plugins disable <id>          # 禁用
openclaw plugins doctor                # 诊断

十、模型管理与安全

模型选择机制

OpenClaw 按以下顺序选择模型：

主模型 (agents.defaults.model.primary)
Fallback 列表 (agents.defaults.model.fallbacks，按顺序）
Provider 内部的 auth failover 在切换到下一个模型之前发生

模型策略建议

主模型设为你能用的最强最新模型
Fallback 用于成本/延迟敏感的任务
对工具启用的 Agent 或不受信任的输入，避免使用旧/弱模型

配置示例

{
  "agent": {
    "model": { "primary": "anthropic/claude-sonnet-4-6" },
    "models": {
      "anthropic/claude-sonnet-4-6": { "alias": "Sonnet" },
      "anthropic/claude-opus-4-6": { "alias": "Opus" }
    }
  }
}

聊天中切换模型

/model              # 打开模型选择器
/model list         # 列出可用模型
/model 3            # 按编号选择
/model openai/gpt-5.2  # 按名称选择
/model status       # 详细状态

CLI 命令

openclaw models list              # 列出模型
openclaw models status            # 当前状态
openclaw models set <provider/model>  # 设置主模型
openclaw models fallbacks add <provider/model>  # 添加 fallback
openclaw models scan              # 扫描 OpenRouter 免费模型

OpenRouter 免费模型扫描

openclaw models scan --min-params 7 --max-age-days 90

扫描结果按以下维度排名：图像支持 → 工具延迟 → 上下文大小 → 参数量。

安全模型

核心假设：个人助手信任模型

OpenClaw 的安全设计基于个人助手部署模式：一个受信任的操作者边界，可能有多个 Agent。

不是多租户安全边界。如果需要对抗性用户隔离，应使用独立的 Gateway + 凭证（最好是独立的 OS 用户/主机）。

安全审计

openclaw security audit          # 基本审计
openclaw security audit --deep   # 深度审计（含 Gateway 探测）
openclaw security audit --fix    # 自动修复
openclaw security audit --json   # 机器可读输出

审计检查项包括：Gateway 认证暴露、浏览器控制暴露、过宽的白名单、文件系统权限、exec 审批策略、开放通道工具暴露等。

三个核心安全问题

谁能和你的 bot 对话？ → 通道白名单、配对审批
bot 被允许在哪里操作？ → 工具 allow/deny、沙箱
bot 能触碰什么？ → 文件系统权限、exec 限制

部署建议

推荐：每台机器/主机一个用户，一个 Gateway
如果多人需要 OpenClaw，每人一个 VPS/主机
主机和配置边界视为受信任的
如果有人能修改 ~/.openclaw（包括 openclaw.json），视其为受信任的操作者

Slack 共享工作区风险

如果 “Slack 中所有人都能给 bot 发消息”，核心风险是委托工具权限。每个能发消息的人都能操控同一套工具权限。

实践建议

从最小权限开始，随着信心增长再逐步放宽：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } }
    }
  },
  "tools": {
    "deny": ["exec"],
    "allow": ["group:fs", "web_search"]
  }
}

十一、CLI 速查表

全局标志

标志	说明
`--dev`	隔离状态到 `~/.openclaw-dev`，偏移默认端口
`--profile <name>`	隔离状态到 `~/.openclaw-<name>`
`--no-color`	禁用 ANSI 颜色
`-V` / `--version`	打印版本

🚀 安装与配置

openclaw setup              # 初始安装
openclaw onboard            # 完整引导流程
openclaw configure          # 配置向导
openclaw config get <path>  # 读取配置
openclaw config set <path> <value>  # 设置配置
openclaw doctor             # 诊断问题
openclaw doctor --fix       # 自动修复

🌐 Gateway 管理

openclaw gateway run        # 前台运行
openclaw gateway start      # 后台启动
openclaw gateway stop       # 停止
openclaw gateway restart    # 重启
openclaw gateway status     # 状态
openclaw gateway health     # 健康检查

💬 通道管理

openclaw channels list      # 列出通道
openclaw channels status    # 通道状态
openclaw channels add       # 添加通道
openclaw channels login     # 登录通道
openclaw channels logout    # 登出通道

🤖 Agent 管理

openclaw agents list --bindings  # 列出 Agent 及路由
openclaw agents add              # 添加 Agent
openclaw agents delete           # 删除 Agent
openclaw agent                   # Agent 向导

📦 模型管理

openclaw models list        # 列出模型
openclaw models status      # 当前模型状态
openclaw models set <ref>   # 设置主模型
openclaw models scan        # 扫描免费模型
openclaw models auth add    # 添加认证
openclaw models fallbacks add <ref>  # 添加 fallback

🔧 插件管理

openclaw plugins list              # 列出插件
openclaw plugins install <pkg>     # 安装
openclaw plugins enable <id>       # 启用
openclaw plugins disable <id>      # 禁用
openclaw plugins update --all      # 全部更新
openclaw plugins doctor            # 诊断

🧠 技能管理

openclaw skills list        # 列出技能
openclaw skills install <slug>  # 安装技能
openclaw skills info <name>     # 技能详情

📋 会话管理

openclaw sessions           # 会话列表
openclaw message send       # 发送消息
openclaw message broadcast  # 广播消息

🔒 安全

openclaw security audit          # 安全审计
openclaw security audit --deep   # 深度审计
openclaw security audit --fix    # 自动修复

⏰ 定时任务

openclaw cron list          # 列出定时任务
openclaw cron add           # 添加
openclaw cron enable <id>   # 启用
openclaw cron disable <id>  # 禁用
openclaw cron runs          # 运行历史

🖥️ 浏览器控制

openclaw browser status     # 状态
openclaw browser start      # 启动
openclaw browser screenshot # 截图
openclaw browser navigate <url>  # 导航

📱 设备与节点

openclaw nodes              # 列出节点
openclaw devices            # 列出设备
openclaw pairing list       # 配对列表
openclaw pairing approve    # 审批配对

输出格式

--json: 机器可读 JSON 输出
--plain: 纯文本，无样式
--no-color / NO_COLOR=1: 禁用 ANSI 样式

十二、Task DAG 对比分析：AWP vs learn-claude-code

来源: github.com/shareAI-lab/learn-claude-code

learn-claude-code 项目简介

shareAI-lab 的 learn-claude-code 是一个从 0 到 1 拆解 Claude Code agent 架构的教学项目。核心理念：模型就是 Agent，代码只是 Harness（缰绳）。通过 12 个渐进式 session（s01-s12），逐步构建出完整的多 agent 协作系统。

其中与我们 Task DAG 直接相关的是：

s07 — Task System（文件持久化 + 依赖图）
s09 — Agent Teams（JSONL 信箱 + 多线程 teammate）
s11 — Autonomous Agents（空闲轮询 + 自动认领）
s12 — Worktree + Task Isolation（目录级隔离 + 生命周期事件）

架构对比总览

维度	learn-claude-code	我们的 AWP Task DAG
运行时	单进程多线程（Python）	多进程多 agent（OpenClaw Gateway）
任务存储	`.tasks/task_N.json`	`tasks/<type>-<target>-<seq>.json`
通信机制	JSONL 信箱（`.team/inbox/name.jsonl`）	OpenClaw `agentToAgent` API
自动认领	代码级 idle loop 轮询（5s 间隔）	`claim_task.sh` 代码级认领 + heartbeat/agentToAgent 双通道触发
依赖管理	`blockedBy` / `blocks` 双向链接	`blocked_by` + `downstream`
隔离方式	git worktree（目录级）	OpenClaw workspace（进程级）
任务类型	通用（subject + description）	领域特化（profiling/analyze/optimize/evaluate）
验证机制	无	`validate_task.sh` 强制校验
事件流	EventBus（append-only JSONL）	`events.jsonl` + `task_events.sh` 查询工具
依赖清理	代码自动（完成时遍历清理）	`complete_task.sh` 代码自动清理

关键差异深度分析

1. 自动认领机制

🟢 2026-03 实现状态更新：claim_task.sh 已落地，认领逻辑已从”LLM 理解自然语言”变为”代码确定性执行”。

learn-claude-code (s11) 的做法：

Teammate 生命周期:
  spawn → WORK → IDLE → WORK → ... → shutdown

IDLE 阶段（代码级实现）:
  每 5 秒轮询一次，最多 60 秒
    ├── 检查 inbox → 有消息？→ 恢复 WORK
    ├── 扫描 .tasks/ → 有未认领任务？→ claim → 恢复 WORK
    └── 超时 60s → shutdown

关键代码逻辑：

# IDLE PHASE: poll for inbox messages and unclaimed tasks
for _ in range(polls):
    time.sleep(POLL_INTERVAL)  # 5s
    inbox = BUS.read_inbox(name)
    if inbox:
        resume = True
        break
    unclaimed = scan_unclaimed_tasks()
    if unclaimed:
        task = unclaimed[0]
        claim_task(task["id"], name)
        resume = True
        break

我们的做法（已更新）：

Analyzer 生命周期:
  heartbeat 唤醒（~10m）→ 读 HEARTBEAT.md → bash claim_task.sh analyzer → 有 task? → 执行
  agentToAgent 通知 → 新会话 → 读 AGENTS.md → Session Startup → bash claim_task.sh analyzer → 执行

认领脚本 skills/awp-task-dag/scripts/claim_task.sh：

# 代码级确定性认领（不再依赖 LLM 理解自然语言）
bash skills/awp-task-dag/scripts/claim_task.sh <agent-id>
# 自动：扫描 tasks/ → 筛选 pending+assignee+blocked_by=[] → 按 priority 排序 → claim 第一个
# 退出码 0 = 认领成功（stdout 输出 task 文件路径），2 = 无可认领 task

当前对比：

方面	learn-claude-code	我们（当前）	状态
认领逻辑	代码级 while loop	`claim_task.sh` 脚本	🟢 已对齐
轮询频率	5 秒	~10 分钟（heartbeat）+ agentToAgent 实时通知	🟡 可接受
触发通道	双通道：inbox + task 扫描	双通道：heartbeat task 扫描 + agentToAgent 通知	🟢 已对齐
失败恢复	超时后 shutdown，下次 spawn 重试	heartbeat 定时兜底，最坏等 ~10 分钟	🟡 可接受
通知可靠性	文件级 inbox，不丢消息	agentToAgent 依赖 Gateway 路由 + LLM 记住发通知	🟠 仍有风险
Idle 连续轮询	5s×12 次连续轮询窗口	无（heartbeat 无 task 即 HEARTBEAT_OK 睡眠）	🔴 未实现

已解决的核心问题：认领逻辑不再依赖 LLM 的自然语言理解，claim_task.sh 用代码保证了扫描→筛选→排序→认领的确定性执行。

剩余风险：agentToAgent 通知仍依赖 LLM 记住”创建 task 后必须发通知”这一步。

2. 通信机制：JSONL 信箱 vs agentToAgent

🟡 2026-03 实现状态：agentToAgent 已全面启用，配合 task 文件作为”真相源”的设计，通信可靠性比初始评估时更好。

learn-claude-code：

.team/inbox/
├── alice.jsonl    ← append-only，drain on read
├── bob.jsonl
└── lead.jsonl

特点：文件级持久化，不丢消息；drain-on-read，简单可靠。

我们的 agentToAgent（当前实现）：

创建 task 的 agent:
  1. echo '<json>' | bash validate_task.sh     → task 文件写入 tasks/
  2. agentToAgent(agentId=<assignee>)           → Gateway 路由到目标 agent
  3. 目标 agent 收到通知 → bash claim_task.sh → 认领 task → 执行

heartbeat 兜底:
  每 10 分钟 → HEARTBEAT.md → bash claim_task.sh → 扫描 tasks/ → 认领遗漏的 task

当前对比：

方面	learn-claude-code	我们（当前）	状态
持久化	文件级（JSONL），不丢消息	task 文件持久化 + agentToAgent 通知	🟢 task 文件不丢
通知可靠性	确定性（代码读写文件）	依赖 Gateway 路由 + LLM 记住发通知	🟠 有风险
兜底机制	每次 loop 迭代都检查 inbox	heartbeat 每 10 分钟 claim_task.sh 扫描	🟢 有兜底
消息类型	5 种（message/broadcast/shutdown 等）	单一类型（“New Task Available” 通知）	🟡 够用但不灵活
幂等性	drain-on-read（读完清空）	claim_task.sh 天然幂等	🟢 已解决
通知触发	代码自动（发消息 = 写文件）	依赖 LLM 记住调用 agentToAgent 工具	🟠 最大风险点

核心设计差异：learn-claude-code 的通信是”消息驱动”，我们的通信是”状态驱动”——task 文件是真相源，agentToAgent 只是加速通知。即使通知完全失败，heartbeat 也能在 ≤10 分钟内发现新 task。

分布式部署视角：为什么状态驱动优于消息驱动

learn-claude-code 的 JSONL 信箱是单机共享文件系统的产物，一旦分布式部署直接崩溃。我们的架构天然适配分布式：

agentToAgent 走 OpenClaw Gateway API（HTTP），不依赖共享文件系统
task 文件迁移分布式时只需换成对象存储或数据库
heartbeat 由 Gateway cron job 驱动
claim_task.sh 可从本地扫描迁移到 API 调用

3. 依赖图管理

learn-claude-code (s07)： 双向链接 blockedBy / blocks，完成时自动清理。

我们的 Task DAG： blocked_by + downstream + parent_task 字段。

方面	learn-claude-code	我们	状态
依赖清理	代码自动	`complete_task.sh` 代码自动清理	🟢 已对齐
双向链接	✅ blockedBy + blocks	❌ 只有 blocked_by + downstream	🟡 够用
parent 追踪	❌ 无	✅ parent_task 字段	🟢 我们更强
类型化	❌ 通用 task	✅ 强类型	🟢 我们更强

4. 隔离机制

learn-claude-code (s12)： git worktree 实现目录级隔离，per-task 粒度。

我们的 OpenClaw workspace： 进程级隔离，per-agent 粒度。通过 symlink 共享 tasks/ 和 skills/。

learn-claude-code 的隔离是 per-task 的（更细粒度），我们的是 per-agent 的（更粗但更安全）。

5. 生命周期事件与可观测性

🟢 2026-03 更新：tasks/events.jsonl 全局事件流已实现。四个脚本自动追加事件，task_events.sh 提供查询能力。

bash skills/awp-task-dag/scripts/task_events.sh --limit 20
bash skills/awp-task-dag/scripts/task_events.sh --agent analyzer
bash skills/awp-task-dag/scripts/task_events.sh --event task.completed --since 2026-03-27

我们做得更好的地方

1. 领域特化的 Task 类型系统

learn-claude-code 的 task 是通用的 {subject, description, status}，我们的是强类型的：

profiling → analyze → optimize → evaluate
                ↑                    |
                └── re-analyze ←─────┘（博弈自愈）

每种 task 有明确的 payload schema，自动流转规则是确定性的，博弈机制（re-analyze）是 learn-claude-code 没有的。

2. 验证机制

echo '<task-json>' | bash skills/awp-task-dag/scripts/validate_task.sh

learn-claude-code 没有任何 task 创建时的验证。

3. 安全阀设计

re-analyze 累计 ≥ 3 次 → 自动 escalation
置信度分级处理（≥0.7 / 0.5-0.7 / <0.5）
补充数据最多 2 轮

4. 进程级隔离

OpenClaw 的 per-agent workspace 提供了比 git worktree 更强的隔离：独立的 session、auth、memory。

我们应该学习的地方

改进项	状态	实现方式
代码级自动认领	✅ 已完成	`claim_task.sh` + HEARTBEAT.md + AGENTS.md Auto-Claim 协议
全局事件流	✅ 已完成	`events.jsonl` + 四个脚本自动追加 + `task_events.sh` 查询
依赖自动清理	✅ 已完成	`complete_task.sh` 完成时自动遍历清理 `blocked_by`
双通道检测	🟡 部分完成	heartbeat task 扫描 + agentToAgent 实时通知（缺连续轮询窗口）
身份重注入	🔴 未实现	需 OpenClaw 平台侧支持 context compact 后自动重注入

总结

learn-claude-code 的核心哲学是”模型是 agent，代码是 harness”——所有确定性逻辑都用代码实现，只把决策交给模型。

我们的 Task DAG 在领域建模（类型化 task、博弈自愈、验证机制、安全阀）上更成熟。基础设施层的三大差距（代码级认领、全局事件流、依赖自动清理）已通过四个脚本补齐。剩余差距集中在轮询频率和身份重注入。

一句话：把确定性的事交给代码，把需要判断的事交给模型。

建议学习路径

先读 一、概览 了解全貌
跟着 三、配置 完成本地部署
选一个通道（推荐 Telegram）按 四、通道 接入
阅读 五、工具 和 六、Skills 理解 Agent 能力
如果需要多人/多角色，深入 八、多代理路由
随时查阅 十一、CLI 速查表
深入 十二、Task DAG 对比分析 了解多代理协作架构的设计权衡

OpenClaw 完全指南：从入门到多代理架构

OpenClaw 完全指南

一、概览与快速入门

什么是 OpenClaw？

核心特点

适用人群

快速入门

前置要求

安装与启动

启动后

环境变量（高级）

工作原理

二、架构与协议

整体架构

三类连接者

通信协议

传输层

消息格式

幂等性

配对与本地信任

远程访问

运维要点

关键不变量

三、配置详解

配置文件位置

最小配置示例

编辑配置的四种方式

配置热重载

重载模式

哪些需要重启？

环境变量

内联环境变量

配置中引用环境变量

Secret Refs（密钥引用）

严格验证

四、聊天通道

概述

内置通道

插件通道（需单独安装）

关键要点

配置示例

五、工具系统

概述

内置工具

工具权限控制

Allow / Deny 列表

工具配置文件（Profile）

工具分组

按 Provider 限制

六、Skills 技能

概述

技能加载位置与优先级

多代理场景

SKILL.md 格式

可选 frontmatter 字段

ClawHub（技能注册中心）

安全注意事项

七、会话管理

会话模型

DM 作用域（dmScope）

安全 DM 模式（多用户必读）

身份链接

状态存储位置

会话维护

默认参数

八、多代理路由

概述

什么是”一个 Agent”？

单代理模式（默认）

多代理配置示例

路由规则（优先级从高到低）

多代理 = 多人格

管理命令

与 Auto-FDO v2 架构的关系

九、插件系统

概述

插件类型

快速开始

官方可安装插件

配置