OpenClaw Windows本地部署教程：从零到跑通第一个智能体任务

最近总有朋友来问我：“OpenClaw 在 Windows 上到底能不能跑？”能跑，但网上能找到的教程大多是 Linux 和 macOS 的，Windows 用户只能对着屏幕干瞪眼，或者折腾半天卡在各种奇怪报错上。

简单说，OpenClaw 是一个可以完全跑在本地电脑上的开源智能体框架：你给它一句自然语言任务，它能调用本地工具、访问文件、执行命令，把大模型的能力和真实操作串起来。数据和中间过程都留在这台机器上，不依赖特定云端服务。很多人选择 Windows 本地部署，图的就是数据可控、断网可用、方便调试。

这篇教程我会按“环境准备 → 获取项目 → 安装依赖 → 初始化配置 → 启动服务 → 跑通第一个任务 → 常见问题排错”的顺序写，尽量做到每一步都拆到最细，不省略任何跳步命令。不管你是第一次接触这类工具的新手，还是已经被各种报错折腾到怀疑人生的朋友，照着手册走，配合第 7 章的排错清单，基本都能把 OpenClaw 在 Windows 上跑起来。

1. 部署前想清楚：OpenClaw 解决什么问题，为什么要装在本机

1.1 一句话讲清 OpenClaw 的核心能力

OpenClaw 本质上是一个“能动手的助手框架”。传统脚本是“人把逻辑写死”，而 OpenClaw 是你告诉它目标，它在本地拆解任务、挑选可用工具、把结果汇总返回。比如你说“统计某个文本文件里出现次数最多的 10 个词”，它不会只是回复一段建议，而是会真的去读文件、数词频、给出结果。

这类框架的核心价值不在“聊天”，而在“行动”。它可以读取本地文件、调用命令行、访问本机服务，甚至把多个步骤串成一个自动化流程。我见过有人拿它做日志归档，有人拿它批量处理表格，有人把它接到内部测试环境做定时巡检。

1.2 为什么值得折腾 Windows 本地部署

很多人一看到“开源智能体框架”就默认它要在服务器上跑，其实完全可以在 Windows 桌面机上跑，而且有几个很实在的优势：

• 数据不出本机。文件内容、任务记录、工具调用日志都留在本地，处理敏感资料时不用提心吊胆。
• 离线可用。只要接的是本地模型，或者只在局域网内调用服务，断网环境也能正常工作。
• 调试方便。终端日志、配置文件、任务结果全在眼前，出了问题一眼就能看到原因。
• 没有按次计费的压力。配合本地模型使用，长期运行不需要为每次调用额外付费。

可能你会觉得“既然是智能体，接云端模型不是更强吗？”确实，云端模型在复杂推理上通常更聪明。但 OpenClaw 这套框架本身并不绑死模型，先本地跑通再说，后续想换更强的模型或服务商，改配置就行。

1.3 这篇教程适合谁

我会默认读者满足下面其中一种：

• 纯新手：没接触过命令行、没装过 Python，但不害怕跟着步骤复制粘贴命令。
• 职场自动化爱好者：想在 Windows 上做文件批处理、定时任务、日志汇总，不想为此专门学 Linux。
• 有一定开发基础的开发者：想快速评估 OpenClaw 的能力，先搭一个最小可用环境再二次开发。

文中的命令我会写出完整版本，包括回车前的所有字符。如果你完全不知道某些命令的含义，先照着做，后面我会解释这件事为什么这样做。

2. 环境准备：Windows 部署最容易翻车的一步

2.1 先把硬件配置对齐：别等启动的时候才傻眼

在开始下载任何东西之前，先看一眼自己的电脑配置。OpenClaw 本身对硬件要求不算高，真正的压力来自模型推理和依赖构建。下面的表是我实测下来的经验值，不是官方最低标准，但很有参考意义：

内存是最值得关注的。如果你打算用本地模型，8 GB 内存会很紧张，Windows 系统本身就占用不少内存，模型再吃几个 GB，容易触发进程被杀。如果只接云端模型 API，8 GB 也能跑，但建议还是 16 GB 起步，因为构建依赖、缓存、浏览器界面同时运行时，内存消耗比想象中快。

2.2 安装 Python：勾对一个选项，能少走两小时弯路

OpenClaw 是基于 Python 的工具，所以 Python 环境是第一关。去 Python 官方下载页面，选 Windows installer 版本。下载好后双击安装，注意安装界面最下面有一个勾选项：“Add python.exe to PATH”。这一步非常关键，一定要勾上。

解释一下 PATH 是什么。简单理解，PATH 是系统寻找程序的“通讯录”。你打开终端输入 python，系统会在 PATH 里列出的目录中查找 python.exe。如果安装时没把 Python 目录加进通讯录，终端会提示“python 不是内部或外部命令”，后面所有命令都执行不了。

安装完成后，需要验证一下。按 Win + R，输入 cmd，回车，在弹出的黑色窗口里输入：

bash复制python --version

如果输出类似 Python 3.11.9 这样的内容，说明 Python 装好了。再检查一下包管理工具：

bash复制pip --version

如果 python 有版本号但 pip 提示找不到，多半是安装时 Python 目录里的 Scripts 文件夹没进 PATH。我建议直接重新运行安装器，选择 Modify，然后在 Optional Features 里确保 pip 被勾选，再走一遍安装流程，比手动配 PATH 省心。

这里要特别提醒一点：如果你是从 Windows 应用商店里装的 Python，可能会遇到“输入 python 后自动打开商店跳转”的情况，这是系统应用执行别名在捣乱。解决办法是去“设置 → 应用 → 高级应用设置 → 应用执行别名”，把 python.exe 和 python3.exe 的别名选项关掉，或者干脆卸载商店版、改用官网安装包。

2.3 安装 Git：只需要点“下一步”的操作水平

OpenClaw 的项目代码需要通过 Git 来获取。Git 是一个版本管理工具，这里我们不必深入理解它的原理，只要会用一条 git clone 命令就够了。

去 Git 官网下载 Windows 版本，安装时一路点 Next，所有默认选项都别改。安装包比较大，耐心等它走完。完成后重新打开一个终端，输入：

bash复制git --version

出现版本号就说明安装成功。有的安装器会自动弹出命令行窗口，有的需要重启终端才能识别 git 命令，如果提示找不到，直接把终端关掉重开一次。

为什么不直接下载 ZIP 压缩包？因为 git clone 拉取的是完整项目仓库，之后想更新版本、切换分支都会方便很多。手动下载 zip 文件容易漏掉子模块，或者更新时只能重新下载整个压缩包，不推荐。

3. 获取 OpenClaw 项目并安装依赖：保姆级操作实录

3.1 项目放哪里：路径这件事千万别头铁

打开终端后，建议把项目放在一个固定目录。我个人推荐新建一个 C:\dev 目录。为什么要单独建目录？两个原因：一是避免中文路径，二是避免路径中的空格。

很多底层依赖库对中文路径和空格支持得不好，轻则编译报错，重则运行时找不到文件。你在“C:\Users\张三\桌面\新建文件夹”这种路径下装 OpenClaw，大概率会遇到奇怪的问题，到时候排查起来极难。

执行下面两条命令：

bash复制mkdir C:\dev
cd /d C:\dev

然后从 OpenClaw 官方仓库拉取项目代码。具体仓库地址以官方文档为准，通常是一条类似这样的命令：

bash复制git clone <OpenClaw官方仓库地址>

拉取完成后，进入项目目录：

bash复制cd openclaw

可以先用 dir 命令看一眼目录内容，正常会看到 README、requirements.txt、config 等文件。如果看到内容，说明项目代码已经完整下载。

3.2 创建虚拟环境：所有 Python 项目都该有的好习惯

依赖安装是新手最容易翻车的地方，而虚拟环境能解决大部分依赖冲突的问题。什么叫依赖冲突？举个例子，你的电脑里可能已经装了 A 工具，它需要某个库的 1.0 版本，而 OpenClaw 刚好需要同一个库的 2.0 版本。如果直接装，A 工具可能就废了。

虚拟环境相当于给 OpenClaw 单独隔出一个“小房间”，里面装什么库都不会影响房间外的其他程序。在项目根目录执行：

bash复制python -m venv venv

这条命令会在当前目录生成一个 venv 文件夹。接下来需要“进入小房间”，Windows 下的激活命令是：

bash复制venv\Scripts\activate

注意不是 venv/bin/activate，那是 Linux 的路径。Windows 的目录结构不一样，Scripts 文件夹里放着 activate 脚本。激活成功后，命令行的最前面会出现一个 (venv) 前缀，像这样：

text复制(venv) C:\dev\openclaw>

看到这个前缀，说明当前操作都在虚拟环境里进行，可以放心装依赖了。如果之后想退出虚拟环境，执行 deactivate 即可。

3.3 安装依赖：耐心一点，别频繁打断

依赖列表一般都在 requirements.txt 文件里。在项目根目录执行：

bash复制pip install -r requirements.txt

首次安装可能会比较慢，因为要下载并安装一堆依赖库。此时终端会滚动大量文字，看起来像刷屏，实际上是在正常工作。建议不要频繁按 Ctrl+C 中断，中断后可能会出现残留的不完整安装，反而更难处理。

如果下载过程中超时报错，网络波动是常见原因。可以重新执行同一命令，或者给 pip 加一个更长的超时时间：

bash复制pip install --timeout 600 -r requirements.txt

600 表示 600 秒，也就是单次请求最长等 10 分钟。这个参数能减少因为个别包下载慢导致的失败。

安装完成后，验证一下 OpenClaw 是否能正常导入：

bash复制pip show openclaw

能看到版本信息就说明安装基本成功。接着检查命令行工具：

bash复制openclaw --version

如果提示 openclaw 不是内部或外部命令，不要慌。这是因为虚拟环境里的 Scripts 目录暂未写入 PATH，你可以改用：

bash复制python -m openclaw --version

这种调用方式也能生效。后面我会提到，只要是运行 OpenClaw 相关命令，用 python -m 前缀几乎不会踩到 PATH 的坑。

4. 初始化配置：告诉 OpenClaw 你的模型地址和偏好

4.1 初始化一次，生成默认配置目录

依赖装好后，先做一次初始化。在项目根目录执行：

bash复制openclaw init

如果提示找不到命令，就用：

bash复制python -m openclaw init

初始化过程会在项目目录下生成必要的配置结构，常见的有 config.yaml 主配置、logs 日志目录、data 数据目录、plugins 插件目录。正式使用前，建议先不改任何内容，直接跑一次默认配置，确认服务能启动。把这一步放在前面，是为了把“环境问题”和“配置问题”分开排查——如果默认配置都启动不了，说明环境还有问题，先解决环境；如果默认配置能启动，之后你再慢慢改配置，出问题就知道是自己改错了。

4.2 模型接入：一条路是本地模型，一条路是云端 API

OpenClaw 本身不带模型，它需要连接一个模型服务才能理解和执行任务。接入方式主要有两种，根据你的情况选一种就行。

第一种，使用云端模型 API。这种方式效果通常更好，适合需要复杂推理能力的场景。需要在配置文件里填写服务地址、密钥、模型名称。配置格式大致像下面这样：

yaml复制model:
  provider: remote
  base_url: "https://example.com/v1"
  api_key: "sk-xxxxxxxx"
  model_name: "some-model"

这里只展示字段结构，真实地址、密钥以你实际开通的服务为准。填入 api_key 时要注意，这个值等同密码，别随意贴到公开平台或分享给他人。另外，使用云端 API 时，任务内容会发送到对应服务端处理，如果你处理的文件比较敏感，请先评估是否可接受；如果很敏感，更建议用本地模型方案。

第二种，使用本地模型。这种方式完全离线，数据不出本机。你需要先在本地装一个模型运行工具，把开源模型加载起来，然后在 OpenClaw 配置里把模型地址指向本机端口。比如本地模型服务跑在 11434 端口，配置大概是：

yaml复制model:
  provider: local
  base_url: "http://127.0.0.1:11434"
  model_name: "qwen2.5:7b"

本地模型建议选几 B 参数规模的版本，比如 7B、8B 这一档。参数太大，普通 Windows 电脑的内存和显存撑不住，跑一个任务要等很久，甚至会直接崩溃；参数太小，任务理解能力又不够。我自己的经验是，在 16 GB 内存的机器上，7B 规模模型是最平衡的选择。

4.3 其他可调参数：端口、日志级别与数据目录

配置文件里还有几个常用参数需要了解：

• port：服务监听端口，默认可能是 8080，如果和你本机其他软件冲突，改成 8081 或 9000 都可以。
• log_level：日志级别，平时用 info 就够了，排查问题时改成 debug。
• data_dir：数据保存目录，默认是 data，可以改成你习惯的路径。

修改配置文件后，必须重启 OpenClaw 服务才能生效。建议每次只改一项、重启一次、测试一次，不要一次性改一堆配置，否则出问题都不知道是哪一项改坏的。

5. 启动服务、打开界面、跑通第一个任务

5.1 启动服务：看到这几行日志就算成功

确认配置没问题后，在项目根目录、虚拟环境激活状态下执行：

bash复制openclaw serve

或者：

bash复制python -m openclaw serve

启动过程会输出一堆日志。看到类似下面这样的信息，说明服务已经起来了：

text复制OpenClaw service is running.
Listening on 0.0.0.0:8080

此时保持终端开着，打开浏览器，访问：

text复制http://127.0.0.1:8080

你就能看到 OpenClaw 的网页界面。界面可能包含任务输入框、任务列表、日志区域。第一次打开可能需要一点时间加载页面，如果长时间空白，回头看一眼终端日志有没有报错。

5.2 第一个任务：让它读取一个文件并统计字数

纸上谈兵没有意义，跑一个真实任务才能验证整条链路。先在项目根目录创建一个测试文件 test.txt，里面写一段文字，比如随便抄一段新闻或你自己的计划清单。

然后回到网页界面，在输入框里输入任务：

text复制读取 test.txt 文件，统计总字数，并按行输出前 5 行内容。

点击运行，观察过程。在正常情况下，你会看到任务状态从“排队”变为“执行中”，最后变为“完成”。结果区域会显示统计出来的字数，以及前 5 行内容。

这个任务背后其实发生了好几步：模型理解了你的意图，把它拆成“读文件”“统计字数”“取前 5 行”几个子步骤，然后依次调用对应工具，最后汇总结果。你可以到日志区域查看每一步的调用记录，这对理解 OpenClaw 的工作机制非常有帮助。

如果任务失败，先看错误信息。大部分失败集中在两类：一是模型配置不对，比如模型名称填错了或服务没启动；二是工具没启用，某些工具需要在配置里打开才允许调用。遇到这类情况，先按第 7 章核对。

5.3 用命令行跑任务：一条命令也能干活

网页界面方便直观，但日常使用中，命令行模式更适合集成到脚本和计划任务里。在虚拟环境激活状态下执行：

bash复制openclaw run "列出当前目录下所有 .txt 文件"

命令会把任务结果直接输出到终端。这意味着你可以把 OpenClaw 任务写进批处理脚本，用 Windows 任务计划程序定时执行。比如每天早上 9 点让 OpenClaw 自动归档昨天的日志文件，然后把归档结果写入一个报告文件。这种能力让 OpenClaw 从“聊天玩具”变成真正能减轻重复劳动的自动化工具。

6. Windows 专属坑位：端口占用、防火墙、后台运行与开机自启

6.1 端口被占用：最常遇到又最好解决的问题

启动时如果报 Address already in use，说明 8080 端口被其他程序占用了。想查清楚是谁占了端口，在终端执行：

bash复制netstat -ano | findstr :8080

输出会有一行包含一个 PID 数字，那就是占用进程的进程号。紧接着执行：

bash复制taskkill /PID <PID> /F

把 <PID> 替换成刚才查到的数字，强制结束进程。如果你不想动那个进程，也可以直接改 OpenClaw 配置里的 port 字段，换成 8081 或 9000。

我个人不太喜欢用 8000 端口，因为很多开发调试工具默认都盯上 8000。8080 也经常被占用，所以我在自己的机器上直接改成 9000，省心很多。

6.2 防火墙弹窗怎么选：默认选“取消”最稳妥

第一次启动 OpenClaw 服务时，Windows 可能会弹出防火墙提示，询问是否允许程序在网络上通信。如果你只是在自己电脑上通过 127.0.0.1 访问，直接取消或选择专用网络即可；想局域网内其他设备访问，再勾选专用网络放行。最稳妥的做法是，在没有明确需求时不勾选“公用网络”，也千万不要图省事直接关闭 Windows 防火墙，否则其他软件的网络安全也会跟着受影响。

6.3 让服务在后台运行或开机自启

终端一旦关闭，OpenClaw 服务就会停掉。如果你希望它在后台跑，可以用 Windows 任务计划程序创建一个计划任务：登录时触发，操作选择“启动程序”，程序填 cmd.exe，参数填：

bash复制/c "cd /d C:\dev\openclaw && venv\Scripts\activate && openclaw serve"

这样每次登录系统，OpenClaw 就会自动在后台启动。但我个人的习惯是：不要开机自启。按需启动更稳妥，省内存，也避免哪天模型配置改坏了，一开机就在后台反复报错。平时用的时候打开终端跑一下，还是挺方便的。

7. 常见问题速查：我见过的大部分报错都在这里

再补充几个排查技巧：

排查问题先看日志，别瞎猜。把配置文件里的 log_level 临时改成 debug，跑一次任务，日志会把每个步骤的调用参数、返回值都打出来。绝大多数问题在 debug 日志里都能找到线索。

最小化复现非常有效。出问题时，把自定义配置全部还原成默认，跑通再逐步加回你的改动。很多人喜欢一次性改五六个参数，真出问题时根本不知道是哪一项的锅，最后只能全部推倒重来。

不要盲目相信“报错信息是不是在骗我”。报错信息基本不会骗你，只是信息量不够。耐住性子从第一条报错开始读，按顺序排查，比自己瞎尝试强得多。

最后分享一个我自己的使用体会：Windows 本地部署 OpenClaw 这件事，最大的障碍不在工具本身，而在环境细节。PATH 没配好、路径带中文、依赖版本冲突、端口被占，这些听起来都不算大问题，但要一个个查出来，心态容易崩。按照上面这套流程走，环境检查和项目安装都稳扎稳打，大多数人都能在一小时内跑通第一个任务。日志先开 debug、改动一次只动一项、多用 python -m 前缀避开 PATH 的坑——这三条习惯能帮你省下大量排查时间。祝顺利。