先说个真实体验网上 OpenClaw 的教程一抓一大把但十篇里有八篇默认你是 Linux 或 macOS 用户剩下两篇即便标题写着 Windows点进去也是让你装个 WSL 然后照着 Ubuntu 的流程跑。我自己第一次在 Windows 上加装 OpenClaw 时就因为这个半吊子教程的现状折腾了整整一个周末踩的坑比装的组件还多。所以这篇我就专门聊 Windows 下的 OpenClaw 安装与初始化把我实际验证过的步骤、踩过的坑、还有那些报错的真实含义都写清楚。如果你手里是台 Windows 电脑又想把这个开源自动代理框架跑起来这篇应该能帮你少走一大半弯路。1. 为什么单独写一篇 Windows 安装教程和 Linux 的差距在哪里1.1 OpenClaw 到底是什么一个被误读的开源自动代理框架先花点时间把概念对齐。很多人第一次听到 OpenClaw以为它是个聊天机器人客户端装上就能像网页版助手一样对话。这个理解基本是错的。OpenClaw 的定位更接近一个会自己动手干活的自动代理框架你可以给它配置不同的模型接入层包括本地部署的 ollama、挂载一堆可复用的技能包skill它再通过这些技能去操作文件、调用命令、访问网页接口、执行定时任务甚至可以配合 rosclaw 之类的扩展去对接 ROS2 仿真环境。真正让它和普通聊天工具有本质区别的是那套 skill 机制——相当于给代理装上了一双手而不只是给了一张嘴。所以你会发现围绕 OpenClaw 的搜索词里有大量和部署技能模型对接相关的组合比如ollama 部署 openclawopenclaw skillopenclaw windows companion 怎么配置。这说明大多数人已经意识到装 OpenClaw 只是第一步把它初始化成能干活的状态才是真正的重点。而这一步在 Windows 上偏偏最容易翻车。1.2 Windows 上安装的主要卡点虚拟环境、编译链与系统服务为什么 OpenClaw 官方和社区都更偏爱 Linux因为这套框架从设计之初就建立在 Unix 风格的环境假设上管理进程靠 systemd装依赖靠 apt跑脚本靠 bash日志往 /var/log 里写。Windows 没有这些东西于是每个环节都要额外做一次翻译。我实际安装下来Windows 的卡点主要集中在四个地方你提前知道心里就有底Python 环境混乱。Windows 上经常同时存在微软商店版 Python、官网安装版 Python、还有 Anaconda 的 Python三者互相抢占 PATH。OpenClaw 对 Python 版本有明确要求装错版本会出现各种莫名其妙的导入错误。C 编译链缺失。如果你选择源码编译安装Windows 上默认没有 make、gcc、cmake 这一套需要单独装 Visual Studio Build Tools而且版本选错照样编译失败。路径分隔符与中文目录。Windows 的\和空格路径会让很多配置文件里的路径解析出问题尤其是放在C:\Users\你的名字\这种带中文和空格的目录下坑一个接一个。守护进程与服务注册。OpenClaw 的常驻组件比如 Windows Companion在 Linux 下用 systemd 一条命令就能托管Windows 上你得手动注册成计划任务或 Windows 服务还要处理权限问题。正因为这些差异直接在 Windows 原生环境装和在 WSL2 里装完全是两条不同的路线。我自己最终是 Windows 原生环境为主、WSL2 为辅后面我会把两条线的取舍都讲清楚。2. 环境准备装 OpenClaw 之前先把这几件事做掉2.1 系统版本与账户权限先说最基础的。OpenClaw 在 Windows 上的表现和系统版本关系很大我自己测试过 Windows 10 22H2 和 Windows 11 23H2 之后的版本整体稳定。如果你的系统还停在 Windows 10 初版或者更老的版本建议先把系统更新做完再继续否则有些系统 API 调用会直接失败。账户权限这块我的建议是日常操作别用管理员账户跑但装依赖时要有管理员权限。Windows 的 UAC 机制会拦截很多后台进程的写文件操作OpenClaw 初始化时要往用户目录写入配置文件夹一般是~/.openclaw/权限不足会直接报写入失败。如果你看到类似 Permission denied 或 Access is denied 的报错先别急着怀疑代码检查一下你是不是在一个没有写权限的目录里操作。另外如果你同时装了 360、电脑管家之类的安全软件注意观察安装过程中有没有弹窗拦截。后面我专门有一节讲杀毒软件引发的诡异问题这里先提个醒装 OpenClaw 的时候把项目目录加进白名单能省很多事。2.2 开发工具链Git、Python、VS Code 与可选 Docker Desktop我建议按下面这张表准备环境每一样都有它存在的理由工具版本要求用途安装注意事项Git for Windows2.40 以上拉取源码、更新 skill 包安装时选 Git from the command line and also from 3rd-party softwarePython3.10 或 3.11运行 OpenClaw 主程序安装时务必勾选 Add python.exe to PATHVS Code最新版编辑配置、查看日志无特殊要求Visual Studio Build Tools选 C 桌面开发工作负载源码编译时用只选这条路线的才需要Docker Desktop最新稳定版走容器化部署路线需要 Windows 10/11 专业版开启 WSL2 或 Hyper-V装完第一件事是打开 PowerShell用命令验证环境不要等报错了再回头查git --version python --version py --list-paths这里我想特别强调 Python 版本的问题。OpenClaw 的依赖列表里有一些包对新旧版本很敏感Python 3.12 刚出来那会儿我试过某些二进制依赖还没有对应的 wheel 包pip 会现场编译然后报错。所以别追求最新版老实按官方要求装 3.10 或 3.11。检查完版本之后顺手把 pip 升级到最新python -m pip install --upgrade pip2.3 本地大模型引擎可选但推荐ollama 的安装与模型下载OpenClaw 本身不内置大模型它需要一个模型推理后端。你可以接云端 API也可以接本地部署的 ollama。我比较推荐先接 ollama原因就两条一是调试的时候不用花钱随便怎么折腾都不心疼二是数据不出本机配置错误最多是报错不存在把私人对话内容传到外部接口的问题。ollama 在 Windows 上的安装很友好官网下一个安装包双击装完就自带服务。装完打开一个新的 PowerShell验证一下ollama --version ollama listollama list这时候应该显示空列表因为还没下载任何模型。我个人建议从 qwen2.5:7b 起步这个模型对中英文的支持都不错而且原生支持工具调用function calling而工具调用能力恰恰是 OpenClaw 这类代理框架能不能正常工作的关键。下载命令ollama pull qwen2.5:7b这条命令会下载大概 4 到 5 个 GB 的模型文件取决于你的网速可能要等一阵。下载完成后再次ollama list能看到模型条目就说明后端准备就绪。注意ollama 的默认服务地址是http://127.0.0.1:11434后面配置 OpenClaw 时会用到这个地址。3. 正式安装两条路线与各自的取舍3.1 路线Apip 安装发布包推荐给绝大多数人如果只是想把 OpenClaw 用起来不做二次开发我强烈建议走这条路线省时省力。**第一步建虚拟环境。**这一步不是可选项是必选项。Windows 上全局装包的后果就是过两个月你根本不知道哪个包是哪个项目在用的冲突起来能让人崩溃。在你想放项目的目录里执行mkdir D:\openclaw cd D:\openclaw py -3.11 -m venv .venv**第二步激活虚拟环境。**注意 PowerShell 里激活脚本路径是.venv\Scripts\Activate.ps1不是 Linux 那种.venv/bin/activate.\.venv\Scripts\Activate.ps1如果提示无法加载脚本说明 PowerShell 执行策略默认禁止运行脚本先放开当前用户权限Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser激活成功后命令行前面会出现(.venv)前缀一眼就能确认。**第三步安装 OpenClaw。**如果你是全局用 pip 装直接执行pip install openclaw如果你是从 GitHub 发布页下载了预构建的安装包就按官方说明执行安装。我在虚拟环境里用的命令是pip install openclaw装完顺手把常用的依赖也补齐。这一步容易漏——很多教程默认你装的是完整包但如果你下载的是精简版可能连openclaw命令行工具都没有。装完后先别急着启动验证一下版本openclaw --version如果提示openclaw 不是内部或外部命令说明脚本目录没进 PATH。虚拟环境的话检查.venv\Scripts\里有没有openclaw.exe有的话手动把路径加进 PATH或者直接用.\.venv\Scripts\openclaw.exe --version。3.2 路线B源码编译安装适合二次开发如果你计划改 OpenClaw 源码或者想装最新的开发分支功能就得走源码编译。这条路在 Windows 上麻烦指数直接翻倍但搞完之后你对整个项目的掌控感是完全不一样的。先用 Git 把仓库克隆下来git clone https://github.com/你的目标仓库地址/openclaw.git cd openclaw克隆完先看子模块。很多开源项目把核心组件放在 submodule 里漏了这步会导致编译时文件缺失git submodule update --init --recursive接下来建虚拟环境并安装开发模式py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt pip install -e .如果是含 Rust 扩展的版本还需要先装 Rust 工具链——去官网下载 rustup-init.exe安装时选默认配置就行。装完验证rustc --version cargo --version然后按项目文档执行编译。这一步通常很慢十几分钟到半小时都是正常的不要看到终端半天没输出就以为卡死了实际是在编译依赖。源码路线最大的坑是依赖版本冲突。Windows 上如果之前装过别的机器学习库requirements.txt里的某个包可能和现有的 numpy、torch 版本打架。真遇到这种情况我建议直接在虚拟环境里从零装不要图省事复用全局 site-packages。3.3 安装后的验证版本号、目录结构与自检命令装完先别急着配置运行一次自检命令确认核心组件都在。不同版本的自检命令可能不太一样常见的是openclaw doctor这个命令会检查 Python 版本、关键依赖、网络连通性、模型后端可达性等输出一串 OK 或 FAIL。看到 FAIL 不用慌后面我会讲怎么逐项排查。另一个快速验证方式是直接问一句openclaw ask 你好简要介绍一下你自己如果走了 ollama 路线而 ollama 服务没启动这一步会报连接错误。所以顺序很重要先确保ollama serve在运行Windows 安装版一般会自动作为后台服务跑着再调 OpenClaw。4. 首次初始化配置文件、工作目录与 Skill 技能体系4.1 初始化命令与生成目录结构安装完成后OpenClaw 还不能直接用它需要先初始化一个工作目录。初始化命令一般是这样openclaw init执行到这个环节它会在你的用户目录下生成~/.openclaw/文件夹整体结构类似这样~/.openclaw/ ├── config.yaml ├── credentials.yaml ├── skills/ │ └── example_skill/ │ ├── skill.yaml │ └── run.py ├── profiles/ ├── storage/ └── logs/第一次看到这个结构你可能以为 config.yaml 就是全部其实 credentials.yaml 同样重要——它专门存各种密钥令牌和主配置分离是为了方便你备份和分享配置时不泄露敏感信息。storage 目录才是 OpenClaw 真正干活的记忆仓库它会往这里写入会话状态、缓存数据、任务记录。logs 就不用说了排错全靠它。4.2 核心配置文件逐项拆解打开 config.yaml默认内容通常是一堆注释加上少量配置项。我捡几个关键的逐项说这些是初始化阶段一定会碰到的model: provider: ollama base_url: http://127.0.0.1:11434/v1 model: qwen2.5:7b storage: type: local path: ~/.openclaw/storage skills: path: ~/.openclaw/skills auto_load: true companion: enabled: false auto_start: false log: level: info path: ~/.openclaw/logsmodel.provider模型提供方。填ollama表示接本地模型填openai之类的表示接云端兼容接口。model.base_urlOpenClaw 走的是 OpenAI 兼容协议所以 ollama 的地址后面要带/v1少这个后缀很多版本直接连不上。storage.type和path本地存储的会话数据放哪。skills.path技能包目录。auto_load: true表示启动时自动加载里面所有技能。companion.enabledWindows Companion 组件的总开关。默认 false我们后面单独配。log.level日志级别。调试阶段建议改成debug跑稳定了再改回info。改完配置文件建议先验证一下语法和路径解析有没有问题openclaw config check这个命令会帮你检查 YAML 格式和路径是否存在。如果路径写错报错会告诉你哪一行有问题非常好用。4.3 配置 Skill让 OpenClaw 学会你的工作流Skill 是 OpenClaw 最核心的扩展机制你可以把它理解成技能插件每个技能是一个文件夹描述一件事怎么做代理在对话中发现需要这个技能时就会加载并执行。我拿一个最朴素的例子说明。假设你要让 OpenClaw 帮你自动整理下载文件夹里的文件可以创建一个技能~/.openclaw/skills/file_organizer/ ├── skill.yaml └── run.pyskill.yaml 描述技能的元信息和触发条件内容大概长这样name: file_organizer description: 按扩展名整理指定目录下的文件 triggers: - 整理文件 - 归类下载run.py 则是实际执行逻辑这里示意一个最小结构import shutil from pathlib import Path def run(directory: str) - str: 将 directory 目录下的文件按扩展名移动到子目录。 base Path(directory) if not base.exists(): return f目录不存在: {directory} for file in base.iterdir(): if file.is_file(): ext file.suffix.lstrip(.).lower() or no_ext ext_dir base / ext ext_dir.mkdir(exist_okTrue) shutil.move(str(file), str(ext_dir / file.name)) return f整理完成请查看目录: {base}写完后运行openclaw skill list如果能看到file_organizer说明技能已经被代理识别。这时你问帮我整理一下 D:\downloads代理就会自动匹配这个技能并执行。我在这个环节的实操经验是别一上来就写复杂技能先从读文件内容发一条通知这种小功能练手摸清技能和代理之间的数据传递规则再去写多步骤工作流。Windows 上的中文路径在技能里尤其小心Python 的 Path 对象对中文兼容还不错但用字符串拼接路径时经常翻车。5. 对接本地模型ollama 部署 OpenClaw 的完整配置5.1 为什么要优先选本地模型我知道有人一上来就想接付费的云端大模型 API觉得效果更好。但我的建议是初学阶段一定要优先用本地模型。理由不光是省钱更重要的是调试体验。OpenClaw 这类代理框架的报错信息经常很含糊一个问题可能是模型响应格式不对也可能是网络超时还可能是本地代码 bug。如果你接的是云端 API每次调试都带着网络延迟和费用焦虑心态很容易崩。本地模型把网络这个变量几乎降为零出问题就用 Wireshark 看本地回环流量或者直接看 ollama 的日志排查链很干净。5.2 Ollama 配置项与验证过程回到 config.yaml 的 model 配置段按照前面说的填好这三个关键项model: provider: ollama base_url: http://127.0.0.1:11434/v1 model: qwen2.5:7b配置完先确认 ollama 服务真的在跑。在浏览器或 PowerShell 里访问一下Invoke-RestMethod -Uri http://127.0.0.1:11434/api/tags -Method Get如果能返回一个包含 models 列表的 JSON说明服务正常。如果报连接失败就去启动 ollama 服务——Windows 上通常在系统托盘有 ollama 图标右键确认它是运行状态。确认服务没问题后再跑一次 OpenClaw 的对话验证openclaw ask 你好请用一句话介绍你自己正常情况下你应该能在几秒内看到模型的回复。如果这里超时或报错优先检查两件事一是 config.yaml 里 base_url 的末尾到底有没有/v1二是 ollama 拉取的模型名是不是和 config 里完全一致。模型名经常有人填错qwen2.5:7b写成qwen2.5-7b就对接不上。5.3 切换模型时的注意点用一段时间后你可能会想换更大的模型比如 qwen2.5:32b或者试试带 vision 的多模态模型。切换本身很简单ollama pull新模型改 config.yaml 里的 model 名重启 OpenClaw 就行。但有几个点必须注意。第一工具调用能力不是所有模型都有。OpenClaw 依赖模型输出特定格式的函数调用指令像 qwen2.5、llama3.1 这些专门优化过工具调用的模型没问题但某些早期模型或量化过度的小模型在这方面的能力很弱表现为代理听懂了但不动手。遇到这种情况先别怀疑配置换个主力模型试试。第二上下文长度和本地显存强相关。任务复杂度越高需要的上下文越长显存占用也越大。7B 模型在 8GB 显存的显卡上跑中等任务还行一旦任务涉及大量文件内容注入很容易触发显存溢出。我的建议是先在ollama run里实测模型能不能稳定处理你的典型任务再切到 OpenClaw 里投产。6. Windows Companion 配置后台服务与系统桥接6.1 Companion 是干什么的如果你只把 OpenClaw 当命令行问答工具上一步就够用了。但要想让它做更贴近自动代理的事——监听剪贴板、发送系统通知、定时触发任务、和本地文件交互——就需要 Windows Companion 这个组件。Companion 的本质是一个常驻后端进程负责把 OpenClaw 的指令翻译成 Windows 系统调用。它解决的问题很现实主程序如果开着 GUI 终端关掉窗口代理就死了有了 Companion 常驻系统层代理的触发逻辑就可以脱离终端独立运行类似 Linux 上的 systemd 服务。6.2 注册成 Windows 服务并设置开机自启Companion 的安装命令因版本而异常见的做法是openclaw companion install这条命令通常会帮你创建 Windows 服务或计划任务。如果命令不支持自动注册服务就手动用 Windows 的服务管理工具注册。先确认服务名sc query openclaw-companion如果返回服务不存在可以用New-Service注册指向openclaw.exe的服务。注册完在配置里打开开关companion: enabled: true auto_start: true然后启动服务Start-Service openclaw-companion启动后查看服务状态确认不是 Pending 或 Stopped 状态。这里有个 Windows 特有的坑服务属于 Session 0不能直接访问当前用户的桌面环境所以如果 Companion 要读剪贴板或弹通知可能需要以交互式服务方式运行或者在计划任务里勾选只在用户登录时运行。我在测试时发现计划任务的登录时触发模式比服务模式更稳因为它跑在用户会话里。追求稳定的朋友可以直接用任务计划程序手动建一个登录时启动 openclaw companion的计划任务。6.3 非提升终端启动守护进程的报错处理我在搜索热词里看到一条很典型的报错error: start the windows daemon from a non-elevated terminal; shared clients。这条报错虽然不是 OpenClaw 独有的但 Windows 用户很容易撞上而且很容易误以为是自己 OpenClaw 配错了。真实原因是某些带守护进程的组件比如 Docker Engine 的 CLI在管理员权限终端里启动时反而会因为共享客户端的模式限制而失败。它背后涉及的 Windows 机制是用户账户控制UAC提升权限的进程和普通权限进程在命名管道、进程通信上存在会话隔离守护进程为了能被普通权限的客户端访问反而要求你在非提升的终端里启动。所以解决办法恰恰是反直觉的——关掉管理员终端改用普通 PowerShell 启动。启动完成后再用管理员终端执行需要提权的管理操作两者分开。这个原则对 OpenClaw Companion 同样适用你安装服务时需要管理员权限但日常启动调试一定用普通终端。7. Windows 踩坑实录高频错误的完整排查链路7.1 杀毒软件静默拦截与长路径策略我在实际安装中遇到的第一个大坑是 Windows Defender 的静默拦截。表现很诡异启动 OpenClaw 时没有任何报错但过几秒进程就消失了日志文件夹里只有启动瞬间的写入记录。排查链是这样的先看进程是否存在Get-Process -Name openclaw发现刚启动就被杀掉于是查 Windows 事件日志里的程序兼容性目录Get-WinEvent -LogName Application -MaxEvents 50 | Where-Object { $_.Message -match openclaw }果然事件里有一条Windows Defender 已阻止运行的记录。原因是 OpenClaw 的技能运行时动态生成 Python 脚本这种程序启动后自己写脚本再执行的行为很容易被安全软件标记为可疑。解决方案不是关掉 Defender而是把~/.openclaw/目录和项目目录加进 Defender 的排除列表Add-MpPreference -ExclusionPath $env:USERPROFILE\.openclaw另一个容易被忽略的是 Windows 的文件名和路径长度限制。OpenClaw 的依赖安装时会生成很深的目录结构如果路径总长度超过 260 字符npm 或者 pip 的解压步骤就会报错。Git 在克隆源码时先把这个限制放开git config --global core.longpaths true并且把 Windows 的注册表项 LongPathsEnabled 改成 1改完重启生效。这个坑在你用中文用户名、目录嵌套又深的情况下特别容易触发。7.2 常见报错速查表下面这张表是我根据自己的踩坑经历和社区常见问题整理的高频报错按症状→原因→解法的顺序写收藏起来能省不少时间症状根因解法openclaw 不是内部或外部命令脚本目录未加入 PATH检查虚拟环境.venv\Scripts\手动加 PATH 或使用完整路径执行ModuleNotFoundError: No module named openclaw未在虚拟环境中安装或没激活虚拟环境确认终端前缀有(.venv)重新执行pip install openclaw连接 ollama 超时ollama 服务未启动或 base_url 写错访问http://127.0.0.1:11434/api/tags验证服务检查地址末尾是否为/v1start the windows daemon from a non-elevated terminal在管理员终端启动守护进程导致共享客户端受限改用普通 PowerShell 启动管理操作用另一个提权终端进程启动后自动消失安全软件静默拦截或端口被占用查事件日志加 Defender 排除目录用netstat -ano查端口占用Path too long或文件名超长Windows 260 字符路径限制开启 longpathsgit config --global core.longpaths true改注册表并重启中文路径加载技能失败编码问题或路径解析分隔符不兼容技能内统一用pathlib.Path()处理路径不要用字符串拼接7.3 日志这么查才对日志级别与关键信息定位排查到最后一切问题都要回到日志。Windows 上 OpenClaw 的日志默认在~/.openclaw/logs/按日期生成文件。调试阶段建议把 log level 从 info 改成 debuglog: level: debug改完重启然后复现一次问题再看日志文件。定位问题有个小技巧不要从头读日志直接搜关键词。搜error或failed定位第一个报错点。搜ollama或model确认模型调用是否成功。搜skill确认技能加载和触发链路是否正常。有一次我的代理在调用技能时反复失败从日志里看错误信息只有一行Permission denied但根本不知道是哪个文件没权限。后来把技能脚本里加了详细日志打印每一步操作的目录和文件名才发现是技能尝试往C:\Program Files写配置文件被系统保护拦住了。这个经验说明OpenClaw 的日志反映的是框架层面的运行状态你自己的技能逻辑有问题的话最好在技能代码里自己打日志双管齐下排查才快。另外备份配置的习惯值得养成。每次初始化完、调通一个技能就把~/.openclaw/下的 config.yaml 和 credentials.yaml 备份一份。我一般是复制到项目目录下带日期后缀规则很简单config-20240101.yaml。这样哪次改坏了配置一条命令就能回滚不用重新初始化整个环境。最后再分享一个小技巧如果你和我一样电脑上同时装了 Docker Desktop 和 ollama注意这两个服务的默认端口不冲突Docker 是 2375/2376ollama 是 11434但它们都依赖后台守护进程。Windows 上跑 OpenClaw 时尽量把非必要的守护进程关掉只留当前要用的能明显减少那种莫名其妙连接被拒的概率。我自己在 Windows 上把 OpenClaw 从装不上到跑通完整技能流程前前后后折腾了三天现在回头看绝大多数时间其实是花在了环境和权限的磨合上真正框架本身的问题反而很少。把这套流程理顺之后不管是继续研究 skill、对接 ollama 换模型还是把整套东西部署到别的 Windows 机器上都是一马平川的事。