OpenClaw 技术分析与部署教程

本文旨在对开源项目OpenClaw进行全面的技术解析，并提供一份详尽的本地化部署教程。文章首先介绍了OpenClaw的项目背景与核心定位，演示了从npm安装、运行向导到最终启动网关的完整部署流程。在技术分析部分，本文深入探讨了其核心组件构成，重点剖析了一次完整调用所涉及的全链路执行流程、Skill机制，以及支持多平台消息集成的Channels系统原理。通过本文，开发者可以系统性地理解OpenCla

Alex_81D

834人浏览 · 2026-03-04 23:15:00

Alex_81D · 2026-03-04 23:15:00 发布

前言

已经有一段时间没有写东西了，不是我最近不想写，而是想写的的确很多，最近一直在忙于各种AI工具、框架的研究调研中，今天终于抽出时间做一点分享，以后会定期写。那今天我们聊点什么呢，那就从最近爆火的OpenClaw聊起吧，先看看这个是何方神圣，能让AI界掀起这样的大暴动。

一、openClaw 是何方神圣？

基本信息：

OpenClaw（曾用名：Clawdbot / Moltbot）：OpenClaw 是一个可自托管的 AI Agent 平台，支持多模型接入、多通信渠道、技能插件化，通过任务自主规划与工具调用能力，将大语言模型从被动问答系统升级为可执行复杂业务逻辑的自动化Agent代理

官网地址：https://docs.openclaw.ai/

Git地址：https://github.com/openclaw/openclaw

开源协议：MIT license

起源

OpenClaw 的走红，并不是一次偶然的“刷屏”，而是多股技术与期望情绪叠加后的结果。

在 2024–2025 年，开发者社区其实已经对「只会聊天的 AI」产生了明显疲劳。ChatGPT、Claude、deepseek 很聪明，但它们停留在web端页面里：不能真正替你完成电脑的实际任务，只能输出文字告诉你“应该怎么做”。与此同时，AutoGPT这类“自治智能体”项目又显得过于学术化、工程负担重、成功率不稳定。Manus和 OpenManus 之类的有有点不够用。

OpenClaw刚好卡位在中间那条断层上：

真简单：一条命令即可本地启动，不需要先搭一整套复杂的向量数据库和调度系统。
真能用：不是演示，而是能真的发消息、跑脚本、读写文件。
真惊喜：它第一次让大量普通用户意识到——“哇，原来 LLM 真的可以替我操作电脑”。

真正点燃社区热情的，是大量“第一天就能复现”的体验分享，一键安装即可。吸引了一众技术和非技术用户：

“我让AI监控一个新闻网页，一有新信息就自动总结。”
“我只是连上 whatsapp，它就变成了我的私人助理。”

“帮我设置一下提醒，xxxx”

二、openclaw部署

系统要求

组件	要求
Node.js——需要提前安装	版本 22+
RAM	最低 2GB（浏览器自动化建议 4GB+）
CPU	最低双核
存储	Docker 部署 20GB
操作系统	macOS、Linux、Windows（WSL2）、树莓派也可以
网络	API 访问需互联网
端口（默认）	18789（Gateway）、18790（Bridge）

1.安装OpenClaw--npm 安装

npm install -g openclaw@latest

# 或者使用 pnpm

# npm install -g pnpm

# pnpm add -g openclaw@latest

2.运行安装向导

openclaw onboard --install-daemon

安装完成后，运行交互式向导，它会引导你完成网关、工作空间、通信渠道和技能的配置，这个命令还会安装一个守护进程服务，让OpenClaw网关能在后台持续运行。

3.启动网关并访问

启动网关服务（默认端口为18789）

openclaw gateway --port 18789 --verbose

三、技术分析

核心架构

用户消息 (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 → 用户

核心组件

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

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

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

执行流程：从一次完整调用看清全链路

① 用户请求："帮我看一下这个飞书文档"

② Agent 读到 Skill 工具描述里的 <available_skills> 列表

→ 看到 "feishu-docx": Export Feishu/Lark cloud documents to Markdown...

→ 推理判断：这个任务需要 feishu-docx 技能

③ Agent 调用 Skill 工具：command: "feishu-docx"

④ 系统验证：

- skill 是否存在 ✓

- 类型是否为 prompt ✓

- 是否禁止模型调用 ✓

- 权限检查 → 询问用户"执行 feishu-docx skill？" → 用户批准

⑤ 系统加载 SKILL.md 正文，注入两条消息：

- 元数据（可见）："正在加载 feishu-docx skill"

- 完整指令（隐藏）：怎么安装工具、怎么调用命令、输出格式是什么

⑥ 系统修改执行上下文：

- 放行 allowed-tools 里声明的工具权限

- 如果指定了 model，切换模型

⑦ 完整消息数组发送到 API

⑧ Agent 带着新指令和新权限开始执行：

→ 调用 Bash: feishu-docx export "https://..." --stdout

→ 获取结果，格式化呈现给用户

核心能力分析

模型支持	支持 OpenAI、Anthropic、Zhipu GLM、Ollama、DeepSeek、通义等
部署方式	可完全私有化部署（本地/内网）
数据隐私	数据不出域，满足医疗行业合规要求
集成能力	支持飞书、微信、Telegram、Discord、API 等多种通信方式
技能扩展	插件机制丰富，可自定义技能（如调用 HIS 接口、写 SQL、发邮件）
任务执行	支持 Shell、文件操作、数据库查询、API 调用等
可观察性	提供日志、监控、审计追踪

文件结构：

~/.openclaw/

├── AGENTS.md          # 智能体的描述和提示词

├── BOOTSTRAP.md       # 初始系统设置

├── HEARTBEAT.md       # 系统健康检查清单

├── IDENTITY.md        # openClaw智能体身份/人设

├── SOUL.md            # 性格特征

├── TOOLS.md           # 可用工具参考

├── USER.md            # 用户偏好/上下文

├── MEMORY.md          # 长期策划记忆（可选）

├── canvas/            # 可视化工作区

├── memory/            # 持久化记忆目录

│   ├── 2026-02-03.md # 每日笔记

│   └── 2026-02-04.md

└── skills/            # 已安装 skills

Skill

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"}}

---

Skills元数据字段详解（metadata.openClaw 下）：

字段	说明
always: true	始终加载（跳过条件检查）
emoji	可选表情符号（macOS Skills UI 显示）
homepage	网站链接
os	支持平台：["darwin", "linux", "win32"]
requires.bins	必需的 PATH 二进制文件列表
requires.env	必需的环境变量
requires.config	必需的配置路径
primaryEnv	主要环境变量（对应 skills.entries.<name>.apiKey）
install	安装器规范（brew/node/go/uv/download）

Skills三层加载机制：

优先级从高到低：

1. Workspace Skills   <当前目录>/.claude/skills/

   └── 项目级别，只在该项目生效

2. User Skills        ~/.clawdbot/skills/

   └── 用户级别，所有项目共享

3. Bundled Skills     内置技能

   └── Clawdbot 自带的基础技能

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

工作区 skills：<workspace>/skills
托管/本地 skills：~/.clawdbot/skills
内置 skills：随安装包分发

内置 Skills（49+ 个）涵盖：

Apple 生态：Notes、Reminders、Things 3、Bear Notes
Google Workspace：Gmail、Calendar、Drive、Docs、Sheets（通过 gog CLI）
通信工具：Slack、iMessage、Twitter/X、Discord
智能家居：Philips Hue、Sonos、Eight Sleep
开发工具：GitHub CLI、Claude Code 子进程、Whisper 转录

Channels 系统：多平台消息集成

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	扩展插件	社区支持
飞书	扩展插件	社区支持

四、常用命令

openclaw gateway           # 运行 WebSocket 网关服务（可加 --port 指定端口）
openclaw gateway start     # 启动
openclaw gateway stop      # 停车
openclaw gateway restart   # 重启
openclaw channels login    # WhatsApp QR 配对登录
openclaw channels add      # 添加 Telegram/Discord/Slack 机器人（可加 --token）
openclaw channels status --probe      # 检查通道健康状态
openclaw onboard # 交互式设置向导（可加 --install-daemon）
openclaw doctor --deep     # 健康检查与快速修复
openclaw config get|set|unset    # 读取 / 写入配置值
openclaw models list|set|status  # 模型管理与认证状态
openclaw models auth setup-token # Anthropic 认证流程设置