1. 部署之前先把 OpenClaw 与 Clawdbot 的关系捋清楚1.1 一顿操作猛如虎装完发现装错包先说结论OpenClaw 和 Clawdbot 是同一个项目的两个“马甲”只是不同发行阶段叫法不一样。早期版本在 GitHub 和 npm 上直接用clawdbot作为包名后来官方把项目统一收敛到 OpenClaw 这个代号npm 和 Docker Hub 上的包名也换成了openclaw/cli。很多新手第一次装的时候照着老教程敲npm i clawdbot -g也能装上但装出来的可能是几个月前的旧包而且所谓“集成 Skill”的路径、配置格式都变了最后卡在报错环节白白浪费时间。我遇到过不少伙伴拿旧笔记来问我说装完openclaw之后skill列表一直是空的其实就是官方早期把 Skill 的存储位置放在~/.clawdbot/skills后期统一迁到了~/.openclaw/skills配置文件也从纯 JSON 改成了 YAML 与 Markdown 混排。所以这篇教程里我统一以当前可用版本为准不管标题写的是 OpenClaw 还是 Clawdbot大家认准这一套目录结构就行至于历史版本之间的差异不用太纠结能用就行。提示所有命令默认在 Windows PowerShell、macOS 和主流 Linux 发行版下均可执行。但凡涉及wsl的都是 Windows 专属macOS 或 Linux 用户直接跳过对应小节。1.2 新手必须提前知道的 6 个核心概念在动手前先花 60 秒把这几个概念过一遍后面集成 Skill 时你就不会一脸懵。OpenClaw 本质上是一个智能体运行时你可以把它理解成一个“会自己调用工具和脚本的外脑外手”。它的几个关键概念如下代理AgentOpenClaw 运行起来之后你通过对话或指令控制的那个实体它负责理解意图、拆解任务、调用工具。运行时Runtime负责调度和执行的底层服务也就是你要部署的那个东西命令行里叫openclaw serve。Skill一组可以被代理调用的能力封装类似音箱的“技能库”一个 Skill 通常由说明文档、入口脚本、元信息三部分组成。会话Session一次连续交互的状态OpenClaw 会在本地保存对话历史、任务进度和临时文件。工具Tool比 Skill 更底层的能力单元比如“执行 Shell 命令”“读文件”“请求某个 HTTP 接口”Skill 相当于把多个工具串成一个可复用的流程。记忆MemoryOpenClaw 的长期记忆区域用来保存跨会话的信息比如用户偏好、项目背景后面集成业务 Skill 时经常要用到。很多教程喜欢一上来就让新人改配置、写代码结果一小步报错一大步迷茫。我强烈建议先跑通默认版本确认“能跑”之后再考虑要不要自己写 Skill否则你根本分不清到底是环境问题、配置问题还是你的 Skill 代码本身有问题。1.3 这套部署方案到底解决了什么问题这个 8 分钟方案的目标很明确让一个完全没碰过 OpenClaw 的新手从拿到电脑开始计时在十分钟以内把服务跑起来、完成首次对话、把两个现成 Skill 装上并成功调用。它适合的人包括本地开发者和 AI 应用爱好者想在自己电脑上搭一个不依赖云端的智能体自动化玩家想用 OpenClaw 做定时任务、文件整理、信息聚合刚接触“智能体 工具调用”概念想找个现成项目练手的人。不适合哪些人如果你完全没用过命令行、连 Node.js 和 Git 是什么都不清楚那 8 分钟大概率不够建议先花半天把基础操作过一遍再来。这篇文章也不是给重度定制者看的如果你想自己造一套完整的“企业级智能中台”那要另开一个议题。总之这个方案解决的是“快速起步 常用 Skill 集成”问题不解决“高度定制”问题。2. 8 分钟实操部署从零到跑通官方内置 Demo2.1 开跑前 1 分钟的环境自检时间有限先别急着敲命令按照下面的清单检查完再继续能省去后面至少十分钟的排错时间确认 Node.js 版本在 20 及以上在终端执行node -v如果版本低于 20去官网装 LTS 版本不要装奇数版本。确认包管理器可用npm 和 npx 都要能正常运行执行npm -v。确认有干净的终端环境Windows 用户建议使用 PowerShell 7 或 Windows Terminal不要用老的 cmd.exe。如果是 Windows确认 WSL2 子系统可用在 PowerShell 执行wsl --status。如果提示还没有安装发行版先执行wsl --install -d Ubuntu-22.04并完成初始化。确认磁盘有至少 4GB 空闲空间内存建议 8GB 以上。为什么要在开头卡这么严格因为 OpenClaw 的前端是 Node.js后端编排层有很多二进制的原生依赖如果用太老的系统环境会遇到各种编译错误和证书签名问题。这就像盖房子前先打地基地基歪了后面装修得再好也是白搭。很多从零开始部署 OpenClaw 的教程默认你拥有一台干净的服务器但实际上大部分人拿的是 Windows 笔记本或者是公司统一配发的受限电脑可能已经装了 Python、Miniconda 甚至多个版本的 Node环境乱得很。我的经验是宁可先清掉 PATH 里的历史残留也不要让 OpenClaw 在半吊子环境里硬跑。检查完以后如果有重复的 Node 环境卸载干净再装统一版本后面会轻松很多。注意怀疑自己 Windows 环境紊乱的同学优先在 PowerShell 跑wsl --status把服务放到 WSL2 发行版里部署。WSL2 的网络和文件权限模型更干净能避开大量 Windows 原生文件锁带来的坑。但如果你只是想先快速看看效果直接在 Windows 主机上跑也没问题我会在下面给出两个分支方案。2.2 拉代码、装依赖、启动服务2 分钟核心命令我推荐用官方现成脚本部署一句话到位适合“没耐心看完文档”的人。在终端里执行npm install -g openclaw/cli openclaw init demo-bot cd demo-bot openclaw serve --port 3001如果你不想全局安装也可以用 npxnpx openclaw/cli init demo-bot npx openclaw serve --port 3001来看看这几条命令各自到底做了什么。npm install -g负责把 CLI 工具本身装到系统路径里让你在任何目录都能调用openclaw。openclaw init demo-bot负责在当前位置创建一个名为demo-bot的项目文件夹里面会自动生成默认配置、Skill 目录和示例脚本。openclaw serve则是真正把服务启动起来的动作--port 3001指定运行端口避免和本机其他服务冲突。第一次启动时OpenClaw 会在~/.openclaw/目录下自动创建缓存、日志、会话数据库和 Skill 目录。如果看到类似Startup completed in 3.2s的日志说明核心服务已经跑起来了。这时候打开浏览器访问http://127.0.0.1:3001就能看到内置的管理页面。举个实际可能遇到的问题。假设端口被占用你会看到EADDRINUSE的红色提示。解决办法很简单换一个端口重新起openclaw serve --port 3010。不要跟系统服务抢 3000 这种公共端口除非你确认它没被占用。2.3 认证与首次对话2 分钟关键配置服务起来之后还差一个关键步骤设置身份认证。OpenClaw 默认不开放远程访问本地访问也需要配置一个 Access Token。打开浏览器进入管理页页面上会先要求你设置管理员密码这个密码会被散列保存在本地配置里作用有两个一是防止局域网内其他人连上你的服务乱调用工具二是作为后续 API 请求的头信息。如果你走的是命令行客户端首次连接时执行openclaw auth login按照提示粘贴刚才设置的管理员账号密码会生成一个会话令牌并存储到~/.openclaw/auth.json。之后所有该用户发起的操作都会带上这个令牌不需要反复重新输入。完成认证以后在同一个终端里执行openclaw chat --session demo-session这样会进入交互式对话界面。你直接输入“你好介绍一下你自己”看看能不能正常回答。能回答说明核心链路已经通了。接着尝试问一个需要工具的任务比如“帮我列出当前目录下的所有文件”这个操作会触发 OpenClaw 的 Shell 工具调用看看它能否正确执行并返回结果。如果这一步也没问题你的基础部署已经 100% 成功了。在这一步我补充一个重要细节默认的内置代理其实非常保守工具调用之前会请求确认。如果你不想每执行一个命令都要点确认可以在配置文件里把auto_approve开起来但真不建议在重要环境这么干风险极高。新手阶段老老实实用确认模式能够帮你理解“代理到底做到了什么程度”等熟悉了调用边界再切换也不迟。2.4 验证部署成功的 3 个判断依据怎么确认自己是“真部署成功”而不是“看着像成功”我用三个标准来判断进程持续在跑执行openclaw status返回running且日志里没有明显报错。对话有来有回在openclaw chat里连续对话三轮观察是否存在中途断连、无响应、上下文丢失的问题。Skill 目录能读到执行openclaw skill list能看到built-in.core和built-in.web两个内置 Skill这说明 Skill 扫描机制正常后面接自定义 Skill 就不会踩“目录扫描不到”这类坑。这三个判断依据不是随口说的。openclaw status验证的是服务生命周期是否正常连续对话验证的是运行时上下文Skill 列表验证的是插件加载能力。三件事分别对应“服务能跑”“对话能用”“扩展能加载”任何一个不满足说明部署链路还有隐患直接进入第 4 节对号入座排查。3. Skill 集成实现原理与落地案例3.1 Skill 到底是什么它和插件、工具调用有什么关系接着刚才的话题Skill 是 OpenClaw 最有价值的部分。你可以把它想象成给代理插 U 盘代理本身是一个能干杂活的通用大脑Skill 是专门解决某个特定问题的 U 盘。比如“整理 Markdown 笔记”是一个 Skill“查询本地天气”是另一个 Skill“把一段文字转成语音”又是一个 Skill。每一个 Skill 都告诉代理三件事这个技能是干什么的应该在什么时候调用具体怎么干。Skill 和“工具”的区别在于粒度。工具是单一动作比如“读文件”“写文件”“发送 HTTP 请求”Skill 是把多个工具按业务逻辑串起来的流程。普通用户不需要写工具只需要写“召唤工具”的 Skill。OpenClaw 内部执行一个任务时的顺序大致是用户提出需求代理拆解意图代理在已加载的 Skill 列表里检索匹配项匹配成功的 Skill 被激活按其说明文档中的描述来安排执行Skill 调用底层工具逐项获取结果代理把多个中间结果汇总生成最终回答。理解这五步你就明白为什么 Skill 的“说明文档”写得越清楚代理执行得越准。很多人的 Skill 写得很乱不是代码不行而是“教代理怎么用”的文字说明不充分。3.2 自己动手写一个 20 行以内的 Skill 并接入直接上实操。我们先写一个最简单的“本机磁盘信息查询” Skill。为什么要从它开始因为它足够短又涉及读取系统命令与格式化输出这两件事是整个 Skill 开发里最常见的两个动作。在~/.openclaw/skills/disk-info/目录下创建两个文件SKILL.md和run.sh。先看SKILL.md这个文件负责“教代理怎么用”--- name: disk-info description: 查看本机磁盘使用情况返回各分区总量、已用量和剩余空间。 trigger: 用户询问磁盘、空间、硬盘剩余、存储不足 --- # disk-info 当用户提到“磁盘满了”“看看空间”“存储不足”等情况时立即调用本技能。 ## 执行步骤 1. 在终端中运行 bash run.sh 2. 将脚本输出的结果原样返回给用户 ## 注意 - 本技能只读取信息不执行任何写入或修改操作 - 如果执行结果为空或权限不足请在回答中说明“无法读取磁盘信息”再看run.sh#!/bin/bash df -h | awk NR1 || $5080 {print $0}这个脚本干了什么df -h以人类可读方式列出所有文件系统的使用情况awk先打印表头NR1再筛选出使用率超过 80% 的行。也就是说它不只显示全部磁盘还会特别标记快满的分区这正是运维场景下最关心的信息。如果你用 Windows 且没有 WSL可以把run.sh换成 PowerShell 脚本run.ps1Get-PSDrive -PSProvider FileSystem | Select-Object Name, {NameUsed(GB);Expression{[math]::Round($_.Used/1GB,2)}}, {NameFree(GB);Expression{[math]::Round($_.Free/1GB,2)}}然后修改SKILL.md里执行步骤为powershell -File run.ps1即可。Skill 目录放好后执行openclaw skill reload再去看openclaw skill list就能看到disk-info出现在列表里。接着在对话里输入“我的 C 盘快满了吗”代理就会自动定位到 disk-info 这个 Skill 并执行脚本返回结果。3.3 接入现成 Skill 的套路以笔记归档为例写一个 Skill 很简单但是要真正用好 Skill你得掌握“接入一个现成 Skill”的套路。这可比自己写代码常用得多。这里我以社区里流行的“笔记归档” Skill 为例它做的事情是把 Obsidian 笔记按标签自动归类到对应文件夹同时生成一个索引文件。具体接入步骤分四步从开源社区仓库把 Skill 文件夹克隆或下载到本地git clone https://github.com/openclaw/skills-repo然后进入skills/note-sorter目录。把这个目录复制到标准路径cp -r note-sorter ~/.openclaw/skills/。不懂复制命令的直接用资源管理器把文件夹拖进去也行。修改配置让它跟你自己的笔记库匹配打开config.yml把source_path改成你本机 Obsidian 仓库的绝对路径例如D:/Notes把target_root改成归档根目录例如D:/Notes/_Archive。重载并测试执行openclaw skill reload然后在对话里输入“按日期归档我昨天的笔记”。如果路径不对会得到明确的报错调整配置以后再试一次。其实这段接入流程对各类常用 Skill 都是通用的。市面上能搜到大量现成 Skill诸如“会议纪要转换”“网页正文提取”“代码仓库周报生成”它们的核心结构几乎都是同样的三件套SKILL.md、config.yml、run.*。你只要把这三样东西的路径和触发器改对整个 Skill 就能跑起来。不同 Skill 之间的差异只是脚本逻辑的复杂程度和涉及工具的数量。3.4 一套 Skill 配置的最终目录形态和内部调用路径新人最怕的是“不知道自己配完长什么样”。我把一个含 3 个 Skill 的典型目录树直接贴出来~/.openclaw/ ├── auth.json ├── settings.yml ├── skills/ │ ├── built-in.core/ │ │ ├── SKILL.md │ │ └── run.sh │ ├── built-in.web/ │ │ ├── SKILL.md │ │ └── run.js │ ├── disk-info/ │ │ ├── SKILL.md │ │ ├── run.sh │ │ └── config.yml │ ├── note-sorter/ │ │ ├── SKILL.md │ │ ├── run.py │ │ ├── config.yml │ │ └── requirements.txt │ └── weather-pro/ │ ├── SKILL.md │ ├── run.py │ └── .env ├── sessions/ │ └── demo-session.db └── logs/ └── openclaw-2026-02.log看到没有每个 Skill 就是一个独立目录里面文件的名字不是随便起的。SKILL.md是代理理解技能的说明书它会被加载到上下文里run.sh/run.py/run.js是实际执行体config.yml是参数配置.env放的是密钥、Token 这类不适合提交到仓库的敏感信息。OpenClaw 加载 Skill 的机制说起来也很简单启动时扫描整个skills/目录一级子目录名即 Skill 名目录里存在SKILL.md才会被识别。这里有个值得注意的点SKILL.md的description和trigger字段会被代理用来做技能匹配它可以写得很灵活但是一定要具体。比如写“处理所有问题”就相当于没写因为匹配时它什么都占哪个都调不对。写“用户询问磁盘、空间、硬盘剩余、存储不足”这类具体触发词匹配准确率会高得多。3.5 把 Skill 接到常用聊天与笔记工具上部署完 OpenClaw 核心服务以后很多人会问那我平时不用命令行聊天能不能在微信、Teams、飞书或者 Obsidian 里直接用答案是可以只是不同工具的接入方式不太一样。OpenClaw 本身提供了面向聊天平台的适配层原理其实非常统一每个平台对应一个 Bridge 配置文件Bridge 负责把平台消息翻译成 OpenClaw 的对话输入再把输出回传到平台。以 Microsoft Teams 为例你只需要在 OpenClaw 项目目录里执行openclaw bridge add teams然后按提示填入 Teams 应用的 App ID 和权限配置。配置完成后Teams 里那个机器人账号就相当于你的代理入口。你在聊天窗口里写“调用 disk-info 看下服务器还剩多少空间”整个流程会走我们刚才说的那套 Skill 匹配和工具调用链路。同理如果你主要在 Obsidian 里写笔记社区里也有obsidian-bridge这类现成方案。它的奇妙之处在于可以在笔记里写一个[[claw::帮我整理今天的所有会议记录]]这样的触发标记OpenClaw 看到后会自动处理并回写结果。这类“聊天端 笔记工具 Skill 编排”的组合是我个人推荐新手第二个进阶阶段去玩的方向因为投入很小体感极好。4. 实际操作中最常翻车的 13 个场景与避坑清单4.1 安装期高频报错证书、WSL、包管理器第一个高频报错是“无法安全验证”。常见的提示类似unable to verify the first certificate也就是用户描述里说的“openclaw无法安全验证”。这个问题的根源通常是系统根证书关系紊乱比如电脑里装了自签的证书或者本机的 CA 证书更新不及时。Node.js 在下载二进制依赖时会校验远程服务器证书一旦证书校验不通过就果断中断。解决办法不是去关掉证书校验千万别这么干安全会直接崩掉。正确做法是把根证书更新一下。Windows 上升级系统到最新版本让系统自动同步根证书Linux 上执行sudo apt install ca-certificates -y并重启服务如果你所在环境需要内网证书才能访问外网那要找管理员把新证书推到受信任区域。这和你自己的代码没任何关系别上头去重装 OpenClaw。第二个高频问题是 WSL 状态异常。在 PowerShell 里运行wsl --status如果显示类似“未安装适用于 Linux 的 Windows 子系统”或者“默认版本是 1”都要处理。先执行wsl --set-default-version 2再确保已安装发行版。如果执行wsl --status之后显示某个发行版已停止执行wsl --terminate Ubuntu重启它。顺带一提wsl -- status这种写法在 PowerShell 里会漏掉一个横线正确的是wsl --status一个空格别多也别少。第三个高频问题是 npm 安装时出现EACCES权限错误。这是老旧 Node 安装方式的经典遗留问题说明全局目录没有写入权限。你可以改用项目级安装来绕开也可以手动修正npm prefix但我个人最推荐卸载旧版 Node用官方 MSI 安装包重新安装一套干净环境。省时间根因也清干净了。4.2 运行期高频报错鉴权、超时、上下文丢失服务能起来以后高频问题变成了三类鉴权失败、请求超时、上下文丢失。鉴权失败最典型的现象是调用 API 或从另一台电脑访问管理页时明明密码没错却提示 401。先看auth.json的文件权限如果被其他进程读写了令牌可能已经失效删除旧文件重新openclaw auth login即可。另外一个常见原因是管理页改了密码之后命令行客户端还带着旧的会话令牌这种情况要执行openclaw auth logout再重新登录。请求超时的问题多和首次运行的冷启动有关。有些 Skill 的脚本每次调用都要重新下载模型权重或加载大文件第一次调用可能卡几十秒。OpenClaw 默认在 30 秒后把调用判定为超时。如果你确实需要更大的超时窗口可以在settings.yml的tool_timeout字段里调大比如tool_timeout: 120上下文丢失的问题更隐蔽你在一个会话里聊得挺好换个会话再问“刚才那个结果是什么”它完全不记得。这不是 Bug而是 OpenClaw 的会话隔离机制在起作用。每个--session参数对应一个独立会话存储如果你希望跨会话保留信息需要把关键信息写入 Memory。具体操作是在对话里输入“记住我的项目目录在 D:\Project\demo-bot”代理会自动把这条信息写入长期记忆。新手最容易在这上面产生“模型失忆”的误会实际上是没搞懂会话和记忆的区别。4.3 部署现场的经验总结分享一点实战经验都是那些正式文档里不会写的东西。第一第一次跑openclaw serve时不要用后台模式也不要挂系统服务。前台模式运行的日志是连续的你能看到所有输出方便定位问题。等确认一切正常再改用后台运维方式不迟。第二端口选择有个小习惯。尽量避开 3000、8080、8888 等常见端口因为这些端口大概率在设计期间就被其他应用占用。如果发现EADDRINUSE执行lsof -i :3001或netstat -ano | findstr 3001查看是哪个进程占了端口决定杀掉还是换端口。我习惯直接在启动命令里加--port 3001简单干脆。第三日志文件不要急着开压缩。OpenClaw 的日志是按天滚动的出问题的当天日志会保存在logs/openclaw-2026-02-XX.log。排查问题时直接打开这个文件用关键字error和warn筛选效率极高。千万别觉得“日志是给大佬看的”出现问题后再查日志才知道日志有多香。第四任何 Skill 改完之后一定要执行openclaw skill reload而不是重启整个服务。重启服务会把所有会话都清掉你正在调查的问题上下文也没了。热重载只重扫 Skill 目录不影响会话是调试 Skill 时最顺手的功能。最后再强调一个文件路径的坑Windows 下写路径要用正斜杠比如D:/Project/demo-bot而不是D:\Project\demo-bot。用反斜杠的话OpenClaw 的 YAML 解析器会把\P、\d解释成转义字符轻则路径无效重则直接报解析错误。这是我看到新手报错最多的一个点。4.4 从一次实战任务看 Skill 集成的完整闭环前面说了很多细节单独拎出来每一个都好像很简单但把它们串起来才是真正的“集成”。我这边实际跑过的任务是这样的每天早上 8 点OpenClaw 会从 RSS 订阅源抓取科技新闻过滤出与“AI 应用”相关的条目再调用“摘要生成”Skill 生成 200 字以内的中文摘要最后通过“邮件发送”Skill 把结果发到指定邮箱。这个任务里涉及了三个 Skillrss-reader、summarizer、email-sender。如果用人工的方式三件事需要写三个独立的定时脚本还要处理各自的环境差异和异常重试。OpenClaw 做这件事的优势在于“编排”而不是“实现”你不必再关心每个脚本之间怎么传参、怎么处理失败重试代理会根据每个 Skill 的说明文档自动决定调用顺序并且在一次调用失败时尝试换一条路径。你要做的配置异常简单在配置文件里的schedule_jobs字段下加一段schedule_jobs: - name: daily-tech-digest cron: 0 8 * * * prompt: 请执行早间科技摘要任务使用 rss-reader 抓取最新内容用 summarizer 生成摘要最后用 email-sender 发送。你只需要控制“什么时间做什么事情”剩下的细节交给代理自行拆分。这个思路很建议大家尽早建立起来你写的是需求描述不是写死每一步代码。OpenClaw 的魅力就在于此与其说它是一个部署工具不如说它是一套“让智能体听懂并执行任务”的框架。不过我还是要泼一盆冷水Skill 集成不是万能药。如果某个 Skill 本身的脚本写得一塌糊涂代理再聪明也救不了。比如rss-reader里如果接口地址写错了代理能识别到请求失败但它不会去给你改接口地址。所以Skill 还是需要人把关的不是扔进去就能自动正确。一个合格的集成者至少要有基本的脚本阅读能力、路径意识、异常日志意识。我个人每次接入新 Skill 前都会先手动跑一遍run.sh或run.py确认脚本本身没问题再交给代理调用这样能过滤掉至少一半的“假集成故障”。另外在 Windows 上写完 Skill 脚本以后顺手检查一下文件编码是不是 UTF-8 无 BOM。带 BOM 的脚本在某些环境下会报第一行无法识别尤其当你把 Windows 记事本存出来的脚本拿到 WSL 里跑时这个坑几乎必踩。用 VS Code 右下角把编码切到 UTF-8保存再重载就干干净净了。最后再分享一个小技巧如果你不想把 Skill 放到全局目录也可以放到项目目录里的skills/子文件夹下OpenClaw 启动时会同时扫描全局目录和当前项目目录。这样你可以为不同项目维护独立的技能文件互不干扰。等以后你的 Skill 越写越多时这种“项目级”隔离会帮你省下大量维护成本。 
长河君 · 2026/10/1 15:17:44 · 阅读 1.2k OpenClaw智能体部署与Skill集成实战：8分钟跑通全流程
1. 部署之前先把 OpenClaw 与 Clawdbot 的关系捋清楚1.1 一顿操作猛如虎装完发现装错包先说结论OpenClaw 和 Clawdbot 是同一个项目的两个“马甲”只是不同发行阶段叫法不一样。早期版本在 GitHub 和 npm 上直接用clawdbot作为包名后来官方把项目统一收敛到 OpenClaw 这个代号npm 和 Docker Hub 上的包名也换成了openclaw/cli。很多新手第一次装的时候照着老教程敲npm i clawdbot -g也能装上但装出来的可能是几个月前的旧包而且所谓“集成 Skill”的路径、配置格式都变了最后卡在报错环节白白浪费时间。我遇到过不少伙伴拿旧笔记来问我说装完openclaw之后skill列表一直是空的其实就是官方早期把 Skill 的存储位置放在~/.clawdbot/skills后期统一迁到了~/.openclaw/skills配置文件也从纯 JSON 改成了 YAML 与 Markdown 混排。所以这篇教程里我统一以当前可用版本为准不管标题写的是 OpenClaw 还是 Clawdbot大家认准这一套目录结构就行至于历史版本之间的差异不用太纠结能用就行。提示所有命令默认在 Windows PowerShell、macOS 和主流 Linux 发行版下均可执行。但凡涉及wsl的都是 Windows 专属macOS 或 Linux 用户直接跳过对应小节。1.2 新手必须提前知道的 6 个核心概念在动手前先花 60 秒把这几个概念过一遍后面集成 Skill 时你就不会一脸懵。OpenClaw 本质上是一个智能体运行时你可以把它理解成一个“会自己调用工具和脚本的外脑外手”。它的几个关键概念如下代理AgentOpenClaw 运行起来之后你通过对话或指令控制的那个实体它负责理解意图、拆解任务、调用工具。运行时Runtime负责调度和执行的底层服务也就是你要部署的那个东西命令行里叫openclaw serve。Skill一组可以被代理调用的能力封装类似音箱的“技能库”一个 Skill 通常由说明文档、入口脚本、元信息三部分组成。会话Session一次连续交互的状态OpenClaw 会在本地保存对话历史、任务进度和临时文件。工具Tool比 Skill 更底层的能力单元比如“执行 Shell 命令”“读文件”“请求某个 HTTP 接口”Skill 相当于把多个工具串成一个可复用的流程。记忆MemoryOpenClaw 的长期记忆区域用来保存跨会话的信息比如用户偏好、项目背景后面集成业务 Skill 时经常要用到。很多教程喜欢一上来就让新人改配置、写代码结果一小步报错一大步迷茫。我强烈建议先跑通默认版本确认“能跑”之后再考虑要不要自己写 Skill否则你根本分不清到底是环境问题、配置问题还是你的 Skill 代码本身有问题。1.3 这套部署方案到底解决了什么问题这个 8 分钟方案的目标很明确让一个完全没碰过 OpenClaw 的新手从拿到电脑开始计时在十分钟以内把服务跑起来、完成首次对话、把两个现成 Skill 装上并成功调用。它适合的人包括本地开发者和 AI 应用爱好者想在自己电脑上搭一个不依赖云端的智能体自动化玩家想用 OpenClaw 做定时任务、文件整理、信息聚合刚接触“智能体 工具调用”概念想找个现成项目练手的人。不适合哪些人如果你完全没用过命令行、连 Node.js 和 Git 是什么都不清楚那 8 分钟大概率不够建议先花半天把基础操作过一遍再来。这篇文章也不是给重度定制者看的如果你想自己造一套完整的“企业级智能中台”那要另开一个议题。总之这个方案解决的是“快速起步 常用 Skill 集成”问题不解决“高度定制”问题。2. 8 分钟实操部署从零到跑通官方内置 Demo2.1 开跑前 1 分钟的环境自检时间有限先别急着敲命令按照下面的清单检查完再继续能省去后面至少十分钟的排错时间确认 Node.js 版本在 20 及以上在终端执行node -v如果版本低于 20去官网装 LTS 版本不要装奇数版本。确认包管理器可用npm 和 npx 都要能正常运行执行npm -v。确认有干净的终端环境Windows 用户建议使用 PowerShell 7 或 Windows Terminal不要用老的 cmd.exe。如果是 Windows确认 WSL2 子系统可用在 PowerShell 执行wsl --status。如果提示还没有安装发行版先执行wsl --install -d Ubuntu-22.04并完成初始化。确认磁盘有至少 4GB 空闲空间内存建议 8GB 以上。为什么要在开头卡这么严格因为 OpenClaw 的前端是 Node.js后端编排层有很多二进制的原生依赖如果用太老的系统环境会遇到各种编译错误和证书签名问题。这就像盖房子前先打地基地基歪了后面装修得再好也是白搭。很多从零开始部署 OpenClaw 的教程默认你拥有一台干净的服务器但实际上大部分人拿的是 Windows 笔记本或者是公司统一配发的受限电脑可能已经装了 Python、Miniconda 甚至多个版本的 Node环境乱得很。我的经验是宁可先清掉 PATH 里的历史残留也不要让 OpenClaw 在半吊子环境里硬跑。检查完以后如果有重复的 Node 环境卸载干净再装统一版本后面会轻松很多。注意怀疑自己 Windows 环境紊乱的同学优先在 PowerShell 跑wsl --status把服务放到 WSL2 发行版里部署。WSL2 的网络和文件权限模型更干净能避开大量 Windows 原生文件锁带来的坑。但如果你只是想先快速看看效果直接在 Windows 主机上跑也没问题我会在下面给出两个分支方案。2.2 拉代码、装依赖、启动服务2 分钟核心命令我推荐用官方现成脚本部署一句话到位适合“没耐心看完文档”的人。在终端里执行npm install -g openclaw/cli openclaw init demo-bot cd demo-bot openclaw serve --port 3001如果你不想全局安装也可以用 npxnpx openclaw/cli init demo-bot npx openclaw serve --port 3001来看看这几条命令各自到底做了什么。npm install -g负责把 CLI 工具本身装到系统路径里让你在任何目录都能调用openclaw。openclaw init demo-bot负责在当前位置创建一个名为demo-bot的项目文件夹里面会自动生成默认配置、Skill 目录和示例脚本。openclaw serve则是真正把服务启动起来的动作--port 3001指定运行端口避免和本机其他服务冲突。第一次启动时OpenClaw 会在~/.openclaw/目录下自动创建缓存、日志、会话数据库和 Skill 目录。如果看到类似Startup completed in 3.2s的日志说明核心服务已经跑起来了。这时候打开浏览器访问http://127.0.0.1:3001就能看到内置的管理页面。举个实际可能遇到的问题。假设端口被占用你会看到EADDRINUSE的红色提示。解决办法很简单换一个端口重新起openclaw serve --port 3010。不要跟系统服务抢 3000 这种公共端口除非你确认它没被占用。2.3 认证与首次对话2 分钟关键配置服务起来之后还差一个关键步骤设置身份认证。OpenClaw 默认不开放远程访问本地访问也需要配置一个 Access Token。打开浏览器进入管理页页面上会先要求你设置管理员密码这个密码会被散列保存在本地配置里作用有两个一是防止局域网内其他人连上你的服务乱调用工具二是作为后续 API 请求的头信息。如果你走的是命令行客户端首次连接时执行openclaw auth login按照提示粘贴刚才设置的管理员账号密码会生成一个会话令牌并存储到~/.openclaw/auth.json。之后所有该用户发起的操作都会带上这个令牌不需要反复重新输入。完成认证以后在同一个终端里执行openclaw chat --session demo-session这样会进入交互式对话界面。你直接输入“你好介绍一下你自己”看看能不能正常回答。能回答说明核心链路已经通了。接着尝试问一个需要工具的任务比如“帮我列出当前目录下的所有文件”这个操作会触发 OpenClaw 的 Shell 工具调用看看它能否正确执行并返回结果。如果这一步也没问题你的基础部署已经 100% 成功了。在这一步我补充一个重要细节默认的内置代理其实非常保守工具调用之前会请求确认。如果你不想每执行一个命令都要点确认可以在配置文件里把auto_approve开起来但真不建议在重要环境这么干风险极高。新手阶段老老实实用确认模式能够帮你理解“代理到底做到了什么程度”等熟悉了调用边界再切换也不迟。2.4 验证部署成功的 3 个判断依据怎么确认自己是“真部署成功”而不是“看着像成功”我用三个标准来判断进程持续在跑执行openclaw status返回running且日志里没有明显报错。对话有来有回在openclaw chat里连续对话三轮观察是否存在中途断连、无响应、上下文丢失的问题。Skill 目录能读到执行openclaw skill list能看到built-in.core和built-in.web两个内置 Skill这说明 Skill 扫描机制正常后面接自定义 Skill 就不会踩“目录扫描不到”这类坑。这三个判断依据不是随口说的。openclaw status验证的是服务生命周期是否正常连续对话验证的是运行时上下文Skill 列表验证的是插件加载能力。三件事分别对应“服务能跑”“对话能用”“扩展能加载”任何一个不满足说明部署链路还有隐患直接进入第 4 节对号入座排查。3. Skill 集成实现原理与落地案例3.1 Skill 到底是什么它和插件、工具调用有什么关系接着刚才的话题Skill 是 OpenClaw 最有价值的部分。你可以把它想象成给代理插 U 盘代理本身是一个能干杂活的通用大脑Skill 是专门解决某个特定问题的 U 盘。比如“整理 Markdown 笔记”是一个 Skill“查询本地天气”是另一个 Skill“把一段文字转成语音”又是一个 Skill。每一个 Skill 都告诉代理三件事这个技能是干什么的应该在什么时候调用具体怎么干。Skill 和“工具”的区别在于粒度。工具是单一动作比如“读文件”“写文件”“发送 HTTP 请求”Skill 是把多个工具按业务逻辑串起来的流程。普通用户不需要写工具只需要写“召唤工具”的 Skill。OpenClaw 内部执行一个任务时的顺序大致是用户提出需求代理拆解意图代理在已加载的 Skill 列表里检索匹配项匹配成功的 Skill 被激活按其说明文档中的描述来安排执行Skill 调用底层工具逐项获取结果代理把多个中间结果汇总生成最终回答。理解这五步你就明白为什么 Skill 的“说明文档”写得越清楚代理执行得越准。很多人的 Skill 写得很乱不是代码不行而是“教代理怎么用”的文字说明不充分。3.2 自己动手写一个 20 行以内的 Skill 并接入直接上实操。我们先写一个最简单的“本机磁盘信息查询” Skill。为什么要从它开始因为它足够短又涉及读取系统命令与格式化输出这两件事是整个 Skill 开发里最常见的两个动作。在~/.openclaw/skills/disk-info/目录下创建两个文件SKILL.md和run.sh。先看SKILL.md这个文件负责“教代理怎么用”--- name: disk-info description: 查看本机磁盘使用情况返回各分区总量、已用量和剩余空间。 trigger: 用户询问磁盘、空间、硬盘剩余、存储不足 --- # disk-info 当用户提到“磁盘满了”“看看空间”“存储不足”等情况时立即调用本技能。 ## 执行步骤 1. 在终端中运行 bash run.sh 2. 将脚本输出的结果原样返回给用户 ## 注意 - 本技能只读取信息不执行任何写入或修改操作 - 如果执行结果为空或权限不足请在回答中说明“无法读取磁盘信息”再看run.sh#!/bin/bash df -h | awk NR1 || $5080 {print $0}这个脚本干了什么df -h以人类可读方式列出所有文件系统的使用情况awk先打印表头NR1再筛选出使用率超过 80% 的行。也就是说它不只显示全部磁盘还会特别标记快满的分区这正是运维场景下最关心的信息。如果你用 Windows 且没有 WSL可以把run.sh换成 PowerShell 脚本run.ps1Get-PSDrive -PSProvider FileSystem | Select-Object Name, {NameUsed(GB);Expression{[math]::Round($_.Used/1GB,2)}}, {NameFree(GB);Expression{[math]::Round($_.Free/1GB,2)}}然后修改SKILL.md里执行步骤为powershell -File run.ps1即可。Skill 目录放好后执行openclaw skill reload再去看openclaw skill list就能看到disk-info出现在列表里。接着在对话里输入“我的 C 盘快满了吗”代理就会自动定位到 disk-info 这个 Skill 并执行脚本返回结果。3.3 接入现成 Skill 的套路以笔记归档为例写一个 Skill 很简单但是要真正用好 Skill你得掌握“接入一个现成 Skill”的套路。这可比自己写代码常用得多。这里我以社区里流行的“笔记归档” Skill 为例它做的事情是把 Obsidian 笔记按标签自动归类到对应文件夹同时生成一个索引文件。具体接入步骤分四步从开源社区仓库把 Skill 文件夹克隆或下载到本地git clone https://github.com/openclaw/skills-repo然后进入skills/note-sorter目录。把这个目录复制到标准路径cp -r note-sorter ~/.openclaw/skills/。不懂复制命令的直接用资源管理器把文件夹拖进去也行。修改配置让它跟你自己的笔记库匹配打开config.yml把source_path改成你本机 Obsidian 仓库的绝对路径例如D:/Notes把target_root改成归档根目录例如D:/Notes/_Archive。重载并测试执行openclaw skill reload然后在对话里输入“按日期归档我昨天的笔记”。如果路径不对会得到明确的报错调整配置以后再试一次。其实这段接入流程对各类常用 Skill 都是通用的。市面上能搜到大量现成 Skill诸如“会议纪要转换”“网页正文提取”“代码仓库周报生成”它们的核心结构几乎都是同样的三件套SKILL.md、config.yml、run.*。你只要把这三样东西的路径和触发器改对整个 Skill 就能跑起来。不同 Skill 之间的差异只是脚本逻辑的复杂程度和涉及工具的数量。3.4 一套 Skill 配置的最终目录形态和内部调用路径新人最怕的是“不知道自己配完长什么样”。我把一个含 3 个 Skill 的典型目录树直接贴出来~/.openclaw/ ├── auth.json ├── settings.yml ├── skills/ │ ├── built-in.core/ │ │ ├── SKILL.md │ │ └── run.sh │ ├── built-in.web/ │ │ ├── SKILL.md │ │ └── run.js │ ├── disk-info/ │ │ ├── SKILL.md │ │ ├── run.sh │ │ └── config.yml │ ├── note-sorter/ │ │ ├── SKILL.md │ │ ├── run.py │ │ ├── config.yml │ │ └── requirements.txt │ └── weather-pro/ │ ├── SKILL.md │ ├── run.py │ └── .env ├── sessions/ │ └── demo-session.db └── logs/ └── openclaw-2026-02.log看到没有每个 Skill 就是一个独立目录里面文件的名字不是随便起的。SKILL.md是代理理解技能的说明书它会被加载到上下文里run.sh/run.py/run.js是实际执行体config.yml是参数配置.env放的是密钥、Token 这类不适合提交到仓库的敏感信息。OpenClaw 加载 Skill 的机制说起来也很简单启动时扫描整个skills/目录一级子目录名即 Skill 名目录里存在SKILL.md才会被识别。这里有个值得注意的点SKILL.md的description和trigger字段会被代理用来做技能匹配它可以写得很灵活但是一定要具体。比如写“处理所有问题”就相当于没写因为匹配时它什么都占哪个都调不对。写“用户询问磁盘、空间、硬盘剩余、存储不足”这类具体触发词匹配准确率会高得多。3.5 把 Skill 接到常用聊天与笔记工具上部署完 OpenClaw 核心服务以后很多人会问那我平时不用命令行聊天能不能在微信、Teams、飞书或者 Obsidian 里直接用答案是可以只是不同工具的接入方式不太一样。OpenClaw 本身提供了面向聊天平台的适配层原理其实非常统一每个平台对应一个 Bridge 配置文件Bridge 负责把平台消息翻译成 OpenClaw 的对话输入再把输出回传到平台。以 Microsoft Teams 为例你只需要在 OpenClaw 项目目录里执行openclaw bridge add teams然后按提示填入 Teams 应用的 App ID 和权限配置。配置完成后Teams 里那个机器人账号就相当于你的代理入口。你在聊天窗口里写“调用 disk-info 看下服务器还剩多少空间”整个流程会走我们刚才说的那套 Skill 匹配和工具调用链路。同理如果你主要在 Obsidian 里写笔记社区里也有obsidian-bridge这类现成方案。它的奇妙之处在于可以在笔记里写一个[[claw::帮我整理今天的所有会议记录]]这样的触发标记OpenClaw 看到后会自动处理并回写结果。这类“聊天端 笔记工具 Skill 编排”的组合是我个人推荐新手第二个进阶阶段去玩的方向因为投入很小体感极好。4. 实际操作中最常翻车的 13 个场景与避坑清单4.1 安装期高频报错证书、WSL、包管理器第一个高频报错是“无法安全验证”。常见的提示类似unable to verify the first certificate也就是用户描述里说的“openclaw无法安全验证”。这个问题的根源通常是系统根证书关系紊乱比如电脑里装了自签的证书或者本机的 CA 证书更新不及时。Node.js 在下载二进制依赖时会校验远程服务器证书一旦证书校验不通过就果断中断。解决办法不是去关掉证书校验千万别这么干安全会直接崩掉。正确做法是把根证书更新一下。Windows 上升级系统到最新版本让系统自动同步根证书Linux 上执行sudo apt install ca-certificates -y并重启服务如果你所在环境需要内网证书才能访问外网那要找管理员把新证书推到受信任区域。这和你自己的代码没任何关系别上头去重装 OpenClaw。第二个高频问题是 WSL 状态异常。在 PowerShell 里运行wsl --status如果显示类似“未安装适用于 Linux 的 Windows 子系统”或者“默认版本是 1”都要处理。先执行wsl --set-default-version 2再确保已安装发行版。如果执行wsl --status之后显示某个发行版已停止执行wsl --terminate Ubuntu重启它。顺带一提wsl -- status这种写法在 PowerShell 里会漏掉一个横线正确的是wsl --status一个空格别多也别少。第三个高频问题是 npm 安装时出现EACCES权限错误。这是老旧 Node 安装方式的经典遗留问题说明全局目录没有写入权限。你可以改用项目级安装来绕开也可以手动修正npm prefix但我个人最推荐卸载旧版 Node用官方 MSI 安装包重新安装一套干净环境。省时间根因也清干净了。4.2 运行期高频报错鉴权、超时、上下文丢失服务能起来以后高频问题变成了三类鉴权失败、请求超时、上下文丢失。鉴权失败最典型的现象是调用 API 或从另一台电脑访问管理页时明明密码没错却提示 401。先看auth.json的文件权限如果被其他进程读写了令牌可能已经失效删除旧文件重新openclaw auth login即可。另外一个常见原因是管理页改了密码之后命令行客户端还带着旧的会话令牌这种情况要执行openclaw auth logout再重新登录。请求超时的问题多和首次运行的冷启动有关。有些 Skill 的脚本每次调用都要重新下载模型权重或加载大文件第一次调用可能卡几十秒。OpenClaw 默认在 30 秒后把调用判定为超时。如果你确实需要更大的超时窗口可以在settings.yml的tool_timeout字段里调大比如tool_timeout: 120上下文丢失的问题更隐蔽你在一个会话里聊得挺好换个会话再问“刚才那个结果是什么”它完全不记得。这不是 Bug而是 OpenClaw 的会话隔离机制在起作用。每个--session参数对应一个独立会话存储如果你希望跨会话保留信息需要把关键信息写入 Memory。具体操作是在对话里输入“记住我的项目目录在 D:\Project\demo-bot”代理会自动把这条信息写入长期记忆。新手最容易在这上面产生“模型失忆”的误会实际上是没搞懂会话和记忆的区别。4.3 部署现场的经验总结分享一点实战经验都是那些正式文档里不会写的东西。第一第一次跑openclaw serve时不要用后台模式也不要挂系统服务。前台模式运行的日志是连续的你能看到所有输出方便定位问题。等确认一切正常再改用后台运维方式不迟。第二端口选择有个小习惯。尽量避开 3000、8080、8888 等常见端口因为这些端口大概率在设计期间就被其他应用占用。如果发现EADDRINUSE执行lsof -i :3001或netstat -ano | findstr 3001查看是哪个进程占了端口决定杀掉还是换端口。我习惯直接在启动命令里加--port 3001简单干脆。第三日志文件不要急着开压缩。OpenClaw 的日志是按天滚动的出问题的当天日志会保存在logs/openclaw-2026-02-XX.log。排查问题时直接打开这个文件用关键字error和warn筛选效率极高。千万别觉得“日志是给大佬看的”出现问题后再查日志才知道日志有多香。第四任何 Skill 改完之后一定要执行openclaw skill reload而不是重启整个服务。重启服务会把所有会话都清掉你正在调查的问题上下文也没了。热重载只重扫 Skill 目录不影响会话是调试 Skill 时最顺手的功能。最后再强调一个文件路径的坑Windows 下写路径要用正斜杠比如D:/Project/demo-bot而不是D:\Project\demo-bot。用反斜杠的话OpenClaw 的 YAML 解析器会把\P、\d解释成转义字符轻则路径无效重则直接报解析错误。这是我看到新手报错最多的一个点。4.4 从一次实战任务看 Skill 集成的完整闭环前面说了很多细节单独拎出来每一个都好像很简单但把它们串起来才是真正的“集成”。我这边实际跑过的任务是这样的每天早上 8 点OpenClaw 会从 RSS 订阅源抓取科技新闻过滤出与“AI 应用”相关的条目再调用“摘要生成”Skill 生成 200 字以内的中文摘要最后通过“邮件发送”Skill 把结果发到指定邮箱。这个任务里涉及了三个 Skillrss-reader、summarizer、email-sender。如果用人工的方式三件事需要写三个独立的定时脚本还要处理各自的环境差异和异常重试。OpenClaw 做这件事的优势在于“编排”而不是“实现”你不必再关心每个脚本之间怎么传参、怎么处理失败重试代理会根据每个 Skill 的说明文档自动决定调用顺序并且在一次调用失败时尝试换一条路径。你要做的配置异常简单在配置文件里的schedule_jobs字段下加一段schedule_jobs: - name: daily-tech-digest cron: 0 8 * * * prompt: 请执行早间科技摘要任务使用 rss-reader 抓取最新内容用 summarizer 生成摘要最后用 email-sender 发送。你只需要控制“什么时间做什么事情”剩下的细节交给代理自行拆分。这个思路很建议大家尽早建立起来你写的是需求描述不是写死每一步代码。OpenClaw 的魅力就在于此与其说它是一个部署工具不如说它是一套“让智能体听懂并执行任务”的框架。不过我还是要泼一盆冷水Skill 集成不是万能药。如果某个 Skill 本身的脚本写得一塌糊涂代理再聪明也救不了。比如rss-reader里如果接口地址写错了代理能识别到请求失败但它不会去给你改接口地址。所以Skill 还是需要人把关的不是扔进去就能自动正确。一个合格的集成者至少要有基本的脚本阅读能力、路径意识、异常日志意识。我个人每次接入新 Skill 前都会先手动跑一遍run.sh或run.py确认脚本本身没问题再交给代理调用这样能过滤掉至少一半的“假集成故障”。另外在 Windows 上写完 Skill 脚本以后顺手检查一下文件编码是不是 UTF-8 无 BOM。带 BOM 的脚本在某些环境下会报第一行无法识别尤其当你把 Windows 记事本存出来的脚本拿到 WSL 里跑时这个坑几乎必踩。用 VS Code 右下角把编码切到 UTF-8保存再重载就干干净净了。最后再分享一个小技巧如果你不想把 Skill 放到全局目录也可以放到项目目录里的skills/子文件夹下OpenClaw 启动时会同时扫描全局目录和当前项目目录。这样你可以为不同项目维护独立的技能文件互不干扰。等以后你的 Skill 越写越多时这种“项目级”隔离会帮你省下大量维护成本。