如果你跟我一样平时主力系统是 Windows但又想跑一个开源的 AI 助理框架那 OpenClaw 绝对值得花一个下午折腾一下。OpenClaw 是一个把大模型能力变成“随时可调用的个人 Agent”的开源项目它可以通过各种 Skill 插件完成信息检索、日程管理、消息处理这类任务也能接入本地 Ollama、DeepSeek、OpenAI 兼容接口等不同模型来源。这篇指南就是我在 Windows 上从零部署 OpenClaw 的完整记录包括环境准备、Docker/源码两种安装方式、模型配置、Skill 启用和常见的坑适合想在 Windows 下试玩或正式使用 OpenClaw 的朋友直接照着操作。很多人一看到“Windows 部署”就觉得是恶魔难度其实 OpenClaw 本身不挑系统难的是 Windows 的 Docker 环境、Git 仓库路径、脚本权限这些细节。只要把前置条件理清楚后面基本就是一路回车的事。我会把每一步“为什么要这么做”也讲明白避免你抄完命令后还是一头雾水。1. 部署前先把 OpenClaw 的运行逻辑搞清楚1.1 OpenClaw 到底是什么它跑起来需要哪些组件OpenClaw 本质上是一个“个人 AI 助理网关”。你可以把它理解成一台小交换机左边接各种模型服务右边接各种 Skill 插件和消息渠道。它不是一个大而全的聊天页面而是一个可编程的 Agent 运行框架。你告诉它“去查一下某个 API 的数据整理成日报发给我”它就能按工作流执行而不是只做一轮问答。从部署角度看OpenClaw 跑起来至少需要下面几个东西一个能长期运行的后端服务通常是容器或 Python 进程配置管理模块用于指定模型供应商、API Key、基础地址、端口等Skill 插件目录每个 Skill 其实就是一组指令和脚本告诉 OpenClaw “遇到什么任务调用什么工具”消息渠道适配层比如终端、Web UI、IM 机器人等。第一个容易踩坑的点就在这里很多 Windows 用户以为把 OpenClaw 下载下来双击就能跑但它的安装脚本和 Docker 编排默认是为 Linux/macOS 设计的。在 Windows 上我们要么用 Docker Desktop 模拟出一个 Linux 环境要么用 Git Bash 把安装脚本“哄骗”过去。理解了这一点后面就不会被各种报错吓到。1.2 为什么 Windows 上部署容易“翻车”我见过太多人在 Windows 上部署类似项目时卡住原因无非这几类一是路径分隔符问题。Windows 用反斜杠Linux 用正斜杠OpenClaw 的配置文件和 Skill 里的脚本经常要写相对路径混用就报错。二是脚本执行环境问题。官方安装脚本一般假设你是 bashWindows 自带的 CMD 和 PowerShell 对某些语法支持不好。最稳的办法是先装 Git for Windows用 Git Bash 来执行。三是 Docker 后端差异。OpenClaw 官方 Docker 编排在 Linux 上很顺Windows 上如果不用 WSL2 后端容器网络、文件挂载性能都很拉胯甚至启动后访问不到服务。四是网络和源的问题。Python 依赖、npm 包、容器镜像都可能在 Windows 上下载超时。这个后面我会给对应方案。所以我给你的第一条建议是不要试图在 Windows 上“裸跑”要么老老实实装 Docker Desktop WSL2要么用 Git Bash 跑官方源码安装脚本。两种方式我都会写你选一条走通就行。1.3 两种部署方式怎么选Docker 还是一键脚本OpenClaw 常见部署方式有两种热词里提到的“可通过安装脚本指定 git 安装方式从 GitHub 的 main 分支检出源码进行”就是第二种。如果你是初学者或者不打算深入改代码优先选 Docker 方式。它把所有依赖打包进容器卸载干净、升级方便也不会污染系统 Python 环境。如果你要二次开发、想体验最新 main 分支功能或者 Docker 在机器上实在跑不起来那就在 Git Bash 里运行官方安装脚本并用--git参数指定从 GitHub 的 main 分支拉源码。这个方式更接近 Linux 上的部署流程但需要你自己准备 Python 3.10 和 pip。我在实际测试中两种都试过。Docker 方式胜在省心源码方式胜在可控。后面章节先讲环境准备因为不管哪条路WSL2、Git 和模型接入都是绕不开的。2. Windows 环境准备装好这几样基本成功一半2.1 开启 WSL2 并设置默认版本WSL2 是 Windows 下跑 Linux 容器的地基。Docker Desktop 的 WSL2 后端比传统 Hyper-V 更轻量也更好用。开启方法很简单以管理员身份打开 PowerShell 或 CMD执行wsl --install这个命令会默认安装 WSL2 和一个 Ubuntu 发行版。装完重启之后再用管理员 PowerShell 确认一下wsl --set-default-version 2 wsl -l -v看到 Ubuntu 的 VERSION 列是 2 就说明成功了。如果显示版本是 1需要手动转换wsl --set-version Ubuntu 2这里有个细节如果你的电脑没有开启“适用于 Linux 的 Windows 子系统”这个 Windows 功能wsl --install会先帮你开启并重启。还有一种情况是公司电脑被组策略限制wsl --install一直失败那就要去“控制面板 - 启用或关闭 Windows 功能”里手动勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”再装 WSL2 内核更新包。2.2 安装 Docker Desktop 并切换 WSL2 后端WSL2 就绪后下载 Docker Desktop 安装包。现在 Docker Desktop 对 Windows 用户比较友好安装时直接勾选“Use WSL 2 instead of Hyper-V”。如果没有勾选也可以在安装完成后去 Settings - General 里切换。安装完成后先确认 Docker 服务能正常启动。在 PowerShell 里执行docker --version docker compose version如果提示找不到命令多半是 Docker Desktop 没有真正启动或者 PATH 没刷新重新打开终端即可。接下来还需要设置 Docker 的资源限制。OpenClaw 是带若干 Skill 插件的 Agent 服务内存占用不低建议在 Docker Desktop Settings - Resources 里把内存至少调到 4GBCPU 按需分配。不然容器启动后很容易被系统 OOM 杀掉表现就是日志突然中断或服务反复重启。2.3 安装 Git 和 Windows TerminalGit for Windows 在 OpenClaw 的源码安装中几乎是刚需。它不仅提供 Git 命令还带了 Git Bash这是我们在 Windows 上跑官方安装脚本的关键工具。安装命令很简单用 winget 一行搞定winget install --id Git.Git -e --source winget装完后开始菜单里会出现“Git Bash”和“Git CMD”。我们后续跑源码安装脚本都建议在 Git Bash 里执行避免 PowerShell 的字符编码和语法兼容问题。Windows Terminal 不是必需品但我还是建议装一个。它同时支持 PowerShell、CMD、Git Bash还能设置独立的配置文件和好看的主题。安装同样用 wingetwinget install --id Microsoft.WindowsTerminal -e --source winget这个工具解决的是“多窗口来回切”的痛点。你在 Git Bash 里跑安装脚本在 PowerShell 里查 Docker 日志在浏览器里看 OpenClaw 管理界面三个窗口用 Tab 管理反而比来回点更快。2.4 准备模型接入本地 Ollama/DeepSeek 或 API KeyOpenClaw 自己不带模型它需要通过模型供应商接入。我建议第一次部署用本地模型这样不会因为 API 额度问题卡住。本地模型最推荐 Ollama。下载 Ollama Windows 版并安装后在 PowerShell 里拉取一个适合 Agent 场景的模型比如 DeepSeek 系列的小参数版本ollama pull deepseek-r1:7b拉完之后用下面的命令验证服务是否正常ollama serve curl http://localhost:11434/api/tags如果看到模型列表说明本地模型服务已经 OK。OpenClaw 里配置 Ollama 时基础地址填http://host.docker.internal:11434。注意如果 OpenClaw 跑在 Docker 容器里不能直接写localhost容器里的 localhost 不是宿主机这又是一个经典坑。如果你打算用 DeepSeek API 或其他兼容 OpenAI 接口的服务那就准备好 API Key 和基础地址。这些信息在 OpenClaw 配置文件里通过环境变量或 config 文件注入下一章我会给具体示例。3. OpenClaw 部署实操两条路线任选3.1 Docker 方式部署最省心的完整流程打开 PowerShell把 OpenClaw 的源码克隆到本地。这里用官方仓库地址如果你因为网络原因克隆慢可以先拉镜像再同步源码但项目本体一定要完整git clone https://github.com/openclaw/openclaw.git D:\openclaw cd D:\openclaw克隆完成后找到.env.example文件复制一份为.envCopy-Item .env.example .env在.env里重点配置这几个变量OPENCLAW_BASE_URLhttp://localhost:7000 OPENCLAW_MODEL_PROVIDERollama OPENCLAW_MODEL_NAMEdeepseek-r1:7b OPENCLAW_OLLAMA_BASE_URLhttp://host.docker.internal:11434如果用的是 DeepSeek API则配置类似这样OPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_NAMEdeepseek-chat OPENCLAW_OPENAI_BASE_URLhttps://api.deepseek.com/v1 OPENCLAW_OPENAI_API_KEY你的Key配置完成后直接执行docker compose up -d第一次启动会拉取 OpenClaw 镜像和依赖镜像耗时比较长耐心等待。启动完成后查看日志docker compose logs -f看到类似OpenClaw started的日志就说明成功。这时候浏览器访问http://localhost:7000就可以看到 OpenClaw 的 Web 界面。Docker 方式最大的好处是升级方便。后面想升级版本直接docker compose down docker compose pull docker compose up -d不需要关心本机 Python 版本、依赖冲突只要 Docker 在服务就在。3.2 源码方式部署用安装脚本指定 Git 安装并检出 main 分支如果你不想依赖 Docker或者想直接改代码那这条路线更适合你。它对应的就是热词里提到的“通过安装脚本指定 git 安装方式从 GitHub 的 main 分支检出源码”。首先确保已安装 Git for Windows并在开始菜单打开 Git Bash。然后进入你准备放项目的目录cd /d/openclaw执行官方安装脚本关键参数是--git和--branch main意思是让脚本通过 Git 从远程仓库的 main 分支检出源码而不是下载 release 压缩包bash install.sh --git --branch main这里提醒一下官方安装脚本可能会检查系统依赖比如 Python 版本、pip、Node.js 等。如果提示某个依赖缺失先按提示安装再重跑。不要跳过否则后面跑起来各种不正常。脚本执行完毕后会在当前目录生成一个 OpenClaw 的运行目录。进入该目录创建配置文件cp config.example.yaml config.yaml编辑config.yaml核心部分如下server: host: 0.0.0.0 port: 7000 model: provider: ollama name: deepseek-r1:7b base_url: http://localhost:11434 api_key: skills: enabled: true directory: ./skills源码方式下OpenClaw 是直接跑在 Windows 上的所以模型地址用http://localhost:11434没问题。启动方式通常是bash start.sh如果项目提供了 Python 入口也可以手动启动python main.py看到监听0.0.0.0:7000的日志后浏览器访问 Web 界面即可。源码方式的优势是调试方便。你可以直接改 Skill 脚本加断点重启进程就能生效不用重新构建镜像。缺点是需要自己维护 Python 环境和依赖。如果 Python 版本不对或者 pip 下载依赖超时就得多花点时间。3.3 配置模型接入与 Skill 的正确姿势很多人在配置模型时会把所有参数堆在启动命令里这样又乱又容易出错。正确做法是统一写在config.yaml或.env里。OpenClaw 支持环境变量覆盖也支持配置文件直接读取。我习惯把模型分成两类配置本地模型这一类核心是providerollama并且要确认模型名写完整。ollama list里显示什么名字就填什么名字别自己改花名。如果 OpenClaw 容器里访问不到宿主机 Ollama优先检查base_url是不是用了host.docker.internal以及 Ollama 是否监听了0.0.0.0。远程 API 这一类核心是provideropenai兼容协议然后配置base_url、api_key、model_name。有些服务商虽然写着 OpenAI 兼容但模型名和接口路径有差异配置前先看官方文档。Skill 插件的启用方式取决于版本。早期版本是在配置文件里手动声明 Skill 路径新版本通常有内置的 Skill 管理命令。比如查看可用 Skillopenclaw skill list安装某个 Skillopenclaw skill install 技能名称这里提醒你Skill 不是越多越好。每个 Skill 都会占用上下文窗口和处理时间装太多反而让 OpenClaw 变“笨”。建议先装两三个核心 Skill跑通流程后再逐步加。比如先装一个定时任务类再装一个网页检索类够日常使用了。4. 启动验证与日常使用4.1 确认服务健康状态不管用 Docker 还是源码方式启动后第一步不是急着聊天而是确认服务健康。我先看日志有没有报错再用浏览器访问默认地址。如果你改了端口记得去配置里查一下。默认情况下 OpenClaw 监听7000浏览器打开http://localhost:7000应该能看到登录页或控制台。如果页面打不开先确认端口没被占用netstat -ano | findstr :7000如果端口被其他程序占用可以换一个端口比如7100同时把配置里的端口改掉。注意容器方式还要同步修改 Docker 的端口映射。健康检查还可以用 API 方式OpenClaw 一般会暴露一个健康检查端点。做一个最基础的 API 调用能确认模型链路是通的。假设模型名是deepseek-r1:7b我可以这样请求curl http://localhost:7000/v1/chat/completions \ -H Content-Type: application/json \ -d {\model\: \deepseek-r1:7b\, \messages\: [{\role\: \user\, \content\: \你好\}]}如果返回正常的 JSON 应答说明模型接入没问题。如果返回 401 或 404先查 API Key 和路径是不是和当前版本一致不要盲目重装。4.2 通过 Web 控制台快速上手Web 控制台是 OpenClaw 最重要的交互入口。第一次进入后你需要确认当前绑定的是哪个模型、哪些 Skill 已被加载。我建议先做几组简单测试问一个常识性问题确认基础对话链路正常创建一个“定时任务”类 Skill让它每天固定时间输出一句话确认 Skill 调度正常连接一个外部 API比如天气查询确认工具调用正常。这三组测试分别对应模型、Skill、外部接口三个层面。哪个环节出问题日志里会有明显提示。比如模型超时可以看时间戳Skill 加载失败会打印模块名外部 API 出错会返回状态码。4.3 安装 Skill 插件从安装到调试Skill 是 OpenClaw 的精华也是大家最容易误解的地方。它不是一个简单的“功能开关”更像是一个带提示词和脚本的“工具包”。比如你装了一个“日报生成”Skill它会告诉模型“每天下午 6 点读取某个数据源生成 Markdown 日报”然后模型在需要时调用对应的 Python 脚本去取数据。安装 Skill 的路径有两种。第一种是通过管理命令openclaw skill install skill-name第二种是手动放到skills目录。只要目录结构符合 OpenClaw 的规范重启服务后就能识别。我建议新手用命令安装等熟悉了目录结构再手动折腾。实际调试 Skill 时最容易遇到的问题不是脚本报错而是模型没有按 Skill 的“指引”行动。这时候要去看 Skill 文件里的提示词描述是否清晰比如“当用户提到天气时调用 get_weather 工具”这种明确描述比“处理天气类请求”更容易被模型理解。4.4 消息渠道接入要注意哪些事OpenClaw 可以接入 IM 渠道比如微信、Telegram、飞书等。这部分功能很香但也是问题最多的地方。以微信这类国内 IM 为例接入时要注意频率限制和会话残留问题。有些第三方接入方式会被平台风控表现是消息发不出去或触发了安全验证。我的建议是先不要一次性开所有自动回复功能把频率调低做好 Session 过期清理。如果出现“会话残留”现象比如同一个回复发了两遍多半是消息回调没有正确标记为已读需要清理本地的会话缓存并重启渠道适配服务。接入这类渠道前一定要先看官方文档确认项目支持你使用的接入方式不要轻信非官方插件。因为 IM 平台接口经常变非官方插件更容易失效也存在隐私风险。5. 常见问题与排查实录5.1 WSL2 安装失败或提示“请启用虚拟机平台”这个问题十有八九是 BIOS 里的虚拟化没开。去 BIOS 设置里找到 Intel VT-x 或 AMD SVM确认开启。Windows 功能里的“虚拟机平台”也要勾选。如果已经开启但还是失败用管理员 PowerShell 执行bcdedit /set hypervisorlaunchtype auto重启后再试。另外部分精简版系统缺少 WSL2 内核需要去微软官方下载“WSL2 Linux 内核更新包”并安装。5.2 Docker 容器启动后访问不到服务先确认容器是否在运行docker ps如果容器状态是 Exited看日志docker logs openclaw常见原因有三个一是端口映射没写对二是模型地址配置成了 localhost三是内存不足导致容器被杀。尤其是内存不足Windows 宿主机如果本身只有 8GB 内存Docker Desktop 默认分配 2GB 很容易触发 OOM。去 Docker Desktop 的设置里把内存调大至少给 4GB。5.3 源码安装时 Python 依赖下载超时源码方式部署时pip 下载慢是老问题。你可以把 pip 镜像源换到国内比如清华源或阿里源。在 Git Bash 里执行pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple如果某个包编译报错先更新 pip 和 setuptoolspip install --upgrade pip setuptools wheel大部分编译错误都是因为缺少 Visual C Build Tools。装一下“Microsoft C Build Tools”再重装依赖。5.4 端口被占用或反复重启端口被占用是最常有的事。先查端口netstat -ano | findstr :7000然后根据 PID 结束进程taskkill /PID 进程号 /F如果是 Docker 方式检查 docker-compose.yml 里的 ports 映射。比如你希望外部访问用 8080容器内部还是 7000可以写成8080:7000。另外容器反复重启不要急着删镜像先看日志。日志里出现address already in use就查端口出现OOMKilled就调内存出现Config Error就检查配置文件。问题定位越准解决越快。5.5 接入 IM 渠道后触发风控或会话残留这个问题我专门提一下因为热词里也出现了“微信插件触发了服务端风控或会话残留”这个场景。如果你遇到类似情况先别慌。第一降低消息发送频率。把自动回复改成人工确认模式或者加一条随机延时避免短时间大量发送。第二清理会话残留。IM 接入有时会因为回调超时导致会话状态没更新。重启 OpenClaw 后先看本地的 session 缓存目录把对应平台的会话文件删除重新登录。第三检查是否触发了平台风控。如果提示异常登录或操作频繁说明你的接入方式或频率不符合平台规则。这时候停止自动回复等一段时间再恢复不要反复尝试。这类渠道接入一定要合规使用低于阈值频率、不群发、不用于骚扰场景才不容易出问题。5.6 如何升级 OpenClaw 版本很多人在旧版本上遇到 bug 后习惯重新下载安装包。其实没必要升级是件很简单的事。Docker 方式docker compose down docker compose pull docker compose up -d源码方式cd D:\openclaw git pull origin main bash install.sh --git --branch main升级前最好备份两个东西配置文件和数据目录。数据目录里包含 Skill 缓存、会话记录如果不备份升级后可能出现“旧对话记录丢失”或“Skill 状态异常”。我一般是把整个 OpenClaw 项目目录压缩一份再执行升级出了问题也能秒回滚。写在最后几个真实体会我在 Windows 上第一次跑 OpenClaw 时花在环境上的时间远远多于项目本身。后来总结下来最值得记住的就三句话WSL2 是一切容器化部署的地基Git Bash 是跑源码安装脚本的救命稻草模型接入要优先确认地址和模型名。先把这三件事做对后面的路就顺了。如果你第一次启动失败别急着卸载重装。按日志去查配置和依赖90% 的问题都能用“看日志、查端口、调内存”三部曲解决。我个人现在是把 OpenClaw 放在 Docker 容器里长期运行配合本地 Ollama 和 DeepSeek 模型日常跑一些自动化和信息整理任务稳定性比我预想中好很多。最后分享一个小技巧在 Windows 上长期运行 OpenClaw建议写一个简单的启动脚本把docker compose up -d、健康检查、日志查看这些步骤串起来下次启动就不用一条条敲命令了。折腾完这一套你再去玩其他开源 Agent 项目会轻松很多因为底层思路都是相通的。