最近OpenClaw在AI代理圈的热度高得离谱群里天天有人问这玩意儿到底怎么装为什么照着教程一步步来还是各种报错作为把OpenClaw在Windows、Linux、还有手机上各折腾过一遍的人我可以很负责地说这个项目本身不算难难在文档太散、坑太深。这篇保姆级指南我会从环境准备开始把OpenClaw部署的每个环节拆开讲再把13000技能库里我实际踩过的高频雷区整理成排雷清单给你。不管你是刚接触本地AI的新手还是已经跑过Ollama的老玩家这篇都值得先收藏再往下看至少能帮你少走两三天弯路。1. OpenClaw到底解决什么问题为什么值得在本地折腾1.1 核心机制Agent Skill 工具链OpenClaw本质是一个开源AI代理框架它自己不做推理推理交给模型自己做的是“调度”和“执行”这两件事。你可以把它想成一副“大脑双手”大脑是本地大模型或云端API负责理解任务、拆解步骤双手则是那13000多个技能包覆盖浏览器自动化、文件处理、数据分析、代码执行、定时任务等等。它的内部大致分三层调度层负责任务规划和技能调用技能层提供可插拔的能力模块工作层负责对接模型和外部工具。这种分层设计最直接的好处是“可替换性”——今天用Ollama跑Qwen明天换LM Studio跑Llama技能和调度逻辑都不用动只需要改配置里模型那一栏。这套架构对个人用户最大的意义是你不再需要为每个自动化需求单独写脚本而是用大白话告诉OpenClaw“帮我查一下这个网页里所有邮箱并整理成表格”剩下的它自己交给技能链去完成。1.2 本地部署的核心价值隐私、成本、可控性很多人问过我OpenClaw接云端模型不是更省事吗为什么非要折腾本地部署我的回答是看你的使用场景。如果你只是偶尔玩一下接云端API当然没问题但如果你想把它当成日常工具天天用本地部署在这三方面的优势就非常明显。第一是隐私。本地部署时你的对话内容、文件内容、浏览器操作数据全部停留在自己设备上不会因为第三方服务的数据留存策略而产生顾虑。第二是成本。云端API按token计费长期跑自动化任务费用累积很可观本地模型只要有硬件就随便跑没有边际成本。第三是可控性。Prompt、技能权限、网络访问、模型参数全部自己说了算不会因为服务商调整接口就导致整个流程崩掉。当然代价也摆在那里——显存和内存吃得多模型能力相对云端旗舰款弱一些。所以我的建议是敏感数据任务用本地一次性复杂推理任务可以临时切云端两者可以共存。1.3 部署形态怎么选桌面、服务器、手机OpenClaw的部署形态比大多数项目都灵活但选错形态往往是第一层报错的来源。桌面上最常用的是Windows和macOS直接跑Python进程适合个人日常使用启动简单也能配合图形界面里的控制台操作。服务器场景建议用Docker部署适合24小时在线或多人共用的环境但要注意GPU透传配置否则容器里看不到显卡强行拉大模型直接报CUDA错误。另外还有手机或者低功耗设备上的Termux方案思路和桌面一致只是受限于硬件建议只跑小模型或者干脆不跑模型只连接局域网里另一台机器的Ollama服务。还有一个容易漏掉的部分Windows上要额外启用Windows Companion组件它负责系统级能力集成比如剪贴板、窗口控制、文件操作。不装这个很多系统类技能会显示permission denied。2. 保姆级部署实操从环境准备到首次启动2.1 部署前检查清单别让环境成为第一道坎我见过太多人一上来就clone项目结果Python版本不对、Node没装、Ollama服务没起报错一条接一条最后还以为是OpenClaw本身的问题。所以在动手之前先花五分钟过一遍环境清单。项目最低要求推荐配置CPU4核8核及以上内存16GB32GB显卡显存8GB跑7B量化模型16GB跑13B/14B量化模型硬盘20GB100GB以上多模型场景系统Windows 10/11、Ubuntu 20.04、macOS 12同一行但建议Linux服务器做长期运行软件层面主要有四样Python 3.10到3.12、Node.js 18以上、Git、Ollama或等效模型服务。这里重点说Python版本OpenClaw官方依赖锁在3.10到3.12之间如果系统默认装的是3.13很多第三方库没有对应轮子会在编译时报出一大片红字非常劝退。Windows用户建议用pyenv-win管理版本Linux用户直接用apt或源码装指定版本都行。2.2 Windows安装OpenClaw主程序完整步骤确认环境没问题后按下面这个流程走就不会在安装阶段卡住。第一步把项目克隆到本地。注意目录路径不要带中文和空格这是Windows下很多奇怪的工程类报错的源头。git clone OpenClaw官方仓库地址 cd openclaw第二步创建虚拟环境并激活。强烈建议用虚拟环境不要直接装到系统Python里不然你以后跑其他项目时会遇到依赖互相打架的惨剧。python -m venv .venv .venv\Scripts\activate第三步安装依赖和项目本身。这里要有点耐心依赖量大有些包需要编译可能出现几十秒的静默期。pip install --upgrade pip pip install -r requirements.txt pip install -e .第四步初始化配置并设置模型提供方为Ollama。openclaw init openclaw config set model.provider ollama第五步启动Ollama并拉取模型。7B模型是底线建议直接用14B量化版效果会明显好一截。ollama pull qwen2.5:14b ollama serve第六步启动OpenClaw。openclaw serve启动成功后浏览器访问控制台地址 http://127.0.0.1:5100 。如果端口打不开先检查防火墙再检查5100端口是否被占用用netstat -ano | findstr 5100就能看到。注意具体仓库地址以你拿到的官方文档为准不同版本启动命令可能略有差异但整体流程是一致的。2.3 配置Windows Companion必踩的坑Windows Companion是OpenClaw在Windows平台上提供系统集成能力的辅助组件很多人忽略了它然后技能一调用系统功能就报权限错误。配置要点有三个首先确保Windows系统安装了WebView2运行时这是Companion的界面和通信基础Win11一般自带Win10老版本需要手动装。其次在OpenClaw配置里打开Companion开关并设置IPC端口默认是5101和主服务端口区分开。最后把OpenClaw进程加入防火墙放行列表否则Companion回调时会出现连接被拒。如果你不需要“打开应用截图”“控制剪贴板”这类系统级技能可以暂时不开Companion。但只要计划用任何涉及Windows原生功能的技能就老老实实配好。2.4 安卓Termux部署手机也能跑但别抱太高期望手机部署是很多人问的毕竟谁都想随时有个AI代理在身边。Termux方案确实可行但我的建议是手机端只做客户端不做重型模型端。具体做法是在Termux里安装Proot容器或直接用Termux原生的Python环境步骤和桌面版类似只是要注意三个限制一是大多数手机没有GPU加速拉大模型跑会非常吃力二是文件系统权限受限技能里涉及读写手机存储的要多一步授权三是内存回收机制可能导致OpenClaw进程在后台被杀。最稳妥的搭配是手机连局域网内已有Ollama服务的那台机器把OpenClaw当瘦客户端用这样既能随时用又不会把手机拖死。3. 对接本地模型这步决定你后面顺不顺3.1 Ollama是最省事的方案没有之一OpenClaw和Ollama的组合是我目前用过最省心的本地方案原因不用多说安装快、模型管理简单、API兼容度高。在Ollama跑起来之后把OpenClaw的配置文件里模型部分改成下面这样即可model: provider: ollama endpoint: http://127.0.0.1:11434 name: qwen2.5:14b context_window: 8192 temperature: 0.3 tool_use: true这里几个参数值得单独说明。context_window是上下文窗口设太小任务稍微复杂一点工具调用就会中途截断设太大显存占用成倍增长14B模型在16G显存上把8192拉满就差不多了。temperature建议固定在0.2到0.4之间工具调用场景最忌讳模型自由发挥温度一高JSON格式乱掉解析阶段必然报错。tool_use必须为true关掉这个开关OpenClaw的整个调度层等于废了。3.2 进阶LM Studio和GPUStack那套OpenAI兼容模式除了OllamaOpenClaw兼容所有提供OpenAI风格API的本地服务这里点名LM Studio和GPUStack两个。LM Studio适合那些不想用命令行拉模型的人图形界面点点就能下载模型并启动本地API。配置OpenClaw时把provider改成openai_compatible就行model: provider: openai_compatible base_url: http://127.0.0.1:1234/v1 api_key: dummy_key name: local-modelGPUStack适合更硬核的场景它支持多GPU负载均衡能把多张显卡的显存拼起来跑一个大模型。我有台机器两张6G老卡单卡跑7B都费劲用GPUStack后勉强能跑13B量化模型还是很实用的。当然它的配置复杂度比Ollama高不少新手不建议一开始就上。3.3 模型选型的硬指标必须支持function calling这可能是整个部署过程中最容易被忽略的一点。OpenClaw的调度层依赖模型输出结构化的工具调用指令如果模型不支持function calling就会出现“模型能正常聊天但一让它执行任务就乱套”的诡异现象。我实测下来Qwen2.5系列、Llama 3.1以上版本、GLM-4系列都是靠谱的选择。尽量避免选一些只做对话优化的通用模型哪怕对话效果再好工具调用只要不稳定OpenClaw就约等于一个高级聊天机器人。另外本地模型版本尽量保持在最新工具调用的稳定性通常靠后期版本更新修复。4. 13000技能机制、安装、升级和排雷一条龙4.1 技能系统的底层逻辑技能库是OpenClaw最吸引人的部分。所谓技能就是一个包含元数据、执行逻辑和依赖声明的独立包。它的标准结构是一个目录里面有skill.yaml描述技能功能和参数main.py或main.js是实际执行逻辑再加一份依赖清单。OpenClaw启动时会扫描技能目录并建立索引实际使用时才懒加载而不是一次性全部装进内存。这个设计很聪明13000多个技能不可能同时驻留懒加载保证系统不会被拖垮。但这也意味着第一次调用某个新技能时它需要现场加载依赖甚至是现场下载浏览器内核之类的外围组件如果那一步超时就变成你看到的“技能没反应”。4.2 安装技能的三种姿势第一种从内置技能市场搜索安装。这是最推荐的方式技能经过基础校验安装路径和依赖关系相对清晰。openclaw skill search browser openclaw skill install browser-search第二种从Git仓库安装社区技能。这种方式很灵活但风险也大装之前先看看仓库的README和最近提交时间太长时间没维护的技能慎装。openclaw skill install git仓库地址 --source git第三种手动放入技能目录。直接把技能目录丢到~/.openclaw/skills/下面OpenClaw启动时会自动扫描。这种方式适合自己写的小技能调试方便但要注意目录结构和skill.yaml格式必须规范否则不会被识别。4.3 技能高频报错实录把这些坑提前填平我在技能这条路上踩过的坑比主程序报错加起来都多。下面这张表是高频问题中最高频的一部分。报错现象常见原因解决方案skill_init_failed技能依赖缺失进入技能目录执行pip install -r requirements.txttimeout waiting for skill首次使用需要下载浏览器内核或模型组件手动预下载组件或调大skill_timeout参数cannot find module playwrightNode层面依赖未安装执行npm install再执行playwright install chromiumpermission denied技能想访问系统能力但未授权启动Windows Companion并放行对应权限skill not found技能名拼错或未正确注册执行openclaw skill list查看实际加载的列表技能执行到一半卡死依赖的系统服务未启动按日志提示定位到具体外部依赖逐个排查一个很重要的经验每装完一个技能就立刻重启OpenClaw再测试。批量装十几个技能后如果出了错日志多到你根本分不清是谁的问题那时候才叫欲哭无泪。4.4 技能冲突和性能损耗不夸张但真实存在很多人以为技能是互不干扰的实际上它们之间会通过Python依赖环境互相踩脚。一个技能要求requests2.31另一个技能强制要requests2.32pip在装第二个的时候会把第一个的版本悄悄升级然后第一个技能可能就出现诡异的调用异常。这类问题排查起来很耗时间。经验做法是给所有技能集中跑一个虚拟环境不要单独给每个技能建环境维护成本太高。同时对技能内的依赖声明保持警惕装新技能前看一眼它依赖了哪些核心库如果和你常用的版本差距大就要想清楚值不值得装。还有一个容易忽略的资源问题每个技能长时间驻留会占用内存。我跑了一周后看监控发现30多个技能积攒了近2G内存占用。后来在配置里把不常用的技能设成超时自动卸载内存立刻降下来一大截。5. 排错方法论日志、复现、速查表5.1 排错第一原则所有报错都从日志开始很多新手一碰到报错就把整个屏幕截图发群里问“怎么办”。我可以直接告诉你没有日志谁也帮不了你。OpenClaw把运行日志写在~/.openclaw/logs/目录下报错时第一件事是打开服务端日志看最后一次报错的时间点附近发生了什么。日志分析要分三层看模型层、调度层、技能层。模型层报错通常是连接失败、输出格式不合规调度层报错一般是任务规划或技能选择出现问题技能层报错就是技能本身执行失败。分清层次之后解决方向就清晰了。你甚至可以写一个简单的错误分类脚本把日志里出现的错误关键词做统计看看自己的环境里最频繁挂掉的是哪一层。5.2 高频报错速查表复制粘贴就能用报错信息原因处理方式CUDA out of memory模型太大或上下文太长换小模型、降低context_window、开启量化Connection refusedOllama服务未启动先执行ollama serve再检查curl http://127.0.0.1:11434yaml.parser.ParserError配置文件缩进错误重新检查YAML缩进禁止用TabAddress already in use: 5100端口被占用换端口或找到占用进程并结束JSONDecodeError模型返回非JSON调低temperature换更强模型AuthenticationErrorAPI key无效云端API检查key本地服务填dummy_key即可ModuleNotFoundError: openclaw虚拟环境未激活确认终端里已执行虚拟环境激活命令5.3 三个真实排错案例复盘第一个案例是“卡加载转圈”。现象是控制台页面出来了但发消息后一直转圈没有任何反应。排查过程先看日志发现OpenClaw没有报错但和Ollama的连接一直处于等待状态。再检查Ollama发现它压根没启动——因为上次关机后没有自启。解决方式是写一个开机启动脚本先检测11434端口通了再拉起OpenClaw从根上解决了这个问题。第二个案例是“技能全部超时”。现象是首次调用浏览器自动化技能时所有相关技能全部timeout。日志里显示playwright在下载浏览器内核但下载过程没有进度提示最后被超时机制切断。解决方式是手动执行一次playwright install chromium把浏览器内核提前装好再把技能的初始化超时从默认的60秒调大到100秒。第三个案例是“模型能聊天但工具调用全失败”。这个问题最隐蔽因为OpenClaw表面上没报错技能也没问题但模型就是不给调度层返回标准的工具调用指令。最后定位到两个原因一是模型本身不支持function calling二是我测试时把temperature调到了0.8模型输出JSON的格式稳定性崩了。换成支持工具调用的模型并降低温度后问题彻底解决。5.4 性能与资源控制别让机器被悄悄拖垮部署成功只是一半后半程是让它在有限硬件里长期稳定运行。我建议做好四件事第一模型优先选Q4_K_M量化版本这是一个在效果和显存占用之间非常甜的点位。第二给OpenClaw的并发任务数设置上限max_concurrent_tasks设成2到3就够了不要让它无限制并发否则小水管内存会瞬间爆炸。第三配置日志按天轮转这句话听着朴素但日志文件在持续运行时膨胀速度惊人我见过有人一周没管日志占了十几个G。第四显存小于16G就不要同时加载多个模型OpenClaw支持多模型配置但那是给大显存玩家准备的。6. 部署后的维护与安全建议6.1 本地部署也不等于绝对安全很多人一听“本地部署”就觉得万事大吉其实不然。技能系统里有一部分能力是执行Shell命令、读写文件、访问网络如果装了来源不明的技能它完全可以在你不知情的情况下读取私人文件或向外部发送数据。我自己的做法是默认关闭技能包中的网络访问权限用哪个技能、访问哪个域名单独在配置里放行。这样虽然每次新技能第一次跑网络请求时要多一个授权步骤但换来了整体可控性值。另外定期检查一下技能目录看有没有非自己安装的奇怪技能混进来。6.2 技能权限分级最小权限原则这里分享一个我实践下来很有效的权限分级方案。把所有技能按风险分三档安全技能文本处理、数据格式化可以直接自动运行普通技能浏览器自动化、文件读取需要配置确认后运行高危技能Shell命令执行、任意文件删除、网络请求必须手动输入确认指令才允许执行。这个分级听起来麻烦但正是这一步避免了我多次误触危险操作。6.3 更新与备份少踩兼容性的雷OpenClaw主程序更新比较频繁我的经验是大版本发布后等至少一周再升级让社区先把新版本的坑踩完。技能更新同理升级前看一眼技能的更新记录如果改动很大先备份旧版本。备份整机不现实但至少把~/.openclaw目录定期打包是必须的这里包括了你的配置、技能和个人数据一个tar包就能让你从灾难中恢复。最后说点个人体会。OpenClaw这类项目本质上是在把“模型能力”和“自动化能力”焊到一起本地部署的门槛不在命令本身而在排错。我踩过最狠的一个坑是Windows杀毒软件把虚拟环境里的python.exe当成威胁隔离导致整个环境一夜之间崩溃所有依赖全部失效。自那以后我装好OpenClaw第一时间就把项目目录加入杀毒信任区。另一个经验是先跑通最简单的链路再逐步加技能别一上来就装十几个那样只会让你连报错出自谁都分不清楚。如果你照着这篇一步步走还卡住大概率只是配置里一个字段写错了把日志发出来按行号去查基本都能解决。 
长河君 · 2026/10/8 19:50:24 · 阅读 1.2k OpenClaw本地部署保姆级指南：环境准备、模型对接与技能排雷
最近OpenClaw在AI代理圈的热度高得离谱群里天天有人问这玩意儿到底怎么装为什么照着教程一步步来还是各种报错作为把OpenClaw在Windows、Linux、还有手机上各折腾过一遍的人我可以很负责地说这个项目本身不算难难在文档太散、坑太深。这篇保姆级指南我会从环境准备开始把OpenClaw部署的每个环节拆开讲再把13000技能库里我实际踩过的高频雷区整理成排雷清单给你。不管你是刚接触本地AI的新手还是已经跑过Ollama的老玩家这篇都值得先收藏再往下看至少能帮你少走两三天弯路。1. OpenClaw到底解决什么问题为什么值得在本地折腾1.1 核心机制Agent Skill 工具链OpenClaw本质是一个开源AI代理框架它自己不做推理推理交给模型自己做的是“调度”和“执行”这两件事。你可以把它想成一副“大脑双手”大脑是本地大模型或云端API负责理解任务、拆解步骤双手则是那13000多个技能包覆盖浏览器自动化、文件处理、数据分析、代码执行、定时任务等等。它的内部大致分三层调度层负责任务规划和技能调用技能层提供可插拔的能力模块工作层负责对接模型和外部工具。这种分层设计最直接的好处是“可替换性”——今天用Ollama跑Qwen明天换LM Studio跑Llama技能和调度逻辑都不用动只需要改配置里模型那一栏。这套架构对个人用户最大的意义是你不再需要为每个自动化需求单独写脚本而是用大白话告诉OpenClaw“帮我查一下这个网页里所有邮箱并整理成表格”剩下的它自己交给技能链去完成。1.2 本地部署的核心价值隐私、成本、可控性很多人问过我OpenClaw接云端模型不是更省事吗为什么非要折腾本地部署我的回答是看你的使用场景。如果你只是偶尔玩一下接云端API当然没问题但如果你想把它当成日常工具天天用本地部署在这三方面的优势就非常明显。第一是隐私。本地部署时你的对话内容、文件内容、浏览器操作数据全部停留在自己设备上不会因为第三方服务的数据留存策略而产生顾虑。第二是成本。云端API按token计费长期跑自动化任务费用累积很可观本地模型只要有硬件就随便跑没有边际成本。第三是可控性。Prompt、技能权限、网络访问、模型参数全部自己说了算不会因为服务商调整接口就导致整个流程崩掉。当然代价也摆在那里——显存和内存吃得多模型能力相对云端旗舰款弱一些。所以我的建议是敏感数据任务用本地一次性复杂推理任务可以临时切云端两者可以共存。1.3 部署形态怎么选桌面、服务器、手机OpenClaw的部署形态比大多数项目都灵活但选错形态往往是第一层报错的来源。桌面上最常用的是Windows和macOS直接跑Python进程适合个人日常使用启动简单也能配合图形界面里的控制台操作。服务器场景建议用Docker部署适合24小时在线或多人共用的环境但要注意GPU透传配置否则容器里看不到显卡强行拉大模型直接报CUDA错误。另外还有手机或者低功耗设备上的Termux方案思路和桌面一致只是受限于硬件建议只跑小模型或者干脆不跑模型只连接局域网里另一台机器的Ollama服务。还有一个容易漏掉的部分Windows上要额外启用Windows Companion组件它负责系统级能力集成比如剪贴板、窗口控制、文件操作。不装这个很多系统类技能会显示permission denied。2. 保姆级部署实操从环境准备到首次启动2.1 部署前检查清单别让环境成为第一道坎我见过太多人一上来就clone项目结果Python版本不对、Node没装、Ollama服务没起报错一条接一条最后还以为是OpenClaw本身的问题。所以在动手之前先花五分钟过一遍环境清单。项目最低要求推荐配置CPU4核8核及以上内存16GB32GB显卡显存8GB跑7B量化模型16GB跑13B/14B量化模型硬盘20GB100GB以上多模型场景系统Windows 10/11、Ubuntu 20.04、macOS 12同一行但建议Linux服务器做长期运行软件层面主要有四样Python 3.10到3.12、Node.js 18以上、Git、Ollama或等效模型服务。这里重点说Python版本OpenClaw官方依赖锁在3.10到3.12之间如果系统默认装的是3.13很多第三方库没有对应轮子会在编译时报出一大片红字非常劝退。Windows用户建议用pyenv-win管理版本Linux用户直接用apt或源码装指定版本都行。2.2 Windows安装OpenClaw主程序完整步骤确认环境没问题后按下面这个流程走就不会在安装阶段卡住。第一步把项目克隆到本地。注意目录路径不要带中文和空格这是Windows下很多奇怪的工程类报错的源头。git clone OpenClaw官方仓库地址 cd openclaw第二步创建虚拟环境并激活。强烈建议用虚拟环境不要直接装到系统Python里不然你以后跑其他项目时会遇到依赖互相打架的惨剧。python -m venv .venv .venv\Scripts\activate第三步安装依赖和项目本身。这里要有点耐心依赖量大有些包需要编译可能出现几十秒的静默期。pip install --upgrade pip pip install -r requirements.txt pip install -e .第四步初始化配置并设置模型提供方为Ollama。openclaw init openclaw config set model.provider ollama第五步启动Ollama并拉取模型。7B模型是底线建议直接用14B量化版效果会明显好一截。ollama pull qwen2.5:14b ollama serve第六步启动OpenClaw。openclaw serve启动成功后浏览器访问控制台地址 http://127.0.0.1:5100 。如果端口打不开先检查防火墙再检查5100端口是否被占用用netstat -ano | findstr 5100就能看到。注意具体仓库地址以你拿到的官方文档为准不同版本启动命令可能略有差异但整体流程是一致的。2.3 配置Windows Companion必踩的坑Windows Companion是OpenClaw在Windows平台上提供系统集成能力的辅助组件很多人忽略了它然后技能一调用系统功能就报权限错误。配置要点有三个首先确保Windows系统安装了WebView2运行时这是Companion的界面和通信基础Win11一般自带Win10老版本需要手动装。其次在OpenClaw配置里打开Companion开关并设置IPC端口默认是5101和主服务端口区分开。最后把OpenClaw进程加入防火墙放行列表否则Companion回调时会出现连接被拒。如果你不需要“打开应用截图”“控制剪贴板”这类系统级技能可以暂时不开Companion。但只要计划用任何涉及Windows原生功能的技能就老老实实配好。2.4 安卓Termux部署手机也能跑但别抱太高期望手机部署是很多人问的毕竟谁都想随时有个AI代理在身边。Termux方案确实可行但我的建议是手机端只做客户端不做重型模型端。具体做法是在Termux里安装Proot容器或直接用Termux原生的Python环境步骤和桌面版类似只是要注意三个限制一是大多数手机没有GPU加速拉大模型跑会非常吃力二是文件系统权限受限技能里涉及读写手机存储的要多一步授权三是内存回收机制可能导致OpenClaw进程在后台被杀。最稳妥的搭配是手机连局域网内已有Ollama服务的那台机器把OpenClaw当瘦客户端用这样既能随时用又不会把手机拖死。3. 对接本地模型这步决定你后面顺不顺3.1 Ollama是最省事的方案没有之一OpenClaw和Ollama的组合是我目前用过最省心的本地方案原因不用多说安装快、模型管理简单、API兼容度高。在Ollama跑起来之后把OpenClaw的配置文件里模型部分改成下面这样即可model: provider: ollama endpoint: http://127.0.0.1:11434 name: qwen2.5:14b context_window: 8192 temperature: 0.3 tool_use: true这里几个参数值得单独说明。context_window是上下文窗口设太小任务稍微复杂一点工具调用就会中途截断设太大显存占用成倍增长14B模型在16G显存上把8192拉满就差不多了。temperature建议固定在0.2到0.4之间工具调用场景最忌讳模型自由发挥温度一高JSON格式乱掉解析阶段必然报错。tool_use必须为true关掉这个开关OpenClaw的整个调度层等于废了。3.2 进阶LM Studio和GPUStack那套OpenAI兼容模式除了OllamaOpenClaw兼容所有提供OpenAI风格API的本地服务这里点名LM Studio和GPUStack两个。LM Studio适合那些不想用命令行拉模型的人图形界面点点就能下载模型并启动本地API。配置OpenClaw时把provider改成openai_compatible就行model: provider: openai_compatible base_url: http://127.0.0.1:1234/v1 api_key: dummy_key name: local-modelGPUStack适合更硬核的场景它支持多GPU负载均衡能把多张显卡的显存拼起来跑一个大模型。我有台机器两张6G老卡单卡跑7B都费劲用GPUStack后勉强能跑13B量化模型还是很实用的。当然它的配置复杂度比Ollama高不少新手不建议一开始就上。3.3 模型选型的硬指标必须支持function calling这可能是整个部署过程中最容易被忽略的一点。OpenClaw的调度层依赖模型输出结构化的工具调用指令如果模型不支持function calling就会出现“模型能正常聊天但一让它执行任务就乱套”的诡异现象。我实测下来Qwen2.5系列、Llama 3.1以上版本、GLM-4系列都是靠谱的选择。尽量避免选一些只做对话优化的通用模型哪怕对话效果再好工具调用只要不稳定OpenClaw就约等于一个高级聊天机器人。另外本地模型版本尽量保持在最新工具调用的稳定性通常靠后期版本更新修复。4. 13000技能机制、安装、升级和排雷一条龙4.1 技能系统的底层逻辑技能库是OpenClaw最吸引人的部分。所谓技能就是一个包含元数据、执行逻辑和依赖声明的独立包。它的标准结构是一个目录里面有skill.yaml描述技能功能和参数main.py或main.js是实际执行逻辑再加一份依赖清单。OpenClaw启动时会扫描技能目录并建立索引实际使用时才懒加载而不是一次性全部装进内存。这个设计很聪明13000多个技能不可能同时驻留懒加载保证系统不会被拖垮。但这也意味着第一次调用某个新技能时它需要现场加载依赖甚至是现场下载浏览器内核之类的外围组件如果那一步超时就变成你看到的“技能没反应”。4.2 安装技能的三种姿势第一种从内置技能市场搜索安装。这是最推荐的方式技能经过基础校验安装路径和依赖关系相对清晰。openclaw skill search browser openclaw skill install browser-search第二种从Git仓库安装社区技能。这种方式很灵活但风险也大装之前先看看仓库的README和最近提交时间太长时间没维护的技能慎装。openclaw skill install git仓库地址 --source git第三种手动放入技能目录。直接把技能目录丢到~/.openclaw/skills/下面OpenClaw启动时会自动扫描。这种方式适合自己写的小技能调试方便但要注意目录结构和skill.yaml格式必须规范否则不会被识别。4.3 技能高频报错实录把这些坑提前填平我在技能这条路上踩过的坑比主程序报错加起来都多。下面这张表是高频问题中最高频的一部分。报错现象常见原因解决方案skill_init_failed技能依赖缺失进入技能目录执行pip install -r requirements.txttimeout waiting for skill首次使用需要下载浏览器内核或模型组件手动预下载组件或调大skill_timeout参数cannot find module playwrightNode层面依赖未安装执行npm install再执行playwright install chromiumpermission denied技能想访问系统能力但未授权启动Windows Companion并放行对应权限skill not found技能名拼错或未正确注册执行openclaw skill list查看实际加载的列表技能执行到一半卡死依赖的系统服务未启动按日志提示定位到具体外部依赖逐个排查一个很重要的经验每装完一个技能就立刻重启OpenClaw再测试。批量装十几个技能后如果出了错日志多到你根本分不清是谁的问题那时候才叫欲哭无泪。4.4 技能冲突和性能损耗不夸张但真实存在很多人以为技能是互不干扰的实际上它们之间会通过Python依赖环境互相踩脚。一个技能要求requests2.31另一个技能强制要requests2.32pip在装第二个的时候会把第一个的版本悄悄升级然后第一个技能可能就出现诡异的调用异常。这类问题排查起来很耗时间。经验做法是给所有技能集中跑一个虚拟环境不要单独给每个技能建环境维护成本太高。同时对技能内的依赖声明保持警惕装新技能前看一眼它依赖了哪些核心库如果和你常用的版本差距大就要想清楚值不值得装。还有一个容易忽略的资源问题每个技能长时间驻留会占用内存。我跑了一周后看监控发现30多个技能积攒了近2G内存占用。后来在配置里把不常用的技能设成超时自动卸载内存立刻降下来一大截。5. 排错方法论日志、复现、速查表5.1 排错第一原则所有报错都从日志开始很多新手一碰到报错就把整个屏幕截图发群里问“怎么办”。我可以直接告诉你没有日志谁也帮不了你。OpenClaw把运行日志写在~/.openclaw/logs/目录下报错时第一件事是打开服务端日志看最后一次报错的时间点附近发生了什么。日志分析要分三层看模型层、调度层、技能层。模型层报错通常是连接失败、输出格式不合规调度层报错一般是任务规划或技能选择出现问题技能层报错就是技能本身执行失败。分清层次之后解决方向就清晰了。你甚至可以写一个简单的错误分类脚本把日志里出现的错误关键词做统计看看自己的环境里最频繁挂掉的是哪一层。5.2 高频报错速查表复制粘贴就能用报错信息原因处理方式CUDA out of memory模型太大或上下文太长换小模型、降低context_window、开启量化Connection refusedOllama服务未启动先执行ollama serve再检查curl http://127.0.0.1:11434yaml.parser.ParserError配置文件缩进错误重新检查YAML缩进禁止用TabAddress already in use: 5100端口被占用换端口或找到占用进程并结束JSONDecodeError模型返回非JSON调低temperature换更强模型AuthenticationErrorAPI key无效云端API检查key本地服务填dummy_key即可ModuleNotFoundError: openclaw虚拟环境未激活确认终端里已执行虚拟环境激活命令5.3 三个真实排错案例复盘第一个案例是“卡加载转圈”。现象是控制台页面出来了但发消息后一直转圈没有任何反应。排查过程先看日志发现OpenClaw没有报错但和Ollama的连接一直处于等待状态。再检查Ollama发现它压根没启动——因为上次关机后没有自启。解决方式是写一个开机启动脚本先检测11434端口通了再拉起OpenClaw从根上解决了这个问题。第二个案例是“技能全部超时”。现象是首次调用浏览器自动化技能时所有相关技能全部timeout。日志里显示playwright在下载浏览器内核但下载过程没有进度提示最后被超时机制切断。解决方式是手动执行一次playwright install chromium把浏览器内核提前装好再把技能的初始化超时从默认的60秒调大到100秒。第三个案例是“模型能聊天但工具调用全失败”。这个问题最隐蔽因为OpenClaw表面上没报错技能也没问题但模型就是不给调度层返回标准的工具调用指令。最后定位到两个原因一是模型本身不支持function calling二是我测试时把temperature调到了0.8模型输出JSON的格式稳定性崩了。换成支持工具调用的模型并降低温度后问题彻底解决。5.4 性能与资源控制别让机器被悄悄拖垮部署成功只是一半后半程是让它在有限硬件里长期稳定运行。我建议做好四件事第一模型优先选Q4_K_M量化版本这是一个在效果和显存占用之间非常甜的点位。第二给OpenClaw的并发任务数设置上限max_concurrent_tasks设成2到3就够了不要让它无限制并发否则小水管内存会瞬间爆炸。第三配置日志按天轮转这句话听着朴素但日志文件在持续运行时膨胀速度惊人我见过有人一周没管日志占了十几个G。第四显存小于16G就不要同时加载多个模型OpenClaw支持多模型配置但那是给大显存玩家准备的。6. 部署后的维护与安全建议6.1 本地部署也不等于绝对安全很多人一听“本地部署”就觉得万事大吉其实不然。技能系统里有一部分能力是执行Shell命令、读写文件、访问网络如果装了来源不明的技能它完全可以在你不知情的情况下读取私人文件或向外部发送数据。我自己的做法是默认关闭技能包中的网络访问权限用哪个技能、访问哪个域名单独在配置里放行。这样虽然每次新技能第一次跑网络请求时要多一个授权步骤但换来了整体可控性值。另外定期检查一下技能目录看有没有非自己安装的奇怪技能混进来。6.2 技能权限分级最小权限原则这里分享一个我实践下来很有效的权限分级方案。把所有技能按风险分三档安全技能文本处理、数据格式化可以直接自动运行普通技能浏览器自动化、文件读取需要配置确认后运行高危技能Shell命令执行、任意文件删除、网络请求必须手动输入确认指令才允许执行。这个分级听起来麻烦但正是这一步避免了我多次误触危险操作。6.3 更新与备份少踩兼容性的雷OpenClaw主程序更新比较频繁我的经验是大版本发布后等至少一周再升级让社区先把新版本的坑踩完。技能更新同理升级前看一眼技能的更新记录如果改动很大先备份旧版本。备份整机不现实但至少把~/.openclaw目录定期打包是必须的这里包括了你的配置、技能和个人数据一个tar包就能让你从灾难中恢复。最后说点个人体会。OpenClaw这类项目本质上是在把“模型能力”和“自动化能力”焊到一起本地部署的门槛不在命令本身而在排错。我踩过最狠的一个坑是Windows杀毒软件把虚拟环境里的python.exe当成威胁隔离导致整个环境一夜之间崩溃所有依赖全部失效。自那以后我装好OpenClaw第一时间就把项目目录加入杀毒信任区。另一个经验是先跑通最简单的链路再逐步加技能别一上来就装十几个那样只会让你连报错出自谁都分不清楚。如果你照着这篇一步步走还卡住大概率只是配置里一个字段写错了把日志发出来按行号去查基本都能解决。