乌龙茶少冰2026 年了，OpenClaw 在 Windows 上的本地化部署还是能让不少人折腾到怀疑人生。
倒不是工具本身设计得有多反人类，而是网上的资料几乎默认你在 Linux 或者 macOS 下操作，真正在 Windows 上从零跑通的完整流程少得可怜。我最近刚在 Windows Server 2022 和 Windows 11 两台机器上各部署了一套 OpenClaw，中间经历了命令行找不到、WSL 内核过期、模型配置报 unknown model、旧版审批文件迁移失败等一系列问题。把踩过的坑串起来之后发现，其实 Windows 本地部署 OpenClaw 的完整链路完全可以分成几步走通：先想清楚跑在什么环境，再准备系统组件，然后安装初始化，接着接模型，最后把记忆和技能配好。这篇就按这个顺序写，尽量做到你把页面往下翻的同时就能直接照做。
如果你是第一次接触 OpenClaw，也不用慌。可以把它理解成一个“有手有脚的 AI 管家”：大模型只是它的大脑，真正干活靠的是它能读写文件、执行命令、调用技能，并且把做过的事情沉淀成长期记忆。Windows 本地部署的核心，就是把这套环境在你的电脑上正确装好、让它跟你本机的模型服务或云端模型 API 打通。这篇教程适合谁？一种是刚接触 Agent 类工具、还没在 Windows 上装过 OpenClaw 的；另一种是已经装上但卡在模型接入或记忆配置的老手。下文所有路径和命令我都基于当时的稳定版本实测过，但版本迭代很快，遇到子命令对不上时先运行 openclaw --help 看一眼，基本都能解决。
1. 动手前先决定运行形态：原生进程、WSL2 还是 Docker 容器
很多人第一步就卡在“我到底该用哪种方式装”。OpenClaw 在 Windows 上并不是只有一种跑法，常见的就有三套路径，选错后面全是坑。
1.1 三种形态的差别和选择逻辑
- 原生 Windows 进程：直接在 PowerShell 里运行 OpenClaw，安装脚本或便携包都会走这条路。优点是没有虚拟机层，启动快，文件路径直观，适合大多数想在个人电脑上日常使用的用户。缺点是有少量为 Linux 设计的技能或组件跑不了，需要等官方出 Windows 版。
- WSL2 里的 Linux 进程：通过 Windows 的 Linux 子系统安装，OpenClaw 实际跑在 Ubuntu 等发行版里。优点是很多官方文档里的命令能直接复制粘贴，处理 Linux 生态的脚本更顺手，适合后续准备把配置迁移到云服务器的人。缺点是 IO 和应用感知有虚拟化损耗，新手还要额外维护一套 Linux 文件系统。
- Docker 容器：OpenClaw 官方镜像拉起来后，通过端口映射和宿主机通信。优点是可移植性最好，依赖隔离最彻底，复制到别的机器几乎零成本。缺点是在 Windows 上跑 Docker Desktop 本身又依赖 WSL2，等于多套了一层，配置模型和挂载目录时更容易出怪问题。
| 运行形态 | 上手难度 | 日常使用体验 | 迁移性 | 踩坑概率 |
|---|---|---|---|---|
| 原生 Windows 进程 | 低 | 启动快，路径直观 | 一般 | 低 |
| WSL2 Linux 进程 | 中 | 接近 Linux 服务器 | 高 | 中 |
| Docker 容器 | 高 | 隔离好但多一层网络 | 最高 | 偏高 |
我自己的建议很明确：如果只是在个人 Windows 电脑上把 OpenClaw 用起来，优先选原生 Windows 进程，这也是后文默认讲的主要路径。只有当你想在服务器上用 Docker 编排多个智能体，或者你本身已经习惯 WSL2 工作流，才需要考虑另外两种。
你可能会问，那为什么网络上搜 OpenClaw 相关教程时总能看到 WSL、Docker 的字眼？因为很多 Agent 类组件天然面向 Linux，OpenClaw 的某些技能包（比如直接操作 Linux 命令行的）确实在 WSL2 里更顺滑。但不要因为“听起来更专业”就盲目上 Docker，本地部署的第一目标是稳定可维护，不是炫技。
1.2 安装前最重要的一个认知：workspace 目录就是 Agent 的工位
无论选哪种形态，OpenClaw 初始化后都会生成一个工作区目录。以 Windows 原生运行为例，默认路径通常是：
text复制C:\Users\Administrator\.openclaw\workspace
这里要特别强调一下：这个 workspace 不是随手创建的文件夹，它是 OpenClaw 读写项目文件、执行命令时的工作目录，相当于给 Agent 划了一间独立办公室。你让它“整理桌面文件”“分析某个项目代码”，它默认只能在 workspace 范围内操作，避免它满硬盘乱跑。理解了这一点，后面遇到权限问题、文件找不到问题，第一反应就应该是去检查路径是否落在 workspace 内，而不是怀疑 Agent 傻了。
如果你用的是 WSL2 形态，初始化时可能提示的是 /root/.openclaw/workspace，这也解释了为什么网上很多人贴的截图路径长得完全不一样——不是版本差异，是运行形态差异。建议在动手前就定好使用哪个形态，省得装到一半才发现文件散落在两套系统里。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：能少装就别乱装，重点是 PowerShell、WSL 内核和网络连通性
不少新手把 OpenClaw 当成“聊天软件”来装，结果按照某个视频教程一口气装了 JDK、Elasticsearch、Redis，最后发现根本没有用上。OpenClaw 的本地化部署，并不需要你先搭一套完整的大数据中间件栈，它只是需要一个干净、权限正确的宿主环境。
2.1 先保证 PowerShell 7 和脚本执行策略
Windows 自带的 Windows PowerShell 5.1 虽然能用，但 OpenClaw 的官方安装脚本和部分技能模块在 PowerShell 7 下更稳定。如果你还没装，我建议先通过 winget 装一个：
powershell复制winget install --id Microsoft.PowerShell --source winget
安装完成后，打开新的 PowerShell 7 窗口，然后设置当前用户的脚本执行策略，否则安装脚本可能直接被拦下来：
powershell复制Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
执行策略的作用很多人不理解，我打个比方：Windows 默认对外来脚本是“先关进小黑屋再说”，RemoteSigned 意思是“有可靠签名的放行，本地自己写的也放行”。这个设置是安全的，不需要动系统级的执行策略，更不要为了跑安装脚本把策略改成 Unrestricted。
2.2 WSL 内核过期：一个会突然拦住你的经典报错
如果你后面还要跑 WSL2 形态或者安装 Docker Desktop，大概率会碰见下面这个报错：
text复制适用于 Linux 的 Windows 子系统必须更新到最新版本才能继续。
可通过运行“wsl.exe --update”来更新。
我第一次在 Windows 11 上装 Docker Desktop 时也被这句话卡了半天。打开管理员 PowerShell 执行：
powershell复制wsl --update
之后可以验证一下默认版本是否已经切到 2：
powershell复制wsl --status
wsl --set-default-version 2
如果你的 Windows 10 版本比较老，可能连 wsl --update 这个参数都没有，那就需要先开启虚拟机平台和 Linux 子系统功能，再执行 wsl --install --no-distribution，重启后再更新。
这这件事特别容易被人忽略，因为安装 OpenClaw 原生版本时并不会触发 WSL 检查，很多人是被某个技能包或容器方案临时拖进 WSL 坑里的。所以我的经验是：如果你暂时用不到 WSL，就不要提前装，等真正需要时再装；如果你确定要用 Docker 或 WSL2 形态，就把 wsl --update 当成必选项先做掉，而不是等报错后再补。
2.3 哪些“经典依赖”其实不是必需的
网上搜 OpenClaw 本地化部署时，会看到很多教程把 DeepSeek 本地化部署、RAGFlow、qwen3-embedding-0.6b、JDK17、Elasticsearch、Redis 这些词全部揉在一起讲。这些技术之间有关联，但不是 OpenClaw 的前置条件。
- JDK17 和 Elasticsearch 通常是 RAGFlow 这类知识库系统需要的，不是 OpenClaw 本体必需的；
- Redis 一般只在某些消息队列插件、群聊分发场景下才用到；
- qwen3-embedding-0.6b 属于本地向量化模型，OpenClaw 的 Active Memory 如果要完全离线工作才会用到，后面我会单独讲；
- DeepSeek 的 API 模型反而是最简单的云端接入方式，不需要本地部署，更不需要显卡。
我的建议是：先跑通 OpenClaw 本体和一个基础模型，再加记忆组件，最后再考虑知识库和外部中间件。一上来就堆全套，出了问题你根本分不清是 OpenClaw 的 bug 还是 Elasticsearch 的配置问题。
2.4 目录和账号的干净程度，决定了后续一半的坑
Windows 上路径带空格、带中文、带用户名乱码，很容易让 OpenClaw 这种为文件操作而生的 Agent 工具出问题。我自己会尽量用位于 C 盘用户目录下的默认路径，因为 .openclaw 的规则在各版本里基本固定。如果自定义安装位置，尽量满足三个条件：纯英文路径、不打到 Program Files 这种受保护目录、当前用户对该目录有完整读写权。
原因很简单，OpenClaw 默认要在 .openclaw 目录下写配置、写记忆、写日志、写审批文件，如果放在 Program Files 下，普通权限根本写不进去，于是你就会看到各种“看起来装了但一启动就失败”的诡异现象。用管理员 PowerShell 安装时创建的文件，之后用普通用户跑也可能读不到，这是 Windows 权限模型导致的，不是 OpenClaw 的 bug。
3. 安装与初始化：官方脚本和便携包两条路，以及 PATH 问题的本质
环境准备好之后，进入正题。OpenClaw 在 Windows 上的安装方式主要有两种：官方 PowerShell 脚本安装，或者是提前打包好的便携包。
3.1 路径 A：通过官方 PowerShell 安装脚本装（长期使用推荐）
打开 PowerShell 7，先确认当前位置，然后执行官方文档给出的安装脚本。网上的命令形式可能各不相同，但核心逻辑都是在当前会话下载安装包并解压到用户目录，然后把可执行文件路径写进 PATH。以我实测时的命令为例（具体网址以官方文档为准）：
powershell复制# 在 PowerShell 7 中执行官方安装脚本，建议先看一遍脚本内容再运行
Invoke-RestMethod https://get.openclaw.dev/install.ps1 | Invoke-Expression
你可能会问：为什么要用管道把远程脚本直接执行，而不是下载下来双击？因为安装脚本通常需要在当前终端上下文里设置环境变量和 PATH，双击运行反而容易丢失这些变更。执行完后，新开一个 PowerShell 窗口，运行：
powershell复制openclaw --version
如果能输出版本号，说明安装成功。如果提示“无法将 openclaw 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”，问题基本出在 PATH 没有生效，新开终端也不管用的情况多半需要手动把安装目录加进 PATH。
这里额外提醒一件事：第一次执行远程安装脚本前，最好还是先下载下来看一眼它执行了什么。我也明白很多新手不会逐行读脚本，但至少要确认来源是官方域名，避免从第三方博客复制安装命令。尤其涉及给系统添加计划任务、修改 PATH 的脚本，来源不明风险很高。
3.2 路径 B：使用便携包快速体验（临时或离线环境推荐）
如果你所在的内网环境不方便执行远程脚本，或者你只是想先体验一下不打算长期安装，便携包是很实用的方案。它的特点是解压即用，不需要安装器。但一定要注意：便携包里的二进制文件应放在一个固定目录，比如 D:\Tools\openclaw，不要直接解压在下载文件夹然后关掉浏览器就算完，因为你以后每次使用都需要找到那个文件。
解压后，把目录加入 PATH：
text复制D:\Tools\openclaw
加入 PATH 后重新打开终端，再执行 openclaw --version 验证。便携包的缺点是更新需要自己重新下载覆盖，不像官方脚本安装那样可以比较方便地处理版本升级差异。如果你打算长期使用，我建议还是走脚本安装。
3.3 首次运行初始化：生成 .openclaw 目录和 workspace
安装完成后，第一次运行 openclaw 通常会进入初始化流程。这个过程会生成上文提到的 .openclaw 目录结构，包括 workspace、配置文件、日志目录、skills 目录等。有的版本会直接进入交互式引导，向你询问默认模型、API Key 等信息；如果当时不想填，可以先跳过，但后面模型接入这一步必须补上。
初始化完成后，去资源管理器确认一下 C:\Users\Administrator.openclaw\workspace 已经生成，然后在里面放一个测试文件：
powershell复制cd C:\Users\Administrator\.openclaw\workspace
Set-Content -Path test.txt -Value "hello openclaw"
这条命令既能测试目录权限，又能给后续第一轮对话留一个操作对象，一举两得。
3.4 旧版审批文件提示：legacy exec approvals 的迁移问题
现在很多人从旧版本升级，或者在 WSL 里折腾过 OpenClaw 后又切回 Windows，会遇到下面这类提示：
text复制Legacy exec approvals exist at /root/.openclaw/exec-approvals.json.
Run `openclaw ...` to migrate them.
先说 exec-approvals.json 是什么。OpenClaw 在执行系统命令之前，默认会弹审批，你允许过的命令会记录在这个文件里，下次同类命令不再重复询问。这个机制很像手机上的“是否允许应用访问相册”，本质是防止 Agent 在无人监督时乱跑高风险命令。
出现 legacy 提示，通常是因为老版本把审批记录写在了旧位置，或者 WSL2 下的 root 用户目录里留了一份额外的历史审批文件。新版本检测到后会要求你迁移。处理方式很简单：先完整读一遍提示，按提示运行给出的迁移命令，不要直接手动删除。迁移成功后，原文件会被移到新位置，以后的审批记录统一管理。如果提示反复出现，并且内容确实已经没用，可以在备份后删除旧文件重新生成。
但这里有个安全禁忌：exec-approvals.json 不是可以随便从别人那里拷贝的东西。它代表的是“你信任 Agent 执行哪些命令”的列表，如果复制了别人的文件，等于把别人的信任边界套到了你的 Agent 上，别人允许过的危险命令可能直接放行。这个文件只应该由自己机器上的实际审批过程生成，不要图省事从网上下载“满配审批文件”。
4. 模型接入：unknown model 报错到底是怎么回事，以及三种主流接入方式
装好框架只是一半，真正跑起来需要让 OpenClaw 能“说话”，也就是接入模型。这里也是大多数新手翻车最集中的区域，其中最常见的报错是：
text复制agent failed before reply: unknown model: deepseek
4.1 先厘清 provider 和 model 的区别
很多人看到 unknown model: deepseek 的第一反应是“我没填对 API Key”或“网络不通”，但首先要搞清楚：OpenClaw 配置里有两层概念，一个是模型服务提供方 provider，一个是具体模型名 model。
打个比方你就明白了。provider 是餐厅，model 是菜品。你可以在配置里把 DeepSeek 这家“餐厅”加进来，但它有什么“菜”取决于你填的 model 名字。如果你告诉服务员“上一道 deepseek”，她当然听不懂，因为菜品名通常是 deepseek-chat 或 deepseek-reasoner。unknown model 报错绝大多数情况下是因为配置里的模型名不在该 provider 支持的模型列表里，或者没有给该 provider 填 API Key，导致 OpenClaw 回退到了某个默认的“不存在的模型名”上。
4.2 接入云端模型：以 DeepSeek 和 OpenAI 兼容接口为例
云端模型接入最直观。以 DeepSeek 为例，先到对应平台创建 API Key，然后在 OpenClaw 配置中声明一个 provider，并把 API Key 写在环境变量里而不是明文写进配置文件：
powershell复制# 临时设置，只在当前终端生效
$env:DEEPSEEK_API_KEY = "sk-你申请到的key"
# 持久化设置，写入当前用户环境变量
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-你申请到的key", "User")
然后在模型配置里，把默认模型名填成 provider 真正支持的模型名，常见写法是 deepseek-chat。由于 OpenClaw 的配置字段在不同版本间有调整，我建议第一次配置时先看官方文档中 models 部分，核心要确认的信息只有三个：模型 ID、接口地址、API Key 从哪个环境变量读取。
如果你用的是支持 OpenAI 兼容协议的服务，打开 OpenClaw 配置里的 provider 类型选择 OpenAI Compatible，然后填对应的 api_base 地址。这个方法对大多数新模型服务都成立，因为现在几乎所有云厂商都默认提供 OpenAI 兼容端点。
4.3 接入本地模型：Ollama、qwen3-embedding 与 NVIDIA NIM 的定位差异
想完全离线部署的人会考虑本地模型。Windows 上最简单的方式是 Ollama。安装后拉取模型并启动本地服务：
powershell复制ollama pull qwen3:8b
ollama serve
OpenClaw 侧的配置逻辑和云端 provider 一样，只是 api_base 改成：
text复制http://127.0.0.1:11434/v1
模型名填成 Ollama 里实际拉取的模型标签，例如 qwen3:8b。这里同样要认真核对模型名，Ollama 的模型标签带冒号和参数版本，填错一个字都会导致 unknown model。
qwen3-embedding-0.6b 这类模型则不是用来对话的，它是嵌入模型，专门用来把文字变成向量，供 Active Memory 做语义检索。你可以把它理解成记忆系统的“索引员”：对话模型负责说话，嵌入模型负责把重要信息归档并快速找出来。0.6B 的参数量在笔记本 CPU 上也能跑，是本地记忆场景性价比不错的选择，但不要在 OpenClaw 的主对话模型配置里填它，否则就像让图书管理员去当主持人，功能错配。
NVIDIA NIM 则是另一个方向，适合手头有 NVIDIA 显卡并且想跑更大参数模型的人。它通常以容器方式提供 OpenAI 兼容接口，OpenClaw 配置它的方式和配置云服务差不多，端口和模型名按容器实际暴露情况填。但 Windows 上跑 NIM 需要比较完整的 GPU 驱动和容器运行时环境，我不建议在入门阶段尝试，先把基础流程跑通再说进阶玩法。
4.4 排查 unknown model 的完整链路
遇到 unknown model 报错时，不要盲目重装 OpenClaw，我建议按下面的顺序排查：
- 看提示里的模型名到底是哪个。如果报错是 unknown model: deepseek，先把这个字符串放到配置里全局搜索，看是哪里引用了它。
- 确认该模型在 provider 下真实存在。去模型服务商文档查，或者运行 openclaw models list 查看当前版本支持的模型列表。如果版本不同没有这个子命令，就运行 openclaw --help 找找跟 model 相关的查看命令。
- 确认 API Key 环境变量已经加载。重新打开终端，运行 echo $env:DEEPSEEK_API_KEY，如果能输出 key，说明环境变量生效；如果为空，说明 setx 之后没有新开终端，或者变量名拼写不一致。
- 区分 provider 名和 model 名。很多人把 provider 配置里的 id 写成 deepseek，然后默认模型名也填 deepseek，就会触发 unknown model。正确做法是默认模型名填 deepseek-chat，或者填你实际购买/可用的那个模型 ID。
- 看日志定位回退原因。OpenClaw 日志一般会记录它尝试加载了哪个模型、为何回退到默认模型。日志目录通常在 .openclaw/logs 下，如果找不到，就在前台启动 OpenClaw，所有关键错误会直接打在终端里。
4.5 第一轮“能干活”的验证
模型配置好以后，不要一上来就测试复杂任务。用最朴素的对话先验证链路是否通了，然后再测试文件操作能力。我会在 workspace 目录下启动 OpenClaw，然后让它做一件不需要联网、但需要读文件的事：
text复制请读取当前目录下的 test.txt，然后用一句话告诉我里面的内容。
如果它能正确读出 hello openclaw 这几个词，说明模型接入、workspace 权限、命令执行审批三件事全部通了。这一步非常关键，能一次性把“模型没接对”和“文件权限问题”区分开。如果它读不到文件，先看是不是 test.txt 真的不在当前工作目录，再看审批提示是否被忽略。
5. 记忆与技能：从“能聊天”到“能干活”的两次关键升级
模型接好后，OpenClaw 就是个能对话的终端机器人。但很多人下载它是为了当长期的智能助理，于是很快会遇到两个疑问：为什么它下次不记得我说过什么？为什么它不会用我电脑上的微信、Obsidian 这类工具？答案分别对应 Active Memory 和 Skills。
5.1 Active Memory：让智能体具备长期工作记忆
Active Memory 是 OpenClaw 比较高阶也比较核心的机制。简单地说，它会把对话和任务执行过程中值得记住的信息抽取出来，经过嵌入模型向量化后存储，下次启动时再把跟当前任务相关的记忆检索出来，放进模型的上下文里。
这个过程我建议用一个比喻理解：它不会像录像机一样保存全部对话，而是像秘书一样手写便签，然后在合适的时机把有用便签翻出来提醒你。所以 Active Memory 的配置关键不是“存储空间多大”，而是“检索准不准”，检索准不准又取决于嵌入模型的质量。
在 Windows 本地全离线场景下，我建议至少准备一个本地嵌入模型，qwen3-embedding-0.6b 就是我实测过够用的小模型。配置 Active Memory 时，一般需要指定两部分：嵌入模型的 API 地址和模型名，以及记忆存储目录。存储目录我建议放在 .openclaw 下的独立子目录，避免和 workspace 混在一起——workspace 适合放临时的、可修改的项目文件，记忆目录则应该更像只读档案库。
开启 Active Memory 之后，日常使用要注意“记忆不是自动越全越好”。如果你执行了大量琐碎的一次性操作，它也可能会把噪音存进去，导致后续检索结果变差。养成定期查看记忆内容、清理过时条目的习惯，比加钱换大模型更管用。这个思路和整理自己笔记是一样的：检索效果取决于输入质量，而不是存储容量。
5.2 Skills：把“提示词”升级成“可复用的技能包”
OpenClaw 的 Skill 机制也是新手容易忽略的点。所谓 skill，本质上是一组包含说明文档和可执行脚本的文件夹，描述“在什么场景下、如何完成一类任务”。例如一个“接入微信”的 skill 会在其中定义如何读取消息、权限范围、回复规范；一个“Obsidian 项目管理”的 skill 会定义如何读取 vault 里的笔记结构、更新项目状态。
为什么不直接在对话里告诉 OpenClaw 该怎么做？因为对话里的临时指示不可复用、不可共享、还容易在长篇上下文中丢失。Skill 则把方法论固化成了 Agent 可以反复加载和执行的资产，相当于给新同事一本岗位手册。
安装 Skill 通常在配置目录下操作。以 .openclaw/skills 为例，把下载好的 skill 文件夹放进去或者通过相关命令安装。我强烈建议不要一次性塞几十个 skill 进去。每个 skill 的说明文档都会占用 Agent 的上下文理解空间，装太多反而会让它在调用时犹豫不决。先装两三个你每天真会用到的，磨合一周再增加。对我来说，Windows 本地场景下最值得先装的 skill 是文件整理类和日志排查类，因为它们跟本地部署强相关，能最快建立信任感。
5.3 Obsidian 和微信：结合本地工具的正确姿势
热搜里经常看到“Obsidian 结合 OpenClaw 做项目管理”“OpenClaw 接入微信”之类的玩法。这些本质上都是给 OpenClaw 接外部工具，但我建议区分对待。
接入 Obsidian 我比较推荐，因为 Obsidian 的 vault 本质上就是本地 Markdown 文件，OpenClaw 操作起来非常自然。实用做法是让 OpenClaw 把 vault 视作只读的知识源，需要更新项目状态时先把相关文件复制到 workspace 再修改，而不是直接改写源文件。因为模型的修改不可控，哪怕只是格式错误，污染整个知识库的代价都比“多复制一份”大得多。
接入微信则要谨慎得多。OpenClaw 要操作微信，通常需要登录网页版或模拟客户端，这会牵扯到账号安全、风控、消息隐私等多重问题。我见过不少人照搬教程去接微信，结果第二天账号被限制登录，得不偿失。如果你确实需要自动处理 IM 消息，先在隔离环境里测试清楚，并且不要把私人高频账号作为实验对象，这一点再怎么强调都不为过。
5.4 Windows 下的“系统人格分裂”：编码、引号和权限
OpenClaw 在 Windows 上干活，有一类坑是 Linux 教程完全不会教的，就是 Windows 的终端编码和权限模型。
先看编码。PowerShell 默认代码页在中文 Windows 上可能是 GBK，而 OpenClaw 和模型的输出基本是 UTF-8，一旦两边不一致，你会在终端看到大量乱码，严重时还会导致 Agent 解析命令结果失败。建议在 PowerShell profile 里加上：
powershell复制[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
也可以在执行前先运行 chcp 65001 把当前代码页切到 UTF-8。如果排查乱码问题，第一件事就是确认代码页，这能省下大量时间。
再看引号。OpenClaw 在 Windows 上执行命令时，PowerShell 的引号转义规则比 Linux shell 复杂得多。你让 Agent 运行一个带空格路径的程序，如果它没有正确处理引号，就会报“不是内部或外部命令”。解决思路不是教 Agent 背规则，而是尽量把可执行文件放到无空格的纯英文目录，或者通过配置定义别名让 Agent 调用。
最后看权限。Agent 使用的终端和你日常管理员终端不一定权限一致。如果 OpenClaw 由管理员启动，它创建的文件夹可能普通用户账号读不了；反过来，普通用户启动时可能写不进某些系统目录。最简单的做法是：固定用一个非管理员但对该目录有完整权限的账号运行 OpenClaw，不要一会管理员一会普通用户混着开，否则启动时大概率会出现配置被锁定、日志无法写入的怪问题。
6. Windows 本地部署高频坑排查手册：能救一个是一个
前面各章其实已经穿插讲了不少具体报错，这里我再集中整理一份排查手册，都是我在 Windows 上重装过多次后才总结出的规律。建议你在遇到问题时直接定位到对应条目。
6.1 “适用于 Linux 的 Windows 子系统必须更新到最新版本才能继续”
如果你安装了 Docker Desktop 或选择了 WSL2 形态，启动时很容易看到这个提示。它的本质是 Docker Desktop 检测到 WSL 内核版本过旧。解决办法是先管理员 PowerShell 执行 wsl --update，再看 wsl --status 是否显示默认版本为 2。如果还是不满足，检查 Windows 版本是否过老，过老的系统需要先开启虚拟机平台功能并重启。
6.2 “无法将 openclaw 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”
这是 PATH 问题最常见的表现。可能原因有三个：安装目录没有加入 PATH、加入后没有重开终端、杀毒软件拦截了安装程序导致文件根本没写进去。处理顺序是：
- 运行 openclaw 的绝对路径验证文件是否存在；
- 确认安装目录路径已加入用户 PATH；
- 重开终端再试；
- 如果还是不行，检查杀毒软件隔离区是否躺着 openclaw 相关文件。
6.3 路径含中文或用户名不是预期的系统账号
OpenClaw 对路径空格和中文的容忍度比传统命令行工具好一些，但配套技能脚本不一定好。如果用户名包含中文，某些依赖文件路径的脚本可能出现编码错乱。这种情况下优先考虑在 D 盘建一个纯英文目录作为工作目录，并把配置里的 workspace 指过去，避免把所有任务都堆在 C 盘用户名路径下。要改 workspace 路径时，注意不能只改显示名，配置文件里的实际路径也要同步更新，最好每次修改后重启 OpenClaw 并确认它在新目录下能正常读写。
6.4 legacy exec approvals 反复出现，迁移命令跑不完
这个前面提过，但值得放进排查手册。