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

截至 2026-10-21，当前常规 stable / npm latest 是 v2026.10.5，extended-stable 是 Gateway 维护线 v2026.9.33。v2026.10.10-beta.3 属于预览版，不应与稳定版混淆。详见版本中心。

10.10-beta.3 重点修复 Windows 首次初始化/Gateway 启动及升级后插件、Agent 状态恢复。这些改进尚不能当作 Stable 已提供的修复；常规新装仍按 10.5 Stable 指南操作，测试 Beta 请先保留可恢复备份。

9.3 引入的 Node 运行时门槛对 10.5 仍有效；复杂环境升级还要核对 Gateway service 的独立 runtime、SQLite 状态库和数据备份，不要只看 CLI 的 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 引入的本地模型引导：保留历史设置边界

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：10.5 已发布 .deb 与 AppImage

v2026.10.5 官方 GitHub Release 已列出 Linux amd64 桌面资产：

• OpenClaw-2026.10.5-amd64.deb
• OpenClaw-2026.10.5-amd64.AppImage

上述两个文件名均来自 10.5 Release 的实际资产列表。仍然要注意：只下载 Release 页面实际存在、与自己架构匹配的官方资产，不要为其他架构或未来版本自行拼 URL。

.deb：Debian / Ubuntu 桌面

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

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

AppImage

chmod +x OpenClaw-2026.10.5-amd64.AppImage
./OpenClaw-2026.10.5-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.10.5 就假设所有 Windows 安装器必须有完全相同的 asset 版本号。

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

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

10.5 继续修复安装、更新恢复与原生客户端问题。复杂 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：9.33 是 Gateway 的独立维护线

截至 2026-10-20，官方 npm extended-stable 版本是 v2026.9.33。官方将其描述为 gateway-only 的较保守维护线：使用 9 月末基线并加入安全、可靠性、性能补丁。它不替代 10.5 regular Stable，也不表示全部桌面平台都提供同版本资产。

只对明确需要这一运维策略的 package install 考虑切换；git checkout 不支持该渠道，切换时还可能涉及降级和数据兼容。先预览：

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

确认备份和实际目标包后，再执行 openclaw update --channel extended-stable。

复杂生产环境：10.5 升级前检查数据格式与回退

10.5 官方 Release 提醒跨 SQLite schema 24 → 25 降级时需要对应的升级前备份；软件包回滚不会恢复升级后的数据库写入。如果 Doctor 明确识别非常旧的状态格式，可能需要先按官方指示通过 2026.9.5 / 2026.9.7 等中间版本修复；普通环境不要盲目安装中间版本。

Kubernetes 只读 root 的旧部署还应按官方容器指南准备可写缓存。9.4 时个别 MCP / systemd / Windows 的问题仍可参阅历史 9.4 文章，但不能把旧 Issue 直接当成 10.5 的普遍故障。

至少真实确认：

1. main 与关键 Agent 的 workspace / Memory 连续性、Session ownership；
2. Workshop 历史版本与 Undo 入口可用，更新后的 Skills/Plugins 生效；
3. 常用模型、消息渠道能真实收发一条测试消息；
4. Browser、自动化、Cloud Worker、MCP / subagent 按需各验证一条低风险路径；
5. 配置与数据备份可实际恢复，必要时保留升级前完整快照。

完整变化见2026.10.5 更新解读。

cleanup 放到最后

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

openclaw update cleanup --dry-run

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

本页核验边界

本页 Stable、Extended Stable、Node、Linux 10.5 桌面资产和升级边界已于 2026-10-20 对照官方 Release Notes、npm 发布渠道、Node 文档及 GitHub Release 核验；Beta 版本与相关预览修复于 2026-10-21 对照官方 npm Registry 与 GitHub Pre-release 核验。其他平台发布节奏可能不同，仍应以实际下载资产、签名和系统要求为准，不能根据 core 版本拼安装链接。

本站没有在每一种 CPU、发行版、容器、模型和远端 Gateway 组合上完成实机验证。新装从起步路径开始，升级异常先走故障排查中心。