鲸游上个月我把一台吃灰的 Windows 笔记本翻出来，打算在上面跑一个能接入微信和飞书的 AI 助手。起初图省事，用了社区里的一键安装包，装是装上了，可每次 OpenClaw 官方更新，我都得重新解压、覆盖文件、再改一遍配置，偶尔还会遇到旧配置直接读不了的情况。后来换成 Git 源码方式安装 OpenClaw，从 git clone 开始把整个环境搭起来，才发现日常升级变成了 git pull 加两条命令的事，配置文件也再没丢过。这篇文章就是这次在 Windows 上完整踩坑的记录，适合想在 Windows 下用源码方式安装 OpenClaw，并且希望后续能平滑升级的朋友。
1. 为什么我最后还是选了 Git 源码安装而不是一键脚本
1.1 一键脚本的便利与隐患
一键脚本确实香，尤其是对刚接触 OpenClaw 的人来说，下载一个压缩包或者执行一行命令，几分钟就能看到一个可以对话的界面。我一开始也这么做，毕竟省去了配环境的时间，还能避免很多低级错误。
但用着用着问题就出来了。第一个问题是版本不可控。一键脚本通常会在某个版本节点打包，不会跟着上游实时更新。OpenClaw 这类迭代很快的项目，可能隔几天就会修掉一个连接 IM 时的诡异 bug，而你拿到的脚本包还停在两周前。第二个问题是升级容易丢配置。脚本包的目录结构和官方仓库的 layout 不一定完全一致，官方更新了 .env 的字段名，脚本包可能还是旧结构，升级时要么手动合并，要么干脆不能直接覆盖，非常折腾。
还有个隐藏的问题：一键脚本为了兼容更多机器，往往把依赖装得很宽泛，比如 Python 包不做精确锁定，导致你本地的环境和别人不一样，出了问题很难复现。对于想长期用、想自己改点代码的人，这绝对是硬伤。
1.2 Git 源码方式的核心优势：可控、可追溯、升级简单
用 Git 源码方式安装，本质上就是把官方仓库原封不动拉到本地，然后用项目的启动脚本跑起来。它的好处可以列得很直白：
- 版本完全可控：你可以通过
git tag、git branch或git log看到每次改动，想回到旧版本随时切。 - 升级就是一次合并：本地代码基于官方仓库，升级时
git pull拉取最新代码，冲突一般只出现在你改过代码的情况下，如果只是配置使用，基本无冲突。 - 便于定位问题：项目代码在本地，遇到报错可以直接看源码，排查问题的时候不用对着一个黑盒猜。
- 和官方文档零偏差：OpenClaw 官方文档里的路径、命令、配置示例，默认就是基于仓库源码结构，你照着做就行，不用再做路径映射。
对于经常需要接入不同模型、不同 IM 平台的人来说，源码方式的灵活性是脚本包给不了的。比如 OpenClaw 的模型配置，源码目录下的 .env.sample 就是最权威的模板，官方更新后，你 git pull 就能看到新字段，比任何二手教程都及时。
1.3 源码安装并不适合所有人的情况
不过话说回来，源码安装并不适合所有人。如果你只是临时跑一下体验，不打算长期维护，那直接下一键脚本或 Docker 镜像更省事。Git 源码方式要求你懂一点 Git 基础命令、会创建 Python 虚拟环境、知道怎么看报错日志，这些门槛会劝退一部分纯小白。
另外，源码方式在 Windows 上比在 Linux 上更容易遇到编码、路径、权限的坑，所以初学者如果不想折腾，我更推荐先用 Docker Desktop 跑官方镜像。但如果你想用 OpenClaw 持续接入自己的 IM 工作流，或者以后想改点逻辑，那源码方式绝对值得你花一下午搭起来。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 开工之前：Windows 环境里最容易被忽略的三件事
2.1 Git 的安装姿势与 PATH 问题
Windows 下安装 Git 看似简单，但很多人装完发现命令用不了，大概率是安装时没勾选 PATH 选项。官方安装包在安装过程中会问你要不要调整 PATH，建议选 "Git from the command line and also from 3rd-party software"，这样不仅 Git Bash 能用，PowerShell 和 CMD 里也能直接敲 git。
装好后打开 PowerShell 输入 git --version，能看到版本号就说明没问题。看不到的话，手动把 C:\Program Files\Git\cmd 加到系统环境变量 PATH 里，重启终端。
一个容易忽略的点：Windows 的 Git 文件名大小写默认不敏感，但 OpenClaw 仓库里可能有用大小写区分文件的场景，这会导致某些依赖安装后无法导入。建议在仓库目录下额外执行：
bash复制git config core.ignorecase false
这个命令能避免以后因为文件大小写问题导致模块找不到。
2.2 Python 版本与虚拟环境：版本匹配是第一道坎
OpenClaw 的源码是基于 Python 3.10 以上开发的，推荐使用 3.10 或 3.11，3.12 也能用，但某些第三方依赖可能在新版本上还没适配好。Windows 的 Python 安装建议直接从官网下载安装包，安装时务必勾上 Add Python to PATH。
这里强烈推荐用虚拟环境，不要图省事直接全局 pip install。原因很简单：OpenClaw 的依赖版本和系统里其他项目的依赖版本可能会互相冲突。比如全局环境里已有的 pydantic 是 1.x，而 OpenClaw 需要 2.x，装完项目可能直接起不来。
bash复制cd 你的OpenClaw仓库目录
python -m venv venv
.\venv\Scripts\Activate.ps1
如果 PowerShell 执行 Activate.ps1 报错，提示脚本被禁止执行，先运行一次：
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
再激活。这个坑十个人有八个会踩。
2.3 中文路径、编码问题和可能的网络设置
OpenClaw 的源码和配置文件里包含大量 UTF-8 编码的文本。如果仓库放在带中文的路径下，比如 D:\我的项目\openclaw，很容易出现编码或路径解析问题。不是一定出问题，但出问题后很难排查，所以强烈建议把仓库目录放在纯英文路径下，比如 D:\dev\openclaw。
另外 Windows 的控制台默认不是 UTF-8，项目打印中文日志时很可能会乱码。可以在启动前先设置：
powershell复制chcp 65001
或者直接在 PowerShell 里用：
powershell复制[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
这样能避免大部分乱码问题。
还有一点要提的是网络环境。Git clone 官方仓库、pip 安装依赖可能比较慢，这不是 OpenClaw 的问题，是网络链路问题。解决方式是在 pip 里临时换用国内镜像源，比如清华源：
bash复制pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
记住，这个操作只是加快下载速度，不会改变依赖内容，你可以放心用。
2.4 先弄清楚：WSL 和 Docker 是不是更适合你
在 Windows 下跑这类服务，其实还有两条路：WSL（Windows Subsystem for Linux）和 Docker。如果是抱着学习源码的态度，我不建议你一开始就上 Docker，因为 Docker 把环境都封装好了，你根本看不到依赖细节。但如果你只是想要一个稳定的运行环境，Docker 反而是更好的选择。
WSL 的好处是直接在 Windows 里跑一套 Ubuntu，很多在 Windows 上痛苦的依赖编译问题在 Linux 下都不是问题，OpenClaw 在 Linux 上的体验比 Windows 原生好很多。但缺点是你得额外维护一套子系统，内存占用也不小。Docker 则更轻量，官方有现成镜像，但你在 Windows 上挂载目录、暴露端口时可能会遇到权限和路径转换的问题。
我这次坚持用 Windows 原生 + Git 源码方式，是想顺便把项目代码研究透。如果你只是日常使用，我建议你评估一下 WSL 或 Docker 是不是更合适。这篇文章还是以 Windows 原生源码安装为主，下面的步骤都基于这种方式。
3. 从 git clone 到第一条回复：源码安装完整实操
3.1 克隆 OpenClaw 仓库
先在本地建一个工作目录，以 D:\dev 为例：
powershell复制cd D:\dev
git clone https://github.com/openclaw/openclaw.git
克隆完成后进入目录：
powershell复制cd openclaw
这里注意，项目名我以官方仓库为准，你自己克隆时用官方主页给你的地址。如果 GitHub 访问速度不行，可以用官方提供的镜像仓库地址，或者通过代理工具临时加速，但代理工具这边不做推荐，你根据自己的网络情况处理。
克隆完成后，先不要急着装依赖，先看下项目结构：
powershell复制ls
一般会看到 requirements.txt、openclaw 核心代码目录、control_ui 界面目录、docs 文档目录，以及 .env.sample 配置文件模板。先确认这些文件都在，再继续下一步。
3.2 创建虚拟环境并安装依赖
进入仓库目录后，按之前说的创建虚拟环境并激活：
powershell复制python -m venv venv
.\venv\Scripts\Activate.ps1
激活成功后，命令行前面会出现 (venv) 标识。接着升级 pip 基础包：
bash复制python -m pip install --upgrade pip
然后安装项目依赖。如果项目有 requirements.txt，直接执行：
bash复制pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
部分版本可能区分 requirements-dev.txt 和 requirements.txt，前者包含测试、lint 工具，后者是运行核心依赖。只跑服务的话装 requirements.txt 就够了。
依赖安装时间取决于网络，中间可能会看到一些源码编译的日志。如果遇到某个包编译失败，先不要慌，大概率是缺少 Windows C++ 构建工具。解决办法是安装 Microsoft C++ Build Tools，安装时把"使用 C++ 的桌面开发"工作负载勾上。
3.3 配置 .env：模型、密钥、通道
项目目录下一般会有 .env.sample，复制一份为 .env：
powershell复制copy .env.sample .env
然后编辑 .env 文件，核心要配置的有几块：
- 模型供应商和模型名称：OpenClaw 支持多家模型，比如 DeepSeek、OpenAI、本地模型等。如果你用的是 DeepSeek，模型名要写
deepseek-chat这种正式名称，不能直接写deepseek，否则后面会报 unknown model 错误。 - API Key：填入对应平台的 API Key，注意不要带空格和引号，换行可能会被误读。
- IM 平台接入：如果要接微信、飞书，这里要填入对应的 App ID、App Secret、Token 等。具体字段名以
.env.sample里的注释为准。 - Control UI：默认可以开启，方便在浏览器里操作。如果启动报错或你不需要界面，设成关闭。
配置完保存，用 UTF-8 编码保存，不要用记事本默认的 ANSI，否则读取时中文会乱码。推荐用 VS Code 或 Notepad++ 编辑。
3.4 启动服务与验证对话
首次启动前，最好先确认端口没有被占用。OpenClaw 一般默认跑在某个固定端口（以官方文档为准，可能是 8080 或 3000），如果启动时报端口占用，可以用下面的命令查看：
powershell复制netstat -ano | findstr "端口号"
找到占用进程后，在任务管理器里结束它，或者改配置文件里的端口。
启动命令一般在 README 里有说明，常见的是：
bash复制python -m openclaw
如果是带 Control UI 的版本，可能需要先启动界面服务：
bash复制python control_ui.py
我个人建议先不带模型直接启动一次，看日志是否能正常加载配置，再开始在界面里提问。启动输出里如果出现 Agent started 或 Listening on 0.0.0.0:xxxx，说明服务基本起来了。
然后打开浏览器访问 Control UI 地址，在对话框里发一条消息。如果模型配置正确，应该能看到回复。这一步如果报 unknown model、connection timeout 之类，就是模型配置或网络的问题，后面批排查部分会详细说。
3.5 让 Windows 下的启动更顺手：脚本和任务计划
每次都要手动激活虚拟环境再运行命令，确实很烦。我习惯在仓库目录下放一个 start.ps1 脚本：
powershell复制$env:PYTHONIOENCODING = "utf-8"
cd $PSScriptRoot
.\venv\Scripts\Activate.ps1
python -m openclaw
以后双击或右键运行这个脚本就行。如果你想开机自动启动，可以在 Windows 任务计划程序里添加一个任务，触发条件选"计算机启动时"，操作为启动这个脚本。但要注意，OpenClaw 依赖网络和模型 API，开机自动启动可能会因为网络未就绪而启动失败，建议设个延迟启动。
4. 升级这件事，git pull 只是开始
4.1 常规升级三步走：备份配置、拉取代码、更新依赖
源码方式升级最简单，但也没简单到一条 git pull 就完事。我总结了三步：
- 备份
.env和自己的修改。.env通常被.gitignore忽略，不会被 git 覆盖，但还是建议备份一份，防止手滑。 - 拉取最新代码：
bash复制git pull origin main
如果你的分支是 master，把 main 改成 master。拉取前最好先 git status 看下本地有没有冲突文件。
- 更新依赖。项目更新后，
requirements.txt里的包版本可能变了，必须重新执行：
bash复制pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
注意，这一步不要加 --upgrade 去把没有变动过的其他包也升一遍，只按 requirements 装就够了。因为 requirements.txt 里固定了版本范围，重新装能保证所有包都在项目要求的范围内。
4.2 依赖冲突是怎么发生的
很多人在升级后遇到服务起不来的情况，大多是依赖问题。比如本次更新把 httpx 从 0.24 升到 0.27，你本地的旧版 /venv 里还是 0.24，pip 在重新安装时可能会因为其他包对 httpx 的版本约束不一致，产生冲突。
这时候有两种操作：
- 如果你不关心本地环境，直接把虚拟环境删了重建，重新装一遍依赖，一劳永逸。命令如下：
bash复制deactivate
rm -rf venv
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
- 如果你想保留原环境，可以尝试：
bash复制pip install --upgrade -r requirements.txt
但这样可能把很多不必要升级的包也升了，反而引入新问题。所以我个人更倾向于删掉重建，反正核心代码在 git 仓库里，依赖重建成本不高。
还有一个容易忽略的点：升级后 .env 里可能有新增的配置项，如果你不补，服务可能不会启动，或者启动后某些功能异常。所以升级后一定要去 .env.sample 里看一眼有没有新字段，然后把需要的字段加到自己的 .env 中。
4.3 配置文件的兼容性检查
OpenClaw 版本更新后，配置项可能会改名或调整格式。比如旧版把 MODEL_NAME 叫 OPENCLAW_MODEL，新版改成了 MODEL_PROVIDER 加 MODEL_NAME 的组合。遇到这种情况，直接拉取代码后启动，大概率会报错。
我的做法是升级前先备份旧 .env，然后创建一个全新的 .env，对照 .env.sample 一项项配置。虽然麻烦一点，但能保证每个字段都符合最新定义。如果你之前的配置很复杂，涉及很多 IM 平台，就先用 diff 工具比较新旧 .env.sample：
powershell复制fc .env.sample .env.sample.bak
或者用 VS Code 的 Compare 功能，很快能看到变了哪些字段。
4.4 升级后必须做的自检清单
升级完别急着关终端，按这个清单快速自检一遍，能省掉很多事后排查：
| 检查项 | 操作 | 正常表现 |
|---|---|---|
| 依赖已更新 | pip list | grep -i 关键包 |
版本符合 requirements |
| 配置文件完整 | 启动日志无 missing config |
无报错 |
| 模型可以对话 | 在 Control UI 发一条测试消息 | 正常回复 |
| IM 通道在线 | 从微信/飞书发消息给机器人 | 能收到自动回复 |
| Control UI 可访问 | 打开浏览器访问本地地址 | 页面能打开 |
这套自检下来，基本覆盖日常影响最大的几个点。如果哪一步失败，就针对那一项看日志，而不是从头开始重装。
5. Windows 下常见报错的完整排查思路
5.1 控制台中文乱码
乱码是最常见也最烦人的问题。原因就是 Windows 控制台默认代码页是 GBK，而 Python 和 OpenClaw 输出的是 UTF-8。
解决办法有三个：
- 在启动命令前设置代码页：
chcp 65001 - 在 PowerShell 里设置输出编码：
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8 - 在 Python 脚本里设置环境变量：
$env:PYTHONIOENCODING = "utf-8"
我建议在启动脚本里把这几条全加上，确保任何时候日志都是可读的中文。如果改了之后还是乱码，检查你的编辑器和 .env 文件是不是以 UTF-8 编码保存的，尤其是 .env 里的中文注释或值。
5.2 pip 安装失败 / 超时
Windows 上装 Python 依赖最容易碰到两类问题：一是下载慢导致超时，二是某些包需要编译报错。对于超时，加长超时时间并换用镜像源：
bash复制pip install --timeout 120 -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
对于编译失败的包，比如 pydantic-core、numpy、tokenizers 这类带 Rust 或 C++ 扩展的包，推荐直接安装预编译的 .whl 文件。Windows 下安装最新版通常有官方 wheel，如果卡在编译，可以先升级 pip 缓存，再试一次。实在不行，就装 Microsoft C++ Build Tools，回头再 pip install。
5.3 Control UI did not start
这个报错在 Windows 上特别典型。我第一次遇到时一脸懵，后来发现是 Control UI 启动依赖 Node.js，而我没装。
解决办法：确认系统装了 Node.js 18 以上，然后看启动日志里有没有具体的错误提示，比如端口被占用、模块缺失。如果代码是用 Vite 构建的，首次启动可能要拉取 npm 依赖，网络不好时也会失败。此时需要进入 control_ui 目录，执行：
bash复制npm install
再回到项目根目录启动。
如果安装 npm 包太慢，可以临时用国内 npm 镜像，比如：
bash复制npm config set registry https://registry.npmmirror.com
装完再启动，基本能解决。
5.4 unknown model 与模型配置
OpenClaw 启动或对话时如果出现类似 unknown model: deepseek 的报错，十有八九是 .env 里的模型名写得不规范。现在的模型供应商一般有严格的名字格式，比如 DeepSeek 的合法名称是 deepseek-chat 或 deepseek-reasoner，你不能只写 deepseek。
这种问题的排查思路很简单：
- 打开模型供应商的文档，找到精确的模型字符串。
- 打开
.env，把模型名改成文档里的写法。 - 如果用的是本地模型（比如通过 Ollama 或 LocalAI），要确认模型服务已启动，并且
.env里的 base_url 指向正确的本地端口，比如http://localhost:11434。
还有一个坑是 .env 里配了多个模型，但启动参数里指定了另一个名字，两边不一致同样会报 unknown model。检查一下启动命令或 Control UI 里选的模型是不是 .env 里的同一个。
5.5 端口占用和 IM 接入问题
端口占用最烦的是开了微信/飞书回调时，系统防火墙会弹窗拦截。如果服务跑起来了但 IM 里收不到消息，先看防火墙是不是禁止了 Python 进程，或者 Windows 是否拦截了入站端口。在 PowerShell 里执行：
powershell复制netstat -ano | findstr "8080"
找到 PID 后，在任务管理器确认是什么进程占用的。如果确实被防火墙拦截，去"Windows 安全中心 -> 防火墙和网络保护 -> 允许应用通过防火墙"里把 Python 加进去。
IM 接入还有一个常见坑：微信或飞书的回调地址需要公网可达。如果你本地测试接不上，通常是回调地址没填对，或者运营商封锁了公网入站。这个要靠内网穿透工具解决，但穿透工具不在本篇讨论范围，建议参考官方文档的网络配置说明。
5.6 升级失败回滚的保命操作
升级后如果服务起不来，最保命的操作是 git revert。先看升级前的 commit 号：
bash复制git log --oneline -10
找到最近一个能正常运行的 commit，然后回滚代码：
bash复制git revert 一个commit号
注意 git revert 会生成一个新的 commit，不会删除本地修改历史，比较安全。如果你确定要硬回到某个版本，也可以用 git reset --hard 版本号，但会丢之后的所有提交，慎用。
回滚代码后，恢复升级前的 .env 备份，再重建虚拟环境装一次依赖，服务就能回到升级前的状态。等下次版本稳定了再重新升级。
6. 关于这套流程，我最后想说的话
如果你是一个长期用 OpenClaw 的人，Git 源码方式绝对值得从第一天就坚持。它在 Windows 下多花的那些配置时间，会在后续每一次升级中成倍省回来。我经历过几次大版本更新，每次都是先备份 .env，然后 git pull，再重新装依赖，整个过程十分钟左右，几乎没有因为升级断过服务。
最后再分享一个小技巧：升级前用 git stash 暂存你自己的代码改动，升级完再 git stash pop 恢复。这样即使你在源码里改过东西，也能和平升级共存，不至于升级时冲突到只能选择放弃本地的改动。Windows 下的大多数"升级后跑不起来"都不是代码本身的问题，而是环境和配置没有跟着版本走。只要把虚拟环境、配置文件、依赖这三个点控制好，源码方式真的可以做到稳定又省心。