如果你跟我一样拿到OpenClaw的第一步就是翻附录A速查表那你大概率会在前十分钟里踩到三个坑PowerShell里报无法安全验证 WSL2 环境、npm装完却找不到openclaw命令、Skill文件夹放对了位置却不生效。别问我是怎么知道的。这篇文章不是把官方附录抄一遍而是我在Windows、WSL2、手机Termux三条路径上各部署了一次踩完报错、翻完日志和issue之后重新整理的一份带注释、带解法、带个人习惯的速查表。想快速跑起来OpenClaw的人、打算接Ollama本地模型的人以及想在手机上放一个轻量实例的人都可以直接照着操作。1. 先对齐概念这份速查表到底要查什么很多人把OpenClaw理解成一个聊天工具这其实窄了。它更像一个跑在本地、可以调配各种工具和模型的智能体运行框架你跟它说一句话它可以自己拆任务、调用Skill、读文件、执行命令最后把结果整理给你。官方文档很长绝大多数人真正高频翻看的其实是附录A的速查表——但官方速查表有个特点只写命令不写前置条件也不写报错。所以我这份速查表的定位很明确把部署和日常使用这件事里的关键信息压成可直接查的资料每条命令配一句什么时候用、踩过什么坑。整体覆盖五个模块正好对应你大概率会遇到的五类问题。1.1 速查表在哪些场景下最能派上用场环境验证阶段新的Windows机器上装完OpenClaw第一次运行就跑出WSL2相关报错。这种情况十有八九不是OpenClaw的问题而是底层WSL2没伺候好。安装部署阶段Windows原生、WSL2、Termux三条路径安装命令、Node版本要求、PATH配置各不相同。照着官方文档只给一条npm命令反而容易在半路卡住。Skill扩展阶段想给OpenClaw加技能却不知道怎么挂载、不知道manifest字段怎么填加了之后又发现AI根本没触发。算力接续阶段不理解API和Ollama本地模型在配置上有什么区别base_url填错然后对着ECONNREFUSED 127.0.0.1:11434发愁。日常排错阶段环境报错、权限报错、磁盘报错、目录缺失报错一张表能解决大部分问题。这五个场景我全经历过所以整理的时候不是按官方文档的目录抄而是按你实际会卡住的地方重新组织。1.2 阅读前先记住的四个基础概念配置目录OpenClaw默认把配置和Skill放在用户主目录下的.openclaw文件夹里Windows上就是C:\Users\你的用户名\.openclawLinux和WSL2里是~/.openclaw。后续所有路径问题先确认这个目录存在。CLI入口通过npm全局安装后终端里用openclaw命令操作全局子命令包括init、run、config、skills、doctor等。不同版本子命令命名有细微差异以openclaw --help为准。Skill体系Skill是挂在配置目录下的能力包每个包由一个manifest清单文件和若干执行脚本组成。AI根据你的对话内容决定要不要调用某个Skill。模型后端OpenClaw本身不带大模型它只负责调度真正的算力来源要么是云端API要么是Ollama这类本地引擎。所以OpenClaw是不是只能用API接入方式使用算力这个问题答案在第五章。一句话总结我的建议先确认自己的目标场景再动手。我见过有人折腾了一周Skill结果核心模型都没接上那属于舍本逐末。2. 动手前先验货WSL2环境检查与无法安全验证的真相在Windows上折腾OpenClaw十个人里有八个会撞见这条报错无法安全验证 WSL2 环境。请在PowerShell中运行 wsl -- status。我第一次看到时很懵我明明装了WSL2为什么它说无法验证后来翻日志才明白OpenClaw在Windows上启动前会做一次环境自检检测目标不是你装了WSL没有而是你的WSL是不是真真正正的WSL2并且可用。这条保护逻辑很严格因为WSL1和WSL2在虚拟化、文件系统、内核兼容性上差异巨大很多Skill里用到的Linux命令在WSL1下行为不一致。OpenClaw检测不通过宁可拒绝启动也不愿意带病运行。2.1 这条报错出现的完整链路正常情况下运行OpenClaw时它会尝试调用WSL2来启动Linux侧的服务或Companion组件依赖链是Windows功能 → WSL内核 → 发行版 → OpenClaw侧检测。如果中间任何一环断了就会出现无法安全验证。常见的断裂点包括Windows功能没开适用于Linux的Windows子系统或虚拟机平台未勾选。WSL内核版本过旧老内核和最新OpenClaw的检测逻辑不匹配。发行版版本是WSL1装了Ubuntu但一直跑在WSL1模式下。没有安装任何发行版WSL命令本身能执行但没有任何可用的Linux系统。很多人第一反应是重装OpenClaw这方向就错了。重装十次也修不好一个没启用的Windows功能先验环境才是正道。2.2 三条命令完成环境体检在PowerShell里按顺序跑下面三条命令前三分钟就能定位问题wsl -- status这条命令看整体状态重点看默认版本是不是2以及有没有报错信息。如果显示默认版本是1说明后续所有发行版默认跑在WSL1上。wsl --list --verbose这条命令列出所有发行版看VERSION列。你的Linux发行版这一列必须是2。如果是1用下面两条迁移wsl --set-default-version 2 wsl --set-version Ubuntu 2再把内核更新到最新很多莫名其妙的兼容问题都会消失wsl --update更新完之后关闭所有终端窗口重新打开再跑一次wsl -- status确认。注意修改Windows功能或WSL版本之后一定要重启一次PowerShell不重启就重新运行OpenClaw检测到的还是旧状态。2.3 WSL2环境最常见的四种翻车姿势检查项命令预期结果失败处理虚拟化平台设置→应用→可选功能→更多Windows功能虚拟机平台已启用勾选后重启WSL版本wsl -- status默认版本为2wsl --set-default-version 2发行版模式wsl --list --verboseVERSION列为2wsl --set-version 名称 2内核版本wsl --update提示已安装最新更新后重启终端我整理出来之后发现大部分人卡在第三个明明装了Ubuntu但初始化的版本是WSL1。也有少部分人是装完Docker Desktop之后Docker和WSL2抢资源导致检测不稳定。如果你机器上有Docker Desktop并且WSL2环境一直怪怪的先看Docker的设置里是不是把WSL集成指向了错误发行版把不需要集成的发行版关掉再重新检测。另外提醒一句这条报错里的提示请在PowerShell中运行 wsl -- status不是让你把输出结果贴到哪儿去而是OpenClaw在告诉你先自查环境别带病启动。我见过有人以为是隐私协议问题折腾了好几天点破之后懊恼得不行。3. 三平台安装速查Windows、WSL2与Termux各走各的路OpenClaw的安装本质上是同一个套路装Node.js运行时然后用npm安装OpenClaw本体。但因为宿主系统不同前置条件和坑点各不一样。我三条路都实际装过下面直接给能复现的步骤。3.1 Windows原生安装先分清Node.js和OpenClaw网上有个高频搜索词是node.js官网下载openclaw这是个误解Node.js官网下载的是运行时不是OpenClaw本体。正确顺序是先装Node再用npm拉OpenClaw。第一步从Node.js官网下载LTS版本安装包版本要求一般不低于20。安装时一定勾选Add to PATH否则后面找不到node命令。装完开一个新的PowerShell验证node -v npm -v两个命令都有输出版本号才算通过。第二步安装Git for Windows。这一步很多人跳过等到Skill需要克隆仓库或者调用git命令时才回头补装不如一开始就装好。第三步安装OpenClawnpm install -g openclaw这一步执行完最常出现的坑是openclaw: command not found。原因不是没装上而是npm的全局bin目录不在PATH里。先跑npm prefix -g看输出的全局根目录npm的可执行文件一般在它的node_modules/.bin目录下Windows上通常是C:\Users\你的用户名\AppData\Roaming\npm。把这个目录加进系统环境变量的PATH再重新开终端。Windows上还有一个容易踩的权限问题不要用管理员身份装的全局包和普通用户PATH混用后面会出现权限不足和找不到命令同时存在的诡异情况。统一用普通用户安装。3.2 WSL2安装我的首选方案如果在Windows上用了一段时间还想长期折腾我的建议是趁早把OpenClaw迁到WSL2里。原因很实际WSL2里的文件权限、命令兼容性、资源隔离都比Windows原生里跑一个跨平台npm包稳而且Skill一旦涉及Linux工具链在WSL2里几乎零摩擦。进入Ubuntu发行版wsl -d Ubuntu先更新源sudo apt update sudo apt upgrade -y装Gitsudo apt install git -yNode的部分注意直接apt install nodejs装出来的版本通常偏旧建议用nvm管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 20装完nvm之后记得重开终端让环境变量生效然后装OpenClawnpm install -g openclaw openclaw initWSL2路径有个天然优势如果你把Ollama也装在同一套WSL2环境里OpenClaw访问模型直接填http://localhost:11434就行不用管跨系统网络问题。这个细节能让配置省心一大半。3.3 Termux手机端轻量用的临时方案在手机上跑OpenClaw靠的是Termux这个Android终端模拟器。装好Termux之后先更新包管理器和基础工具pkg update pkg upgrade -y pkg install nodejs git -y npm install -g openclawTermux上我踩过两个坑。第一个是存储权限执行一次termux-setup-storage把存储目录放开否则后续Skill读写文件会报权限错误。第二个是后台保活手机锁屏一段时间后系统会把Termux进程杀掉会话直接断开任务也中断。需要在系统设置里允许Termux后台运行并关闭电池优化。性能方面手机端只适合轻量使用比如查个日历、记个笔记、跑点简单对话。别指望在手机上跑大型模型或者批量处理文件闪存类型和散热都扛不住。3.4 三条路径怎么选安装路径适用场景难度核心注意点Windows原生快速验证、桌面日常低PATH配置、WSL2检测报错WSL2长期使用、开发调试中内核更新、Node版本切换Termux手机临时使用中存储权限、后台保活我的真实建议是装来体验一下就删的走Windows原生没问题打算当成主力工具用的直接进WSL2手机上只是偶尔用一下的Termux够用但别指望它干重活。4. Skill技能挂载速查目录结构、配置字段与生效规则openclaw skill是社区里被问得最多的话题之一。很多人把Skill理解成普通插件装进目录就以为完事了结果AI根本不触发。要搞明白Skill得先知道它的设计逻辑。4.1 Skill本质上是能力包不是插件目录Skill由两部分组成一个清单文件manifest和一组执行逻辑。清单文件给AI看告诉AI这个Skill什么时候该用、调用时需要什么权限执行逻辑才是真正干活的脚本。AI根据对话内容判断语义匹配命中之后才调用Skill。这跟传统插件的区别在于传统插件是用户手动触发Skill是AI语义触发。所以写清楚manifest里的描述字段极其重要。描述写得泛AI就会乱调用描述写得具体AI又可能漏调用。这个平衡需要自己调我后面会讲。4.2 一个Skill的标准目录与配置字段目录结构长这样我用的是OpenClaw配置目录下的skills文件夹~/.openclaw/ ├── config.yaml └── skills/ ├── web-search/ │ ├── manifest.yaml │ └── run.py └── file-watcher/ ├── manifest.yaml └── watch.shconfig.yaml里声明skills目录的加载路径同时把模型配置也放在这里skills: - skills/ model: provider: ollama base_url: http://localhost:11434 model: qwen2.5:7b每个Skill内部的manifest.yaml核心字段不多我贴一个最小可用的例子name: web-search description: 当用户需要搜索网页、查找资料、获取链接时使用 when: 用户提到搜索、查找信息、获取最新内容 permission: confirm run: python run.pynameSkill的唯一标识AI靠它区分不同技能。description语义描述这是AI决定是否触发Skill的核心依据要写得像给人看的自然语言。when触发条件的补充说明进一步缩小使用范围。permission权限等级。safe表示直接执行confirm表示每次询问用户root表示最高权限一般用于管理类操作。run执行入口相对于Skill目录的路径。我之前把description写得像技术文档比如本技能提供网页搜索功能结果AI几乎不触发。改成当用户需要搜索网页、查找资料、获取链接时使用之后命中率立刻上来了。原因很简单AI理解自然语言不理解函数名。4.3 挂载、查询、重载的完整命令流把Skill文件夹放对位置只是第一步还要让OpenClaw知道它存在。我用的版本支持下面这套命令openclaw skills list查看当前已加载的所有Skill确认名字和状态。openclaw skills add /path/to/skill把自己写的或者从社区下载的Skill挂载进去。这一步会把Skill复制到配置目录等于正式登记。openclaw skills remove name移除指定Skill。openclaw skills reload修改manifest或脚本之后重新加载。注意这个动作非常重要——很多版本带的还是启动时扫描机制没有热更新。改完manifest不reloadAI看到的还是旧描述你测试一整天都是白费。4.4 Skill权限收口安全不是可选项Skill的权限设计是我非常看重的一部分。我的习惯是默认只给safe和confirmroot权限只给两类情况一是自己逐行读过源码的本地脚本二是明确只在隔离环境里运行的实验类Skill。原因不复杂AI的语义触发本质上是概率性的描述写得再好也有误触发可能。一个挂着root权限的文件处理Skill万一被AI误解成删除目录里的所有文件后果你跑一次就懂。还有两个小建议第一从社区下载的Skill在挂载前先读一遍源码至少确认它没有藏私地调用你本地的密钥第二Skill的manifest描述保持克制不要为了触发率高就把适用范围写得很宽宁可漏掉一次调用也不要让AI在错误场景乱执行。5. 算力接线速查API直连、Ollama本地与混合模式怎么选社区里有个高频问题OpenClaw是不是只能用接入API的方式使用算力答案是否定的。OpenClaw本身只负责调度任务和调用工具模型后端是抽象的一层既可以接云端API也可以接Ollama这类本地推理引擎。关键区别全在配置文件里的model字段。5.1 API直连高质量来自云端接API的方式最省事配置里指定provider、api_key、base_url和model就行model: provider: anthropic api_key: sk-xxx base_url: https://api.xxx.com model: claude-sonnet-4-5这种方式适合追求回复质量、任务复杂、需要稳定推理速度的场景。模型在云端不吃本地硬件OpenClaw跑在什么平台上都一样。但有两个代价一是按token计费重度使用一个月下来费用需要心里有数二是数据要出本地所有对话内容和Skill读取的文件都可能发送给API服务商隐私敏感的场景要慎重。配置上最容易翻车的点有两个base_url填错比如自定义网关写成了https://api.xxx.com/v1而实际路径不带v1会直接报ECONNREFUSED或者404另一个是API key写在配置文件里然后整个目录被同步到Git仓库密钥泄露。我的习惯是api_key从环境变量读不在配置文件里写死。5.2 Ollama本地把模型拉到自己的机器上本地算力的方案是通过Ollama把模型拉下来OpenClaw配置成对接本地服务ollama pull qwen2.5:7b配置文件写为model: provider: ollama base_url: http://localhost:11434 model: qwen2.5:7b这种方式的好处是隐私全本地、零API费用、离线可用。代价是速度完全取决于你的硬件7B参数模型在16G内存且带核显或独显的机器上可以流畅跑纯CPU硬扛也不是不行但对话生成速度会明显变慢。这里有个跨系统的坑必须单独说。OpenClaw跑在WSL2里时如果Ollama装在Windows侧那么localhost:11434这个地址指向的是WSL2自己不是Windows宿主。需要拿到Windows在局域网里的实际IP在WSL2里用这个命令查ip route show default | awk {print $3}然后把base_url改成http://那个IP:11434。更省心的方案是把Ollama也装进同一个WSL2环境里两边共用localhost彻底避开这个坑。Termux方案同理OpenClaw跑在手机上Ollama在局域网服务器上就填服务器的局域网IP。5.3 混合模式日常轻量关键时刻上重兵实际用起来我更喜欢混合模式日常能走本地模型的走本地遇到复杂任务或者Agent需要更强推理能力时切API。实现上不用太复杂的路由我的做法是维护两份配置文件config.ollama.yaml和config.api.yaml按场景执行openclaw run --config config.ollama.yaml openclaw run --config config.api.yaml这样虽然不算智能调度但简单可靠而且切换成本其实就是一条命令。如果你的版本支持在Skill级别覆盖model配置那更精细的路由也可以做——把复杂交互类任务绑到API把数据读取类任务绑到本地模型。只是这种配置对文章的受众来说可能稍重建议先跑通单配置再折腾。5.4 算力选型对照表维度云端APIOllama本地成本按token计费电费隐私数据出本地完全本地延迟受网络波动影响由硬件决定离线不支持支持适合场景生产环境、复杂任务个人使用、隐私敏感所以OpenClaw是不是只能用API接入方式使用算力这个问题准确答案是可以用API也可以接Ollama本地模型还可以两者混用。选择权重主要看你是更在意回答质量还是更在意隐私和成本。6. 高频报错速查表现象、根因、一条命令解决速查表的价值最后都落在排错上。下面这张表是我在部署和日常使用里实际遇到过的高频问题每个都按现象-根因-解法三列整理直接照着做。6.1 用一张表搞定八成报错报错现象根因快速解法无法安全验证 WSL2 环境WSL2未启用或内核过旧wsl --update重启终端确认默认版本为2openclaw: command not foundnpm全局bin不在PATHnpm prefix -g找到bin目录加入PATHNode版本过低运行时版本太老用nvm安装Node 20 LTSECONNREFUSED 127.0.0.1:11434Ollama没启动或base_url错误先ollama list确认服务再检查base_urlWSL2跨系统访问要填宿主IPSkill validation failed: unknown fieldmanifest.yaml字段名不对对照name/description/when/permission/run检查No such file or directory: skills初始化不完全运行openclaw init重建配置目录ENOSPC磁盘空间不足常见于Termux清理缓存或termux-setup-storage扩展存储EACCES permission deniednpm全局安装没有写入权限Windows避开Program FilesLinux用nvm改全局目录这张表覆盖了我遇到的八成问题。剩下两成的问题是环境组合出来的奇怪报错尤其常见于Windows版本过旧、WSL内核和Docker Desktop互相干扰这类场景往下看诊断思路。6.2 报错不在表里怎么办诊断三连遇到表里没有的报错我建议按这个顺序排查能快速缩小范围node -v npm -v第一步确认运行时健康。Node版本低于预期后面所有问题都可能牛头不对马嘴。wsl -- status第二步确认WSL2健康在Windows上跑OpenClaw时这是必检项。openclaw doctor第三步跑OpenClaw自带的诊断。我用的版本里有这个子命令会检查配置目录、Skill合法性、模型连通性把常见问题一次性列出来。如果你的版本没有这个命令跑openclaw --help看有没有类似的自检子命令。诊断完之后去配置目录下的logs文件夹里看最后100行日志。报错发生时的堆栈信息几乎都在日志里比你在网上搜索报错文案有用得多。6.3 一个完整的排查示例我举一个实际案例让大家感受一下排查链路怎么走。现象是openclaw run启动后对话里只要涉及模型调用就报ECONNREFUSED 127.0.0.1:11434。我的排查顺序是先跑ollama list发现服务根本没起来。执行ollama serve手动启动再测试。这一步排除了配置对但服务没启动的最大嫌疑。服务启动后重新运行OpenClaw问题消失。说明根因就是Ollama没启动和配置文件无关。为了防止下次启动又忘把Ollama设为系统服务/自启动。看起来简单但我最初在这上面浪费了不少时间因为一看到ECONNREFUSED就以为是API key或者base_url配错了反复改配置结果根源只是Ollama进程没在跑。排查的顺序真的很重要先环境再配置后Skill最后模型连通性。按这个顺序来大部分问题都能在十分钟内解决。最后分享两个我踩坑后养成的习惯第一凡是玄学报错先跑一遍wsl -- status和node -v。这两个命令能定位掉至少一半的环境问题别急着重装重装只会让问题藏得更深。第二Skill的权限只给confirm哪怕是我自己写的Skill也一样。AI误触发脚本这种事遇到了就来不及后悔权限收口是唯一可靠的防线。这两条习惯帮我省了大量时间也让我的OpenClaw跑得比刚上手时稳得多。这份速查表还有很多可扩展的地方比如多用户配置、远程模型网关、自托管模型服务等后续实践多了再补充。如果你部署时碰到我上面没写到的新奇报错欢迎留言交流我对这类问题还挺有兴趣的。