下载安装和跑通

🏛️ 需要理解的前置概念

在开始动手操作之前，了解清楚这些概念更有利于更顺利的玩转 OpenClaw。

OpenClaw 采用"微核 + 插件 + 统一网关"的架构模式，可以类比为一个"AI 操作系统"。

架构总览

WhatsApp / Telegram / Slack / Discord / 飞书 / ... / WebChat
                    ↓
            ┌───────────────┐
            │    Gateway    │
            │  (控制平面/中枢) │
            │ ws://127.0.0.1:18789 │
            └───────────────┘
                    ↓
        ┌──────────┼──────────┐
        ↓          ↓          ↓
    Pi Agent    CLI 工具    WebChat UI
    (RPC)    (openclaw...)  macOS App
                          iOS/Android

Gateway（网关）

Gateway 是整个系统的心脏，负责管理所有连接、会话、配置、定时任务和 Webhook。

功能模块	说明
统一接入与协议处理	WebSocket 主控制协议（双向）、HTTP 服务（Hooks、集成）
身份认证与安全边界管控	用户/设备认证、工具调用沙箱策略、白名单 & 权限
消息路由与会话管理	匹配 Agent 实例、并发控制（队列）、上下文状态持久化
全局状态管理与广播	实时执行 & 任务广播、跨终端状态同步

提示

Gateway 自己不做"思考"——思考交给 Agent。把它理解为一个"电话总机"：所有渠道的消息进来，它负责转接给合适的 Agent 处理。

Channels（消息渠道适配器）

每个聊天平台都有一个独立的适配器，通过消息总线与 Agent 解耦。

你可以同时连接 WhatsApp、Telegram 和 Slack，在任何一个平台上跟你的 AI 助手对话，体验完全一致。

核心优势：解耦核心计算与外部通讯，实现 AI 无缝挂载。

Hooks（扩展机制）

Hooks 是事件驱动的底层自动化扩展机制，无需修改核心代码即可扩展 AI 能力边界。

在 OpenClaw 的运行周期内，系统会不断产生各种生命周期事件：

• 系统启动
• 开启新会话 /new
• 触发特定工具
• 运行报错

Hooks 允许开发者预先埋入特定的逻辑，当这些系统事件发生时，自动"拦截"并触发执行。

CronJob（定时任务）

常规的 AI 助手通常是"被动响应式"的，必须依赖用户的 Prompt 唤醒才能工作。

CronJob 打破这一限制，让 AI 可以主动执行：

特性	说明
基于时间的自动化调度	在特定时间节点或按固定频率唤醒智能体
脱离即时指令	独立完成周期性数据巡检、生成汇总报告、定时信息推送
数字员工模式	行为模式更接近具备自主性的"数字员工"

四大核心概念的协同关系

四个模块相互协同，共同构成了 OpenClaw 高可扩展、高可控、高灵活的核心架构：

┌─────────┐     用户指令      ┌─────────┐
│Channels │ ───────────────→ │         │
│ 渠道    │                  │         │
└─────────┘                  │         │
      ↑                      │ Gateway │←──────┐
      └──────────────────────│  网关   │       │
            标准化数据       │         │       │
                             │         │       │
┌─────────┐   Gateway 调度   │         │       │
│CronJob  │ ←─────────────── │         │       │
│定时任务  │                  └────┬────┘       │
└─────────┘                       │            │
      ↓                           ↓            │
 自动化任务                  ┌─────────┐       │
                             │AI 智能体 │←─────┘
┌─────────┐   无侵入能力增强  │         │ 任务的过程
│  Hooks  │ ←─────────────── │         │
│  钩子   │                  └────┬────┘
└─────────┘                       │
      └──────────────────────────→┘
              事件处理完成 → AI 响应

组件	定位	作用
Gateway	网关 - 核心中枢	所有组件的接入与调度中心
Channels	渠道 - 交互入口	为 Gateway 提供标准化的用户指令
Hooks	钩子 - 事件扩展机制	基于 Gateway 分发的事件实现无侵入式能力增强
CronJob	定时任务 - 主动执行引擎	通过 Gateway 调度 AI 智能体实现自动化任务

记忆系统：OpenClaw 的灵魂

这是 OpenClaw 最具突破性的设计，采用分层记忆架构：

层级	文件	作用
身份层	SOUL.md	定义 AI 的性格、语调、行为边界
用户层	USER.md	用户的个人资料和偏好
操作层	AGENTS.md	操作指南、工作流程、能力边界
索引层	MEMORY.md	核心信息索引，保持精简（<40行）
项目层	memory/projects.md	各项目当前状态与待办
基础设施层	memory/infra.md	服务器、API、部署配置速查
经验层	memory/lessons.md	踩过的坑，按严重程度分级
日志层	memory/YYYY-MM-DD.md	每日原始记录

提示

一个月后，你的龙虾就会摸清你的工作作息、沟通偏好、正在推进的项目、讨厌的细节、常用工具，还懂你十几项不同任务里"按老样子来"到底是什么意思。

这种持续使用的复利效应是任何无状态 AI 工具无法复制的。

🚀 把 OpenClaw 跑起来

这个章节中，你将了解搭建 OpenClaw 的环境要求，具体的安装流程，以及初始化向导中的一些推荐配置。

环境要求

安装 OpenClaw 需要 Node.js 22 以上的版本。

安装方式一：图形界面安装

1. 打开官网：https://nodejs.org/，直接下载「LTS版」的 .pkg 安装包
2. 双击下载的 .pkg 文件，依次点击「继续」→「同意」→「安装」，输入电脑密码验证权限
3. 等待安装进度条走完，点击「关闭」即可

安装方式二：Homebrew 安装

打开终端，输入一行命令：

brew install node

安装完成后，在命令行执行验证：

node -v

若看到版本号 >= v22，可以继续后续的安装操作。

安装命令

现在你的电脑上已经拥有了 Node.js 环境，使用 npm 来安装 openclaw：

npm install -g openclaw@latest

然后静静等待几分钟即可，中间输出的 warning 可以直接忽略。

安装成功后，执行版本检查：

openclaw --version

如果看到类似的版本号（如 2026.2.26），说明安装成功。

配置向导

接下来，运行 openclaw 提供的初始化向导来完成必要的配置：

openclaw onboard --install-daemon

第一步：安全确认

首先会看到 openclaw 给出的安全提示。OpenClaw 是一个 hobby project，默认是个人 agent，bot 可以读取文件和运行操作。如果你认为当前环境足够安全（可以接受被攻击可破坏），选择 Yes 继续。

第二步：选择配置模式

接下来会提示你选择配置模式，新手推荐选择 QuickStart，先快速跑起来，后续所有的配置都可以再进行更改。

第三步：选择模型厂商

接下来会提示你选择一个模型厂商：

• 如果不差钱，直接使用 Anthropic/OpenAI 的旗舰模型，效果是最好的
• 如果考虑性价比，可以选择国产的 GLM、MiniMax、Qwen 等

选择后会提示你配置对应的 API Key。

提示

如果使用的模型厂商不在推荐列表中，或需要配置自定义本地模型服务，可以先选择 Skip for now，后续在 Gateway 中进行配置。

第四步：选择模型

根据上一步选择的模型提供商选择合适的模型即可。如果希望后续再自定义模型，这一步就选择 Enter model manually。

第五步：配置 Channel

接下来会提示你配置 Channel，这里建议先 Skip，尽量先保证基础的流程能够跑通再接入三方平台，这样排查问题比较方便。

第六步：安装 Skills

接下来会提示你安装 Skills，为了先跑通流程，建议选择 Skip for now，后续在网页中进行单独配置。

第七步：配置 Hooks

接下来会提示你配置 Hooks，有两个 Hooks 建议直接开启（空格选中）：

Hook	作用
command-logger	将系统中所有命令相关的事件统一记录到一个集中的审计文件中，排查问题非常有用
session-memory	在用户执行 /new 或 /reset 命令时，将当前的会话上下文数据保存到内存中，避免会话状态丢失

第八步：完成安装

Hook 配置完成后，会自动进行网关的配置，然后选择 TUI 默认选项结束安装。

向前翻一下终端，可以看到带有 Token 的 WebUI 地址，例如：

http://127.0.0.1:18789/#token=4c9ace27b324109b6d5720b934c2bfc8facb477

在浏览器中访问这个地址，如果正常出现 OpenClaw 控制台界面，则代表安装过程已经成功。

验证运行

进入 OpenClaw Control 界面后，可以看到概览页面显示：

• 网关访问：WebSocket URL、网关令牌、默认会话密钥
• 快照：状态（正常）、运行时间、最后频道刷新
• 实例、会话、定时任务等状态信息

点击左侧「聊天」，如果刚刚在向导过程中已经配置过模型 API Key，现在就可以尝试和它进行对话了。

在聊天框输入 /model status 指令可以查看当前已经配置好的所有模型。

提示

如果配置过多个模型，可以使用 /model 模型标识 快捷切换模型。

📝 总结

至此，已经完成了 OpenClaw 的：

• ✅ 环境准备（Node.js 安装）
• ✅ 工具安装（npm 全局安装）
• ✅ 初始化配置（向导配置）
• ✅ 运行验证（WebUI 访问和对话测试）

📚 参考资料

• 需要理解的前置概念 | OpenClaw 完全指南

• 把OpenClaw跑起来 | OpenClaw 完全指南