1. 部署前准备与环境检查想在 Windows 上把 OpenClaw 部署起来与其直接复制网上那些零散命令不如先花三分钟看清楚自己要什么。OpenClaw 是一个主打本地运行的智能体/自动化编排框架它把“模型调用”“工具执行”“任务调度”这几件事统一到一个服务里。你通过一个 Web 界面下发任务服务内部按“理解任务—拆解步骤—调用工具—返回结果”的流程跑完。它特别适合两类人一类是不想把私人数据上传到云端希望所有任务都在本机完成的用户另一类是刚开始接触智能体类项目想找一个上手成本足够低的 Windows 部署方案的人。这篇笔记面向的正是“恰好有一台 Windows 机器想简单跑起来”的朋友不是讲高深原理而是直接给可执行步骤。1.1 OpenClaw 到底解决什么问题我最初看到这类工具时也愣了一下现在的 AI 工具不是打开浏览器就能用吗为什么还要本地部署一套服务原因其实很现实。浏览器里的 AI 产品虽然方便但你的文件路径、聊天记录、任务脚本都会经过远端服务器不少开发者对这一点比较敏感。OpenClaw 这类本地框架把核心逻辑放在你自己电脑上模型文件、任务数据、执行日志都留在本机断网时已经启动的服务也能继续处理本地任务。另外它的“任务编排”能力比单纯问一句“帮我写一段代码”要实用得多。你可以一次性下达“扫描 D 盘某个文件夹按文件类型整理并把整理结果生成一张表格”这样的复合任务服务会调用文件工具、脚本工具、模型总结能力逐步完成。传统自动化脚本只能执行固定规则OpenClaw 则让模型参与决策、工具负责执行两者结合在一起才叫智能体。对我来说它解决的核心问题就是让电脑自己干活并且每一步在干什么都可追踪、可回滚。第一次尝试的人不用把目标定太大。先跑通一个最简单任务感受一下“任务下发—工具调用—结果返回”的完整链路比一开始就追求复杂工作流更有价值。1.2 Windows 系统要求与版本选择OpenClaw 本身是跨平台的但 Windows 环境有几个细节和其他系统不一样。部署之前建议先对照下面这张表检查一下你的机器检查项最低建议推荐配置操作系统Windows 10 22H2 及以上Windows 11 64 位CPU4 核以上8 核以上内存16 GB32 GB 或更高显卡不强制但影响模型速度NVIDIA 显卡显存 8 GB 以上磁盘剩余空间10 GB20 GB 以上固态硬盘优先很多教程默认你有一块性能还过得去的显卡因为运行本地模型时显存决定你能跑多大参数量的模型。如果只是体验 OpenClaw 的任务编排功能不接本地大模型那么核显机器也能跑只是模型推理会明显偏慢。我个人建议第一次尝试别追求大模型先用一个 7B 参数的量化版本例如 Q5 量化跑通流程再决定要不要换更大的。Windows 版本方面尽量选 64 位系统避免在 32 位环境下碰到莫名其妙的兼容问题。Windows 11 的默认终端和防火墙交互会更友好Windows 10 的话把系统更新到 22H2 之后再装不然某些底层的运行库会缺失启动时容易报“找不到指定模块”之类的错误。1.3 Windows 下容易漏装的三个前置依赖部署 OpenClaw 之前三样东西我必须确认已经装好版本管理工具 Git、Python 解释器、容器运行时可选。Git 不一定直接参与 OpenClaw 的启动但我习惯用它来拉取安装包和后续同步更新省去手动下载压缩包再解压的麻烦。安装时选“Next Next”一路过去就行唯一要注意的是在安装向导里选择“Git from the command line”这样 PowerShell 和命令提示符里都能直接使用 git 命令不用再手动配环境变量。Python 版本建议装 3.10 到 3.11 之间的稳定版本。不是越新越好因为 OpenClaw 依赖的某些编译库对新版 Python 的支持存在滞后我在 3.12 上遇到过一个第三方库编译失败的情况退回 3.11 后一次通过。装 Python 时有一个关键操作在安装向导第一页勾选“Add Python to PATH”。这个勾不上的话后面在终端里敲 python 会提示找不到命令到时就只能手动把 Python 安装目录加进系统环境变量了。容器运行时这次不是必须的。OpenClaw 的默认安装方式是 Python 虚拟环境不需要容器也能跑只有你想把外部工具链隔离成独立插件时才需要容器服务。为了减少变量第一次部署建议先跳过等主流程跑通后再回来补。依赖装完后最好做一次最后验证。打开 PowerShell依次输入git --version和python --version能看到版本号代表环境正常。看不到的话多半是 PATH 没配对把对应目录手动加进系统环境变量即可。这一步虽然简单但能够避免后面执行部署命令时到处找问题。2. 核心配置与初始化流程环境就绪之后OpenClaw 的部署动作实际上就三件事拿代码、装依赖、改配置。这一部分我把每一步拆开讲清楚尤其是配置文件里的坑。很多人卡在部署环节不是因为命令复杂而是不了解每个文件是干什么的遇到报错不知道从哪里下手。2.1 安装包怎么拿克隆仓库与目录结构在项目目录下执行git clone https://example.com/openclaw/openclaw.git openclaw cd openclaw git checkout stable第一行里的地址是示例写法实际操作时去官方文档页复制真实仓库地址。如果网络不稳定导致克隆中断可以先只克隆默认分支后续再手动切换。切换分支后建议运行一次git status确认当前所在分支避免改配置时改到了其他分支的文件产生混乱。克隆完成后目录里应该能看到这样的核心结构openclaw/ ├── app/ # 主程序代码 ├── config.example.yaml # 配置模板 ├── models/ # 本地模型文件存放目录 ├── data/ # 任务数据与数据库文件 ├── requirements.txt # Python 依赖清单 └── openclaw.py # 命令行入口不要小看这个结构。部署过程中你最常打交道的其实是两个路径一是config.example.yaml所有服务行为都由它定义二是data/目录任务记录和数据库都在这里备份时只要打包这一个目录就够了。模型文件目录models/默认是空的需要你手动放模型或运行下载命令。这里有一个我后来才体会到的经验克隆项目后最好保留.git目录后续git pull更新版本非常方便。如果你担心自己改动过配置文件导致更新冲突就先复制一份原版配置再把改动合并回去这样即使出了问题也能快速对照。2.2 创建虚拟环境与安装依赖在项目根目录打开 PowerShell执行python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt为什么非要用虚拟环境因为 OpenClaw 依赖上百个 Python 包直接装进系统环境很可能和你机器上其他项目冲突。虚拟环境相当于一个独立的小房间项目依赖都放在这里想卸载干净时删掉整个目录就行。有两点需要提醒PowerShell 默认可能禁止运行脚本。如果执行激活命令报“禁止运行脚本”错误用管理员身份运行Set-ExecutionPolicy RemoteSigned解除限制或者临时用cmd进入.venv\Scripts\activate.bat激活。安装依赖时需要联网下载包等待时间取决于网络和机器性能。看到Successfully installed openclaw这类字样才算结束中间出现红色报错时先看是哪个包失败再决定重试还是换 Python 版本。个别库如果总是下载失败可以尝试更换镜像源但不要随意把整个环境切到不熟悉的源上。依赖装好之后可以先执行一次python openclaw.py --help。如果能看到命令列表说明主程序已经能运行了后面的失败基本只剩配置问题。这一步验证看起来多余但能把“代码没拉全”和“配置写错”两类问题区分开排查效率高很多。2.3 配置文件逐项解读host、model、tools、executorOpenClaw 的配置逻辑不复杂核心是四个块服务地址、模型来源、可用工具、执行策略。先把配置模板复制成正式配置copy config.example.yaml config.yaml然后打开config.yaml建议逐项阅读server: host: 127.0.0.1 port: 8765 model: provider: local path: models/local-model-7b-q5.gguf context_length: 8192 gpu_layers: 20 tools: - file_ops - python_exec - web_search executor: max_steps: 10 timeout_seconds: 120这里有几个参数要特别注意。server.host默认是127.0.0.1这是回环地址只允许本机访问。OpenClaw 是本地服务如果随手改成0.0.0.0局域网内其他设备都能访问你的任务接口安全隐患很大。没有特殊需求就别改更不要把它暴露到公网。model.provider选local还是remote决定模型从哪里来。本地部署当然选local但前提是models/目录下真的有模型文件。没有模型文件时服务能启动任务会一直卡在“加载模型”阶段。如果下载条件允许用官方命令拉取模型文件否则把模型手动拷进目录也可以。gpu_layers控制模型有多少层放在显卡上其余层用 CPU 计算。显存 8 GB 的显卡建议先从 20 开始尝试跑不动就往下调到 10 或 0虽然推理变慢但至少能稳定运行。executor.max_steps控制一个任务最多执行多少步工具调用防止模型陷入死循环新手建议先用 10 以内的数值。配置保存后先跑一次检查命令python openclaw.py check-config看到configuration OK再继续。这一步能帮你提前发现 YAML 缩进错误、路径写错之类的低级问题避免等到启动失败再回头翻日志。3. 启动服务与本地联调配置没问题接下来就是启动和验证。这个阶段的目标只有一个让服务跑起来并且能真实完成一个任务。我见过不少人在这个环节被各种小问题绊住所以下面把顺序和关键输出都写清楚。3.1 初始化生成密钥与本地数据库OpenClaw 第一次启动前需要初始化这会生成一个本地密钥文件并创建 SQLite 数据库文件。执行python openclaw.py init正常输出类似[INFO] OpenClaw initialized. [INFO] Key file created: data/secret.key [INFO] Database created: data/openclaw.db密钥文件很重要任务数据的加密和通信校验都依赖它。如果你把这个文件弄丢了已加密的历史任务记录可能就无法读取所以备份时记得把它和data/目录放在一起。数据库文件记录了两类东西任务历史和执行日志。日常使用中如果发现界面卡顿可以把这个文件压缩备份一次再继续不影响服务运行。初始化的另一个作用是为后续启动做好目录准备。如果models/目录不存在初始化过程会自动创建如果配置里指定了绝对路径它也会检查路径是否可写否则任务执行到写文件那一步会报权限错误。3.2 启动主进程命令与启动日志初始化完成后启动服务python openclaw.py serve --host 127.0.0.1 --port 8765第一次启动时 Windows 防火墙可能会弹窗询问是否允许网络通信这里一定要点允许否则浏览器访问不到服务。如果手滑点了拒绝可以去 Windows 安全中心的“防火墙和网络保护”里手动添加允许规则。启动成功的标志是日志出现[INFO] Uvicorn running on http://127.0.0.1:8765这时打开浏览器访问http://127.0.0.1:8765/ui应该能看到 OpenClaw 的 Web 管理界面。界面会显示当前服务状态、模型加载情况、工具列表。注意不要急着关掉这个 PowerShell 窗口窗口一旦关闭服务就停了建议把窗口最小化或单独用一个终端跑服务。启动之后先别急着跑任务刷新一下界面确认模型状态是“已加载”。如果显示“未加载”多半是模型路径写错或模型文件缺失回到配置检查一下。新手容易忽略的一点是模型加载往往需要十几秒到几十秒刚启动时显示“加载中”是正常的等日志出现模型加载完成再提交任务。3.3 跑通第一个任务从界面到命令行在 Web 界面左侧输入框里输入一个最简单的任务列出 D:\temp 目录下所有文件并按照修改时间排序。点击执行后你会看到任务状态经历“等待、正在思考、正在执行、完成”几个阶段。日志里会依次出现“调用 file_ops 工具、读取目录、生成结果”等记录。这一步能跑通说明 OpenClaw 的完整链路已经没问题后面只是使用深度和扩展的问题。除了 Web 界面也可以用命令行直接提交任务python openclaw.py task D:\temp 目录里有哪些文件逐个输出文件大小或者通过 Python 调 API 接口。实际项目中我用的是 requests 库import requests resp requests.post( http://127.0.0.1:8765/api/task, json{cmd: 统计 D:/temp 目录下文件名包含 2024 的文件数量} ) print(resp.json())注意这个 HTTP 接口没有做复杂鉴权绑定在 127.0.0.1 时风险可控但不要把它暴露到公网。第一次跑任务建议选一个只有少量文件的目录方便观察执行轨迹。如果任务报“找不到路径”先检查 Windows 路径写法特别是反斜杠转义问题命令行里路径加引号Python 代码里用正斜杠或双反斜杠都能避开大部分坑。4. 真实部署中遇到的高频坑前面流程看着顺真到自己动手时还是可能卡住。这一章写的都是我实际踩过的坑以前看别人教程里一句“如果启动失败”就带过结果自己遇到时卡了两小时。现在把这些情况整理成速查式经验遇到类似问题的时候直接对照。4.1 端口占用与防火墙拦截最常见的启动失败原因是端口被抢。执行python openclaw.py serve时如果控制台提示address already in use先用这个命令找占用端口的进程netstat -ano | findstr 8765输出最后一列是 PID到任务管理器里搜索该 PID 结束进程或者换一个端口比如--port 8766。如果只是临时测试换端口比杀进程更省事改配置里的server.port也能永久生效。同一个机器上有多个 Python 服务时这种事尤其容易发生比如你之前跑过其他 Web 服务没关干净。防火墙弹窗误操作后浏览器访问不到界面的表现是“连接超时”而不是“拒绝连接”。先去系统设置检查“允许应用通过防火墙”找到 Python 进程的“专用网络”勾选打勾实在搞不定就临时添加一条入站规则只放行 TCP 8765 端口等调试完再删掉。注意如果是公司电脑或有统一安全策略的设备加防火墙规则可能需要管理员权限提前确认好。4.2 中文路径乱码与代码页问题Windows 默认代码页在中文系统上是 936GBK而很多配置文件、日志输出用的是 UTF-8两者不一致就会在控制台看到乱码严重时任务里包含中文路径会直接报错找不到文件。这个问题在英文系统上不太会有中文环境几乎必现尤其当你的用户名是中文时项目路径下会自动带上中文路径更容易触发。我的解决办法有两个任选其一启动前在 PowerShell 执行chcp 65001把代码页切成 UTF-8。设置环境变量PYTHONUTF81让 Python 解释器默认用 UTF-8 处理文件读写。我更推荐第二种因为一次配好后续不用每次切换。操作路径系统属性 → 高级系统设置 → 环境变量 → 新建用户变量变量名PYTHONUTF8值1。设置完成后重启 PowerShell 生效。如果项目路径本身就在中文目录下建议直接把项目转移到纯英文路径比如C:\projects\openclaw能避开很多隐藏问题。4.3 模型加载慢、显存不足、反复重启任务提交后一直卡在“加载模型”或者进程启动后频繁退出多半是模型资源问题。三个信号对应三种处理方式症状原因建议加载极慢CPU 占用拉满模型文件在机械硬盘或未开启内存映射放到固态盘开启模型配置里的mmap: true启动后闪退显存不足模型层数超出显存容量调小gpu_layers例如 20 改 10或改为 0任务常报上下文超限context_length 设置过大先从 8192 开始再根据实际需要调成 4096 或 16384这里多说一句显存不够时把gpu_layers调小不是让模型不工作而是让更多层交给 CPU 计算。速度会下降但至少能稳定跑完任务。7B 量化模型在纯 CPU 上跑一个小任务通常几十秒可以接受。如果你在用到 20 层 GPU 加速时经常闪退先检查显卡驱动是否最新再检查显存是否被其他程序占用。4.4 配置文件被改坏导致服务无法启动这个坑最隐蔽。有时候服务能启动但任务执行行为异常有时候直接报语法错误。原因大多是从网上复制了一段不适合的配置片段或者 YAML 缩进写错了。YAML 对缩进极其敏感多两个空格或少两个空格都会出问题而且它的错误提示不一定指向真正的出错行。我的排查流程是先跑python openclaw.py check-config它能报出配置语法问题。如果提示不明显就把config.yaml和config.example.yaml做一次文本对比找出差异。实在找不到问题直接恢复备份配置再把改动一项一项加回去不要一次改三四个地方。经验是初学阶段只改最必要的三项——模型路径、端口、gpu_layers其余保持默认能跑通再动其他配置。任何配置修改后都建议保留一份config.bak.yaml别嫌麻烦关键时刻能救命。5. 从“跑通”到“日常能用”的扩展建议服务能跑、任务能完成其实只是开始。这一章写几个我实测过有效的扩展方向适合你把基础部署稳定之后再来尝试。不用一次做完挑一两个最接近你实际需求的就行。5.1 把模型来源换成更可控的后端如果本地量化模型效果不够好OpenClaw 支持配置provider: remote指向一个内网里自建的模型网关服务。这样做的好处是模型推理放到性能更强的机器上任务编排仍然留在本机数据链路依然可控不会经过外部公共网络。我理解很多人一开始追求“完全本地”但在家用场景里一台普通电脑跑大模型确实吃力把计算和编排拆开是更务实的选择。配置时把model.provider改成remote并填上服务地址model: provider: remote endpoint: http://192.168.1.100:8000/v1 api_key: local-key-here切换之后建议重新跑一次第 3 章的简单任务确认模型链路通畅。这类内网服务地址我建议用固定 IP不要用机器名避免 DNS 解析出问题。如果条件允许在网关服务端也加上访问白名单只允许你本机 IP 调用。5.2 给智能体加权限边界让一个智能体替你操作系统文件本质上是很危险的事。我的文件工具在测试时指向D:\temp任务无论怎么折腾都影响不到其他磁盘。真要开放更大范围也不要直接给全盘权限按“最小目录授权”原则设置可访问路径。这个原则听起来简单但真正执行起来要留意Windows 下的路径权限和 Linux 不一样OpenClaw 的进程以当前用户身份运行拥有该用户能访问的所有文件权限所以只能在配置层拦住它而不是依赖系统权限。OpenClaw 的tools列表里如果有python_exec相当于允许运行代码片段这就更需要谨慎。日常使用建议关掉只保留file_ops和web_search这类相对可控的内置工具。等你能完全理解每条命令的影响之后再按需打开更强能力的工具。5.3 开机自启与日志维护想让服务在重启电脑后自动启动可以用 Windows 的任务计划程序。触发条件选“登录时”操作指向虚拟环境里的python.exe参数填完整路径加openclaw.py serve。有一个关键点经常被忽略工作目录一定要设置成项目根目录否则服务找不到配置文件和模型文件。任务计划程序的操作界面里有一个“起始于”字段填项目根目录即可。日志会随时间越积越多。OpenClaw 默认把日志写到data/logs/建议每隔一段时间清理一次或者写一个小脚本只保留最近 7 天的日志文件。本地服务不像生产环境那样需要复杂的日志收集但提前处理一下可以避免磁盘被日志撑满。我自己习惯每个季度看一眼日志目录大小如果超过几百 MB 就清理一次目前运行一年多没有任何异常。这些扩展点不用一次全做完先把前面的部署步骤跑稳再按自己的需求逐个尝试即可。
