Windows 原生 + 原生 Ollama + 官方 OpenClaw 2026.3.11-beta.1推荐部署方案

这份指南针对的是 官方 openclaw。openclaw-cn 在 npm 页面明确写了“非官方 cn 版本”。如果你机器上混用了 openclaw 和 openclaw-cn，最容易出现的就是命令、配置目录、认证行为不一致。默认你统一使用官方版。(OpenClaw)

我把路线分成两层。主线给你的是 Windows 原生 + Windows 原生 Ollama + 官方 OpenClaw，避免 WSL2 和 Windows 主机之间再做一层联网配置。默认你已经在 Windows 上把 Ollama 跑通了，这条路最省事，与此同时，官方文档仍然把 WSL2 视为 Windows 上的推荐路径，因为运行时一致性更好、Linux 工具链兼容性更强、技能和依赖问题更少；这个我放在附录最后单列。(OpenClaw)

---

一、推荐部署方案：Windows 原生 + 原生 Ollama + 官方 OpenClaw 2026.3.11-beta.1

1) 先把前置环境补齐

官方要求 Node 22.16+，推荐 Node 24；Windows 原生安装时还建议把 Git for Windows 放进 PATH，否则常见报错就是 spawn git / ENOENT。官方安装脚本会自动处理 Node 检测与安装，但 Git/PATH 这类 Windows 基础问题仍然要你本机环境正确。(OpenClaw)

建议你先在 PowerShell 里确认：

node -v
npm -v
git --version
ollama --version

这样做的原因很简单：后面 OpenClaw 的安装、升级和插件同步都依赖 Node/npm；Git 则是安装器和某些更新/插件流程的基础依赖。Ollama 既然你已经跑通，这一步主要是把环境状态固化下来。(OpenClaw)

---

2) 先安装官方 OpenClaw，再锁定到你要的 beta 版本

官方 Windows 快速安装方式是 PowerShell 安装脚本：

iwr -useb https://openclaw.ai/install.ps1 | iex

官方把这个脚本列为 Windows 推荐安装入口；它会处理 Node 检测、OpenClaw 安装，并可进入 onboarding。(OpenClaw)

安装完后，不要直接停在“当前最新”状态，而是显式锁定到你指定的版本：

openclaw update --tag 2026.3.11-beta.1
openclaw --version

之所以这样做，而不是泛泛地“装 beta”，是因为官方 update 命令支持 --tag <dist-tag|version>，这能把你固定到确切版本，避免后来又被切到更新的 beta。(OpenClaw)

如果你以后想改回正式通道，用：

openclaw update --channel stable

如果想继续跟 beta 通道滚动，用：

openclaw update --channel beta

这是官方通道切换方式。(OpenClaw)

---

3) 先验证 Ollama API，而不是只验证 ollama run

OpenClaw 接的是 Ollama 的 HTTP API，不是 CLI 交互。官方文档对 Ollama 集成写得很清楚：OpenClaw 使用 Ollama 的原生 API（/api/chat），自动发现模型时会去查 /api/tags，并尽量读取 /api/show。所以，ollama run 能对话，不等于 OpenClaw 一定能接进去。(OpenClaw)

先检查：

ollama list
curl http://localhost:11434/api/tags

如果 curl 返回模型列表 JSON，说明 OpenClaw 以后要用的那条链路是通的。官方在 Ollama troubleshooting 里给的也是这条检查方式。(OpenClaw)

---

4) 设置 OLLAMA_API_KEY，即使本地 Ollama 实际并不需要真实密钥

这是很多人第一次踩坑的点。官方文档明确说，OpenClaw 对 Ollama 的隐式发现模式依赖 OLLAMA_API_KEY（或者 auth profile）这个“开启信号”；当你设置了它，而且没有手写 models.providers.ollama，OpenClaw 才会从 http://127.0.0.1:11434 自动发现本地模型。它不是在说 Ollama 本身需要鉴权，而是在说 OpenClaw 的 provider discovery / availability check 需要这个 opt-in 标记。(OpenClaw)

在 PowerShell 里建议这样设为当前用户永久变量：

[Environment]::SetEnvironmentVariable("OLLAMA_API_KEY", "ollama-local", "User")

当前窗口立即生效再补一遍：

$env:OLLAMA_API_KEY = "ollama-local"

然后新开一个 PowerShell，确认：

echo $env:OLLAMA_API_KEY

我这里用 ollama-local 只是占位字符串。原因不是“给 Ollama 授权”，而是满足 OpenClaw 的本地 provider 发现逻辑。官方文档给出的最简示例也是设置这个环境变量。(OpenClaw)

---

5) 不要一开始就手写 models.providers.ollama

如果你的场景只是“本机 Windows 上的 Ollama，端口默认 11434，模型已经在本地”，那一开始不要自己定义 models.providers.ollama。官方文档明确写了：一旦你显式定义了这个 provider，自动发现就会被关闭，你必须手工维护模型列表、上下文窗口等字段。(OpenClaw)

这也是我推荐你走“隐式发现模式”的原因。它最适合当前场景，配置最少，出错面最小，后续 ollama pull 新模型后，OpenClaw 也能跟着发现。(OpenClaw)

---

6) 跑 onboarding，并安装 Gateway 服务

安装完成后，按官方推荐执行：

openclaw onboard --install-daemon

官方把这条命令列为推荐路径；它会处理模型/认证、workspace、Gateway 设置、可选的消息渠道、守护服务安装、健康检查和技能选择。(OpenClaw)

这里给你一个建议选项策略，以及为什么这样选：

1. 模型提供方选 Ollama，本地模式优先。
   原因：你当前目标是先把本地 Windows + Ollama 跑稳，避免把云模型、OAuth、外部账单一起引入。官方也支持本地模型优先。(OpenClaw)

2. primary model 先选你已经验证过的一个模型。
   例如 ollama/qwen2.5:14b 或你 ollama list 里真实存在的模型。OpenClaw 的模型引用语法是 provider/model，官方示例就是 ollama/llama3.3 这种形式。(OpenClaw)

3. Gateway 先只绑定本机，不要暴露到公网。
   这一步是为了把问题域缩到最小：先证明“本机 Dashboard/本机 agent 能跑”，再去接 Telegram/Discord/远程设备。官方 Windows 原生路径本来也更适合先做本机 CLI 和本机 Gateway 验证。(OpenClaw)

4. Daemon/service 安装选 Yes。
   原因：官方推荐 --install-daemon，这样 Gateway 会由系统接管，后续你只需要查状态和重启，不需要每次手动拉前台进程。Windows 原生下会先尝试 Scheduled Task，失败再回退到当前用户 Startup 文件夹。(OpenClaw)

5. 频道（Telegram/WhatsApp/Discord 等）先跳过。
   原因：你现在的目标是先解决本地模型链路；很多“看起来像模型问题”的报错，实际是在频道层、pairing、gateway 暴露策略或 token 层。官方 FAQ 也把 onboarding 里的 channel/provider/gateway 分成了不同阶段。先把本地 Dashboard 跑通再接频道，排障更干净。(OpenClaw)

6. 技能和插件先最小化。
   原因：你当前优先级是模型链路，不是扩展功能。插件可以后装，官方也支持安装后再启用。(OpenClaw)

---

7) 安装后做四个验证动作

官方 Getting Started 给出的检查动作包括 gateway status 和 dashboard。我建议你按下面顺序做：(OpenClaw)

openclaw gateway status
openclaw models list
openclaw dashboard
openclaw --version

接着把 primary model 再显式指定一遍：

openclaw models set ollama/你的模型名

OpenClaw 官方 Ollama 文档和模型文档都给出了 openclaw models list / openclaw models set <provider/model> 的方式。这样做的意义是把“环境变量已设、模型已发现、默认模型已绑定”三件事一次性坐实。(OpenClaw)

在 Windows 原生上，还可以跑一个官方文档给出的 smoke test：

openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."

这是官方 Windows 页面给出的原生 CLI smoke 测试，用来确认本地 agent/provider 最基础链路正常。(OpenClaw)

---

8) 只在需要时再编辑 openclaw.json

OpenClaw 的主配置文件是 ~/.openclaw/openclaw.json，官方说明 Gateway 会监视这个文件并做热重载；默认重载模式是 hybrid，安全变更热应用、关键变更自动重启。(OpenClaw)

在你已经走完 onboarding 的前提下，建议只做一个最小编辑：确认默认主模型被固定住。例如：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/你的模型名"
      }
    }
  },
  "gateway": {
    "reload": {
      "mode": "hybrid",
      "debounceMs": 300
    }
  }
}

改动选项解释：
primary 是你当前最关键的业务选择；hybrid 是官方默认推荐的折中模式，避免你每次改一点小配置都手工重启。(OpenClaw)

---

9) 可选的“先求稳”配置：先禁掉高风险工具

如果你当前只是想把本地模型作为聊天、代码、基础问答代理跑起来，而不是一上来就让它操作浏览器或系统工具，可以在 openclaw.json 里先加一个最小 denylist，例如：

{
  "tools": {
    "deny": ["browser"]
  }
}

官方工具文档明确支持 tools.allow / tools.deny。这样做的原因不是功能上必须，而是把问题空间缩小：先验证模型本身可用，再逐步把工具打开。(OpenClaw)

---

10) 后续更新策略

后续如果你还想继续停在 beta 线，用：

openclaw update --channel beta

如果想切回正式稳定线，用：

openclaw update --channel stable

如果只是升级安装但不想重新跑 onboarding，官方推荐“重新跑官网安装器”做原地升级；也可以直接走 openclaw update。(OpenClaw)

---

二、这份指南这么配的优势

第一，没有把 ollama launch openclaw 作为主路径。Ollama 官方集成页确实把它写成 quick start，但 2026-03-02 的官方 GitHub issue 报告了一个回归：通过这条路径启动时，本地 Ollama 模型可能会在 Web UI 一直显示 typing、不返回内容。对已经有本地 Ollama，想稳定部署 OpenClaw的场景，直接装官方 OpenClaw CLI 并显式控制版本/配置，可诊断性更强。(Ollama 文档)

第二，优先走 隐式发现，而不是一开始就写 models.providers.ollama。因为官方已经说明：你只要给 OLLAMA_API_KEY 这个 opt-in 标记，并且不手写 provider，OpenClaw 就会自动从本地 Ollama 做模型发现。当前你的场景最适合这种模式。(OpenClaw)

第三，坚持使用 原生 Ollama API URL，即 http://127.0.0.1:11434，而不是 /v1。官方文档明确警告：OpenAI-compatible /v1 模式下，工具调用不可靠，可能把工具 JSON 当纯文本吐出来；只有在代理/兼容层强制要求 OpenAI 格式时才建议这样做。(OpenClaw)

第四，先跑本机 Gateway 和 Dashboard，再接 Telegram/Discord。原因不是“功能少”，而是把排障链路切短。官方 FAQ 也表明 onboarding 本身就涉及模型、workspace、gateway、channels、daemon、skills 多个环节；把这些同时打开，出问题时最难定位。(OpenClaw)

---

三、附录：最常见疑难问题与处理顺序

附录 A：No API key found for provider "ollama" 怎么办

官方文档给出的根因路径很明确：如果要走 Ollama 的隐式发现模式，必须设置 OLLAMA_API_KEY 或 auth profile；如果没设，或者 provider 配置切到了显式模式但没补全模型定义，就会出现检测或认证层面的异常。官方 troubleshooting 也直接把“先确保 Ollama 在跑、已设置 OLLAMA_API_KEY、且未定义显式 models.providers.ollama”列为检查项。(OpenClaw)

按这个顺序处理最有效：

1. 先确认本机 API 通：

   curl http://localhost:11434/api/tags
   

2. 确认当前 shell 和用户环境里都有 OLLAMA_API_KEY。

3. 确认你没有手写 models.providers.ollama；如果写了，先删掉，让它回到隐式发现。

4. 重新执行：

   openclaw onboard --install-daemon
   openclaw models list
   openclaw gateway restart
   

5. 再测一次本地 agent / dashboard。(OpenClaw)

需要你心里有数的是，这个错误在 2026.2.x 到 2026.3.x 期间，官方仓库里确实有多条活跃/近期 issue，说明它不总是纯粹的“你配错了”，也可能是版本回归。比如 2026.2.19-2 的 issue #22055 就报告了：即便模型检测、auth store、默认模型都看起来正常，Telegram/Web UI 仍然可能在回复前报 No API key found for provider "ollama"。所以如果你严格按上面步骤做了仍重现，不要在同一个坏状态上死磕，优先切回 2026.3.11 正式版或更新的正式版再测。(GitHub)

---

附录 B：Ollama not detected / No models available

官方处理逻辑很直接：
先看 Ollama 进程，再看 /api/tags，再看本地模型是否真已 pull 下来。没有模型时，OpenClaw 也只会告诉你“没有可用模型”，因为自动发现依赖的就是本地模型清单。(OpenClaw)

处理方式：

ollama serve
ollama list
ollama pull 你的模型名
openclaw models list

只要 ollama list 里有，且你走的是隐式发现，openclaw models list 理论上就该能看到相应的 ollama/... 模型。(OpenClaw)

---

附录 C：上下文窗口被识别成 4096，报 “context window too small”

这个不是空想问题，官方仓库里有对应 issue。有人在 2026.2.x/2026.3.x 遇到 OpenClaw 把本来更大的 Ollama 模型窗口识别成 4096，从而在 agent 启动前直接阻断。官方 Ollama 文档同时说明：如果你走显式 provider 配置，可以自己覆盖 contextWindow 和 maxTokens。(GitHub)

因此处理策略是：

1. 先尝试隐式发现，避免自己把配置写坏。
2. 如果仍识别错误，再切到显式 provider 配置，手工指定 contextWindow 和 maxTokens。
3. 如果即便显式配置仍被强制压到异常值，那更像是版本级 bug，不是你的 JSON 写法问题。(GitHub)

---

附录 D：本地模型一直 typing、无输出、或者挂起

这个在 2026.3.x 里也不是孤例。官方 issue 里至少出现过三类相近现象：
一类是 ollama launch openclaw 路径下本地模型不回包；一类是 2026.3.8 本地模型在会话里超时零输出；一类是 Telegram 场景里一直显示 typing 却没有可见错误。(GitHub)

我建议你按这个顺序排：

1. 先脱离频道，只在 Dashboard 或 openclaw agent --local 里测。
2. 先别用 ollama launch openclaw。
3. 坚持原生 Ollama API，不要主动切 /v1。
4. 确认模型本身在 ollama run 和 curl /api/chat 下真的能稳定输出。
5. 只有在你明确遇到某个 2026.3.x 分支的 native api: "ollama" 回归时，才把 /v1 视为临时排障手段，而不是正式配置。因为官方文档已经明确把 /v1 定义成“Legacy OpenAI-Compatible Mode”，并提示它会损伤工具调用可靠性；恰好也有 2026.3.x 的 issue 报告把 /v1 当作临时 workaround。(OpenClaw)

---

附录 E：auth-profiles.json 丢失、重置、升级后又坏

这同样有近期 issue。有人报告升级后 auth-profiles.json 被重置，结果反复触发 No API key found for provider "ollama"；也有人报告子代理/子会话拿不到 Ollama 凭据，甚至出现意外回退。(GitHub)

稳妥做法是：

1. 每次升级前备份 ~/.openclaw。

2. 升级后立即跑：

   openclaw --version
   openclaw models list
   openclaw gateway status
   

3. 一旦再次出现 Ollama auth 报错，先别改十几处配置，先重新检查 OLLAMA_API_KEY 和 agent 级 auth store 路径。官方安全文档给出的模型认证文件路径是 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json。(OpenClaw)

---

附录 F：Windows 上 git not found / openclaw is not recognized

这是官方 FAQ 直接列出来的两个 Windows 常见问题。
git not found：装 Git for Windows，并确保 git 在 PATH。
openclaw is not recognized：检查 npm config get prefix，把那个目录加入用户 PATH；Windows 下一般是 %AppData%\npm，而且不要自己再加 \bin。改完后重新开 PowerShell。(OpenClaw)

---

附录 G：Windows 终端中文乱码

官方 FAQ 也给了 PowerShell 临时修复方案。若你看到 exec/output 中文乱码，先切 UTF-8，再重启 Gateway：(OpenClaw)

chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

openclaw gateway restart

---

附录 H：Gateway 服务不自启

Windows 原生下，官方文档说明 openclaw gateway install 会优先尝试 Windows Scheduled Tasks；如果创建被拒绝，就会回退到当前用户的 Startup 文件夹登录项。Scheduled Tasks 仍是首选，因为状态管理更好。(OpenClaw)

检查命令：

openclaw gateway install
openclaw gateway status --json

如果你只是想做本机前台调试，而不需要系统托管，可以直接：

openclaw gateway run

官方 Windows 页面也给出了这种“native CLI only”的路径。(OpenClaw)

---

附录 I：WSL2 备用方案，适合追求更高兼容性的部署

官方对 Windows 的总建议仍然是 WSL2。原因是 CLI + Gateway 在 Linux 用户态里更一致，Node/Bun/pnpm、Linux 二进制、skills 都更兼容。官方给出的 WSL2 基本链路是：wsl --install，启用 systemd，然后在 WSL 里安装和运行 OpenClaw。(OpenClaw)

最短步骤是：

wsl --install

进 WSL 后启用 systemd：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

然后在 Windows PowerShell 里：

wsl --shutdown

再回到 WSL 安装 OpenClaw 并跑 onboarding。官方 WSL 页面给了源码安装示例，也明确说在 WSL2 里使用 openclaw onboard --install-daemon / openclaw gateway install 是正式支持路径。(OpenClaw)