把 OpenClaw 跑在 Windows 本地这件事我在一台几乎没装过任何开发环境的普通电脑上完整走了一遍。从空荡荡的目录到它能听懂指令、自动整理文件、按我的要求调接口拿数据前前后后折腾了一整天踩的坑比装过的软件还多。这篇文章就是那份保姆级过程的文字版每一步我都会告诉你“为什么要这么做”和“怎么确认自己有没有做对”不说那些让人看完更懵的术语只讲能直接照抄的操作。文章适合两类人一类是刚接触本地部署、对终端还有恐惧感的新手另一类是用过网上各类AI助手、想把核心数据留在本地、自己把控整个流程的进阶用户。下面内容全部依据 OpenClaw 在 Windows 原生环境下的安装体验写成你不需要一开始就懂架构跟着走完一遍自然就通了。1. 先把部署思路捋清楚OpenClaw 在 Windows 上靠哪几块拼图跑起来我见过不少人一上来就急着下载、安装、报错然后卡在一个压根看不懂的提示上。OpenClaw 本质是一套把大模型对话能力、任务编排、工具调用整合到一起的框架你可以把它理解为一个“调度中枢”。它自己并不内置推理能力真正干活的是背后接的大模型服务它也不负责所有外部操作很多功能依赖你给它配置好的插件和技能脚本。所以本地部署 OpenClaw至少需要四块拼图主程序框架OpenClaw 的核心代码和依赖库负责接收指令、编排任务、调用工具、输出结果。语言模型“大脑”通过接口接入的大模型服务可以是付费的云服务也可以是本地推理服务。没有这个OpenClaw 就像没有脑子的躯壳。工具与技能OpenClaw 能执行的具体动作比如读取文件、请求网页、发送通知。这部分需要额外配置或编写。运行环境包括 Python 运行时、Git、系统终端、必要的网络环境。Windows 下还需要处理权限、路径、防火墙等系统级问题。第一遍安装时我更推荐直接用 Python 原生进程跑而不是一上来就套 Docker。原因很实际原生方式看得见每个报错日志清晰改配置立即生效适合理解整个框架的工作逻辑。Docker 方式当然有隔离、清理方便这些优点但对刚接触的人来说多了一层容器概念出了问题反而不容易定位。对比维度原生进程方式Docker 容器方式安装复杂度低跟踪 Python 包即可中需要额外理解镜像、容器、挂载排错直观程度高终端直接看日志低要进容器或看容器日志依赖隔离靠虚拟环境天然隔离资源占用相对较少有额外开销但整体可控适合场景新手学习、日常调试、快速改技能长期稳定运行、多服务并行、快速搬迁我的建议是你打算认真用起来、还要自己写技能那就原生装一次你只是想先跑个 Demo 看效果Docker 反而更省事。这篇教程按原生方式展开后面维护部分会顺带讲容器方式怎么选。2. 环境准备阶段三样东西不备齐后面每一步都别扭在敲任何“安装 OpenClaw”的命令之前先检查这三样东西Python、Git、模型服务凭据。缺了任何一样你都会在某个莫名其妙的地方卡住而且报错信息往往看不出真正原因。2.1 Python 运行时版本选得太新或太旧都会吃苦头OpenClaw 这类依赖较多的框架Python 版本直接决定了你后面能否顺利装完依赖。以我实际操作的经验建议装 Python 3.11 或 3.12不要追最新的大版本也不要停留在老版本上。原因是一些底层依赖库对新版 Python 的适配有滞后太旧的版本则可能缺失部分语法支持。安装步骤其实简单去 Python 官网下载对应版本的 Windows 安装包运行后务必勾选Add Python to PATH这一步不勾后面终端里输python大概率会提示找不到命令。装完之后打开 PowerShell 输入python --version看到类似Python 3.12.x的输出就说明成功了。如果系统里还装了别的 Python 发行版建议在命令里用py -3.12 --version指定版本避免混用。2.2 Git 与终端环境超六成报错其实从这里开始OpenClaw 主程序通常通过 Git 仓库或 Python 包分发无论哪种方式Git 都是推荐先装的工具。Git 安装包一路默认即可装完后同样需要验证git --version另一个 Windows 特有的拦路虎是 PowerShell 执行策略。很多同学的终端一运行脚本就报错“无法加载文件因为在此系统上禁止运行脚本”这就是执行策略的限制。解决方法是在 PowerShell 里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这条命令的作用是允许本地脚本运行同时仍拦截未签名的远程脚本。如果家里终端还是 Windows 自带的老式控制台我强烈建议换成 Windows Terminal显示中文不会乱码支持多标签后面看启动日志舒服太多。2.3 模型服务凭据OpenClaw 的“大脑”需要一把钥匙刚开始部署时最容易犯的认知错误是以为 OpenClaw 装完就能上网回答问题。它只是个框架真正给你生成回复、理解意图的是后台的大模型服务。所以你得提前准备好一个可用的模型服务接口地址和一个 API Key。选择什么服务完全看你自己的情况预算充足、要效果好的可以用成熟的云端接口想完全离线、数据不出本机的也可以部署本地推理服务。无论选哪种只要服务能提供一个“API 地址 密钥”就能对接。申请密钥通常在你的服务商控制台里完成创建令牌之后复制保存这部分注意几点密钥只保存在本机环境变量或配置文件中不要直接贴到博客、聊天工具或仓库里。建议通过环境变量读取而不是硬编码到配置文件这样即使配置文件被同步到网盘也不至于连带密钥泄露。先确认这个服务支持怎样的请求格式OpenClaw 多数版本兼容业界通用的接口格式保守起见以官方文档为准。设置 Windows 环境变量可以这样操作# 临时设置只对当前终端窗口生效 $env:LLM_API_KEY 你的密钥 # 永久写入用户环境变量 setx LLM_API_KEY 你的密钥注意setx写完后新开的终端才会读到当前窗口最好用上面的$env:方式再设一次。3. 安装 OpenClaw 主程序从拉代码到看到初始化成功环境就绪后就可以开始正式安装。这一章节我按“建目录—拉代码—装依赖—初始化—自检”的顺序来讲你照着做基本不会出大岔子。3.1 建议单独建一个目录别到处乱放很多初次接触的人喜欢把项目随便放在下载目录或桌面后面找配置文件、清理依赖时会手忙脚乱。我习惯在某个稳定的位置建一个专用目录比如D:\Apps\OpenClawmkdir D:\Apps\OpenClaw cd D:\Apps\OpenClaw然后拉取主程序代码。OpenClaw 的具体仓库地址请以官网或 README 为准流程都一样。如果主程序是纯 Python 包也可以直接安装发行包这里我按“源码方式”演示因为对后续写自定义技能更友好。git clone https://你的仓库地址/openclaw.git cd openclaw拉代码这一步如果卡住半天没反应大概率是网络问题。多试几次或者换一个网络环境不要反复中断重试容易留下残缺目录。3.2 用虚拟环境隔离依赖给你的系统环境留一条后路我强烈建议在项目根目录里创建虚拟环境而不是直接把依赖装进全局 Python。虚拟环境相当于给 OpenClaw 单独划了一个“小房间”里面的包版本不会干扰你其他 Python 项目哪天不想要了直接删文件夹干净利落。python -m venv .venv .venv\Scripts\activate注意 Windows 下激活脚本是在.venv\Scripts\activate不是很多人习惯性敲的.venv/bin/activate。激活成功后命令行提示符前面会出现(.venv)这时候你装任何包都只会进这个虚拟环境。接着升级包管理工具再安装依赖python -m pip install --upgrade pip pip install -r requirements.txt如果 OpenClaw 也支持直接作为 Python 包安装可以等价执行pip install openclaw。这一步是下载量最大、最容易超时的部分。安装过程中屏幕会滚动大量输出你只需要等到出现类似Successfully installed ... openclaw ...的字样就说明核心依赖装完了。中途如果报红色错误不用急着慌把错误信息里“最后一行”复制出来搜索通常能直接找到答案。3.3 初始化配置与自检验证你的安装没有装了个寂寞依赖装完后进入配置阶段。先看帮助信息确认当前版本的命令命名openclaw --help一般框架都会提供初始化指令常见的叫init或setup。执行初始化命令让它自动生成默认配置openclaw init初始化会创建数据目录和配置文件。在实际运行过的 Windows 系统上配置和数据通常会放在类似C:\Users\你的用户名\.openclaw\的目录下如果你自己指定了OPENCLAW_HOME环境变量则以那个路径为准。目录下会看到一个config.yaml或config.json之类的文件这就是你以后做各种调整的主战场。初始化完成后再运行一次自检openclaw doctor如果版本命令不一致也可以直接查看配置文件是否存在来间接验证。自检会列出环境是否满足、依赖是否齐全、网络访问是否正常等信息。看到所有项目都是绿色或 OK 状态就说明基础环境通过有黄色警告就先看是什么比如“未设置模型 API Key”这一类下一章节正好会处理。4. 接上“大脑”模型配置与第一次对话主程序装好只算完成了 50%剩下 50% 是让 OpenClaw 能真正理解和回答你的话。这一步的核心在配置文件里搞懂几个字段后面大概率不会再被绕晕。4.1 配置文件里的模型参数到底怎么填打开刚才找到的config.yaml里面的模型相关配置通常长这样字段名可能有所差异但思路是通用的model: provider: your_provider_name # 你的服务商标识按服务文档说明填 name: your-model-id # 具体的模型标识 base_url: https://your-model-service.example.com/v1 api_key_env: LLM_API_KEY # 从哪个环境变量读取密钥 temperature: 0.7 max_tokens: 2048逐一解释一下provider不是随便填的它对应你使用的服务接口类型。多数服务商会提供兼容通用的接口格式具体取值要看你那个服务商文档里的说明。name你要调用的模型标识比如服务商后台能查到的那个 ID。base_urlAPI 服务地址通常类似https://服务地址/v1本地推理服务则是http://127.0.0.1:端口/v1。api_key_env告诉 OpenClaw 去哪读密钥这里填环境变量名不是密钥本身好处是不用明文写在配置里。temperature和max_tokens控制回答的随机性和最大输出长度刚开始用默认值即可以后根据场景调整。我自己在最初配置时最喜欢犯的错误是base_url多加了或漏掉了末尾的/v1导致鉴权一直报错。建议先浏览器访问一下这个地址看有没有返回提示能访问再填进去。4.2 启动 OpenClaw看懂关键日志配置完成后回到项目目录启动openclaw run首次启动会有初始化模型连接的过程正常情况会在日志里看到连接成功、模型加载完成之类的内容。如果看到以下状况可以对照排查日志症状最常见原因处理方式401 / 403 / unauthorizedAPI Key 错误或已失效重新设置环境变量并确认没写错404 / model not found模型 ID 不正确在服务商后台核对模型标识超时 timeout网络不稳定或服务地址不通延长超时或换个时段再试上下文超长请求 token 超出模型限制减小max_tokens精简输入内容乱码 / 字符异常终端编码问题用 Windows Terminal执行chcp 65001切换 UTF-8 编码一切正常后就能在交互界面里尝试提问。第一次对话建议从简单的开始比如“请介绍一下你自己”或者“你现在能做什么”。不用期待它一次性回答得多惊艳关键是验证整条链路是通的你的问题被 OpenClaw 接住转发给模型得到回复再显示到屏幕上。等到对话能连续进行说明 OpenClaw 的“大脑”已经接好了。退出时按Ctrl C两次让它优雅关停避免进程残留。如果命令行卡住直接关闭终端窗口也能强制结束但要留意后台是不是还有残留的 Python 进程。5. 先别急着冲功能Windows 本地部署的高发问题一次说清模型接好以后很多人会立刻尝试复杂任务然后开始在各种奇怪的地方翻车。Windows 上跑服务有五个高频拦路点值得提前排查。5.1 端口被占用OpenClaw 起不来、日志提示端口绑定失败OpenClaw 有时会内置一个本地 web 入口或 API 服务默认监听某个端口。如果那个端口已经被其他程序占了启动就会失败。解决办法是先找到占用进程再决定是换端口还是清进程netstat -ano | findstr :端口号 tasklist | findstr 进程PID # 确认是无关进程后可以结束它 taskkill /PID 进程PID /F也可以在配置里直接把端口改成没人用的高位端口比如 17890 之类一劳永逸。5.2 杀毒软件和防火墙安装没问题联网却失败Windows 自带的防护和第三方安全软件可能把 OpenClaw 的进程或本地脚本当成可疑行为拦截。表现各有不同有的是启动时部分组件被隔离有的是第一次联网请求直接被静默拦截。建议在安装和调试阶段把项目目录和.openclaw数据目录加入安全软件的排除列表。Windows 防火墙如果弹出允许访问网络的提示记得勾选“专用网络”否则局域网内其他设备也可能无法访问你本地开的服务。5.3 长路径限制文件一多就报路径找不到Windows 默认对路径长度有限制而 OpenClaw 这类依赖较多的项目虚拟环境和缓存目录很容易产生超长路径。报错场景多为“系统找不到指定的路径”或“文件名太长”。可以通过注册表或组策略开启长路径支持在运行里输入gpedit.msc专业版以上或修改注册表把LongPathsEnabled置为 1然后重启系统。如果你用的是家庭版也可以直接把项目放在盘符根目录附近比如D:\claw缩短路径层级简单有效。5.4 中文乱码日志和回复全是方块这个几乎每个 Windows 用户都会遇到。原因是 OpenClaw 很多输出默认按 UTF-8 编码而老式终端默认代码页未必是 UTF-8。最省事的方案是换 Windows Terminal然后启动前执行chcp 65001或者在 Windows Terminal 设置里把默认代码页调成 UTF-8。改完之后看到的日志就不会再是天书了。5.5 依赖被系统版本污染运行报“找不到模块”如果你之前没有用虚拟环境而是直接把依赖装到了全局后面装了其他 Python 包就可能把某个依赖版本顶掉导致 OpenClaw 运行时报ModuleNotFoundError。这也是为什么我前面反复强调用.venv。如果已经踩了坑最稳的办法是删除.venv目录重建一个重新执行一次依赖安装半小时内能恢复。遇到任何诡异问题第一习惯应该是去看logs目录下的日志文件而不是只看屏幕那几行。日志里有完整调用栈定位问题快得多。6. 让它真正帮你干活一个可复制的自定义技能配置实例OpenClaw 最值得花时间的部分不是聊天而是让它按照你的规则去执行任务。它提供了一个“技能”机制你可以编写脚本再告诉 OpenClaw 什么情况下调用它。下面我用一个实际例子演示完整流程。6.1 需求场景与脚本编写假设我希望 OpenClaw 能读取指定目录下的文件清单并生成一个 Markdown 索引方便我把某个项目里几十份文档汇总起来。我先在 OpenClaw 能识别到的技能目录里新建一个脚本文件比如叫list_files.py内容如下import os import sys from datetime import datetime def main(folder_path): if not os.path.isdir(folder_path): return 指定的路径不存在 lines [] now datetime.now().strftime(%Y-%m-%d %H:%M) lines.append(f# 目录索引 - {folder_path}) lines.append(f生成时间{now}) lines.append() for root, dirs, files in os.walk(folder_path): for file in files: full_path os.path.join(root, file) try: size os.path.getsize(full_path) lines.append(f- {os.path.relpath(full_path, folder_path)}{size} 字节) except Exception as e: lines.append(f- {full_path}无法读取{e}) return \n.join(lines) if __name__ __main__: if len(sys.argv) 1: print(main(sys.argv[1])) else: print(main(.))这个脚本本身不复杂它的意义在于让 OpenClaw 能够把“帮我把这个目录整理成索引”这样的自然语言指令转化成一个具体的脚本调用动作。6.2 让 OpenClaw 认识这个技能脚本放到技能目录后还需要在配置里声明技能名称、描述、入口命令一般格式大致如下skills: list_files: description: 读取指定目录下的所有文件生成 Markdown 格式的索引清单 command: python scripts/list_files.py \{folder_path}\ parameters: folder_path: type: string required: true description: 要读取的文件夹绝对路径配置里最关键的是descriptionOpenClaw 会通过它来判断用户意图是否应该匹配到该技能。描述写得越清楚匹配越准。保存配置后重启 OpenClaw然后在对话里输入帮我把 D:\Work\随笔 这个目录下的所有文件整理成一份 Markdown 索引正常情况下OpenClaw 会识别出技能、执行脚本、把返回值整理后输出。如果它没有自动匹配多试两种说法或者检查技能描述是否足够明确如果匹配了但执行报错看日志确认是不是路径和参数传递的问题。6.3 我在这个实验里学到的一件事技能机制看起来像普通的“定时脚本”但区别在于它有自然语言入口。你不需要记忆命令只要用正常语气描述需求OpenClaw 自动理解并拼接参数。这也意味着你写的脚本越“标准”接收参数、返回文本、有明确退路OpenClaw 用起来越顺手。我在实际调试中发现脚本里没有处理好路径中的空格会导致参数被拆成两截后来在配置里给参数加上引号才好。记住一点脚本永远要自己处理异常OpenClaw 的模型层不会替你的脚本兜底。7. 部署验收、日常维护以及几句实在话等 OpenClaw 能稳定对话、能调用你写的技能本地部署这条路就算走通了。但工具是要长期用的建议做一次完整验收顺带规划后面的维护节奏。我先列一个验收清单你可以逐项打勾重启电脑后能正常启动 OpenClaw不需要重装任何依赖。模型 API Key 不依赖当前终端会话新终端里也能自动读取。自定义技能在重启后仍然有效日志无报错。Windows 防火墙不再频繁拦截安全软件未隔离关键文件。配置文件和技能目录已纳入你的备份计划。知道怎么更新 OpenClaw 和对应的依赖包。关于日常维护有几点经验可以参考定期备份配置目录尤其是config.yaml和你写的技能脚本。配置文件里不要存明文密钥密钥靠环境变量恢复即可。更新前先看更新日志不要盲目升到最新版。对于刚跑稳定的本地服务我的习惯是“小版本随缘大版本先备份”。日志文件会随使用逐渐变大可以使用日志轮转工具或者定期手动清理logs目录里超过一周的文件。如果你部署的是 Docker 版本升级时通常要重新拉镜像再重建容器记得把配置和数据目录通过挂载方式放在容器外才不会升级一次丢一次配置。卸载清理时除了程序目录还要检查C:\Users\你的用户名\.openclaw这样的隐藏数据目录一并删除才干净。说到底OpenClaw 这类框架的价值取决于你怎么用。它不是一个聊天网页更像一个你可以不断往里加“手和脚”的私人管家。本地部署的优势不仅是数据可控更是你可以随时拆开看它每一步到底发生了什么、在哪一步出错、能不能修这种掌控感是用在线产品完全体会不到的。最后再分享一个小技巧保持 OpenClaw 常驻运行后给它配一个每天定时执行的小技能比如汇总当日新增文件、整理工作目录让它每天至少帮你完成一件琐碎事。跑通第一个真正有生产力的技能后你会发现自己开始主动给这个“管家”添置越来越多的工具那时候这趟本地部署就算真正值回票价了。