OpenClaw 这套东西我前前后后折腾了快两个月。最初连命令行都敲不进去到后来把扩展栈完整跑通中间踩过的坑、翻完的文档加起来能写小半本书。最近社区里问 openclaw 安装、openclaw 配置、openclaw 扩展路径的人明显变多所以我干脆把自己最终能跑通的完整路径整理出来。这篇不会只讲怎么装更多是讲清楚为什么这么装哪些东西必须提前想明白你照着走一遍能少走我以前走过的那一堆弯路。文章适合两类人一类是准备把 OpenClaw 当作 AI 代理基础设施来用的开发者另一类是在用但想把它从一个孤立 CLI 工具扩展成完整工作流的人。如果你只是想装个客户端点两下那这篇文章可能对你有点重但如果你是做本地部署、技能扩展或者想把这套东西接进自己的项目管理和 IM 工具那它正好对得上。1. 先搞清楚 OpenClaw 扩展栈的设计思路1.1 扩展栈的三个层次我用一个不算太严谨的类比切入OpenClaw 本身像一个底座操作系统它只管最基本的循环——拿到指令、启动代理、执行任务、返回结果。但真正让它好用起来的是叠加在上面的扩展栈。这个栈不是一个独立安装的大包而是一组不同粒度的组件协同工作。按我自己的理解它大致分为三层。最底层是运行时与环境包括 openclaw 主程序、工作目录默认在用户目录下的 .openclaw以及它依赖的本地或远程模型服务中间层是权限与审批机制核心就是 exec-approvals.json 这个文件它决定了代理在执行命令时哪些可以自动通过、哪些必须人工确认最上层是能力层也就是各种 skill 和外部接入比如连飞书、连微信、连 NVIDIA NIM 推理服务或者写一个脚本把项目管理软件里的任务同步过来。这个设计最大的好处是核心保持轻量、能力按需追加。坏处也很明显——没有把三层一次性搞清楚就去改配置很容易出现代理跑起来了但命令全被拒skill 装上了却不生效这类看着莫名其妙的坑。我后来复盘发现大部分问题都能归到某个层次没理顺而不是 OpenClaw 本身有 bug。1.2 与 ClawHub 的定位差异网上常有人把 OpenClaw 和 ClawHub 放在一起比其实它们的层级不太一样。ClawHub 更偏市场或者说分发中心负责收集、发布、分享现成的代理、技能和扩展OpenClaw 更偏运行时负责把拿到的技能真正跑起来。换句话说你在 ClawHub 上看到一个 skill下载下来之后真正去解释它、调度它、执行它的是 OpenClaw 这边的事。这个定位差异直接影响你安装时的选择偏好。如果你只是想用别人写好的技能那只要把 OpenClaw 装到能正常加载外部技能的程度就够了几乎不需要自己写底层代码。但如果你想做一个内部专用的技能包就得摸清 skill 的目录约定、依赖声明方式以及 OpenClaw 在运行时怎么解析和执行这些内容。建议刚上手时先把官方文档里extension vs skill vs tool的区分看明白。我一开始就把这三者当成一回事结果后面写配置的时候反复改错文件白白浪费了不少时间。现在回想起来如果当时花半小时把几个核心概念的关系理清楚后面的排查成本至少能减一半。1.3 为什么要用扩展栈而不是插件中心有人会问既然有现成的插件市场为什么不直接往里面塞插件还要自己搭扩展栈我的理解是插件通常是一个已经封装好的独立功能而扩展栈更像是一套可以不断组合的能力体系。插件解决的是我要一个固定的能力扩展栈解决的是我要让代理具备一连串可编排的执行能力。举个例子接一个飞书机器人只是插件级的事但让代理收到飞书消息后自动查数据库、生成报告、把报告发回群里这就是扩展栈级的事。后者需要消息通道、权限审批、技能编排、模型调度多个层次一起工作。明白这个差异之后你再看 OpenClaw 的完整路径就不会只盯着装哪个插件不放而是会去想我要的这条链路每一层分别该放什么。2. 从零开始Windows 与 Linux 的安装差异完整安装路径我会分平台说。先说明一点无论哪个系统安装过程本身都不算复杂复杂的是安装完之后那些零零碎碎的路径和权限问题。2.1 Windows 安装的目录指定问题Windows 上最常见的问题不是装不上而是装到了哪、能不能改。以 PowerShell 为例很多安装命令默认会把用户配置写到C:\Users\你的用户名\.openclaw下包括 workspace、配置文件和日志。如果你希望装到别的盘就得在安装时指定目录。根据我自己的实测PowerShell 下安装是支持指定目录的关键是先确保该目录有完整读写权限否则后续启动代理时会出现莫名其妙的文件写入失败。我建议在安装前先执行一句New-Item -ItemType Directory -Force -Path D:\OpenClaw把想要的目录提前建好并确认权限再跑安装命令。另一个值得注意的点Windows 上如果命令行里直接敲openclaw提示无法识别十有八九是环境变量没刷新。不要急着重装重新打开一个 PowerShell 窗口或者手动把安装目录的 bin 路径加到系统的 PATH 环境变量里通常问题就消失了。还有一点Windows 下尽量避免把工作路径放在带有空格或中文特殊字符的目录里。有些工具自己处理得了但扩展栈里的脚本、skill 不一定都能正确处理一个空格就能让路径解析断掉查起来还挺隐蔽。2.2 Ubuntu 下部署的几个细节点Ubuntu 上的安装相对清爽但有一个高频问题安装完后进程跑着、界面却看不到任何输出。我在 Ubuntu 上遇到过的典型情况是服务正常启动端口也在监听但前台终端没有任何日志。这时候别慌用ps aux | grep -i openclaw看一下进程状态确认它是不是以后台方式起来了。还有一点要特别提醒Ubuntu 下如果使用 root 用户配置目录会是/root/.openclaw而不是/home/你的用户名/.openclaw。很多人排查半天找不到配置文件其实就是因为这个路径差异。启动时如果看到类似legacy exec approvals exist at /root/.openclaw/exec-approvals.json的提示说明系统里已经存在旧版审批文件它是在提示你升级或迁移不是报错但需要按提示处理。第三节我会专门讲审批文件的细节。Ubuntu 部署还有一个容易被忽略的点系统的时区和默认 shell 环境。代理在执行定时任务或生成日志时如果时区不对时间记录全部偏移排查问题时很容易被误导。建议部署后第一时间确认时区和系统 locale 是一致的。2.3 安装后如何快速验证装完之后第一件事是确认版本和基本命令正常。在终端分别执行openclaw --version openclaw --help如果两条命令都能正常输出说明核心安装成功。接下来我建议你不要急着干别的先跑一个最简的启动命令确认代理能完成一条最小的指令往返。不要一上来就接模型、接 IM、接技能那样一旦出问题你根本分不清是哪一层挂的。这一步做完再去看~/.openclaw或C:\Users\你的用户名\.openclaw目录下生成了哪些文件对比一下和你预期的是否一致。目录里通常会有 workspace、配置文件、审批文件等几个关键项具体内容下一节展开。3. 配置路径与数据目录动手前必须搞清楚3.1 ~/.openclaw 目录下的核心文件老实说我到现在都觉得 .openclaw 这个目录是整套工具的灵魂。它就像人的家目录所有状态、配置、数据都在这里。初次运行后你会看到几个常见内容workspace工作目录代理执行任务时产生的文件、中间产物基本都在这。exec-approvals.json命令审批规则决定哪些命令可以免确认执行。其他配置文件存放模型连接、运行参数等内容。你不需要记住每一个文件的含义但至少要能回答三个问题workspace 在哪、审批文件在哪、日志去哪找。把这三个问题的答案记在笔记里后面出问题排查时会省下大量时间。我最初使用的时候根本不看这些文件任由程序写到哪算哪。后来有一次需要把整个环境迁到另一台机器才发现自己连哪些文件是配置、哪些文件是缓存都分不清迁移过程痛苦得不行。你要是刚开始用建议先把目录结构截图存档以后做迁移或重置就有据可查。3.2 workspace 的迁移与多环境切换有段时间我想把工作文件从 Windows 默认路径迁到另一个更大的盘符折腾了一圈才明白与其手动复制文件不如直接把配置里的 workspace 路径指过去然后把旧目录整个搬过去。具体做法就是改配置里对应的路径字段将C:\Users\xxx\.openclaw\workspace改成新目录的绝对路径然后先把代理完全关闭再迁移文件。这个顺序很重要我试过一次没关进程直接搬结果文件写到一半新目录里出现一堆半截文件旧目录也被写入了新数据两边都不完整最后只能回到备份点重新来。多环境切换也是同一个思路。比如开发机和云端服务器用不同目录那就分别维护两套配置。切换时不要只改一个路径还要确认对应的审批文件、模型配置是否跟着切换否则很容易出现本地能跑、云端跑不动的情况。我的习惯是每个环境单独建一个配置文件副本环境切换时连同模型参数一起换避免只改了一半。3.3 runtime metadata 到底存了什么OpenClaw runtime metadata是网上热门搜索词也是很多人困惑的地方。简单说它记录了运行时的各类元信息比如当前版本、加载过的技能、连接过的服务、运行记录等。它不像 workspace 那样直接存放生成文件更像是一本台账帮程序在下次启动时恢复状态。对普通使用者来说基本不需要手动改 metadata。比较实用的场景是自己写了一个 skill想让它在不同环境之间复制那你要关注的是 skill 本身的目录和配置文件而不是篡改 metadata。等哪天排查时发现改过的配置没生效可以检查一下是不是 metadata 里缓存了旧状态清理后再重启往往能解决。我遇到过一次比较典型的故障修改模型服务地址后代理仍然往旧地址发请求查了半天最后发现是运行时元数据缓存了旧连接信息。清理缓存重启之后才恢复正常。所以遇到改了配置不生效的局面别急着怪配置文件先想想有没有缓存层在捣乱。4. exec-approvals.json扩展栈的安全阀门4.1 为什么需要命令审批机制第一次看到 exec-approvals.json 这个文件名时我以为它只是权限配置的一大堆样板后来才意识到这是整套扩展栈最重要、也最容易出事的一道闸门。OpenClaw 作为 AI 代理会代替用户执行真实的系统命令这能力很能打风险也不小——如果代理被诱导去执行危险操作没有审批机制兜底后果很难收拾。审批机制的初衷就是把代理想执行的命令和你允许它执行的命令之间划一条明确的线。凡是命中审批规则范围内的命令代理可直接执行未命中或者需要更高权限的操作代理要么等待人工批准要么直接拒绝。说实话我第一次跑通扩展栈时因为嫌审批麻烦曾经把规则配得很宽结果代理执行任务时确实很自由但自由到它自己把一个临时文件清理脚本跑到了我重要目录里。虽然损失不大但那次之后我学乖了审批规则宁紧勿松尤其是自动化任务比较多的场景。4.2 审批规则怎么写才既安全又顺手这个文件的格式并不复杂核心是以命令或命令模式为键标注是否允许自动执行。常见规则包括允许执行的命令集合、拒绝执行的命令集合以及哪些路径可以写、哪些不能动。举个例子如果你希望代理在工作区内自由读写文件但禁止执行删除系统关键目录的命令那就把工作区下的写操作加入允许列表同时把 rm -rf 这类高危命令加入拒绝列表。写规则时路径范围尽量精确规则写得越宽失控风险越高。修改完文件后建议重启 OpenClaw 再测试因为部分规则可能在启动时加载。如果你直接让它热加载最好先确认版本支持否则改了半天没反应还会产生规则没生效的误判。我自己的节奏是小改动顺手重启一次大改动先离线整理规则列表确认无误再一次性写入。4.3 关闭与重置的注意事项如果系统提示legacy exec approvals exist at /root/.openclaw/exec-approvals.json. run \openclaw ... 之类的信息它一般是在告诉你旧版审批文件存在建议你执行某个命令来做迁移或重置。很多人看到里面有legacy就以为没用的文件直接删了结果代理的审批行为变得很古怪。正确做法是先备份旧文件再按提示执行迁移操作最后检查新文件是否生成。如果你确实不想保留任何历史规则可以备份后重置为默认配置而不是直接删除目录。我个人的习惯是每次改动审批规则前都会先复制一份备份到当天日期的文件名。这个习惯救过我至少三次其中两次都是因为改完规则后代理行为异常回滚备份直接解决了问题。备份文件不用保留太多留最近三五天的就好。5. 技能开发与模型接入5.1 创建你的第一个 Skill在 OpenClaw 里skill 是能力扩展的基本单元。它通常不是一个大软件而是一个包含描述、依赖、执行逻辑的目录或配置项。你添加一个 skill就是在告诉代理我多了一个能干这件事的技能。我自己写的第一个 skill 特别简单让代理把某目录下的 txt 文件批量转换成 Markdown 格式。真正动手后才发现一个可用的 skill 通常包含三块内容一是让代理理解这个技能做什么的描述信息二是技能依赖的环境参数三是具体执行的动作逻辑。描述信息别随便写。如果你写得模糊代理经常会在任务复杂时忘记该调用这个技能或者把它用错场景。我自己调试时发现描述越具体、越贴近日常任务口径技能被正确调用的概率越高。比如将临时目录里的 TXT 批量转换成带标题的 Markdown 文件就比文本文档转换器好用得多。5.2 接入 NVIDIA NIM 推理后端OpenClaw 本身并不强制绑定某一个模型服务它可以通过配置对接不同的推理后端。NVIDIA NIM 是很多人重点问的一个选项场景上大概是为了在本地或企业环境利用 NVIDIA 的推理优化能力。接入 NIM 的核心是搞清楚你要在配置里指定推理服务的地址、模型名称、API 鉴权信息。不要只填写服务器地址就去试探建议先用一个最简请求验证 NIM 服务本身可用再把这个可用的服务信息配置到 OpenClaw 里。这样如果还是跑不通问题定位就在两者之间的协议或参数上而不是 NIM 本身。我踩过的一个小坑是本地 NIM 服务已启动但 OpenClaw 里填错了模型标识结果接口报错报了半天最后发现只是名字大小写不匹配。这类问题查起来很费时间建议配置里每个参数都从官方接口返回里复制不要手打。5.3 自定义中转站与模型路由热门词里出现了自定义中转站这个说法放在 AI 代理语境里一般指将模型请求先经过一个自己掌控的中转服务再转发到真正的模型后端。这样做的原因各有不同有的是为了统一鉴权有的是为了记录请求日志有的是为了把多路后端做负载调度。对 OpenClaw 来说你只需要把模型的 Base URL 指到中转站地址然后保证中转站能把标准的模型请求继续转发到最终后端并原样返回结果即可。核心验证还是要先 curl、再接。直接用一条最简单的模型调用命令测中转站curl -X POST https://你的中转站地址/v1/chat/completions \ -H Content-Type: application/json \ -d {model:你的模型名,messages:[{role:user,content:hi}]}能拿到正常响应再去改 OpenClaw 的配置。很多接不上的案例最后查下来都是中转站本身就有问题而不是 OpenClaw 这边配置错误。接的时候注意协议兼容性有的中转站只支持特定请求格式OpenClaw 发送的标准请求反过来也可能被它拒掉。6. 接入 IM 消息入口飞书与微信6.1 飞书应用的接入流程把 OpenClaw 接入飞书本质上是在做消息通道IM 的消息进入代理代理的处理结果再回传给 IM。这一步非常见成效因为你可以直接在聊天里和人交互让代理去查数据、写纪要、跑任务。接飞书时常见做法是利用飞书开放平台创建一个应用拿到应用凭证然后配置事件订阅地址让 OpenClaw 作为消息接收端。这个流程里最需要注意的是回调地址要和实际部署环境匹配。本地调试时可以用内网穿透工具临时暴露一个公网地址但正式使用时尽量部署在有固定地址的服务器上。我头一次接飞书时在事件订阅这一步卡了很久原因是我把回调地址填成了管理后台地址而不是 OpenClaw 实际监听消息的接口。这类问题日志里通常有提示但要仔细读不然很容易忽略。6.2 微信插件与消息转发微信那边则是通过微信插件或网关把消息转发到 OpenClaw 的接口上。因为微信生态对这类自动交互的限制比较多一般不建议直接尝试官方层面的深度集成更多是用第三方网关或自建的消息转发插件来做。接入时同样会涉及回调地址、端口监听和消息格式转换。建议先在一个本地测试环境里打通再上到服务器。如果你只需要接收自己的消息那就把转发规则配得窄一点只转发指定联系人或指定群的消息避免所有好友消息都涌到代理那边既费模型配额又容易产生隐私问题。6.3 从能收发消息到能干活接好消息通道之后很多人会发现一个问题消息能收发但代理只会回一些简单的固定内容离能干活差得远。这个阶段的关键不是再增加通道而是把技能编排做起来。我的建议是先从场景倒推。比如你想让代理在群里自动整理待办那就先写一个把聊天内容转成待办清单的 skill再把这个 skill 绑定到消息处理流程里。消息进来先判断意图再判断是否命中某个 skill最后执行并回复。这个链路打通之后IM 接入才算真正有了价值。还有个小技巧消息通道接入初期把它的输出日志单独开一个文件方便你查消息到底有没有到代理这一层。我踩过好几次坑结果都是消息根本没过网关白白浪费在代理日志里翻来找去的时间。7. 实战把 OpenClaw 用进日常项目管理7.1 与 Obsidian 的联动很多人包括我自己会把 Obsidian 当作项目管理的主要入口因为它的本地 Markdown 方案很适合记录任务、想法和文档。让 OpenClaw 和 Obsidian 联动其实就是让代理能够读写 Obsidian 的 vault 目录把任务整理、会议纪要、待办清单这些杂活自动化。我的做法比较简单把 Obsidian vault 路径加入 OpenClaw 的 workspace 可访问范围然后写一个 skill让代理根据输入的会议原文生成结构化的 Markdown 笔记并按指定规则命名存放。这样开会时我只需把录音转文字的大段内容丢给代理它就能顺手整理成一页像样的笔记。这里最容易出错的是路径和文件命名规则。不同平台的路径写法不一样Windows 有盘符Linux 有斜杠如果代理生成的文件没有按照你预期的命名放好多半是 skill 的描述规则里没写清楚命名规范。建议在技能描述里把命名格式写死例如日期前缀、模块名之类。7.2 设计一套可控的任务自动化流程把 OpenClaw 用进项目管理不只是让它帮忙写纪要更重要的是设计一套可控的自动化流程。我现在的做法是每天早上让代理读取当天任务清单输出一份优先级建议每周结束时让它汇总本周完成事项生成周报草稿。这套流程跑通之后我在项目管理上花的时间明显少了很多。但这个流程刚开始跑的时候并不顺利最大的问题就是代理做得太随意。比如我让它生成周报它就真的只生成一段文字没有标题层级、没有完成状态、没有风险项。后来我在 skill 里把输出格式彻底固定成模板才解决这个问题。我的体会是给代理定的输出结构越明确你后期要改的东西就越少。还有一点自动化任务一定要加人工确认环节。哪怕是让它自动生成的文件也建议只写到一个待确认目录你审核之后才正式归档。别嫌多一步这一步能挡住绝大多数低质量输出。7.3 云端部署与本地使用的取舍网上有人问如何在云端部署 openclaw我自己在两种环境都跑过说说区别。本地部署的好处是数据不出本机、调试方便适合开发阶段云端部署的好处是稳定、可以长期运行适合定时任务和 IM 接入这类 7x24 小时的场景。云端部署时最需要注意的是安全组和端口暴露范围。OpenClaw 控制端口和消息回调接口不要全部对公网开放尽量用防火墙或安全组限制来源 IP。如果一定要暴露公网建议在前面加一层带鉴权的反向代理。这个经验是我被扫描工具扫过之后才长记性的你可以不必非走这一趟弯路。至于选择哪条路我的建议是开发期用本地稳定任务放云端两边共用一套配置模板通过环境变量区分路径和密钥。这样既兼顾灵活性又保证生产环境的稳定性。8. 常见报错与排查技巧8.1 命令行找不到 openclaw在 Windows 上出现openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称是高频报错。它代表解释器根本没有在 PATH 里找到 openclaw 可执行文件。排查顺序是先确认安装目录是否存在可执行文件再确认该目录是否在 PATH 中最后重新打开终端。注意 PowerShell 不会自动刷新会话的 PATH旧窗口里检测不到新添加的路径很正常不要怀疑安装包有问题。8.2 端口、进程与残留进程清理代理长时间运行后可能出现端口被占用、进程残留导致新服务起不来的情况。排查时用ps aux | grep -i openclaw找到残留进程必要时手动结束它再重启。Windows 上对应的是查端口占用和终止 PID。这种问题在开发阶段特别常见因为频繁重启是常态。我建议每次调试前先检查有没有残留进程养成先清场再启动的习惯能少很多奇怪的问题。8.3 卸载后重装不干净卸载 OpenClaw 时除了卸载程序本体还要留意用户目录下的.openclaw残留。如果之后想重装一个干净环境光卸载程序是不够的因为旧配置和数据还在重装后它仍会读取这些残留文件导致新装却像旧版的现象。最稳妥的做法是先备份再卸载程序然后清理.openclaw目录中不需要的配置项。如果你只是想移除某些规则或技能在应用里清理对应配置即可不必整个目录删掉。我把高频问题整理成一个速查方向表方便你对照现象优先排查方向openclaw 命令找不到PATH 是否包含安装目录、是否重开终端服务启动但无日志输出是否以后台进程运行、日志文件位置是否正确配置文件改了不生效metadata 缓存、是否需要重启审批规则没生效是否有旧版 exec-approvals.json 残留IM 消息收不到回调地址、端口监听、网关转发是否正常模型调用失败Base URL、模型标识、鉴权参数是否与接口一致9. 最后分享一点我的使用体会OpenClaw 这套体系的真正价值不在装好一个工具而在于你能把它的扩展栈当成自己的自动化底盘来用。我的经验是从最小场景开始扩展——先跑通一条指令再接入一个模型再加一个技能最后再接消息通道。每加一层都确认上一层没坏这样整体稳定很多。另外审批规则和 workspace 路径这两个东西是我认为全流程里最该认真对待的。很多人装完就急着加技能、接飞书结果基础路径和审批规则没处理好后面各种问题接连冒出来。先把底层理顺后面扩展的时候你会感觉整个体系都是顺的。这篇文章的内容来自我实际部署和使用 OpenClaw 的经验之谈配置项和命令细节在不同版本里可能存在差异建议你以自己安装版本的官方文档为准。如果你正准备动手我的建议就一句话别急着追求功能多先保证一条最小链路能稳定往返再一步一步往上加。