OpenClaw 安装：先选 Quick Start、Windows、macOS、Linux 或 Docker

截至 2026-09-13，当前常规 stable / npm latest 是 v2026.9.4。v2026.6.35 仍属于 extended-stable 的 June 维护线，不会替代 9.4；两条渠道的区别见版本中心。

9.3 引入的 Node 运行时门槛在 9.4 继续有效；9.4 重点补上 CLI 私有 Node 与 stale Gateway service runtime 的恢复路径。旧环境升级前仍先跑 node -v。

先把三个概念分开：

• Desktop Companion：桌面交互、托盘 / Quick Chat、连接管理和设备能力入口；可以连接本地或远程 Gateway。
• CLI / Gateway：真正承载 OpenClaw 服务、会话、模型与渠道的核心运行路径，适合终端和常驻服务。
• Docker / VPS：用于远程常驻、隔离、可重复运维；不是普通桌面用户的默认前置条件。

Quick Start：继续作为快速验证入口

fresh install，包括：

npx openclaw@latest

可以进入 Quick Start。OpenClaw 会寻找机器上已经可用的 Claude Code / Codex 登录或已有 provider key，并做真实验证；确认一个可用选择后，可以启动前台 Gateway 并打开 Web Dashboard。

9.3 起的 setup 强调显式 provider 选择：检测到可用 provider 不等于自动激活；连接失败或取消也不应悄悄切到另一套凭据。

这条路径仍有几个容易被误解的边界：

• foreground Gateway 能聊天，不代表已经安装常驻 service。 service / daemon 仍是后续显式动作。
• 检测到配置不代表直接信任，官方路径会做可用性检查；失败或取消不应覆盖之前可用的配置。
• headless / VPS 给出的 authenticated dashboard link 与 SSH tunnel 是管理入口，不应改造成长期共享 Gateway credential。
• 需要精细选择 provider、runtime、网络和权限时，继续用完整 Custom setup，不要为了少几步跳过边界设计。

9.2 引入的本地模型引导，9.4 继续有效

managed local-model setup 会读取运行 OpenClaw 那台机器的内存、GPU 与磁盘条件，再给出更合适的本地模型建议。

官方最小 recipe 有 8 GiB 级别资源门槛。激活前不仅验证模型能输出文字，还会执行真实文件读取工具测试；失败或取消时保留之前的默认模型，不把一个没有验证通过的本地路线硬切成 primary。

对于较小的本地模型，OpenClaw 会使用更精简的工具集合来减少 schema 与上下文压力。多 Agent Gateway 不要为了一个小模型随意改共享 defaults，否则可能同时影响其他 Agent。

先选安装路径

环境	推荐起点	什么时候选它
已有 Claude Code / Codex / provider key	Quick Start	想最快验证 OpenClaw 是否能工作，再决定是否装 service
Windows 10 20H2+ / Windows 11	Windows Hub / CLI	想要原生 GUI，或明确需要命令行 Gateway
macOS	macOS Companion / Quick Start	普通桌面使用；需要脚本化再装 CLI
Linux x86-64 桌面	Linux Desktop Companion / CLI	想用托盘、Quick Chat，或连接本地 / 远程 Gateway
Linux 服务器 / Headless	CLI / Gateway	VPS、SSH、systemd user service、无桌面环境
VPS / 强隔离环境	Docker / Podman	需要容器化部署、隔离和可重复运维

Node.js：9.4 仍沿用当前硬要求

官方当前支持：

• Node.js 24.16.0+，仅 24.x；
• Node.js 26.1.0+；
• Node 26 是官方推荐运行时；
• Node 22、23、25 不支持；
• Node 24 低于 24.16.0、Node 26 低于 26.1.0 也不支持。

官方明确建议先升级 Node，再更新 OpenClaw，用于避免 SQLite TEXT truncation 风险。

先检查：

node -v

如果当前交互式 CLI 运行在不兼容 Node 上，9.4 可以发现机器上已有的兼容 Node，或在用户确认后为 OpenClaw 安装私有 runtime；交互路径也可以出现类似提示：

Update NodeJS: Y/N [N]:

选择 Y 时会使用 OpenClaw 自己的兼容 Node runtime 并重试当前命令；它不会为了 OpenClaw 直接替换其他应用使用的系统 Node。首次安装需要用户批准，之后可以复用。

如果 CLI 已经恢复，但后台 Gateway service 还绑着旧 Node，9.4 可以通过 openclaw gateway install 把 stale service runtime 切到可用的受支持版本。CLI runtime 与 service runtime 要分别验证。非交互、CI 等路径仍应提前准备兼容环境。

这里还要区分“推荐运行时”和“安装器缺 Node 时实际装什么”：官方 Node 文档当前说明，macOS installer 缺 Node 时会 provision Node 26；Linux installer 默认 provision 受支持的 Node 24 LTS。RPM-based Linux 若 distro Node 关联的 SQLite 不满足安全条件，安装器会给 OpenClaw 使用 user-space Node runtime，而不是简单删掉系统 Node。

Linux Desktop Companion 是另一条路径。当本地 setup 需要 CLI / Node 时，Companion 可以使用自己的 managed runtime；普通桌面安装不要求你先全局配好 OpenClaw CLI 与 Node。自己维护独立 Gateway 时，再按上面的 CLI Node 范围管理。

Linux Desktop Companion：9.4 已实际发布 .deb 与 AppImage

v2026.9.4 GitHub Release 已经实际包含 Linux amd64 桌面资产：

• OpenClaw-2026.9.4-amd64.deb
• OpenClaw-2026.9.4-amd64.AppImage

因此本页不再停留在“只确认到 8.2”的旧状态。仍然要注意：只下载 Release 页面实际存在、与自己架构匹配的官方资产，不要为其他架构或未来版本自行拼 URL。

.deb：Debian / Ubuntu 桌面

sudo apt install ./OpenClaw-2026.9.4-amd64.deb

.deb 后续由系统包管理器管理，不要把它和 AppImage 自更新机制混在一起。

AppImage

chmod +x OpenClaw-2026.9.4-amd64.AppImage
./OpenClaw-2026.9.4-amd64.AppImage

AppImage 与 package-managed 安装的更新方式不同。以后 core Stable 再变化时，也继续以对应 GitHub Release 的真实 assets 和官方 Linux 文档为准。

Linux Companion 和 Gateway 是什么关系

Companion 可以连接：

• 当前机器的 local Gateway；
• 自动发现或手工填写的 remote Gateway；
• SSH 连接的 Gateway。

它不是“把 Gateway 功能完全塞进 GUI 里”。连接远程 Gateway 时，无需为了有 GUI 再在笔记本上运行第二套 Gateway；需要本地服务时，再由相应 CLI / service 路径管理生命周期。

Linux CLI / Gateway：服务器和终端用户继续用这条路

官方脚本仍是最短路径之一：

curl -fsSL https://openclaw.ai/install.sh | bash

安装后根据需要进入 onboarding / service 安装：

openclaw onboard --install-daemon

对于 headless VPS，这条路线通常比安装 Desktop Companion 更合适。Quick Start 给出的 Dashboard 链接和 SSH tunnel 是进入管理界面的路径，不等于应该把 Gateway 端口直接暴露到公网。

Windows：桌面 Companion 与 CLI 分开看

Windows Hub / Companion 与 core CLI / Gateway 的发布节奏可以独立。不要看到 core 是 2026.9.4 就假设所有 Windows 安装器必须有完全相同的 asset 版本号。

如果只需要 CLI / Gateway，可继续用官方 PowerShell installer：

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

9.4 继续修复 Windows Gateway task 停止、service check 与 update 边界。复杂 Scheduled Task / managed-service 环境升级后仍应实际验证 Gateway restart 与 update handoff。只有明确需要更完整 Linux runtime 或 Linux-only 工具链时，才把 WSL2 当优先方案。

macOS：Companion 与 CLI 仍是两层

macOS 桌面用户从官方 Release / macOS 文档核对当前实际发布资产、签名与系统要求，不要根据 core 版本自行构造下载 URL。

macOS Companion 可以连接本地或远程 Gateway。普通远程连接不要求你先安装独立 CLI；只有需要 setup / 管理 app-owned local Gateway、终端自动化或脚本能力时，再按 CLI 路径安装。

9.4 修复了新版 Homebrew Bash 下 installer 可能卡住的问题，并继续改善远程连接与启动诊断；这些变化不改变 Companion 与 CLI / Gateway 的安装边界。

Docker / VPS：为了隔离与运维，不是为了“能装上”

Docker / Podman 适合：

• 远程常驻 Gateway；
• 明确文件、网络、依赖隔离；
• 多环境重复部署；
• 已经有容器监控、备份和升级流程。

如果只是个人电脑第一次试用，Quick Start、对应桌面 Companion 或 CLI 通常更容易定位问题。

9.4 修复 Docker source dependency installation，并继续拆分 Docker 运维文档。已有生产 compose / volume 不要因为版本更新就顺手重建所有持久化目录；先备份，再按官方更新路径处理。

安装后先验证 Gateway，再接权限

CLI / Gateway 环境至少执行：

openclaw --version
openclaw gateway status
openclaw dashboard

确认：

1. CLI 返回预期 core 版本；
2. Gateway 稳定运行或 Companion 正确连接到目标 remote Gateway；
3. Control UI / Dashboard 指向正确实例；
4. 用公开或虚构数据完成一条只读测试。

模型、渠道、浏览器、插件与高权限工具按“一次加一个”的方式接入，避免首次安装就把所有权限同时打开。

共享 Gateway：9.2 起的跨 Agent 默认值仍需显式检查

9.2 引入的默认边界在 9.4 仍然需要注意。当对应配置完全省略时：

tools.sessions.visibility = all
tools.agentToAgent.enabled = true

这意味着具备相关工具的 Agent，在满足其他策略时可能访问其他 Agent 的 Session，甚至包含其他用户的 transcript。

如果不想采用这个宽默认，升级前显式配置。例如：

{
  "tools": {
    "sessions": { "visibility": "agent" },
    "agentToAgent": { "enabled": false }
  }
}

严格当前 Session 使用 self；需要部分 Agent 互通时用明确 allow list。

agent 仍不是租户隔离：多人共用一个 Agent 时，仍可能看到其他人的 Session。互不信任的用户应该用独立 Gateway。

更完整的解释见安全入口与2026.9.2 更新解读。

Skill Library、Skill Workshop 与 9.4 扩展发现：不要混成一个概念

9.1 的 Personal Skill Library 仍然有效；9.3 把 Skill Workshop 调整为每个 Agent 跨 workspace 持久的一套 collection；9.4 又加入统一 Skills / Plugins 发现与 Learn from past conversations 可见学习聊天。

这意味着“个人用户管理的 Skill”、“workspace Skill”、“ClawHub package”、“Gateway plugin”、“Agent 学习后进入 Workshop 的 Skill/Suggestion”仍然是不同边界。可发现、可推荐不等于可信；长期环境仍应实际检查来源、revision、capability 与 Workshop target。

详见Skill 安装与验证。

从旧版本升级到 9.4

不要用“重复覆盖安装”代替诊断。先确认 Node：

node -v

再预览：

openclaw --version
openclaw update status
openclaw update --dry-run

确认目标后再更新：

openclaw update
openclaw doctor
openclaw gateway status --deep

9.4 继续沿用 candidate validation / activation，并加强 failed-update rollback、update repair 与 plugin finalization；但生产环境仍要保留快照，因为 app rollback 不会自动恢复数据，candidate validation 也不会替你验证业务语义。

如果核心包已经更新，但插件同步、capability review、registry refresh 或 doctor finalization 没完成：

openclaw update repair

复杂环境建议追加：

openclaw doctor --post-upgrade
openclaw plugins inspect <id> --runtime --json

生产环境不要只看 openclaw --version 就认为 core、plugin、runtime、Memory 与渠道已经一致。

Extended Stable：6.35 是另一条维护线，不是 9.4 的替代版本号

截至 2026-09-10，v2026.6.35 是当前 extended-stable，官方称它为 June 2026 Extended Stable 的最终版本。

它只适合已经明确选择滞后维护线的 package install。先预览：

openclaw update --channel extended-stable --dry-run

再决定是否切换：

openclaw update --channel extended-stable

Extended Stable 是 package-only；git checkout 不支持该 channel。若目标比当前安装版本低，还会触发 downgrade confirmation。大多数普通用户继续用 regular stable 即可。

复杂生产环境：9.4 仍建议先做 staging / 副本验证

v2026.9.4 是 Stable，但发布后已经出现几类值得跟踪的现场报告：

• Issue #146887 报告 9.3 → 9.4 的 Linux / systemd 环境连续遇到 stdio MCP candidate Doctor timeout、security finding update gate 与 managed-service handoff recovery 失败；
• Issue #147007 记录一套 Windows 9.3 → 9.4 update 在 validating / managed-service-preflight 阶段失败，但 rollback 状态显示可安全重启；
• 多渠道、stdio MCP 与长期 Gateway 还有更具体的 9.4 现场信号，集中整理在2026.9.4 更新解读。

这些不代表所有 9.4 都会失败，但复杂环境不应只以 openclaw --version 作为升级验收。

至少真实确认：

1. main 与关键 Agent 仍能读取应有 workspace / Memory；
2. Session ownership 与 visibility 正确；
3. Workshop / Suggestions 和常用 Skill / Plugin 正常；
4. 常用模型与消息渠道各跑一条真实低风险收发；
5. Browser、自动化、Cloud Worker、MCP / subagent 按实际使用情况各验证一条路径；
6. 长期 stdio MCP 用户额外观察一次子进程是否正常回收。

9.3 的旧环境 migration 风险记录仍保留在2026.9.3 更新解读，跨多个版本升级时仍可作为检查清单参考。

cleanup 放到最后

只有升级和迁移已经验证正常、备份也确认可用后，才预览：

openclaw update cleanup --dry-run

真正 cleanup 会永久放弃被删除 migration originals 对应的 rollback，不能当作“清缓存”。先 dry-run，再确认备份，不要直接执行清理。

本页核验边界

本页 regular stable、Extended Stable、Quick Start、本地模型引导、Node.js 范围、桌面 Companion 边界、Linux 9.4 assets 与升级命令已于 2026-09-13 对照 OpenClaw 官方 docs、v2026.9.4 Release Notes、Release channels 与 GitHub Release 核验。

桌面资产可能在 core Release 后继续 qualification / publication，所以本站只写本次核验时实际能确认的资产，不根据版本号自行拼文件名。本站也没有在每一种 CPU、发行版、容器、模型和远端 Gateway 组合上独立完成实机测试。

从零开始时先看起步路径；升级或 migration 异常直接进入故障排查中心。