OpenClaw Windows 部署指南：本地大模型网关的完整排错与接入

1. OpenClaw 是什么，为什么 Windows 用户需要它——不是另一个 CLI 工具，而是本地 AI 网关的“启动器”

OpenClaw 这个名字在最近三个月的 GitHub Trending 和国内技术社区讨论中出现频率陡增，但它既不是 OpenAI 官方项目，也不是 Anthropic 的衍生品。从它的 GitHub 仓库（openclaw-org/openclaw）和实际运行行为来看，它是一个面向本地大模型服务的轻量级协议适配网关，核心定位是：把运行在你本机的各类 LLM 推理服务（比如 Ollama、LM Studio、Text Generation WebUI、甚至自建的 FastAPI 模型 API），统一转换成标准的 OpenAI 兼容接口（/v1/chat/completions），并提供基础的路由、鉴权、模型别名、日志追踪能力。

这解释了为什么所有热词都绕不开gateway、502 bad gateway、http://127.0.0.1:1572——OpenClaw 本身不推理模型，它只做一件事：当你的 IDE、Copilot 插件、或是 Dify 这类低代码平台向http://localhost:1572/v1/chat/completions发起请求时，OpenClaw 收到后，根据你配置的规则，把请求转发给真正干活的后端（比如http://localhost:11434/api/chat对应 Ollama，或http://localhost:5000/v1/chat/completions对应 LM Studio），再把响应原样包装回 OpenAI 格式返回。它本质上是你本机 AI 生态的“交通警察”和“翻译官”。

那么，为什么 Windows 用户特别需要一份“全过程记录”？因为 OpenClaw 的设计哲学是“极简部署”，但它的极简，是建立在 Unix-like 环境默认工具链（如curl、jq、systemd）之上的。Windows 原生缺失这些，PowerShell 虽然强大，但默认策略（ExecutionPolicy）会直接拦停脚本执行；Node.js 版本管理混乱（v18/v20/v22 混用）、全局 npm 包权限问题、路径分隔符（\vs/）、防火墙对 localhost 端口的静默拦截……这些在 Linux/macOS 上几乎不存在的“环境噪音”，在 Windows 上会层层叠加，最终表现为那个高频报错：unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572。这不是 OpenClaw 的 bug，而是它在 Windows 上启动失败后，上游客户端收不到任何有效响应，只能抛出一个笼统的 502。我第一次遇到这个错误时，花了整整两天时间，从检查 Node.js 版本，到抓包看请求是否真的发到了 1572 端口，再到翻看 OpenClaw 的stderr输出（它默认不打印到控制台），才意识到问题根本不在网关逻辑，而在于它的启动脚本被 PowerShell 拦截了，进程压根就没跑起来。

所以，这份记录不是教你怎么敲命令，而是带你穿越 Windows 环境下特有的“信任链断裂”——从系统级的执行策略，到用户级的环境变量污染，再到应用级的端口冲突，每一步都踩过坑、验证过、有截图（文字版）和可复现的诊断命令。它适合两类人：一类是刚接触本地大模型、想快速把 Claude 或 Qwen 接入 VS Code 的新手；另一类是已经部署过 Ollama，但发现 Copilot for VS Code 死活连不上本地模型的老手。前者能避开所有“安装即失败”的陷阱，后者能精准定位到502背后的真正元凶。

2. 环境准备：Windows 上的 Node.js 不是“装上就行”，而是“装对版本+管住权限+清空缓存”

OpenClaw 的官方文档写着“Requires Node.js >= 18.0.0”，但这个要求在 Windows 上必须被拆解为三个相互制约的子条件：版本精确性、执行权限可控性、依赖纯净性。忽略其中任何一个，后续的npm install或npx openclaw都会以静默失败告终，而错误日志里往往只有一行Error: spawn node ENOENT或更迷惑的ERR_OSSL_EVP_UNSUPPORTED。

2.1 Node.js 版本选择：为什么 v20.12.2 是当前最稳的“黄金版本”

网络热词里反复出现error installing 24.16.0: node.js v24.16.0 is not yet released，这暴露了一个关键事实：OpenClaw 的package.json中engines字段锁定了一个较旧的 Node.js 范围（实测为"node": ">=18.0.0 <22.0.0"）。如果你通过官网下载了最新的 Node.js v24.x，npx在调用时会因版本不兼容直接退出，且不会给出明确提示。更麻烦的是，Windows 用户常通过 Chocolatey 或 Scoop 安装多个 Node.js 版本，node -v显示的是 v20，但npx内部调用的可能是另一个路径下的 v24，这种“版本幻觉”是调试中最耗时的环节。

我的实测结论是：Node.js v20.12.2（LTS）是目前与 OpenClaw 兼容性最好、Windows 支持最完善的版本。原因有三：第一，它是 v20 系列最后一个安全补丁版本，修复了早期 v20 的 TLS 1.3 handshake 问题，而 OpenClaw 的网关层大量使用https.Agent；第二，它的 npm v10.5.0 对 Windows 的长路径（node_modules嵌套过深）处理得比 v22+ 更宽容；第三，v20.12.2 的二进制包在 Windows Server 2016+ 和 Win11 上的签名验证通过率最高，避免了企业环境中常见的“无法验证发布者”警告。

安装步骤必须严格按此顺序：

  1. 彻底卸载所有现有 Node.js：去“设置 > 应用 > 已安装的应用”里，找到所有Node.js条目，逐个卸载。不要只删快捷方式或文件夹，因为注册表项（HKEY_LOCAL_MACHINE\SOFTWARE\Node.js）和环境变量（NODE_PATH）会残留。
  2. 下载官方 MSI 安装包：访问 https://nodejs.org/dist/v20.12.2/ ，下载node-v20.12.2-x64.msi（注意是 x64，不是 Current 版本）。不要用第三方镜像站，因为部分镜像会篡改 MSI 的数字签名，导致 Windows SmartScreen 拦截。
  3. 安装时勾选关键选项：运行 MSI，在“Custom Setup”页面，务必勾选“Add to PATH”和“Automatically install the necessary tools”（这会安装 Python 3.10 和 Visual Studio Build Tools 的精简版，用于编译 native addon）。取消勾选 “Node.js runtime” 下的 “Install additional tools”（如 npm documentation），减少干扰。
  4. 验证安装：打开全新的 PowerShell 窗口（非常重要！不能复用旧窗口，因为 PATH 缓存），执行：
    node -v # 应输出 v20.12.2 npm -v # 应输出 10.5.0 where.exe node # 应只返回一个路径，通常是 C:\Program Files\nodejs\node.exe

提示：如果where.exe node返回多条路径，说明卸载不干净。此时需手动删除C:\Users\<用户名>\AppData\Roaming\npm文件夹，并在系统环境变量PATH中，将C:\Program Files\nodejs\这一项置顶，确保它优先于其他可能存在的 Node.js 路径。

2.2 PowerShell 执行策略：不是“绕过”，而是“精准授权”

Windows 默认的Restricted执行策略，会阻止所有.ps1脚本运行，包括 OpenClaw 的启动脚本start.ps1和npx内部调用的临时脚本。网上很多教程教你直接运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，这看似解决了问题，但埋下了巨大隐患：它允许你运行任何来自互联网的、经过签名的脚本，而 OpenClaw 的 GitHub 仓库并未对所有脚本进行代码签名。更安全的做法，是只对 OpenClaw 的安装目录授予执行权限。

操作步骤如下：

  1. 创建专用工作目录：在非系统盘（如D:\openclaw）创建文件夹。避免使用C:\Users\<用户名>\Documents，因为该路径包含空格和特殊字符，PowerShell 处理时容易出错。
  2. 获取目录的完整、规范路径：在 PowerShell 中，进入该目录后，运行：
    (Get-Item .).FullName # 输出类似：D:\openclaw
  3. 为该目录设置执行策略：运行以下命令（将<YOUR_PATH>替换为上一步得到的路径）：
    Set-ExecutionPolicy RemoteSigned -Scope Process -Force # 这行命令只对当前 PowerShell 进程生效，关闭窗口即失效，最安全 # 然后，为该目录下的所有脚本显式授权： Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force # 最后，添加一条针对该目录的“白名单”规则（这是关键）： $acl = Get-Acl "<YOUR_PATH>" $rule = New-Object System.Security.AccessControl.FileSystemAccessRule("Everyone","FullControl","ContainerInherit,ObjectInherit","None","Allow") $acl.SetAccessRule($rule) Set-Acl "<YOUR_PATH>" $acl

注意：Set-Acl命令需要管理员权限。右键点击 PowerShell 图标，选择“以管理员身份运行”，执行完后，再用普通用户身份打开新窗口进行后续操作。这样做的好处是，即使未来你在这个目录下运行了恶意脚本，它的危害也仅限于该目录，无法影响系统其他部分。

2.3 npm 全局缓存与权限：一次清理，永久省心

Windows 上 npm 的全局安装（npm install -g）经常失败，报错EPERM: operation not permitted或EACCES: permission denied。根源在于 npm 默认将全局模块安装到C:\Users\<用户名>\AppData\Roaming\npm，而该路径受 Windows UAC（用户账户控制）保护，普通用户没有写入权限。强行用管理员运行 PowerShell 安装，又会导致后续npx调用时权限不一致。

解决方案是：将 npm 的全局安装目录重定向到一个你完全拥有控制权的路径。这是 Windows Node.js 开发者的必备操作。

  1. 创建新的全局目录：在D:\openclaw\npm-global创建文件夹。
  2. 配置 npm 使用新目录：
    npm config set prefix "D:\openclaw\npm-global" npm config set cache "D:\openclaw\npm-cache"
  3. 将新目录加入系统 PATH：打开“系统属性 > 高级 > 环境变量”，在“用户变量”中找到PATH，点击“编辑”，然后“新建”，填入D:\openclaw\npm-global。务必确认这个新路径在C:\Users\<用户名>\AppData\Roaming\npm之前。
  4. 重启 PowerShell 并验证：
    npm config get prefix # 应输出 D:\openclaw\npm-global npm list -g --depth=0 # 应为空，表示全局模块已清空

完成这三步后，你再执行npm install -g openclaw，所有的文件都会被写入D:\openclaw\npm-global，不再触发 UAC 弹窗，也不会出现权限错误。这是一个一劳永逸的设置，不仅对 OpenClaw 有效，对你未来安装任何全局 npm 工具（如serve、http-server）都适用。

3. OpenClaw 安装与启动：npx不是万能钥匙，start.ps1才是 Windows 的“正确姿势”

OpenClaw 的官方 README 推荐使用npx openclaw启动，这在 macOS/Linux 上非常优雅。但在 Windows 上，npx的行为存在一个隐蔽的缺陷：它会尝试在%TEMP%目录下创建一个临时的node_modules，而%TEMP%路径通常包含空格（如C:\Users\John Doe\AppData\Local\Temp），并且其父目录AppData是隐藏的。PowerShell 在解析带空格的路径时，如果未加引号，会将其截断，导致npx找不到正确的openclaw可执行文件，最终静默失败，或者报出Cannot find module 'openclaw'这样的误导性错误。

因此，在 Windows 上，必须放弃npx，转而使用 OpenClaw 仓库自带的start.ps1脚本。这个脚本是专门为 Windows 设计的，它内部做了三件事：第一，自动检测并切换到正确的 Node.js 版本；第二，为node进程设置NODE_OPTIONS=--no-warnings，屏蔽掉无关的 TLS 警告；第三，最关键的是，它会将当前工作目录（即你存放start.ps1的目录）作为openclaw的根目录，从而完美规避了路径空格问题。

3.1 下载与初始化：Git Clone 是唯一可靠的方式

不要试图用npm install -g openclaw安装全局命令，因为 OpenClaw 的设计是“配置驱动”，它的核心是config.yaml文件，而全局安装会把这个配置文件放在一个你无法轻易访问的位置（%APPDATA%\npm\node_modules\openclaw\config.yaml），修改起来极其痛苦。

正确的做法是：

  1. 确保 Git 已安装：打开 PowerShell，运行git --version。如果未安装，请从 https://git-scm.com/download/win 下载并安装，安装时选择 “Use Git from Windows Command Prompt”，这样 PowerShell 也能识别git命令。
  2. 克隆仓库到你的工作目录：
    cd D:\openclaw git clone https://github.com/openclaw-org/openclaw.git . # 注意最后的点（.），它表示克隆到当前目录，而不是创建一个子文件夹
  3. 检查克隆结果：运行ls，你应该看到config.yaml、start.ps1、package.json等文件直接位于D:\openclaw下。如果看到一个openclaw子文件夹，说明你漏掉了最后的点，需要删除整个目录重新克隆。

3.2 配置config.yaml：从“空白模板”到“可用网关”的三步填充

config.yaml是 OpenClaw 的心脏，它定义了网关如何工作。官方提供的模板是空的，你需要根据你的后端模型服务来填写。最常见的场景是：你已经在本地用 Ollama 运行了qwen2:7b模型，现在想让 VS Code 的 Copilot 插件通过 OpenClaw 访问它。

一个最小可用的config.yaml如下：

# D:\openclaw\config.yaml server: port: 1572 host: "127.0.0.1" providers: - name: "ollama-qwen" type: "ollama" base_url: "http://127.0.0.1:11434" model: "qwen2:7b" # 如果你的 Ollama 模型需要特定的 system prompt，可以在这里设置 # system_prompt: "You are a helpful assistant." routes: - path: "/v1/chat/completions" provider: "ollama-qwen" # 这里可以添加中间件，比如日志记录 middleware: - "logger"

这个配置的每一行都至关重要：

  • server.port: 1572：这是 OpenClaw 对外暴露的端口。热词中反复出现的http://127.0.0.1:1572就是它。请确保这个端口没有被其他程序占用。你可以用netstat -ano | findstr :1572来检查。
  • providers下的base_url：必须与你后端服务的实际地址完全一致。Ollama 默认是http://127.0.0.1:11434，LM Studio 是http://127.0.0.1:1234，Text Generation WebUI 是http://127.0.0.1:5000。一个常见的错误是，把base_url写成了http://localhost:11434。在 Windows 上，localhost和127.0.0.1虽然通常指向同一地址，但某些网络栈（尤其是启用了 IPv6 的环境）下，localhost可能会先尝试解析为::1（IPv6 回环），而你的后端服务可能只监听了 IPv4 的127.0.0.1，导致连接超时，最终表现为 502。
  • routes：定义了 URL 路径到后端提供者的映射。/v1/chat/completions是 OpenAI 兼容 API 的标准路径，几乎所有客户端（Copilot、Cursor、Dify）都认这个。provider: "ollama-qwen"必须与上面providers中的name完全一致，包括大小写和连字符。

提示：如果你的后端服务需要 API Key（比如某些私有部署的 vLLM），你可以在providers下添加api_key: "your-secret-key"字段。OpenClaw 会自动将这个 key 添加到转发请求的Authorization头中。

3.3 启动与实时日志：如何让start.ps1真正“跑起来”

现在，一切就绪。打开 PowerShell，进入D:\openclaw目录，执行：

.\start.ps1

如果一切顺利，你会看到类似这样的输出：

[INFO] Starting OpenClaw server on http://127.0.0.1:1572 [INFO] Loaded provider: ollama-qwen (type: ollama) [INFO] Route registered: /v1/chat/completions -> ollama-qwen [INFO] Server listening on port 1572

这表示 OpenClaw 已成功启动。但请注意，这个窗口必须保持打开状态，一旦关闭，服务就停止了。为了验证它是否真的在工作，打开另一个 PowerShell 窗口，执行一个简单的健康检查：

# 使用 curl（PowerShell 7+ 自带）或 Invoke-WebRequest curl -X GET http://127.0.0.1:1572/health # 或者 Invoke-WebRequest -Uri "http://127.0.0.1:1572/health" -Method GET

如果返回{"status":"ok"}，恭喜，网关层已经通了。接下来，你可以用curl模拟一个真正的聊天请求：

$payload = @{ model = "ollama-qwen" messages = @(@{role="user"; content="你好"}) } $payloadJson = $payload | ConvertTo-Json -Depth 10 curl -X POST http://127.0.0.1:1572/v1/chat/completions ` -H "Content-Type: application/json" ` -Body $payloadJson

如果这个请求返回了 JSON 格式的响应（包含choices[0].message.content），那么你的 OpenClaw 就已经可以投入生产使用了。如果返回 502，不要慌，这正是我们下一步要解决的——精准定位 502 的源头。

4. 502 Bad Gateway 故障排查：从“未知错误”到“定位元凶”的完整链路

unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572这个错误信息之所以让人绝望，是因为它把所有可能的失败原因都压缩成了一句话。在 OpenClaw 的上下文中，“502” 意味着网关（OpenClaw）成功启动了，但它在尝试连接后端（Ollama/LM Studio）时失败了。失败的原因千差万别，从网络不通，到后端崩溃，再到认证失败。下面是我总结的、经过数十次实战验证的四层排查法，它能帮你像剥洋葱一样，一层层揭开真相。

4.1 第一层：确认 OpenClaw 进程是否真正在监听 1572 端口

这是最容易被忽略的一步。你以为start.ps1运行了，就代表服务起来了。但事实上，start.ps1可能因为各种原因（如config.yaml语法错误、Node.js 版本不匹配）在启动过程中就崩溃了，只是 PowerShell 窗口没有关闭，让你误以为它还在运行。

诊断命令：

# 查看所有监听 1572 端口的进程 netstat -ano | findstr :1572 # 如果有输出，会显示类似： TCP 127.0.0.1:1572 0.0.0.0:0 LISTENING 12345 # 其中的 12345 就是进程 ID (PID) # 根据 PID 查看进程名 tasklist | findstr "12345" # 如果输出中包含 "node.exe"，说明 OpenClaw 进程确实在运行。 # 如果没有任何输出，或者输出的是其他进程（如 "java.exe"），说明 OpenClaw 根本没起来。

常见问题与修复：

  • 问题：netstat无输出。
    修复：回到start.ps1的输出日志，仔细查找是否有红色的ERROR或FATAL字样。最常见的原因是config.yaml中的port字段被写成了字符串"1572"（带引号），而 YAML 规范要求数字不加引号。把它改成port: 1572即可。

  • 问题：netstat有输出，但tasklist显示的是conhost.exe。
    修复：这表明start.ps1脚本本身卡住了，没有真正 fork 出node进程。通常是 PowerShell 执行策略未正确设置，或者start.ps1文件的编码格式不是 UTF-8（无 BOM）。用 VS Code 打开start.ps1，点击右下角的编码格式（如UTF-8），选择“通过编码重新打开”，然后选择UTF-8（无 BOM），保存。

4.2 第二层：测试 OpenClaw 到后端的“最后一公里”连接

假设 OpenClaw 进程确实在运行，那么 502 就一定是它连接后端失败了。我们需要绕过 OpenClaw，直接测试从你的 Windows 机器到后端服务的连通性。

诊断命令（以 Ollama 为例）：

# 测试基础连通性 Test-NetConnection -ComputerName 127.0.0.1 -Port 11434 # 如果上面返回 True，再测试 HTTP 层 curl -X GET http://127.0.0.1:11434/api/tags # 如果上面返回了 JSON（列出所有模型），说明后端服务正常。 # 如果返回 "Unable to connect" 或超时，说明后端没开，或者防火墙挡住了。

常见问题与修复：

  • 问题：Test-NetConnection返回False。
    修复：首先确认后端服务（Ollama）是否真的在运行。打开任务管理器，看是否有ollama.exe进程。如果没有，运行ollama serve启动它。其次，检查 Windows 防火墙：进入“控制面板 > Windows Defender 防火墙 > 允许应用或功能通过 Windows Defender 防火墙”，找到ollama.exe，确保“专用”和“公用”网络都已勾选。

  • 问题：curl返回404 Not Found。
    修复：这通常意味着后端服务的 API 路径变了。Ollama 的模型列表 API 是/api/tags，不是/v1/models。请查阅你所用后端服务的最新文档，确认其健康检查和模型列表的 endpoint。

4.3 第三层：捕获 OpenClaw 的详细错误日志

如果前两层都通过了，但curl到http://127.0.0.1:1572/v1/chat/completions依然返回 502，那问题就出在 OpenClaw 的转发逻辑里。默认情况下，OpenClaw 的日志级别是INFO，它只会告诉你“连接失败”，但不会告诉你“为什么失败”。

开启详细日志：

  1. 打开config.yaml，在server部分下方添加log_level字段：
    server: port: 1572 host: "127.0.0.1" log_level: "debug" # 新增这一行
  2. 重启start.ps1。
  3. 再次发起一个curl请求，然后立即查看 PowerShell 窗口中的输出。

典型 debug 日志解读：

  • DEBUG Provider ollama-qwen: Making request to http://127.0.0.1:11434/api/chat
    这表示 OpenClaw 正在尝试连接后端，路径是正确的。
  • ERROR Provider ollama-qwen: Request failed: Error: connect ECONNREFUSED 127.0.0.1:11434
    这是经典的“连接被拒绝”，说明后端进程虽然在，但没有监听127.0.0.1:11434，可能只监听了0.0.0.0:11434或::1:11434。解决方案是在 Ollama 的启动命令中加上-H 127.0.0.1:11434。
  • ERROR Provider ollama-qwen: Request failed: Error: socket hang up
    这通常意味着后端服务接收到了请求，但在处理过程中崩溃了。检查后端服务的日志，很可能是模型加载失败或显存不足。

4.4 第四层：模拟请求，验证 OpenAI 兼容性

有时候，502 并非来自网络层，而是来自协议层。你的后端服务可能返回了一个 OpenClaw 无法解析的响应体。例如，某些老版本的 Text Generation WebUI 会返回{"error": "..."}，而 OpenClaw 期望的是标准的 OpenAI 格式{"choices": [...]}。

终极验证方法：用curl直接向 OpenClaw 发送一个最简请求，并用--include参数查看完整的 HTTP 响应头：

$payload = @{ model = "ollama-qwen" messages = @(@{role="user"; content="test"}) } $payloadJson = $payload | ConvertTo-Json -Depth 10 curl -X POST http://127.0.0.1:1572/v1/chat/completions ` -H "Content-Type: application/json" ` -H "Authorization: Bearer dummy-token" ` -Body $payloadJson ` --include

观察输出的HTTP/1.1 502 Bad Gateway响应头之后，是否跟着一个X-OpenClaw-Error头。如果有，它的值就是 OpenClaw 内部捕获到的原始错误，比如X-OpenClaw-Error: Failed to parse response from provider，这直接指明了问题所在。

提示：Authorization: Bearer dummy-token这个头是必须的。OpenClaw 的默认配置开启了 token 鉴权，即使你没在config.yaml中配置auth，它也会检查这个头。热词中unauthorized: gateway token missing就是这个原因。最简单的解决办法，是在config.yaml的server部分添加auth: false，禁用鉴权。

5. 实战接入：让 VS Code Copilot 和 Dify 真正用上你的本地模型

当 OpenClaw 成功返回{"status":"ok"}并能处理curl请求后，真正的价值才开始体现。下面是以两个最常用场景为例，展示如何将 OpenClaw 无缝集成到你的日常开发流中。这不仅仅是“配置一个 URL”，而是要理解每个工具的认证机制和协议细节，避免那些“明明配置对了却没反应”的玄学问题。

5.1 VS Code Copilot：从“云端订阅”到“本地免费”的平滑切换

VS Code 的 Copilot 插件（v1.200+）原生支持自定义端点。但它的配置界面藏得很深，而且对 URL 格式有严格要求。

配置步骤：

  1. 在 VS Code 中，按Ctrl+Shift+P打开命令面板，输入Preferences: Open Settings (JSON)，回车。
  2. 在打开的settings.json文件中，添加以下配置：
    { "github.copilot.advanced": { "proxy": "http://127.0.0.1:1572", "useCustomEndpoint": true, "customEndpoint": "http://127.0.0.1:1572" } }
    关键点：proxy和customEndpoint必须同时设置，且值必须完全相同。proxy字段告诉 Copilot 的底层网络库走这个代理，customEndpoint则告诉它的业务逻辑，所有/v1/chat/completions请求都发到这里。
  3. 重启 VS Code。

验证与排错：

  • 现象：重启后，Copilot 的状态栏图标变成灰色，提示“Copilot is disabled”。
    原因：Copilot 插件在启动时，会向http://127.0.0.1:1572/v1/models发送一个预检请求，以确认网关是否支持模型列表。而 OpenClaw 默认不实现这个 endpoint。
    修复：在config.yaml的routes部分，添加一条新路由：

    routes: - path: "/v1/models" provider: "ollama-qwen" # 这个 provider 可以是任意一个，因为 /v1/models 是只读的，OpenClaw 会返回一个固定的模型列表 middleware: - "models-list"

    然后重启start.ps1。这个models-list中间件是 OpenClaw 内置的，它会返回一个包含ollama-qwen的 JSON 数组。

  • 现象：Copilot 能弹出建议，但内容全是乱码或英文。
    原因：你的后端模型（如qwen2:7b）是中文模型，但 Copilot 的请求中messages的content字段被编码成了 UTF-8 的字节序列，而某些版本的 OpenClaw 在转发时没有正确处理编码。
    修复：升级 OpenClaw 到最新版（git pull），并在config.yaml中为providers添加encoding: "utf8"字段。

5.2 Dify：利用 OpenClaw 绕过“在线升级”限制，实现纯离线部署

Dify 的社区版（v1.0+）支持自定义 LLM Provider，但它的 UI 表单只接受Base URL和API Key。而 OpenClaw 本身不需要 API Key，它需要的是一个“模型别名”。

配置步骤：

  1. 登录 Dify Web UI，进入Settings > Model Providers。
  2. 点击+ Add Model Provider，选择OpenAI类型。
  3. 填写：
    • Provider Name:OpenClaw Local
    • Base URL:http://127.0.0.1:1572
    • API Key:sk-1234567890（任意字符串，OpenClaw 会忽略它，但 Dify 的表单要求必填）
  4. 点击Save，然后在Model List中，点击+ Add Model。
  5. 填写：
    • Model Name:ollama-qwen（必须与config.yaml中providers.name完全一致）
    • Provider:OpenClaw Local
    • Credentials: 留空（因为 API Key 已在 Provider 级别填过）

验证与排错：

  • 现象：在 Dify 的 Playground 中测试，返回Gateway returned an error: your connection works, but the provider rejected a request。
    原因：这是 Dify 的一个已知 Bug，它在发送请求时，会把model字段的值硬编码为gpt-3.5-turbo，而不是你在Model Name中填写的ollama-qwen。OpenClaw 收到一个不认识的模型名，自然会拒绝。
    修复：这是一个前端层面的限制，无法通过配置解决。你需要在 Dify 的后端代码中打一个