乐于分享
好东西不私藏

OpenClaw 保姆级教程:从安装到多 Agent,零基础教程(2026 更新版)

OpenClaw 保姆级教程:从安装到多 Agent,零基础教程(2026 更新版)

OpenClaw 一直很火,如果你想在自己电脑上装一个 AI 助理的普通人,不需要会编程,不需要懂命令行,跟着此篇教程复制粘贴、能对照图片核对结果,就能搭建起来。

本文将讲解这几个方面:

  • 一个装在自己电脑上、能在网页后台随时对话的 AI 助理;
  • 给它安装"技能"(Skill)的几种方法;
  • 能落地的实战案例:如自动收集资讯、写公众号文章、办公自动化等;
  • 让你知道什么时候才需要多个 Agent。

补充一个好消息:OpenClaw 官方文档已经有简体中文版,本文提到的所有官方链接,都可以切换成中文阅读。https://docs.openclaw.ai/zh-CN

一、OpenClaw 到底是什么?

如果把普通聊天机器人理解成“只负责回答问题的顾问”,那么 OpenClaw 更像一名长期在线的数字助理:它有自己的工作目录、记忆、技能和工具,还能通过 Telegram、WhatsApp、Slack、Discord 或网页界面接收任务等。OpenClaw 像你雇了一个住在自己电脑里的数字员工

  • 它有自己的办公桌和档案柜(Workspace,工作区);
  • 有一套可以反复使用的工作手册(Skills,技能);
  • 能用工具实际干活——读写文件、跑命令、开浏览器,而不是只动嘴;
  • 你可以在网页后台、Telegram、WhatsApp、Discord 等地方随时喊它。

OpenClaw 是运行在自己设备上的个人 AI 助手网关。它把消息渠道、大模型、工作区、技能与外部工具连接起来,让 AI 不只“告诉你应该怎么做”,还可以在获得授权后实际执行任务。

它的核心不是某一个模型,而是 Gateway:

  • 外部消息先进入 Gateway;

  • Gateway 判断应该交给哪个 Agent;

  • Agent 读取自己的 Workspace、长期规则和记忆;

  • 根据任务选择 Skill 与工具;

  • 完成后把结果返回原来的消息渠道。

先搞清楚这几个个词的含义:

术语
解释说明
Gateway
前台总机,统一收消息、转消息
Agent
真正干活的"数字员工"
Workspace
这名员工的办公桌和档案柜
Skill
一份可以反复用的标准工作手册(SOP)
SubAgent
一次任务里临时叫来的帮手

二、别急着安装部署,遵循以下步骤

新手最容易犯的错,是第一天就同时折腾模型、渠道、技能和多 Agent。任务一多,出了问题连该查哪都不知道。正确的节奏是下面这六步:

  • 先完成安装和 Onboarding;

  • 确认 Gateway 正常、网页后台可以对话;

  • 理解 Workspace 中每个文件的用途;

  • 只安装一个 Skill,拿真实任务测试;

  • 单 Agent 稳定后再创建长期角色;

  • 最后才尝试 SubAgent 并行协作。

三、安装前的准备

1. 一台电脑。 macOS、Linux、Windows 都支持。建议就装在自己天天用的电脑上——新手别急着上云服务器,远程连接、建立隧道这些额外步骤只会增加部署难度。

2. 会打开"终端"。

  • macOS:按 Command + 空格,输入"终端"(Terminal),回车;
  • Windows:开始菜单搜索 PowerShell,右键"以管理员身份运行";

给纯新手的技巧: 如果你装了 Cursor、Trae 这类 AI 编辑器,可以直接用它内置的终端来跑本文所有命令——遇到看不懂的报错,框选终端里的输出,右侧对话框里直接问 AI,不用来回切窗口截图。装 OpenClaw 的过程本身,就是练习"有问题问 AI"的好机会。

3. 准备一个大模型的使用授权。 OpenClaw 本身不带"大脑",它需要连接一个大模型才能思考。首次配置时会让你选择提供方并完成授权,所以请提前准备好对应的 API Key 或账号。

密钥就是密码。 一定要保管好,不要对外公开、贴进文章或代码库。

4. Node.js?新手直接跳过这一条。 官方安装脚本会自动检查并装好合适的 Node.js 版本,你完全不用提前折腾。只有选择 npm 手动安装的老手,才需要自己准备——可以用 node -v 查看当前版本,具体要求以官方安装页为准。

https://docs.openclaw.ai/zh-CN/install

四、第一步:安装(复制命令,回车,等它跑完)

1. macOS / Linux / WSL2

打开终端,粘贴这一行,回车:

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

脚本会自动识别系统、装好依赖、装好 OpenClaw,然后直接带你进入配置向导。中途按提示确认即可。

2. Windows 三种安装方法

  • Windows Hub(纯新手首选)
    官方的图形化安装程序,鼠标点点就装好,还带托盘状态和诊断面板。入口见官方 Windows 页面 :

    https://docs.openclaw.ai/zh-CN/platforms/windows

  • PowerShell 命令行:在 PowerShell 里执行:
iwr -useb https://openclaw.ai/install.ps1 | iex
  • WSL2
    适合本就在用 Linux 工具的老手,可以按上面 macOS/Linux 的命令装。

    在已经管理好 Node 环境的老手安装:

npm install -g openclaw@latest

npm 手动安装可能涉及脚本授权参数,细节以官方安装页:https://docs.openclaw.ai/zh-CN/install为准。新手用安装脚本,没有这些麻烦。

3. 安装后进行检查,确认安装

先关掉终端,重新开一个(这一步很重要,否则可能找不到命令),然后执行:

openclaw --version

能看到版本号,安装就成功了。如果提示"命令不存在",先重开终端再试;还不行就翻到文末排查表的第一行。

五、第二步:首次配置(跟着向导步骤)

如果安装脚本没有自动带你进向导,或者你中途退出了,手动执行:

openclawonboard--install-daemon

这会启动一个问答式配置向导。--install-daemon 的意思是顺便把 OpenClaw 装成后台服务、开机常驻——新手建议带上

安装向导会连着问你一串问题,看着很多,其实只要记住一个原则:除了模型相关的两三问必须认真答,其余全部可以先跳过——包括预置技能、各种服务密钥、Hook、消息渠道等,这些在网页后台或用 openclaw configure 随时能增加。照下图右侧的"新手建议"选就行:

如果只是想重新进入配置流程,可以运行:

openclaw onboard

当前官方还保留更完整的经典向导:

openclaw onboard --classic

经典模式适合自定义模型提供方、远程 Gateway、渠道配对和高级配置。第一次使用不必急着打开所有选项。

选什么模型?

海外:向导支持两种授权方式,有 Anthropic、OpenAI 会员的,可以直接网页登录授权;没有的就填 API Key。

国内:国产模型走 API Key 路线就行,Kimi、智谱、DeepSeek 等主流厂商都在支持列表里。这里推荐 Kimi:它的 API 缓存命中计费便宜,而 OpenClaw 这种长上下文、高频对话的用法恰好命中率极高,日常用下来成本明显低于他之前用的海外模型。具体价格,以每个模型的官网定价为准。

这里需要注意: 同一家模型往往有多个开放平台(如 Kimi 分国内的 .cn 和海外的 .ai,"编程套餐"的 Key 和普通 API Key 也不通用)。你的 Key 在哪个平台生成的,向导里就必须选对应的那个入口,选错了会一直报鉴权失败。

关于"绑定消息渠道"这一步:

建议先跳过。网页后台完全够用,渠道以后随时能加;真想在手机上随时调用,第七节末尾有一个 3 分钟的 Telegram 绑定指南。以后想补充或修改任何配置,运行 openclaw configure;想重新走一遍完整向导,再运行一次 openclaw onboard 即可。

六、第三步:确认"总机"在工作

配置完成,先确认 Gateway 真的在运行:

openclaw gateway status

正常会显示 Gateway 正在运行,监听默认端口 18789

如果显示没在运行(没有启动),请运行

openclaw gateway start

七、第四步:打开网页后台,发出第一条消息

打开命令行,输入命令:

openclaw dashboard

浏览器会自动打开控制台(Control UI)。

本机地址通常是 http://127.0.0.1:18789/。左侧是功能导航(对话、概览、Agents、Skills、渠道、定时任务等),右侧就是聊天区:

进去后,把这三条消息依次发给它,看下三类核心能力都正常:

  1. "用一句话介绍你自己"
    ——确认模型连通了;
  2. "看看我桌面上有哪些文件"
    ——确认它能操作你的电脑(文件工具);
  3. "查一下今天本地的天气"
    ——确认它能联网。

三条都有像样的回复——恭喜,你的 AI 助理已经正式上岗。这时它多半会反问你:叫它什么名字、希望它用什么风格说话。认真回答这几个问题,你说的内容会被自动写进它的档案文件,这就是它"越用越懂你"的起点。

三个让新手少走弯路的小技巧:

  • 它自己就是最好的 OpenClaw 老师。
    直接问它"你现在有哪些工具和技能可用""定时任务怎么设置",它会读取本地文档和配置来回答你——比翻文档快得多;
  • 想看它干活的过程
    发送 /verbose,它会把调用了什么工具、执行到哪一步都展示出来(默认只报结果),看完发 /verbose off 关掉。注意别在群聊里开,工具执行细节会暴露给所有群成员;
  • 排查问题优先看网页端。
    网页后台是流式输出、信息更全;聊天软件那边要等全部生成完才推送,感觉上会"卡"一点,这是正常的。

如果连第一条消息都没有回复,跑这两个诊断命令:

openclaw doctor          # 体检:自动检查常见配置问题openclaw logs --follow   # 实时日志:盯着红色报错找线索

如果配置有问题,可以尝试:

openclaw doctor --fix

安全提醒,非常重要: 这个网页后台 Control UI 管理界面,拥有配置和执行权限,绝对不要把它直接暴露到公网。想在外面远程访问,用 Tailscale、SSH 隧道或带身份验证的反向代理,具体见 Control UI 官方文档。

https://docs.openclaw.ai/zh-CN/web/control-ui

选配:绑定 Telegram,手机上随时调用:

Telegram 在国内需要自备网络工具,它是官方文档里公认最容易接入的通话APP,不绑定也不影响 OpenClaw 的全部功能

  • 在 Telegram 里搜索 BotFather,发送 /newbot
  • 按提示起一个显示名称,再起一个用户名——用户名必须以 bot 结尾,提示重名就换一个;
  • 创建成功后 BotFather 会发来一串 HTTP API Token,复制它;
  • 把Token填进配置向导里(或事后用 openclaw configure 增加);
  • 第一次给你的机器人发 /start,它会回一条授权命令——把这条命令复制到电脑终端执行一次,配对就完成了。

配置以后,用手机上的 Telegram 就可以直接对话安排工作。


到这里,基础部分全部完成。 下面部分则是进阶内容。

八、进阶一:Workspace,让它越来越懂你

Workspace 是 Agent 的工作目录。它不仅保存文件,还决定 Agent 的身份、行为边界、用户背景、工具说明和长期记忆。可以说Workspace是Agent 的"办公桌+档案柜",默认位置在 ~/.openclaw/workspace/

里面几个文件全都是普通文本文件,用任何编辑器都能修改:

一个实用的整理原则:

  • "以后都要遵守的规矩"写进 AGENTS.md
  • "希望它怎么说话"写进 SOUL.md
  • "关于你和项目的事实"写进 USER.md
  • 临时任务别往 MEMORY.md 里塞;
  • 会反复执行的流程,做成 Skill(下一节来讲)。

如果把所有信息都塞进一个文件,Agent 每轮都要读取大量无关内容,既浪费上下文,也容易让规则互相冲突。

顺便认识一下 ~/.openclaw/ 目录里的其他文件,现在不用动,知道在哪就可以了:

  • openclaw.json :全局主配置(模型、渠道、多 Agent 等);

  • agents:存会话历史;

  • skills: 放全局共享的技能。

注:不同版本默认生成的文件可能略有差异,以你本机实际看到的为准,分工思路是一样的。

九、进阶二:给它装第一个 Skill

Skill 就是一份写给 Agent 看的标准作业手册(SOP)。它通常是一个文件夹,核心文件是 SKILL.md,其功能作用主要是:

  • 什么情况下应该触发;

  • 需要遵守哪些步骤;

  • 可以使用哪些工具;

  • 哪些文件或操作禁止触碰;

  • 最终应当交付什么结果。

Skill 并不等于一个完整应用。它更像是“任务说明书 + 必要脚本与资源”。

安装使用 Skill 主要有下面几种方式

方式一:在网页后台的 Skill 菜单里寻找适用的技能(最省事)

打开后台的 Skills 页面,里面有一批官方预置技能(密码管理、笔记工具等),

方式二:使用现成的技能市场 ClawHub,https://clawhub.ai/。每个 Skill 的说明、版本和安全扫描状态都能直观的看到。

方式三:官方命令行(主力方式)

官方推荐直接使用 OpenClaw 自带命令,按照如下步骤:

第 1 步:搜索 Skill

openclaw skills search "calendar"

第 2 步:安装前先验证

openclaw skills verify @owner/skill-name

verify 会核对这个 Skill 在 ClawHub 上的发布信息和信任状态,但还是建议打开它的 SKILL.md,看清它要读哪些文件、要不要 API Key、会不会执行命令和联网。

第 3 步:安装到当前工作区

openclaw skills install @owner/skill-name

默认安装到当前 Workspace 的 skills/ 目录,只对当前 Agent 生效。如果多个 Agent 都要使用,加上 --global 安装到共享目录。

第 4 步:测试使用。 安装完成拿一个真实任务测试。

第 5 步:定期更新。

openclaw skill supdate ——all

方式四:npx skills add(装 GitHub 上的技能包)

很多优质技能包发布在 GitHub 上、不在 ClawHub 里,这时用 Vercel 出的通用技能安装器 skills CLI (https://github.com/vercel-labs/skills)进行安装。

npx skill sadd 作者名/仓库名 # 整个技能包一起装 npx skill sadd 作者名/仓库名--skill技能名 # 只装其中一个

运行后它会让你选装给哪个工具(列表里选 OpenClaw)、装到当前项目还是全局。技能目录 skills.sh (https://skills.sh/)可以当商店逛。

两个提醒:优先粘贴完整的 GitHub 链接来安装,简写形式曾出现过解析到同名第三方包的翻车案例,安装完成检查 skills/ 目录里是不是你要的技能;另外这类第三方技能大多需要你把相应平台的密钥填进它指定的 .env 文件才真正可用, SKILL.md 里一般都会说明怎么填写。

在安装第三方 Skill时,一定要安明确几个问题:

  • 发布者是谁,仓库是否可信?

  • Skill 会读取哪些文件?

  • 是否要求 API Key、登录凭证或浏览器会话?

  • 是否会运行命令、安装依赖或访问网络?

  • 是否可能发送消息、删除文件或修改外部服务?

  • 出错后怎样回滚?

最后三个实用技巧:

  • 装完在对话里找不到新技能?
    运行 openclaw gateway restart 重启网关,新开一个会话,十有八九就出现了;
  • 懒得自己搜技能
    可以先装一个"找技能的技能":
    npx skills add vercel-labs/skills --skill find-skills
    之后直接在对话里说"帮我找几个 XX 方面的技能",它会代你搜索并把安装命令列出来;
  • 有些教程是先单独装 clawhub CLI 再 clawhub install。现在普通用户直接用 openclaw skills 这一套就够了,单独的 clawhub CLI 主要留给发布者做登录、发布和管理用。

十、进阶三:多 Agent:让不同角色拥有各自的工作区

1. 大多数人前两周只需要默认的那一个 Agent( main)。出现下面这些情况,才值得建新角色:
  • 工作消息和私人消息必须隔离;
  • 不同渠道需要不同身份(私人 WhatsApp 归生活助理,工作 Telegram 归工作助理);
  • 写代码、做研究、写文章需要完全不同的规则和工具权限;
  • 各个角色需要各自独立的长期记忆。

2. 多 Agent 不是简单地复制几个聊天窗口。OpenClaw 中每个 Agent 都可以拥有独立的:

  • Workspace;

  • 人格和操作规则;

  • 模型配置;

  • 授权信息;

  • 会话与记忆;

  • Skills 和工具权限。

这意味着你可以长期设置研究员、写作者和开发者,而不用让一个 Agent 同时背负所有角色。

3.多 Agent 适合什么场景

  • 不同渠道需要不同身份;

  • 工作与私人数据必须隔离;

  • 编程、研究和内容生产需要不同规则;

  • 某些角色只能使用特定工具;

  • 希望不同角色拥有独立长期记忆。

如果只是当前任务需要并行查三份资料,不必为每份资料创建一个永久 Agent,这正是 SubAgent 更适合的地方。

4. 创建长期 Agent。创建就是一行命令:

openclaw agents add dailynews # 新建一个叫 dailynews 的角色openclaw agents list  # 看看现在有哪些员工openclaw agents list --bindings # 看消息渠道分别绑给了谁

agents add 会启动一个小向导,依次确认四件事,照实际需求设置:

  1. 工作区目录
    默认建在 ~/.openclaw/workspace-名字,回车即可;
  2. 要不要从 main 复制身份配置
    新角色和主助理差不多就选"是",想完全重练就选"否";
  3. 要不要单独配模型
    可以按任务给不同角色配不同的模型——写代码的用强模型,跑日常摘要的用便宜模型;
  4. 要不要绑独立渠道
    比如给"每日资讯"角色单独建一个 Telegram 机器人,流程和第七节那个 3 分钟指南完全一样(新机器人第一次 /start 同样会给授权命令,去终端执行一次)。

绑定(binding)解决的是"消息该转给谁"的路由问题:比如私人 WhatsApp 绑给 home,工作 Telegram 绑给 work。改完配置记得运行 openclaw gateway restart 让它生效。日常使用中,在会话里发 /model 可以查看和切换当前模型,发 /status 可以查看运行状态。

如果只是"这个任务需要同时查三份资料",不要为此建三个永久 Agent——这正是下一节 SubAgent 的用武之地。

十一、进阶四:SubAgent,一次任务里的临时帮手

1. 简要说明。多 Agent 是"长期雇人",SubAgent 是"临时叫帮手":主 Agent 执行任务时临时拉起几个分身并行干活,干完把结果交回主 Agent,然后自动归档(默认 60 分钟后清理)。

一个典型任务可以这样拆解:

  • SubAgent A:搜集官方资料;

  • SubAgent B:检查安装命令;

  • SubAgent C:从新手角度寻找遗漏步骤;

  • 主 Agent:合并、去重并生成最终教程。

2. 使用方式。这个功能开箱即用,一行配置都不用改。 直接在对话里下指令就行,比如:

调度子代理,并行查询北京、上海、深圳今天的实时天气,汇总成一张表给我。

主 Agent 就会自动拆任务、派生分身并行执行、汇总结果。

3. 在任务执行的过程当中,随时可以用这几条命令查询当前状态:

/subagents list        # 现在有几个帮手在干活/subagents info <id>   # 看某个帮手的详情/subagents log <id>    # 看它的执行日志

4. 怎么去判断该用多 Agent 还是 SubAgent?只看这是一个长期岗位,还是这一单任务里的临时分工。

对比
多 Agent
SubAgent
生命周期
长期存在
任务内临时创建,用完归档
上下文
各自独立的 Workspace
默认只带任务说明的干净上下文
记忆
长期保存
只为完成本次任务
消息路由
可绑定渠道
由主 Agent 调度
适用场景
长期角色、权限隔离
并行研究、检查复核

5. 允许 Agent 调用其他 Agent。

如果你想让主 Agent 把工作安排给其他已经建好的 Agent(比如让 main 指挥 researchwriter),这要在 ~/.openclaw/openclaw.json 里加白名单(allowlist)。示意配置如下:

agents.entries格式的完整配置:main可以调用researchwriterreviewer,三个辅助Agent不能继续创建下级Agent:

{  agents: {    defaults: {      subagents: {        // 所有任务合计最多同时运行4个子Agent        maxConcurrent: 4,        // 只允许主Agent创建一级子Agent        maxSpawnDepth: 1,        // 子Agent完成60分钟后自动归档        archiveAfterMinutes: 60,      },    },    entries: {      main: {        default: true,        workspace: "~/.openclaw/workspace",        // main允许调用的Agent白名单        subagents: {          allowAgents: [            "research",            "writer",            "reviewer",          ],        },      },      research: {        workspace: "~/.openclaw/workspace-research",      },      writer: {        workspace: "~/.openclaw/workspace-writer",      },      reviewer: {        workspace: "~/.openclaw/workspace-reviewer",      },    },  },}

字段名可能随版本调整,最终以 SubAgent 官方文档为准。

SubAgent 默认只继承 AGENTS.md 里的规则,不会自动带上 SOUL.mdUSER.md 和长期记忆。所以在安排分配工作时要把任务说明写清楚。

十二、常见问题排查

诊断三个步骤,能解决大部分问题:

现象
优先检查
openclaw 命令不存在
重开一个新终端;再检查 npm 全局路径和安装器输出
向导里模型鉴权总失败
检查 Key 与生成平台是否对应(如 Kimi 的 .cn / .ai、编程套餐 Key 不通用)
Gateway 没有运行
openclaw gateway status,必要时 openclaw gateway start
网页后台打不开
检查 18789 端口、Gateway 日志、本机防火墙
后台提示 Unauthorized
用 openclaw dashboard 重新打开,检查 Gateway Token
模型没有回复
检查模型授权、API Key、额度和网络连接
配置校验失败
运行 openclaw doctor,检查 JSON5 格式(可试 --fix
新装的 Skill 对话里找不到
openclaw gateway restart,然后新开一个会话再试
Skill 不触发
检查 SKILL.md 的 name、description、目录位置和依赖
Skill 安装后报错
读它的依赖说明,检查所需命令、.env 密钥和环境变量
Agent 收不到消息
openclaw agents list --bindings,检查渠道账号和首次授权是否完成
无法创建目标 SubAgent
检查 subagents.allowAgents 和目标 Agent 是否存在
更新后后台显示异常
openclaw gateway restart,强制刷新并清浏览器缓存

十三、推荐的案例仓库

  • awesome-openclaw-usecases 

  • awesome-openclaw-usecases-zh

网址:https://github.com/AlexAnys/awesome-openclaw-usecases-zh

这是一个面向中文用户的 OpenClaw 应用案例库,并不是 OpenClaw 官方项目。仓库目前收录约50个经过整理的真实用例,其中包含23个针对国内生态设计或适配的场景。

内容覆盖:

  • 飞书、钉钉、企业微信机器人;
  • 小红书、公众号和播客内容自动化;
  • A股监控、财报追踪和竞品研究;
  • 邮件、会议纪要及客户服务;
  • 早间简报、知识库和个人助理;
  • 多Agent协作、自动化开发与服务器运维。

每个用例通常会说明解决的痛点、实现功能、所需技能、配置步骤、可复制提示词以及注意事项,并按照一至三星标注难度,对新手比较友好。仓库还提供AGENTS.md、用例索引和跨Agent概念对照,因此也可以把其中的案例交给OpenClaw、Codex或Claude Code辅助复现。

需要注意的是,其中引用的第三方Skills和依赖并未全部经过仓库维护者安全审核,正式使用前应检查源代码、权限范围及密钥配置。

比较优质、值得试用的案例:

  • 多智能体协作操作系统

    将 Agent 划分为战略参谋、技术负责人、执行者、审计和知识管理等角色,还设计了分级授权、跨 Agent 通信和知识沉淀机制。适合系统学习多 Agent 架构。

  • 多智能体内容工厂

    将内容生产拆成调研、写作和封面生成三个环节,由不同 Agent 接力完成,还可以设置每天定时运行。与你目前的文章创作场景最贴近。

  • 微信公众号自动化

    面向公众号选题、内容处理和发布流程,适合参考如何把“搜集资料—写稿—审核—发布”串成自动化工作流。

  • 小红书内容自动化

    更偏向社交媒体内容,包括选题、文案、图片和发布流程,对研究多平台内容改写也有参考价值。

  • 中国互联网深度调研

    适合建立持续追踪、资料收集和阶段性总结的研究 Agent。

  • 本地知识库与 RAG

    用来让 Agent 查询自己的文章、文档和历史资料,适合积累长期可复用的个人内容库。

  • 办公自动化

    偏向文档、表格和日常办公任务,比较容易落地,适合作为第一个实操案例。

下载地址:https://pan.quark.cn/s/2d36cdd65362

结语:

OpenClaw 的学习门槛主要来自有很多组件,而不是某一步特别难。把这套系统进行拆解,也就如下几个安装使用流程:

  • # 安装 CLI

  • 完成 Onboarding

  • 验证 Gateway 与 Dashboard

  • 整理 Workspace

  • 安装并测试 Skill

  • 创建长期 Agent

  • 使用 SubAgent 并行分工