OpenClaw 是什么？一文看懂它的架构与核心模块

大家好！我是写代码的中年人！

在 AI 助手泛滥的今天，大多数产品都要求你把数据上传到云端，依赖某家公司的服务器，接受随时可能涨价或关闭的风险。

OpenClaw 走了一条完全不同的路：自托管、本地优先、完全开源。OpenClaw（前身为 Clawdbot/Moltbot）是一个以 MIT 协议开源的 AI 网关框架，它的核心理念是：AI 助手运行在你自己的机器上，对话记录、长期记忆、技能文件全部以纯文本（Markdown 和 YAML）形式保存在本地，你可以用任何文本编辑器查看、用 Git 备份、用 grep 搜索。

模型调用可以选择云端大模型，也可以完全离线（通过 Ollama 或 LM Studio 运行本地模型）。更重要的是，OpenClaw 不只是一个命令行聊天工具：它是一个多渠道 AI 网关，让你能从 WhatsApp、Telegram、Discord、iMessage、Slack、飞书 等任意平台向自己的 AI 发消息，随时随地获得响应，就像给助理发短信一样自然。本文将带你从零开始，一步步掌握 OpenClaw 的安装、配置、渠道接入、多智能体编排，直到高级运维技巧，是一份真正的从入门到精通指南。

01、核心概念与架构理解

在动手安装之前，花几分钟理解 OpenClaw 的架构，能让你在后续配置中少走很多弯路。

Gateway：一切的核心

当你运行 openclaw gateway 时，你启动的是一个长期运行的 Node.js 进程，这个进程就是整个系统——它同时承担着渠道连接、会话状态管理、智能体循环、模型调用、工具执行和记忆持久化的职责。

Gateway 的默认监听地址是 


ws://127.0.0.1:18789，所有客户端（CLI、Web UI、macOS App、iOS/Android 节点）都通过 WebSocket 与它通信。

Channels（渠道）：消息入口

渠道是用户与 OpenClaw 交互的入口点。内置支持的渠道包括：WhatsApp、Telegram、Discord、Google Chat、Signal、BlueBubbles（iMessage）、IRC、Slack、Microsoft Teams、Matrix、Feishu（飞书）、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Twitch、Zalo、WebChat 等。

每个渠道都可以独立配置访问权限（白名单、配对策略等），并可以绑定到不同的智能体。

Agents（智能体）：执行单元

智能体是实际处理消息、调用模型、执行工具的执行单元。每个智能体拥有独立的工作区（Workspace）、记忆、工具权限和模型配置。OpenClaw 支持在同一个 Gateway 进程内运行多个完全隔离的智能体，并通过绑定规则将不同渠道路由到不同智能体。

Tools（工具）：智能体的能力

工具赋予智能体执行特定任务的能力，包括：浏览器控制（基于 CDP 的 Chrome/Chromium）、文件操作、系统命令、Cron 定时任务、会话管理、Discord/Slack 动作等。

Skills（技能）：可复用的行为模块

技能以 SKILL.md 文件的形式存在，包含 YAML 前置信息和自然语言指令，描述智能体在特定场景下应如何行动。技能文件格式与 Claude Code 和 Cursor 兼容，可以通过 ClawHub（技能注册中心）自动搜索和拉取。

02、安装与初始化

系统要求

Node.js 22 或更新版本

推荐：Brave Search API Key（用于网络搜索工具）

推荐：至少一个 AI 提供商的 API Key

检查 Node 版本：

node --version# 应输出 v22.x.x 或更高

安装 OpenClaw

macOS / Linux 一键安装脚本（推荐）：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

通过 npm 全局安装：

npm install -g openclaw@latest

通过 pnpm（从源码构建推荐）：

pnpm add -g openclaw@latest

运行引导向导

安装完成后，运行引导向导进行初始化配置：

openclaw onboard --install-daemon

向导会引导你完成以下配置步骤：

模型/认证：选择 AI 提供商并配置 API Key

Gateway 设置：配置端口、认证令牌等（向导会自动生成 Gateway Token 并存储）

渠道配置：可选配置 WhatsApp、Telegram、Discord、Mattermost 等

配对默认值：配置安全的私信策略

工作区初始化与技能加载

可选的后台服务：以 launchd（macOS）或 systemd（Linux）守护进程形式运行

安装服务后，可以通过以下命令检查状态：

openclaw gateway status

打开控制面板

Gateway 启动后，运行以下命令打开浏览器控制面板：

openclaw dashboard

或直接访问 http://127.0.0.1:18789/。

如果控制面板成功加载，恭喜你——你的 Gateway 已经就绪，可以开始使用了！

控制面板的主要功能区：

Overview（概览）：Gateway 运行状态、连接节点数、活跃智能体数、系统资源使用情况

Agents（智能体）：所有智能体列表，包含模型设置、技能配置、对话历史和任务执行记录

Channels（渠道）：所有已配置渠道的状态、连接健康度、消息吞吐量、错误日志

Logs（日志）：Gateway 和节点的实时日志流，支持过滤、搜索和时间范围查询

03、渠道配置

本次渠道配置我们以飞书为例：

飞书（Feishu / Lark）是国内企业用户最常见的协作平台之一。OpenClaw 通过 WebSocket 长连接与飞书对接，无需公网 IP、无需服务器暴露端口，穿透 NAT 即可正常工作，是企业场景下接入 AI 助手最顺畅的选择。

安装飞书插件

飞书渠道以插件形式提供。OpenClaw ≥ 2026.2 已内置官方飞书插件，运行向导时选择 Download from npm 即可自动安装。

在飞书开放平台创建应用

第一步：登录飞书开放平台

访问 https://open.feishu.cn/app 并登录企业账号。(个人账户也可以)

第二步：创建企业自建应用

点击「创建企业自建应用」

填写应用名称（如「我的 AI 助手」）和描述

上传一个应用图标

第三步：添加机器人能力

进入应用后，依次点击：应用能力 → 添加应用能力 → 按能力添加 → 机器人 → 添加

第四步：批量导入权限

进入「权限管理」页面，点击「批量导入/导出权限」→「导入权限」，将以下 JSON 完整粘贴并提交：

{  "scopes": {    "tenant": [      "aily:file:read",      "aily:file:write",      "application:application.app_message_stats.overview:readonly",      "application:application:self_manage",      "application:bot.menu:write",      "cardkit:card:read",      "cardkit:card:write",      "contact:user.employee_id:readonly",      "corehr:file:download",      "event:ip_list",      "im:chat.access_event.bot_p2p_chat:read",      "im:chat.members:bot_access",      "im:message",      "im:message.group_at_msg:readonly",      "im:message.p2p_msg:readonly",      "im:message:readonly",      "im:message:send_as_bot",      "im:resource"    ],    "user": [      "aily:file:read",      "aily:file:write",      "im:chat.access_event.bot_p2p_chat:read"    ]  }}

第五步：发布一个初始版本

在「版本管理与发布」中创建并发布一个初始版本（内容随意填写）。这一步必须完成，否则后续配置事件订阅时会报错。

第六步：配置事件订阅

进入「事件与回调 → 事件配置」，订阅模式选择长连接（推荐，无需公网 URL），然后添加事件：

im.message.receive_v1

注意: 如果此时 Gateway 尚未运行，长连接配置可能保存失败。建议先完成 OpenClaw 配置和 Gateway 启动后，再回来完成这一步。

第七步：获取凭证

进入「凭证与基础信息」，复制：

App ID（格式：cli_xxxxxxxxxxxxxxxx）

App Secret（请妥善保管，不要提交到代码仓库）

在 OpenClaw 中配置飞书渠道

执行命令：

openclaw channels add# → 选择 Feishu# → 粘贴 App ID# → 粘贴 App Secret

04、大模型配置

配置本地模型（Ollama）

如果你希望完全离线运行，可以通过 Ollama 使用本地模型：

{  "providers": {    "ollama": {      "baseUrl": "http://localhost:11434/v1"    }  },  "agents": {    "defaults": {      "model": {        "primary": "ollama/qwen2.5:32b"      }    }  }}

注意：OpenClaw 需要至少 64K 的上下文窗口。社区经验表明，14B 参数的模型勉强可以处理简单任务，32B+ 参数（需要至少 24GB 显存）才能可靠支持多步骤智能体任务。

模型故障转移

OpenClaw 支持配置认证轮换和指数退避的故障转移链：

{  "agents": {    "defaults": {      "model": {        "primary": "主模型",        "fallbacks": [          "备用模型1",          "备用模型2"        ]      }    }  }}

当主要模型不可用时，系统会自动切换到备用模型，保证 Gateway 持续运行。

05、智能体进阶配置

工作区与记忆

每个智能体都有自己的工作区目录，默认为 ~/.openclaw/workspace。对话记录、长期记忆和技能文件都以 Markdown/YAML 格式存储在这里，完全可读可编辑。

{  "agents": {    "defaults": {      "workspace": "~/.openclaw/workspace"    }  }}

心跳（Heartbeat）定时任务

心跳功能让智能体能够定期自主执行任务，非常适合每日简报、自动监控等场景：

{  "agents": {    "defaults": {      "heartbeat": {        "every": "30m"      }    }  }}

启用后，智能体会按指定间隔运行 HEARTBEAT.md 文件中定义的任务。你可以在工作区创建这个文件，写入自然语言指令，例如：

# Heartbeat 任务
每次运行时：1. 检查今日天气预报2. 查看待处理的 GitHub Issues3. 总结最新邮件（如果有）4. 将摘要发送到 Telegram

Cron 定时作业

比心跳更精细的定时控制：

{  "cron": {    "enabled": true,    "maxConcurrentRuns": 2,    "sessionRetention": "24h",    "runLog": {      "maxBytes": "2mb",      "keepLines": 2000    }  }}

通过 CLI 管理 Cron 作业：

# 列出所有作业openclaw cron list
# 添加作业openclaw cron add --schedule "0 9 * * *" --task "发送每日简报"

沙箱隔离

对于处理不可信数据或执行高危操作的场景，启用沙箱隔离：

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

mode 选项：

off：不使用沙箱

non-main：非主会话使用沙箱（推荐）

all：所有会话都使用沙箱

上下文管理

对于长对话，配置上下文裁剪策略防止 Token 溢出：

{  "agents": {    "defaults": {      "contextPruning": {        "mode": "sliding"      },      "compaction": {        "mode": "safeguard"      }    }  }}

contextPruning.mode 选项：

cache-ttl：超时后裁剪

sliding：保留最近的上下文（推荐）

none：不裁剪

06、多智能体编排

何时需要多智能体？

在考虑多智能体之前，先问自己：单智能体是否已经无法满足需求？

不需要多智能体的情况：

个人助理场景，处理多个渠道的消息

工具使用种类不多

上下文混用不构成问题

需要多智能体的情况：

需要真正的隔离（不同工具权限、不同记忆库）

家庭成员/团队成员需要各自独立的 AI 助手

工作和个人场景需要完全分离

持久智能体配置

在同一个 Gateway 中运行两个完全隔离的持久智能体：

{  "agents": {    "list": [      {        "id": "home",        "default": true,        "workspace": "~/.openclaw/workspace-home"      },      {        "id": "work",        "workspace": "~/.openclaw/workspace-work"      }    ]  },  "bindings": [    {      "agentId": "home",      "match": { "channel": "whatsapp", "accountId": "personal" }    },    {      "agentId": "work",      "match": { "channel": "whatsapp", "accountId": "biz" }    }  ]}

bindings 数组中，规则按顺序匹配，越具体的规则应放在越前面（特定 peer 规则优先于宽泛的渠道规则）。

子智能体（Sub-agents）

主智能体可以在运行时动态生成子智能体执行后台任务，任务完成后自动归档。这非常适合并行研究和耗时的工具任务。

子智能体通过两种方式调用：

会话工具中的 sessions_spawn

子智能体工具页面的 /subagents spawn

典型使用场景：

用户: 帮我对比分析 GPT-4o、Gemini 2.0 的性价比，      同时搜集各自的最新 Benchmark 评测数据

此时主智能体可以同时派生三个子智能体并行研究，最后汇总结果返回给用户，大幅缩短等待时间。

路由绑定最佳实践

多智能体部署中最常见的问题是绑定规则冲突。调试步骤：

# 列出所有智能体及其绑定规则openclaw agents list --bindings
# 检查特定消息的路由结果openclaw routing test --channel telegram --peer "tg:123456"

07、常用 CLI 命令速查

# 启动/停止/重启 Gatewayopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway status
# 打开 Web 控制面板openclaw dashboard
# 配置管理openclaw config get agents.defaults.workspaceopenclaw config set agents.defaults.heartbeat.every "2h"openclaw config unset tools.web.search.apiKey
# 渠道管理openclaw channels login        # 扫码登录 WhatsAppopenclaw channels list         # 查看渠道状态
# 智能体管理openclaw agents listopenclaw agents list --bindings
# 发送消息（测试用）openclaw message send --target +15555550123 --message "Hello from OpenClaw"
# 健康检查openclaw doctor
# 查看版本openclaw --version

聊天内置命令

在 WhatsApp/Telegram/Slack 等渠道发送以下命令：

/status        — 查看会话状态（模型、Token 用量、费用）/model         — 切换使用的 AI 模型/session       — 管理当前会话/help          — 显示帮助信息

# ONE

OpenClaw 的美妙之处在于它的渐进性——你可以从最简单的单渠道单智能体开始，用一个Bot 满足日常需求；随着使用深入，逐步引入多智能体、定时任务、语音控制、MCP 扩展，最终构建出一套完全属于你自己的、数据私有的 AI 自动化系统。

记住几个核心原则：

安全第一：在向外暴露任何接口之前，先用 openclaw doctor 检查配置，将 Gateway 地址限制为本地回环，启用 Token 认证。

循序渐进：先掌握单智能体，再考虑多智能体。不要为了技术先进性而增加不必要的复杂度。

数据主权：OpenClaw 的所有数据都存储在 ~/.openclaw/ 目录下，随时可备份、迁移、审计。这是自托管相比 SaaS 服务最核心的优势。

社区驱动：项目以 MIT 协议开源，拥有活跃的社区。遇到问题可以在 GitHub Issues 或官方 Discord 寻求帮助，也可以为 ClawHub 贡献自己的技能。