02-安装部署指南

02 安装部署指南 02 安装部署指南 Modified June 10 Code block Plain Text level: "debug", }, } ⠀ 11.2 测试环境 ⠀ Code block Plain Text { gateway: { port: 18789, }, agents: { defaults: { model: "openai/gpt 5.4", }, }, logging: { level: "info", }, } ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 11.3 生产环境 ⠀ Code block Plain Text { gateway: { port: 18789, auth: { token: "${OPENCLAW GATEWAY TOKEN}", }, }, agents: { defaults: { model: "openai/gpt 5.4", }, }, logging: { level: "warn", }, } ⠀ 注意：environment、debug、logLevel（在 gateway 下）、rateLimit、security 等字段并非 OpenClaw 配置模式中的真实字段。Gateway 认证通过 gateway.auth.token 配置，日志级别通过顶层 logging 配置。 ⠀ 11.4 使用不同配置文件 ⠀ Code block Plain Text 可以通过命令行参数指定配置文件 openclaw gateway config /.openclaw/openclaw dev.json openclaw gateway config /.openclaw/openclaw prod.json 12. 安装验证和健康检查 ⠀ 12.1 基本验证 ⠀ Code block Plain Text 检查 CLI 是否正常 openclaw version openclaw help 检查配置 openclaw config get 检查 Gateway 状态 openclaw status 运行诊断工具 openclaw doctor ⠀ v2026.5.22 首次运行行为：如果直接执行裸命令 openclaw，且本机还没有 authored config，新版会进入 classic onboarding。教程仍推荐显式运行 openclaw onboard install daemon，因为它更清楚地表达“配置 + 安装后台服务”两个动作。 ⠀ 12.2 启动 Gateway 并验证 ⠀ Code block Plain Text 启动 Gateway openclaw gateway port 18789 verbose 检查 Gateway 是否在运行（另一个终端） openclaw status 期望输出： Gateway Status: running Port: 18789 Uptime: 5 seconds Connected Channels: 0 Active Agents: 1 ⠀ v2026.5.22 对 Gateway ready 路径做了缓存和延迟加载优化：未用到的 handler tree、插件 metadata、channel catalog、ACPX runtime 不应阻塞首次 ready。排障时先区分三种状态： ⠀ 状态 说明 处理方式 CLI 可用但 Gateway 未 ready 配置或后台服务还没启动完 看 openclaw gateway verbose Gateway ready 但插件未 ready 可选插件仍在懒加载 看插件日志，不要直接判定安装失败 Gateway ready 抖动 restart trace 或依赖服务异常 先跑 openclaw doctor，再看 Gateway 日志 ⠀ 12.3 API 连通性测试 ⠀ Code block Plain Text 检查模型状态 openclaw models list 健康检查 openclaw health ⠀ 12.4 Control UI 访问 ⠀ Gateway 启动后，Control UI 通过 Gateway WebSocket 提供，访问 http://localhost:18789，你应该能看到： ⠀ • Gateway 运行状态 • 已连接的消息平台列表 • Agent 列表和状态 • 消息统计和日志 💡 遇到问题？ 直接来这里找答案，大部分安装问题都能在这里解决 ⠀ 13. 常见安装问题排查 ⠀ 13.1 权限问题 ⠀ 症状：EACCES: permission denied ⠀ Code block Plain Text 方案一：使用 nvm（推荐） curl o https://raw.githubusercontent.com/nvm sh/nvm/v0.40.1/install.sh | bash nvm install 22 npm install g openclaw@latest 方案二：修改 npm 目录权限 mkdir p /.npm global npm config set prefix ' /.npm global' echo 'export PATH= /.npm global/bin:$PATH' /.bashrc source /.bashrc ⠀ 13.2 网络问题 ⠀ 症状：npm ERR! network timeout ⠀ Code block Plain Text 使用淘宝镜像 npm config set registry https://registry.npmmirror.com npm install g openclaw@latest 或者使用代理 npm config set proxy http://127.0.0.1:7890 npm config set https proxy http://127.0.0.1:7890 npm install g openclaw@latest 安装完成后恢复 npm config delete proxy npm config delete https proxy npm config set registry https://registry.npmjs.org ⠀ 13.3 Node.js 版本过低 ⠀ 症状：Error: OpenClaw requires Node.js 22.19 or higher ⠀ Code block Plain Text 检查当前版本 node version 使用 nvm 升级 nvm install 22 nvm use 22 或者使用 NodeSource 升级 curl fsSL https://deb.nodesource.com/setup 22.x | sudo E bash sudo apt install y nodejs ⠀ ⠀ 11.2 测试环境 ⠀ ⠀ ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了 ⠀ 11.3 生产环境 ⠀ ⠀ 注意：environment、debug、logLevel（在 gateway 下）、rateLimit、security 等字段并非 OpenClaw 配置模式中的真实字段。Gateway 认证通过 gateway.auth.token 配置，日志级别通过顶层 logging 配置。 注意：environment、debug、logLevel（在 gateway 下）、rateLimit、security 等字段并非 OpenClaw 配置模式中的真实字段。Gateway 认证通过 gateway.auth.token 配置，日志级别通过顶层 logging 配置。 ⠀ 11.4 使用不同配置文件 ⠀ 12. 安装验证和健康检查 ⠀ 12.1 基本验证 ⠀ ⠀ v2026.5.22 首次运行行为：如果直接执行裸命令 openclaw，且本机还没有 authored config，新版会进入 classic onboarding。教程仍推荐显式运行 openclaw onboard install daemon，因为它更清楚地表达“配置 + 安装后台服务”两个动作。 v2026.5.22 首次运行行为：如果直接执行裸命令 openclaw，且本机还没有 authored config，新版会进入 classic onboarding。教程仍推荐显式运行 openclaw onboard install daemon，因为它更清楚地表达“配置 + 安装后台服务”两个动作。 ⠀ 12.2 启动 Gateway 并验证 ⠀ ⠀ v2026.5.22 对 Gateway ready 路径做了缓存和延迟加载优化：未用到的 handler tree、插件 metadata、channel catalog、ACPX runtime 不应阻塞首次 ready。排障时先区分三种状态： ⠀ 状态 说明 处理方式 CLI 可用但 Gateway 未 ready 配置或后台服务还没启动完 看 openclaw gateway verbose Gateway ready 但插件未 ready 可选插件仍在懒加载 看插件日志，不要直接判定安装失败 Gateway ready 抖动 restart trace 或依赖服务异常 先跑 openclaw doctor，再看 Gateway 日志 状态 状态 说明 说明 处理方式 处理方式 CLI 可用但 Gateway 未 ready CLI 可用但 Gateway 未 ready 配置或后台服务还没启动完 配置或后台服务还没启动完 看 openclaw gateway verbose 看 openclaw gateway verbose Gateway ready 但插件未 ready Gateway ready 但插件未 ready 可选插件仍在懒加载 可选插件仍在懒加载 看插件日志，不要直接判定安装失败 看插件日志，不要直接判定安装失败 Gateway ready 抖动 Gateway ready 抖动 restart trace 或依赖服务异常 restart trace 或依赖服务异常 先跑 openclaw doctor，再看 Gateway 日志 先跑 openclaw doctor，再看 Gateway 日志 ⠀ 12.3 API 连通性测试 ⠀ ⠀ 12.4 Control UI 访问 ⠀ Gateway 启动后，Control UI 通过 Gateway WebSocket 提供，访问 http://localhost:18789，你应该能看到： ⠀ • Gateway 运行状态 • 已连接的消息平台列表 • Agent 列表和状态 • 消息统计和日志 💡 遇到问题？ 直接来这里找答案，大部分安装问题都能在这里解决 💡 遇到问题？ 直接来这里找答案，大部分安装问题都能在这里解决 ⠀ 13. 常见安装问题排查 ⠀ 13.1 权限问题 ⠀ 症状：EACCES: permission denied ⠀ ⠀ 13.2 网络问题 ⠀ 症状：npm ERR! network timeout ⠀ ⠀ 13.3 Node.js 版本过低 ⠀ 症状：Error: OpenClaw requires Node.js 22.19 or higher ⠀ ⠀ 13.4 原生模块编译失败 ⠀ 症状：node gyp rebuild failed ⠀ ⠀ 13.5 端口被占用 ⠀ 症状：Error: listen EADDRINUSE: address already in use :::18789 ⠀ ⠀ 13.6 API Key 无效 ⠀ 症状：Error: Invalid API key ⠀ ⠀ 13.7 WSL2 网络问题 ⠀ 症状：WSL2 中无法访问外部网络 ⠀ 14. 卸载 ⠀ 14.1 卸载 CLI ⠀ ⠀ 14.2 清理配置和数据 ⠀ ⠀ 14.3 Docker 卸载 ⠀ 下一步 ⠀ 安装完成后，建议按以下顺序继续： ⠀ 下一步 文档 说明 快速体验 03 快速开始指南 5 分钟上手 配置模型 04 模型配置指南 详细的模型配置 接入平台 05 消息平台接入指南 连接 Telegram、WhatsApp 等 Docker 部署 09 Docker部署指南 生产环境容器化部署 安全配置 10 安全配置指南 API Key 安全、网络安全 下一步 下一步 文档 文档 说明 说明 快速体验 快速体验 03 快速开始指南 03 快速开始指南 5 分钟上手 5 分钟上手 配置模型 配置模型 04 模型配置指南 04 模型配置指南 详细的模型配置 详细的模型配置 接入平台 接入平台 05 消息平台接入指南 05 消息平台接入指南 连接 Telegram、WhatsApp 等 连接 Telegram、WhatsApp 等 Docker 部署 Docker 部署 09 Docker部署指南 09 Docker部署指南 生产环境容器化部署 生产环境容器化部署 安全配置 安全配置 10 安全配置指南 10 安全配置指南 API Key 安全、网络安全 API Key 安全、网络安全 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 难度等级：🟢 入门 • 阅读时间：20 分钟 • 前置知识：会用命令行（终端） ⠀ 本篇你将学会： 在 macOS/Linux/Windows 上安装 OpenClaw，配置运行环境，完成首次启动 ⠀ 小白速通： 直接跳到"快速安装"章节（第 3 节），跟着复制粘贴命令就行。遇到问题看第 12 13 节的故障排查 ⠀ 概述 ⠀ 这篇指南覆盖 OpenClaw 在所有主流平台上的安装、配置、升级和故障排查。不管你是 macOS 用户、Linux 服务器管理员还是 Windows 开发者，都能找到适合自己的安装方式。 ⠀ 安装 OpenClaw 的核心流程就三步： ⠀ 1. 系统要求 ⠀ 1.1 硬件要求 ⠀ 项目 最低要求 推荐配置 说明 CPU 1 核 2 核+ Gateway 守护进程常驻运行 内存 512 MB 2 GB+ 多平台连接时内存消耗线性增长 磁盘 500 MB 可用空间 2 GB+ 包含 node modules 和日志文件 网络 能访问 AI 模型 API 稳定的宽带连接 WebSocket 长连接需要稳定网络 项目 项目 最低要求 最低要求 推荐配置 推荐配置 说明 说明 CPU CPU 1 核 1 核 2 核+ 2 核+ Gateway 守护进程常驻运行 Gateway 守护进程常驻运行 内存 内存 512 MB 512 MB 2 GB+ 2 GB+ 多平台连接时内存消耗线性增长 多平台连接时内存消耗线性增长 磁盘 磁盘 500 MB 可用空间 500 MB 可用空间 2 GB+ 2 GB+ 包含 node modules 和日志文件 包含 node modules 和日志文件 网络 网络 能访问 AI 模型 API 能访问 AI 模型 API 稳定的宽带连接 稳定的宽带连接 WebSocket 长连接需要稳定网络 WebSocket 长连接需要稳定网络 ⠀ 名词解释：Gateway（OpenClaw 的核心服务进程）以守护进程（daemon，在后台持续运行的服务）方式运行，负责管理所有消息平台连接和 Agent 调度。 名词解释：Gateway（OpenClaw 的核心服务进程）以守护进程（daemon，在后台持续运行的服务）方式运行，负责管理所有消息平台连接和 Agent 调度。 ⠀ 说明：OpenClaw 本身很轻量，主要资源消耗来自 Gateway 守护进程和消息平台连接。如果你同时连接多个平台（WhatsApp + Telegram + Discord），建议至少 2 GB 内存。 ⠀ 如果使用本地模型（Ollama），硬件要求会大幅提升： ⠀ 模型规模 最低内存 推荐 GPU 推荐磁盘空间 7B 参数 8 GB RAM 6 GB VRAM 10 GB 13B 参数 16 GB RAM 12 GB VRAM 20 GB 70B 参数 64 GB RAM 24 GB+ VRAM 50 GB 模型规模 模型规模 最低内存 最低内存 推荐 GPU 推荐 GPU 推荐磁盘空间 推荐磁盘空间 7B 参数 7B 参数 8 GB RAM 8 GB RAM 6 GB VRAM 6 GB VRAM 10 GB 10 GB 13B 参数 13B 参数 16 GB RAM 16 GB RAM 12 GB VRAM 12 GB VRAM 20 GB 20 GB 70B 参数 70B 参数 64 GB RAM 64 GB RAM 24 GB+ VRAM 24 GB+ VRAM 50 GB 50 GB ⠀ 提示：如果你只用云端 API（OpenAI、Anthropic、Google），不需要 GPU，一台普通的云服务器就够了。 提示：如果你只用云端 API（OpenAI、Anthropic、Google），不需要 GPU，一台普通的云服务器就够了。 ⠀ 1.2 操作系统要求 ⠀ 操作系统 支持版本 备注 macOS 12 (Monterey) 及以上 Intel 和 Apple Silicon 均支持 Ubuntu/Debian 20.04 LTS 及以上 推荐 22.04 LTS CentOS/RHEL 8 及以上 需要 EPEL 仓库 Arch Linux Rolling Release 社区维护 AUR 包 Windows 10 (1903+) / 11 强烈推荐通过 WSL2 安装 Alpine Linux 3.18+ Docker 镜像常用基础系统 操作系统 操作系统 支持版本 支持版本 备注 备注 macOS macOS 12 (Monterey) 及以上 12 (Monterey) 及以上 Intel 和 Apple Silicon 均支持 Intel 和 Apple Silicon 均支持 Ubuntu/Debian Ubuntu/Debian 20.04 LTS 及以上 20.04 LTS 及以上 推荐 22.04 LTS 推荐 22.04 LTS CentOS/RHEL CentOS/RHEL 8 及以上 8 及以上 需要 EPEL 仓库 需要 EPEL 仓库 Arch Linux Arch Linux Rolling Release Rolling Release 社区维护 AUR 包 社区维护 AUR 包 Windows Windows 10 (1903+) / 11 10 (1903+) / 11 强烈推荐通过 WSL2 安装 强烈推荐通过 WSL2 安装 Alpine Linux Alpine Linux 3.18+ 3.18+ Docker 镜像常用基础系统 Docker 镜像常用基础系统 ⠀ 1.3 软件依赖 ⠀ 软件 最低版本 推荐版本 用途 Node.js 22.19+ 兼容 24.x 运行时环境 npm（Node Package Manager，Node.js 的包管理器） 10.0.0 10.x（随 Node.js 附带） 包管理器 Git 2.30+ 最新版 克隆仓库、本地构建、版本管理 Python 3.10+（可选） 3.12 部分 Agent 工具依赖 Docker 24.0+（可选） 最新版 容器化部署 软件 软件 最低版本 最低版本 推荐版本 推荐版本 用途 用途 Node.js Node.js 22.19+ 兼容 22.19+ 兼容 24.x 24.x 运行时环境 运行时环境 npm（Node Package Manager，Node.js 的包管理器） npm（Node Package Manager，Node.js 的包管理器） 10.0.0 10.0.0 10.x（随 Node.js 附带） 10.x（随 Node.js 附带） 包管理器 包管理器 Git Git 2.30+ 2.30+ 最新版 最新版 克隆仓库、本地构建、版本管理 克隆仓库、本地构建、版本管理 Python Python 3.10+（可选） 3.10+（可选） 3.12 3.12 部分 Agent 工具依赖 部分 Agent 工具依赖 Docker Docker 24.0+（可选） 24.0+（可选） 最新版 最新版 容器化部署 容器化部署 ⠀ 检查当前环境是否满足要求： ⠀ 2. Node.js 环境安装 ⠀ OpenClaw 当前的官方口径是：Node.js 24.x 推荐，22.19+ 兼容。如果你已经满足这个基线，可以跳过这一节。 ⠀ 💡 阅读提示：下面部分命令示例仍保留 Node 22 写法，因为它仍然在兼容范围内；如果你是新装环境，直接把示例里的 22 换成 24 会更符合当前官方推荐。 💡 阅读提示：下面部分命令示例仍保留 Node 22 写法，因为它仍然在兼容范围内；如果你是新装环境，直接把示例里的 22 换成 24 会更符合当前官方推荐。 ⠀ Termux / 移动 Linux 提示：v2026.5.22 之后，Termux 场景会更稳地回退到可写 home 目录。不要把 OpenClaw 配置放到系统只读目录；先确认 node version、npm version 和 echo $HOME 都指向当前用户环境。 Termux / 移动 Linux 提示：v2026.5.22 之后，Termux 场景会更稳地回退到可写 home 目录。不要把 OpenClaw 配置放到系统只读目录；先确认 node version、npm version 和 echo $HOME 都指向当前用户环境。 ⠀ 2.1 使用 nvm 安装（推荐） ⠀ nvm（Node Version Manager）是管理 Node.js 版本的最佳方式，可以在多个版本之间自由切换。 ⠀ macOS / Linux： ⠀ ⠀ Windows： ⠀ Windows 用户使用 nvm windows： ⠀ 1. 从 nvm windows releases 下载最新安装包 nvm windows releases 2. 运行安装程序 3. 打开新的命令行窗口： ⠀ ⠀ 2.2 使用官方安装包 ⠀ 直接从 Node.js 官网 下载 LTS 版本安装包： Node.js 官网 ⠀ • macOS：下载 .pkg 文件，双击安装 • Windows：下载 .msi 文件，双击安装 • Linux：使用 NodeSource 仓库 ⠀ ⠀ 2.3 使用 Homebrew（macOS） ⠀ ⠀ 2.4 安装方式对比 ⠀ 方式 优点 缺点 适用场景 nvm 多版本管理、不需要 sudo 需要额外安装 开发环境（推荐） 官方安装包 简单直接 升级麻烦、可能需要 sudo 新手、单版本需求 Homebrew macOS 生态集成好 仅限 macOS macOS 用户 NodeSource 系统包管理器集成 版本更新可能滞后 服务器部署 方式 方式 优点 优点 缺点 缺点 适用场景 适用场景 nvm nvm 多版本管理、不需要 sudo 多版本管理、不需要 sudo 需要额外安装 需要额外安装 开发环境（推荐） 开发环境（推荐） 官方安装包 官方安装包 简单直接 简单直接 升级麻烦、可能需要 sudo 升级麻烦、可能需要 sudo 新手、单版本需求 新手、单版本需求 Homebrew Homebrew macOS 生态集成好 macOS 生态集成好 仅限 macOS 仅限 macOS macOS 用户 macOS 用户 NodeSource NodeSource 系统包管理器集成 系统包管理器集成 版本更新可能滞后 版本更新可能滞后 服务器部署 服务器部署 3. 安装 OpenClaw CLI ⠀ v2026.5.27 安装基线：官方 README 当前写法是 Node 24 recommended，Node 22.19+ supported。新装优先走 openclaw onboard，升级和回滚按 release channel 选择 stable / beta / dev；教程里的固定版本号只用于复现问题，不建议长期锁死。v2026.5.28 目前是 beta，v2026.5.29 alpha.1 仅作为 tag 出现，不作为本教程默认稳定基线。 v2026.5.27 安装基线：官方 README 当前写法是 Node 24 recommended，Node 22.19+ supported。新装优先走 openclaw onboard，升级和回滚按 release channel 选择 stable / beta / dev；教程里的固定版本号只用于复现问题，不建议长期锁死。v2026.5.28 目前是 beta，v2026.5.29 alpha.1 仅作为 tag 出现，不作为本教程默认稳定基线。 ⠀ 这一轮还会影响排障口径： ⠀ • Pi packages 更新到 0.75.1，遇到内部运行时错误时先确认安装包版本。 • Bundled Codex harness 已随 v2026.5.26 对齐到 Codex CLI 0.134.0，Codex code mode 问题不要只查外部 Codex CLI，也要看 OpenClaw app server 与 auth profile。 • macOS app 内嵌 Peekaboo Bridge 更新到 3.2.1，UI 自动化权限问题先重新授权 Accessibility / Screen Recording。 • Gateway 启动路径有缓存和延迟加载优化，升级后启动变快是正常现象；启动失败时看 openclaw doctor、Gateway 日志和 v2026.5.27 release verification。 • Docker runtime workspace templates、Alpine 安装、Windows Scheduled Tasks 和稳定 channel 选择在 v2026.5.26 / v2026.5.27 有加固；生产部署不要跳过发布包 integrity / shrinkwrap 校验。 ⠀ 3.1 npm 全局安装（推荐） ⠀ ⠀ 3.2 使用 yarn ⠀ ⠀ 3.3 使用 pnpm（高性能的 npm 替代品） ⠀ ⠀ 3.4 使用 npx（免安装体验） ⠀ 如果你只是想试试，不想全局安装： ⠀ ⠀ 注意：npx 每次运行都会检查最新版本，适合体验，不适合生产环境。 注意：npx 每次运行都会检查最新版本，适合体验，不适合生产环境。 ⠀ 3.5 安装方式对比 ⠀ 方式 命令 优点 缺点 npm npm i g openclaw@latest 最通用、文档最多 全局安装可能需要权限 yarn yarn global add openclaw 速度快、缓存好 需要额外安装 yarn pnpm pnpm add g openclaw 磁盘占用小 需要额外安装 pnpm npx npx openclaw 免安装 每次启动慢 方式 方式 命令 命令 优点 优点 缺点 缺点 npm npm npm i g openclaw@latest npm i g openclaw@latest 最通用、文档最多 最通用、文档最多 全局安装可能需要权限 全局安装可能需要权限 yarn yarn yarn global add openclaw yarn global add openclaw 速度快、缓存好 速度快、缓存好 需要额外安装 yarn 需要额外安装 yarn pnpm pnpm pnpm add g openclaw pnpm add g openclaw 磁盘占用小 磁盘占用小 需要额外安装 pnpm 需要额外安装 pnpm npx npx npx openclaw npx openclaw 免安装 免安装 每次启动慢 每次启动慢 4. 引导向导（openclaw onboard） ⠀ 安装完 CLI 后，运行引导向导完成初始配置：