乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > ��OpenClaw Agent 手册:你的私人 AI 助手,你掌控一切

��OpenClaw Agent 手册:你的私人 AI 助手,你掌控一切

当前时间： 2026-05-18 14:35:18 更新时间： 2026-05-18 分类：软件教程 评论(0)

��OpenClaw Agent 手册:你的私人 AI 助手,你掌控一切

     — 探索 AI 与 AGI 前沿 · 大模型 & AI Agent 实践 —       记录从传统开发到 AI 新时代的技术转型之旅     

37 万 + GitHub Star，TypeScript 构建，MIT 开源——OpenClaw 是当前最炙手可热的个人 AI 助手框架。

一、什么是 OpenClaw？

OpenClaw 是一个运行在你自有设备上的个人 AI 助手（Personal AI Assistant）。它不是 SaaS，不是云服务，而是一个你可以在本地安装、配置、扩展的 AI 代理系统。

标语：**EXFOLIATE! EXFOLIATE!**（蜕壳！蜕变！——灵感来源于龙虾蜕壳生长的生物学意象）

它的内核是一个称为 Gateway（网关） 的控制平面，统一管理所有会话、消息通道、工具和事件。你通过熟悉的即时通讯软件与它交互，它通过调用工具来帮你完成真实世界的任务。

项目背景

OpenClaw 最初是作者 Peter Steinberger（steipete） 的个人实验项目，旨在构建一个真正有用的、能在真实计算机上运行任务的 AI 助手。它经历了多次改名迭代：

Warelay → Clawdbot → Moltbot → OpenClaw

项目为 Molty（一只太空龙虾 AI 助手 🦞）而生，如今已发展为社区驱动的顶级开源项目，拥有 372K+ Stars、77K+ Forks。

核心理念

  • 本地优先（Local-First）：Gateway 运行在你的设备上，你的数据由你掌控
  • 频道驱动（Channel-First）：在你想用的地方说话，WhatsApp、Telegram、微信、Discord……
  • 安全默认（Secure by Default）：陌生人 DM 需要配对验证，非主人会话默认沙箱隔离
  • 可扩展（Extensible）：Skill + Plugin + MCP 三层扩展体系
  • Own Your Data：你的数据、你的模型、你的规则

二、架构全景

OpenClaw 的架构可以用一张图概括：

 ┌─────────────────────────────────────────────────────┐ │                    OpenClaw Gateway                  │ │  (控制平面 — 会话、频道、工具、事件、安全策略)           │ ├─────────────────────────────────────────────────────┤ │                                                       │ │  ┌──────────┐  ┌──────────┐  ┌──────────┐            │ │  │ Agent A  │  │ Agent B  │  │ Agent C  │ ...        │ │  │ (主会话)  │  │ (团队会话)│  │ (沙箱会话)│            │ │  └────┬─────┘  └────┬─────┘  └────┬─────┘            │ │       │              │              │                   │ │  ┌────▼──────────────▼──────────────▼────┐             │ │  │          Workspace (工作区)              │            │ │  │  AGENTS.md · SOUL.md · TOOLS.md        │            │ │  │  skills/ · config/ · data/             │            │ │  └─────────────────────────────────────────┘            │ │                                                       │ │  ┌──────────────────┐  ┌──────────────────┐           │ │  │    Channels      │  │     Tools        │           │ │  │  Telegram/微信   │  │  Browser/Cron    │           │ │  │  Discord/Slack   │  │  Canvas/Nodes    │           │ │  │  WhatsApp/iMsg   │  │  Sessions/Discord│           │ │  └──────────────────┘  └──────────────────┘           │ │                                                       │ │  ┌──────────────────┐  ┌──────────────────┐           │ │  │    Plugins       │  │      MCP         │           │ │  │  Code/Bundle     │  │  Server/Client   │           │ │  └──────────────────┘  └──────────────────┘           │ └─────────────────────────────────────────────────────┘

2.1 Gateway（网关）

Gateway 是整个系统的控制平面，承担以下职责：

  • 会话管理：为每个对话创建隔离的 Agent 会话
  • 频道路由：将来自不同消息平台的消息分发到对应的 Agent
  • 工具注册与调用：管理所有可用工具的发现和执行
  • 安全策略执行：DM 配对、沙箱策略、权限控制
  • 事件系统：Cron 定时任务、Webhook、Gmail Pub/Sub 等自动化事件

Gateway 作为守护进程运行（launchd / systemd user service），支持 macOS、Linux 和 Windows（WSL2）。

2.2 Agent（智能体）

Agent 是实际与 LLM 交互并执行任务的核心组件。每个 Agent 会话拥有独立的：

  • 模型配置（provider + model ID）
  • 系统提示词（从 AGENTS.md / SOUL.md 注入）
  • 工具集合
  • 会话历史

多 Agent 路由：你可以将不同的消息通道或联系人路由到不同的 Agent 配置，实现场景隔离。

2.3 Workspace（工作区）

默认路径 ~/.openclaw/workspace/，包含：

  • AGENTS.md — Agent 行为提示词
  • SOUL.md — 灵魂/角色设定（可选）
  • TOOLS.md — 工具使用说明
  • skills/ — 技能目录（每个技能是一个子目录 + SKILL.md）
  • 用户数据、配置文件

2.4 Channels（消息通道）

OpenClaw 支持的超多消息平台（当前已实现）：

类别
平台
即时通讯
WhatsApp、Telegram、Signal、iMessage
团队协作
Slack、Discord、Microsoft Teams、Google Chat
中文平台
 微信

、QQ、飞书（Feishu）、LINE
传统协议
IRC、Matrix、Mattermost、Nextcloud Talk
其他
Nostr、Synology Chat、Tlon、Twitch、Zalo
Web
WebChat（内置 Web 界面）

2.5 开发语言选择

OpenClaw 的核心是 TypeScript。为什么不是 Python？

“OpenClaw 本质上是一个编排系统：提示词、工具、协议和集成。TypeScript 保持了可 hackability——广泛知晓、快速迭代、易于阅读和扩展。”

三、快速安装与入门

3.1 系统要求

  • Node.js 24（推荐）或 Node.js 22.16+
  • macOS / Linux / Windows（WSL2 强烈推荐）

3.2 安装步骤

# 全局安装npm install -g openclaw@latest# 或使用 pnpmpnpm add -g openclaw@latest# 运行引导（推荐）openclaw onboard --install-daemon

openclaw onboard 是官方推荐的安装方式，会逐步引导你完成：

  1. Gateway 守护进程安装
  2. 模型提供商配置
  3. 消息频道配对
  4. 技能安装

3.3 最小配置

最低配置只需 ~/.openclaw/openclaw.json：

{  agent: {    model: "<provider>/<model-id>",  },}

支持的提供商包括 OpenAI、Anthropic、Google Gemini 以及几乎所有兼容 OpenAI API 的第三方提供商。

3.4 基本使用

# 启动 Gatewayopenclaw gateway --port 18789 --verbose# 发送消息openclaw message send --target "+123****7890" --message "你好"# 与助手对话openclaw agent --message "帮我列一份购物清单" --thinking high# 查看运行状态openclaw doctor

3.5 开发模式（本地构建）

git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm openclaw setup           # 首次安装pnpm gateway:watch            # 开发模式（热重载）pnpm build                    # 生产构建

四、Agent 核心技术

4.1 模型支持

OpenClaw 支持几乎所有主流 LLM 提供商：

  • OpenAI（GPT-4o、o1、o3 系列）
  • Anthropic（Claude 3.5/4 系列）
  • Google（Gemini 系列）
  • 本地模型（通过 Ollama、llama.cpp 等）
  • 任何兼容 OpenAI API 的第三方模型

模型故障转移（Model Failover）：支持配置多个认证配置文件，当主模型不可用时自动回退到备用模型，确保服务连续性。

4.2 思考模式（Thinking Level）

Agent 支持不同级别的推理深度控制：

  • /think low — 快速响应，适合简单查询
  • /think medium — 默认模式
  • /think high — 深度推理，适合复杂任务

4.3 会话命令

在对话中随时使用的斜杠命令：

命令
作用
/status
查看当前会话状态
/new
开启新会话
/reset
重置当前会话
/compact
压缩会话历史
/think <level>
设置推理深度
/verbose on|off
显示详细推理过程
/trace on|off
开启/关闭跟踪
/usage off|tokens|full
显示 Token 用量
/restart
重启 Agent
/activation mention|always
设置触发方式

4.4 AGENTS.md / SOUL.md 系统

这些文件位于 Workspace 根目录，用于定义 Agent 的行为：

  • AGENTS.md — 任务执行指南、工具使用偏好、输出格式要求
  • SOUL.md — 角色性格、语气风格、价值观设定

每次 Agent 启动时，这些文件会被注入到 LLM 的系统提示词中。

4.5 会话模型

每个对话是一个独立的会话（Session），拥有：

  • 独立的消息历史
  • 独立的工具环境
  • 独立的模型配置
  • 可跨频道访问（通过 sessions_list / sessions_send 工具）

五、Tool 与 Skill 系统

5.1 内置工具（Tools）

工具
功能
bash
执行 shell 命令
read

 / write
文件读写
edit

 / patch
文件编辑
browser
Web 浏览与交互
canvas
Live Canvas 视觉工作区
nodes
管理 iOS/Android 节点
cron
定时任务调度
sessions
会话管理（列表/历史/发送/生成）
discord
Discord 平台操作
gateway
Gateway 管理
process
后台进程管理
vision
图片理解分析

5.2 技能系统（Skills）

Skill 是 OpenClaw 的过程性记忆——将特定任务的完整工作流打包为可复用的模块。

存储位置：~/.openclaw/workspace/skills/<skill-name>/SKILL.md

Skill 的组成部分：

  • YAML 元数据头（触发条件、分类、版本）
  • Markdown 正文（步骤、命令、注意事项、验证方法）
  • 引用文件（模板、脚本、参考文档）

Skill 注册中心：**ClawHub** — 官方技能市场

5.3 插件系统（Plugins）

两种插件风格：

  1. 代码插件（Code Plugin） — 运行 OpenClaw 插件代码，适用于深层运行时扩展
  2. 包式插件（Bundle Plugin） — 打包技能、MCP 服务器和相关配置，接口更小、更稳定

记忆（Memory） 是一个特殊的插件插槽，一次只能激活一个记忆插件。

5.4 MCP 支持

OpenClaw 同时支持 MCP Server 和 MCP 客户端两种角色，作为运行时集成接口。

六、安全模型

6.1 DM 配对策略

由于 OpenClaw 连接真实消息平台，安全是第一优先：

  • 默认策略：dmPolicy="pairing" — 未知发送者收到配对码，Bot 不会处理其消息
  • 批准命令：openclaw pairing approve <channel> <code>
  • 开放模式：dmPolicy="open" — 需显式开启，并配置 allowFrom: ["*"]

6.2 沙箱隔离（Sandboxing）

对于非主人会话（如群聊），默认启用沙箱：

  • 默认沙箱允许：bash、process、read、write、edit、sessions_list/sessions_history/sessions_send/sessions_spawn
  • 默认沙箱拒绝：browser、canvas、nodes、cron、discord、gateway
  • 后端：Docker（默认）、SSH、OpenShell
  • 配置：agents.defaults.sandbox.mode: "non-main"

6.3 安全检查

运行 openclaw doctor 可以检测并报告有风险的 DM 策略和配置问题。

核心哲学：安全是可操作性与风险之间的刻意权衡——强默认值，但不扼杀能力。

七、高级功能

7.1 Voice Wake（语音唤醒）

  • macOS：支持唤醒词 + 即按即讲（push-to-talk）
  • iOS/Android：持续语音触发（通过 ElevenLabs + 系统 TTS 回退）
  • 硬件支持：通过 Node 应用连接

7.2 Live Canvas（实时画布）

Agent 驱动的可视化工作区，支持 A2UI（Agent-to-UI）协议：

  • 实时渲染图表、流程图、界面原型
  • 双向交互（Agent 可操作，用户可编辑）
  • 目前支持 macOS 和 iOS/Android 节点

7.3 定时任务（Cron）

完全集成的 Cron 调度系统，支持：

  • 灵活的时间表达式（30m、every 2h、0 9 * * *）
  • 技能绑定（自动加载技能后执行任务）
  • 跨频道结果分发

7.4 Webhook 自动化

支持 Webhook 订阅，实现事件驱动的自动化工作流。

7.5 桌面与移动端 App

平台
功能
macOS

（OpenClaw.app）
菜单栏控制、Voice Wake、WebChat、远程 Gateway 管理
iOS
Gateway WebSocket 配对、语音触发转发、Canvas 表面
Android
WS 节点配对、Connect/Chat/Voice 标签、Canvas、摄像头、屏幕捕捉

八、配置详解

8.1 核心配置结构

配置文件 ~/.openclaw/openclaw.json：

{  // Agent 配置  agent: {    model: "openai/gpt-4o",    defaults: {      workspace: "~/.openclaw/workspace",      sandbox: {        mode: "non-main",    // 非主人会话启用沙箱        backend: "docker",      },    },  },  // 消息通道配置  channels: {    telegram: { /* ... */ },    discord: { /* ... */ },    wechat: { /* ... */ },    // ... 更多通道  },  // 工具权限  tools: {    // 按工具名配置权限  },}

完整配置参考：https://docs.openclaw.ai/gateway/configuration

8.2 开发渠道

渠道
npm 标签
说明
stable latest
稳定发布版（vYYYY.M.D）
beta beta
预发布版
dev dev
main 分支 HEAD

切换命令：openclaw update --channel stable|beta|dev

九、赞助商与生态

金牌赞助商

OpenClaw 由行业巨头赞助：

  • OpenAI（ChatGPT/Codex 集成）
  • GitHub
  • NVIDIA
  • Vercel
  • Blacksmith
  • Convex

社区生态

  • ClawHub（clawhub.ai）— 技能与插件注册中心
  • Clawdinator Bot — 自动化 PR 机器人
  • Nix-OpenClaw — Nix 包管理支持
  • Docker 部署 — 官方 Docker 镜像

十、与其他 Agent 框架的对比

特性
OpenClaw
AutoGPT
CrewAI
LangGraph
Claude Code
语言
TypeScript
Python
Python
Python
TypeScript
消息通道
20+ 平台
无
无
无
无
本地优先
✅
❌
❌
❌
❌
多 Agent 路由
✅
❌
✅
✅
❌
沙箱隔离
✅
❌
❌
❌
❌
语音/Canvas
✅
❌
❌
❌
❌
移动端 App
✅
❌
❌
❌
❌
Cron/Webhook
内置
插件
插件
插件
❌
MCP 支持
双向
❌
❌
有限
客户端
企业赞助
✅
❌
❌
✅
✅
GitHub Stars
372K+
175K+
27K+
15K+
35K+

OpenClaw 的独特之处：它不仅仅是一个 Agent 框架，而是一套完整的个人 AI 基础设施——从消息入口到工具执行，从语音交互到移动端 App，从定时任务到安全策略，全部开箱即用。

十一、未来路线

根据 VISION.md 的优先事项：

当前优先级：

  • 安全与默认配置加固
  • Bug 修复与稳定性提升
  • 首次安装体验优化

下一阶段：

  • 支持所有主流模型提供商
  • 改进主流消息频道支持（增加高需求频道）
  • 性能优化与测试基础设施
  • 更好的 Computer Use 和 Agent 工具能力
  • CLI 和 Web 前端人机工程学
  • macOS、iOS、Android、Windows、Linux 全家桶

明确不会合并的方向：

  • 可托管在 ClawHub 的新核心技能
  • 全文档翻译
  • 已支持频道的冗余封装
  • Agent 层级框架（manager-of-managers 嵌套规划树）
  • 冗余编排层

十二、快速参考

常用 CLI 命令

命令
说明
openclaw onboard
交互式引导安装
openclaw gateway
启动网关
openclaw agent --message "<text>"
向 Agent 发送消息
openclaw doctor
检查系统状态
openclaw pairing approve <ch> <code>
批准 DM 配对
openclaw update --channel <ch>
更新/切换渠道
openclaw nodes …
管理节点设备
openclaw message send
发送消息

链接汇总

资源
地址
官网
https://openclaw.ai
文档
https://docs.openclaw.ai
GitHub
https://github.com/openclaw/openclaw
ClawHub
https://clawhub.ai
Discord
https://discord.gg/clawd
X/Twitter
https://x.com/openclaw

结语

OpenClaw 代表了一种新范式：AI 助手不再是云端的黑盒服务，而是跑在你设备上的、由你完全控制的、连接你熟悉的一切消息平台的个人的、本地的、开放的智能体。

“OpenClaw is the AI that actually does things. It runs on your devices, in your channels, with your rules.”

它还在快速迭代中，但已经是一个可以真正投入日常使用的系统。如果你一直在寻找一个能真正替你干活、又尊重你隐私的 AI 助手，OpenClaw 值得一试。

蜕壳吧，让 AI 成为你的力量。🦞

本文数据截至 2026 年 5 月。OpenClaw 仍处于早期快速迭代阶段，具体功能以官方文档为准。

👇 如果这篇文章对你有帮助，欢迎点赞、收藏、转发！

— 本文由 AI大本营自习室 出品，转载请注明出处 —

点击下方卡片，让「AI大本营助手」为您实时答疑：支持24小时在线