一、OpenClaw是什么

OpenClaw（原名 Clawdbot，过渡名 Moltbot）是 2026 年 1 月突然爆火的开源个人 AI 助手项目，由 Peter Steinberger（PSPDFKit 创始人）开发。

OpenClaw 是一个可执行任务的智能体，我们给指令，它不仅回答，还能主动操作系统、访问网页、处理邮件、整理文件、发起提醒甚至自动编写代码。
在这里插入图片描述

OpenClaw 是一个把 本地算力 + 大模型 Agent 自动化 玩到极致的开发者效率工具。

OpenClaw 目标是让 AI 不只是给建议，而是直接完成完整工程任务。

1.1 OpenClaw 的演进

在这里插入图片描述
因为 Anthropic 在 1 月 27 日发律师函称 Clawd / Clawdbot与 Claude 太像，项目在当天紧急更名为 Moltbot（脱皮龙虾之意，吉祥物是小龙虾 Molty 🦞），但功能完全一致，旧命令 clawdbot 仍然兼容。

Moltbot 是项目组为了应对侵权风险想出的过渡名字，OpenClaw 这是目前的最终官方名称。

Clawbot、Moltbot 和 OpenClaw 其实是同一个开源项目，名字演进顺序为：

Clawdbot → Moltbot → OpenClaw

在这里插入图片描述

二、环境准备

OpenClaw 的安装被设计得极为友好，即使是非开发者也能快速上手。

安装前系统要求说明：
1.1 Node.js ≥ 22：推荐使用最新LTS版本
1.2 API密钥：至少一个LLM提供商的API密钥
1.3 5分钟时间：完成初始设置
1.4 磁盘空间：≥ 500MB

2.1 安装方法

方式1：终端快捷指令（推荐）

// macOS/Linux 系统:
curl -fsSL https://openclaw.ai/install.sh | bash

// Windows 系统
#PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

#CMD
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

这会自动安装 Node.js（≥22）并完成基本配置。

方式2：NPM全局安装（推荐）

需要 Node.js ≥22 并完成基本配置：

使用 npm：

npm i -g openclaw

# 如果速度慢可以指定国内镜像
npm i -g openclaw --registry=https://registry.npmmirror.com

或使用 pnpm：

pnpm add -g openclaw

安装完成后，初始化并安装后台服务（launchd / systemd 用户服务）：

openclaw onboard

方式3：从源码安装（开发模式）

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖（推荐使用pnpm）
pnpm install

# 构建UI（首次运行自动安装UI依赖）
pnpm ui:build

# 构建项目
pnpm build

# 运行onboarding向导
pnpm openclaw onboard --install-daemon

# 开发循环（TypeScript更改时自动重载）
pnpm gateway:watch

方法4：Docker安装

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 使用docker-compose启动
docker-compose up -d

# 或使用setup脚本
chmod +x docker-setup.sh
./docker-setup.sh

2.2 配置引导

通过上面推荐的方式安装会完成环境检测，并且安装必要的依赖，还会启动 onboarding(设置向导) 流程。
后期要重新进入设置向导，可以执行以下命令：

openclaw onboard --install-daemon

在这里插入图片描述
然后，会提醒你这个龙虾能力很强，当然风险也很大，我们选 yes（no 就不安装了） 就好了：
在这里插入图片描述
接下来我们就选快速启动 QuickStart 选项：
在这里插入图片描述
接下来我们需要配置一个大模型，Model/Auth Provider 选择 AI 供应商，国内外的供应商基本都支持。
在这里插入图片描述
如果没有海外的账号，配置咱们国内的 Qwen、MiniMax、智谱的 API key 也是可以的，认证配置文件（OAuth + API 密钥）在~/.openclaw/agents//agent/auth-profiles.json，后期也可以在这个文件上修改。

然后会出现选择聊天工具的选项，海外的一般都没有可以选最后一个：
在这里插入图片描述
其他配置，比如端口的设置 Gateway Port，按默认的 18789 即可，比如 Skills、包的安装管理器选 npm 或其他，可以一路 Yes 下去。
在这里插入图片描述
选一些自己喜欢的 skills，也可以直接跳过，使用空格按键选择：
在这里插入图片描述
这些 API key，没有的直接选 no：
在这里插入图片描述
最后这三个钩子可以开启，使用空格按键选择，主要做内容引导日志和会话记录：
在这里插入图片描述
选择Open the Web UI，使用浏览器打开：
在这里插入图片描述
安装完后，就会自动访问 http://127.0.0.1:18789/chat，就可以打开聊天界面让它开始工作。

比如搜索最新的科技新闻：
在这里插入图片描述
启动后，我们可以使用 openclaw status 命令查看状态：

openclaw status

如果你在新手引导期间安装了服务，Gateway 网关应该已经在运行：

openclaw gateway status

手动运行（前台）：

openclaw gateway --port 18789 --verbose

安装后可以执行的命令：

  • 运行新手引导：openclaw onboard --install-daemon
  • 快速检查：openclaw doctor
  • 检查 Gateway 网关健康状态：openclaw status + openclaw health
  • 打开仪表板：openclaw dashboard
  • 使用内置卸载程序：openclaw uninstall

三、工作原理

3.1 整体架构概览

ClawdBot 用一套相对完整的智能体架构设计，并验证了可行性：Gateway 统一多渠道接入、Tools + Skills 定义能力边界、Memory 实现持久化记忆、多层防护保证设备安全。
在这里插入图片描述
从架构上来看，你可以把 openClaw 想象成一间智能平台，有五个重要功能区：

  1. Gateway（大门）：管理会话、路由请求、做鉴权。它通常在本地运行，默认将控制面板绑定到 loopback（只允许本机访问），并支持通过 Tailscale 等私有网络扩展远程访问。
  2. Agent（大脑）：有专门的人设，负责理解上下文意图、制定分步计划、决定要调用哪些工具或技能。
  3. Skills（工具箱）：一组插件/技能（以 Markdown 与脚本描述），让 Agent 可以“开门、倒咖啡、发邮件、跑脚本”。
  4. Channels（通道）：连接 各种app，如WhatsApp、Telegram、Discord、Slack、SMS 等，让 AI 与用户的日常通信无缝对接。
  5. Nodes（传感器/终端）：运行在用户端设备（手机、笔记本、Raspberry Pi，台式机）的小智能体，可以提供摄像头、地理位置或系统通知等本地能力。

在这里插入图片描述

组件名称 功能定位 技术细节
Gateway(网关) 中央控制平面 运行在本地或VPS上的Node.js守护进程，负责会话
管理、权限验证与路由
Pi Agent(智能体) 推理大脑 负责处理自然语言、制定任务计划并选择合适的工具。
支持Claude、GPT-4及Ollama本地模型
Skills(技能) 执行能力集 模块化的插件系统，通过SKILL.md定义功能，支持文件
操作、浏览器控制、API调用等
Channels(通道) 通信接口 连接用户现有的即时通讯软件(WhatsApp,
Telegram,Discord,Slack等)
Nodes(节点) 设备端扩展 运行在iOS/Android或macOS上的轻量级智能体，允许AI
访问相机、地理位置或发送系统通知

这样的分层设计方式让 openClaw 既能快速扩展社区技能skill和mcp等，也能够在不同设备间弹性部署和执行任务。

3.2 核心功能详解

3.2.1 Gateway网关

Gateway 是openclaw系统的核心枢纽——负责长期运行的守护进程，负责管理所有消息通道并作为 WebSocket 控制平面。ClawdBot 支持多 Agent 创建和运行。一个 Gateway 可以托管多个独立的 Agent。

Gateway 主要做三件事：
（1）接收消息：从各个渠道收集用户指令
（2）路由分发：决定这条消息应该交给哪个 Agent 处理
（3）回复投递：把 Agent 的回复发送回对应的渠道
在这里插入图片描述
默认配置：
（1）WebSocket 端点：ws://127.0.0.1:18789
（2）Canvas 服务器：HTTP 端口 18793，路径 /openClaw/canvas/
（3）每台主机建议运行单个 Gateway（独占 WhatsApp Web 会话）

3.2.2 Agent 推理引擎
3.2.3 Skills 能力扩展机制

Skills 是 智能体执行任务或者使用工具的指引插件，openClaw 的核心扩展机制，遵循 AgentSkills 规范——这是 Anthropic 开发的开放标准，已被 Claude Code、Cursor、VS Code、OpenAI Codex、Gemini CLI、GitHub Copilot 等广泛采用。

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

SKILL.md 格式规范：

---
name: nano-banana-pro
description: 通过 Gemini 3 Pro 生成或编辑图像
homepage: https://example.com
user-invocable: true
disable-model-invocation: false
command-dispatch: tool
command-tool: image-gen
command-arg-mode: raw
metadata: {"openClawt":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
---

Skill 加载优先级（从高到低）：

工作区 skills：<workspace>/skills
托管/本地 skills：~/.clawdbot/skills
内置 skills：随安装包分发
3.2.4 Channel 多平台消息继承

Channels 负责连接各消息平台到中央 Gateway。根据配置与不同的渠道（比如飞书）建立安全链接，完成消息收发（通常是WebSocket 协议）以及格式转换 — 即翻译成 Clawdbot 能听懂的格式。

Channel 协议/库 特性
WhatsApp Baileys（WhatsApp Web协议） QR登录、媒体支持、群组提及及网关
Telegram grammY（Bot API） 流式传输、Webhook支持
Discord discord.js 原生命令、DM策略
Slack Bolt DM配对策略、频道白名单
Signal signal-cli 需本地安装signal-cli
iMessage imsg CLI 仅macOS
Google Chat Chat API 扩展渠道
Matrix、Teams 扩展插件 社区支持

WhatsApp 配置示例：

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"],
      "groups": { "*": { "requireMention": true } }
    }
  },
  "messages": { 
    "groupChat": { "mentionPatterns": ["@clawd"] } 
  }
}
3.2.5 Node 移动/桌面扩展

Nodes 就是在主机之外的其他“能力”节点，连接到 Gateway 的子设备（iOS、Android、macOS），提供设备本地功能：

旧手机、闲置电脑都可以作为 Node 加入网络，以提供更多的能力，比如摄像头、屏幕录制、系统控制、屏幕共享、显示可交互式的UI界面等。Nodes 需要在远程设备上运行相应的Node 客户端 App。

Node 支持的类型：

平台 功能
iOS Node Canvas、语音唤醒、摄像头拍照/录像、屏幕录制、语音触发
Android Node Canvas、语音交互、摄像头、屏幕截图、短信集成(可选)
macOS Node system.run(执行命令)、system.notify(通知)、Canvas/摄像头

Node 通信协议：
（1）传输：Gateway WebSocket（LAN/Tailscale/SSH 隧道）
（2）发现：node.list / node.describe 枚举能力
（3）执行：node.invoke 运行设备本地操作
（4）命令：camera.snap/camera.clip（拍照/录像）、screen.record、location.get、notifications

这实现了"远程大脑，本地双手"的架构——Gateway 可运行在远程 Linux 实例，而 Nodes 通过 Tailscale 连接，执行操作运行在设备本地。

场景：Gateway 跑在 Linux 服务器上，但你想用 Mac 的摄像头拍照。

// 列出已连接的节点
{ "tool": "nodes", "action": "status" }

// 在 Mac 节点上执行命令
{ "tool": "nodes", "action": "run", "node": "office-mac", "command": ["echo", "Hello"] }

// 拍照
{ "tool": "nodes", "action": "camera_snap", "node": "iphone-1" }

// 屏幕录制
{ "tool": "nodes", "action": "screen_record", "node": "office-mac", "duration": "10s" }

// 获取位置
{ "tool": "nodes", "action": "location_get", "node": "iphone-1" }
3.2.6 Memory 持久化记忆

openClaw 的记忆系统非常简单明了，直接基于纯 Markdown 文件——文件是真实来源，模型只"记住"写入磁盘的内容。

记忆文件结构：

~/clawd/
├── AGENTS.md          # 智能体的描述和提示词
├── BOOTSTRAP.md       # 初始系统设置
├── HEARTBEAT.md       # 系统健康检查清单
├── IDENTITY.md        # openClaw智能体 身份/人设
├── SOUL.md            # 性格特征
├── TOOLS.md           # 可用工具参考
├── USER.md            # 用户偏好/上下文
├── MEMORY.md          # 长期策划记忆（可选）
├── canvas/            # 可视化工作区
├── memory/            # 持久化记忆目录
│   ├── 2026-01-28.md  # 每日笔记
│   └── 2026-01-29.md
└── skills/            # 已安装 skills

向量记忆搜索：
（1）默认启用
（2）索引文件：MEMORY.md + memory/**/*.md
（3）分块策略：约 400 token 目标，80 token 重叠
（4）存储：sqlite-vec 加速向量搜索
（5）嵌入提供商（自动选择顺序）：local → openai → gemini

混合搜索（BM25 + 向量结合）配置：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4
          }
        }
      }
    }
  }
}

自动记忆刷新机制：当会话接近自动压缩时，触发静默智能体回合，提示模型将持久记忆写入磁盘。

3.3 工作流与实现细节

3.3.1 消息处理完整流程
用户消息 (WhatsApp/Telegram/Discord/等)
        ↓
    Channel Adapter（标准化为内部格式）
        ↓
    Gateway (WebSocket API - ws://127.0.0.1:18789)
        ↓
    Agent Runtime (Pi agent via RPC)
        ↓
    LLM Provider (Claude/GPT/本地模型)
        ↓
    Tool Execution（按需执行）
        ↓
    Response → Gateway → Channel Adapter → 用户

以“自动整理文章纪要并发 WhatsApp 提醒”为例：
（1）感知：Slack 的 webhook 或文件上传触发消息到 Gateway。
（2）计划：Agent 从短期对话与长期记忆（本地的 MEMORY.md 等持久文件）中抓取上下文，生成一个 multi-step plan。
（3）执行：按计划调用 Skill（可能在 Docker 沙箱中执行浏览器脚本或 shell 命令）。
（4）反哺：结果写回本地记忆并发送给用户，同时将关键操作记录供将来检索。

这套闭环让 openClaw看起来像一个“会思考的执行器”，而不是只会说话的聊天机器人。

3.3.2 Heartbeat 心跳机制

Heartbeat 实现定时任务的自动行为——openClaw 可在无用户提示时主动联系用户。

配置示例：

{
  "agent": {
    "heartbeat": {
      "every": "30m",
      "activeHours": { "start": "08:00", "end": "22:00" }
    }
  }
}

工作原理： 在 ~/clawd/HEARTBEAT.md 创建检查清单：

心跳检查清单
（1）检查邮箱中的重要消息
（2）查看未来 2 小时的日程事件
（3）如果空闲超过 8 小时，发送简短问候

3.3.3 Cron 定时任务（插件）

一次性提醒：

openClaw cron add \
  --name "发送提醒" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "提醒：提交费用报告。" \
  --wake now \
  --delete-after-run

周期性任务：

openClaw cron add \
  --name "早间状态" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结今天的收件箱和日历。" \
  --deliver \
  --channel whatsapp \
  --to "+8613800138000"
3.3.4 Docker 沙箱隔离

沙箱配置：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent",
        "workspaceAccess": "none"
      }
    }
  }
}

沙箱模式：
（1）“none”：无沙箱（工具在主机运行）
（2）“non-main”：仅非主会话沙箱化
（2）“all”：所有会话沙箱化

隔离范围：
（1）“agent”（默认）：每智能体一个容器
（2）“session”：更严格的每会话隔离
（3）“shared”：单容器共享（安全性较低）

工作区访问级别：
（1）“none”（默认）：智能体工作区不可访问
（2）“ro”：智能体工作区只读挂载到 /agent
（3）“rw”：智能体工作区读写挂载到 /workspace

安全容器运行示例：

docker run \
  --name openClaw-secure \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64M \
  --security-opt=no-new-privileges \
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  --cpus="1.0" \
  --memory="2g" \
  -u 1000:1000 \
  openClaw/agent:latest

四、进阶使用

4.1 Skills

4.2 Cron任务

五、最佳实践

5.1 项目架构设计

1）目录结构

~/.openclaw/
├── openclaw.json          # 主配置文件
├── credentials/             # 加密凭证存储
├── workspace/              # 工作区
│   ├── skills/            # 自定义技能
│   ├── AGENTS.md          # Agent配置
│   ├── SOUL.md            # AI人格定义
│   └── TOOLS.md           # 工具定义
├── logs/                  # 日志文件
├── data/                  # 数据存储
└── cache/                 # 缓存目录

2）工作区配置

（1）AGENTS.md：Agent配置

# OpenClaw Agent配置

## 概述
专业开发助手，专注于代码生成、审查和调试。

## 能力
- 多语言支持：Python, TypeScript, Go, Rust
- 框架专长：React, Node.js, FastAPI
- 最佳实践：代码审查、重构、文档

## 限制
- 不执行破坏性操作
- 需要确认敏感操作
- 提供测试用例

（2）SOUL.md：AI人格定义

# AI Personality

## 语调
专业、友好、精准，适度幽默。

## 回答风格
- 简洁但完整
- 代码示例优先
- 解释复杂概念

## 示例
用户：如何优化循环？
AI：好的！这里有几个优化策略...
（详细说明+代码）

5.2 安全实践

1）最小化攻击面

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["verified-users"]
    }
  }
}

2）审计日志

# 定期检查日志
openclaw logs --tail 100

# 监控异常
grep "ERROR\|WARN\|DENIED" ~/.openclaw/logs/gateway.log

3）备份配置

# 备份配置
cp ~/.openclaw/openclaw.json ~/backups/

# 定期备份
openclaw backup --destination ~/backups/

5.3 性能优化

1）会话管理

# 定期压缩会话
openclaw sessions compact --all

# 删除旧会话
openclaw sessions delete --older-than 7d

2）资源限制

{
  "gateway": {
    "sessions": {
      "maxMemory": 2048,
      "maxTokens": 100000
    }
  }
}

3）缓存策略

{
  "agent": {
    "cache": {
      "enabled": true,
      "ttl": 3600,
      "maxSize": 100
    }
  }
}

六、故障排查

6.1 诊断工具

1）健康状态诊断

# 完整诊断
openclaw doctor

# 输出示例
✓ Node.js version: 22.1.0
✓ Configuration valid
✓ API key configured
✓ Channels connected: 3/5
✓ Gateway running
⚠ High memory usage: 85%
✓ Permissions: OK
✓ Nodes paired: 2/2

2）日志分析

# 查看实时日志
tail -f ~/.openclaw/logs/gateway.log

# 搜索错误
grep "ERROR" ~/.openclaw/logs/*.log

# 统计错误
grep -c "ERROR" ~/.openclaw/logs/gateway.log

# 查看最近错误
grep "ERROR" ~/.openclaw/logs/gateway.log | tail -10

3）性能监控

# 资源使用统计
openclaw stats

# 输出示例
Sessions: 15
Memory: 2.3GB / 8GB (29%)
CPU: 12%
Uptime: 5d 12h 34m
Messages: 1,234
Errors: 0

6.2 常见问题

1） An unknown git error occurred
执行以下命令配置 Git（避开中文用户名 / SSH 坑）

# 全局配置 Git 用 HTTPS 代替 SSH（核心：避免 SSH 权限/路径错误）
git config --global url."https://github.com/".insteadOf ssh://git@github.com/
git config --global url."https://github.com/".insteadOf git@github.com:
# 若用户名含中文，额外配置 Git 缓存目录到无中文路径
mkdir C:\GitTemp
git config --global core.cacheDirectory "C:\GitTemp"

七、总结与材料

7.1 最后总结

OpenClaw（曾用名 Clawdbot、Moltbot）是一款开源AI智能体，其通过整合多渠道通信能力与大语言模型，构建具备持久记忆、主动执行能力的定制化AI助手，可在本地私有化部署。

使用注意：由于OpenClaw在部署时“信任边界模糊”，且具备自身持续运行、自主决策、调用系统和外部资源等特性，在缺乏有效权限控制、审计机制和安全加固的情况下，可能因指令诱导、配置缺陷或被恶意接管，执行越权操作，造成信息泄露、系统受控等一系列安全风险。

使用建议 相关单位和用户在部署和应用OpenClaw时，充分核查公网暴露情况、权限配置及凭证管理情况，关闭不必要的公网访问，完善身份认证、访问控制、数据加密和安全审计等安全机制，并持续关注官方安全公告和加固建议，防范潜在网络安全风险。

7.2 相关材料

官方材料
1.1 OpenClaw 官网
1.2 OpenClaw 中文文档
1.3 OpenClaw Github地址
1.4 OpenClaw 技能合集

学习材料
1.1 OpenClaw (Clawdbot) 教程（菜鸟教程）
1.2 一文读懂：openClaw 分析与教程+免费大模型（Moltbot、Clawdbot）
1.3 OpenClaw（大龙虾）完全使用手册（语雀）
1.4 OpenClaw 架构深度解析（musicml）

运用材料
1.1 OpenClaw 接入飞书

安装材料
1.1 windows如何安装open claw（语雀）

# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

天气查询 Agent 零基础教程

avatar 龙虾开发者社区
cover

2026年怎么搭建Hermes Agent/OpenClaw？保姆级部署及token Plan配置教程

avatar 龙虾开发者社区
cover

2026年Hermes Agent/OpenClaw如何集成？喂饭级部署及token Plan配置全攻略

avatar 龙虾开发者社区