OpenClaw 安装与部署完全指南：全平台覆盖（2026）

OpenClaw（v2026.2.6，2026 年 2 月）可以在 macOS、Linux 或 Windows WSL2 上通过一条命令完成安装：curl -fsSL https://openclaw.ai/install.sh | bash。唯一的前置要求是 Node.js 22 或更高版本，安装脚本会自动处理检测和安装。如需全天候部署，建议使用 Docker Compose 或配备 2 vCPU、4 GB RAM 的 VPS。本指南覆盖所有平台，从本地机器和树莓派到云服务器，提供逐步命令、安全加固和维护工作流。

要点速览

OpenClaw 是一个开源的个人 AI 助手（MIT 许可证，截至 2026 年 1 月 GitHub 星标已超过 60,000），它可以将你喜欢的大语言模型（Claude、GPT、Gemini 或本地 Ollama 模型）连接到 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams 和 Google Chat 等消息平台。OpenClaw 最初由 Peter Steinberger 创建（在开源重命名之前曾使用 ClawdBot 和 MoltBot 的名称），如今已成长为 Node.js 生态中维护最活跃的个人 AI 助手项目之一。以下是最快上手的安装路径：

快速决策：先在本地运行测试，确认无误后再迁移到 VPS 上的 Docker 以实现 24/7 全天候可用。

核心命令：

bash

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

# 首次配置
openclaw onboard

# 健康检查
openclaw doctor

# 启动 Web 控制台
openclaw dashboard

最低要求：Node.js 22+、2 GB RAM、20 GB 磁盘空间。安装脚本会在所有支持的平台上自动检测和安装 Node.js。如果需要全天候 VPS 部署，根据服务商和流量大小，每月预算约 5-20 美元。

如何选择你的 OpenClaw 部署方式

大多数安装指南会直接跳到命令行操作，却没有先回答最重要的问题：你究竟应该用哪种方式？OpenClaw 提供了七种安装方式（安装脚本、npm、pnpm、源码、Docker、Nix、Ansible，以及实验性的 Bun 支持），但大多数用户只需要考虑其中三种。正确的选择取决于你的硬件情况、你对终端操作的熟悉程度，以及你是否打算让助手全天候运行。

安装脚本是所有首次安装 OpenClaw 用户的推荐起点。它适用于 macOS、Linux 和通过 WSL2 运行的 Windows，会自动检测你的 Node.js 版本（如果缺失则自动安装），整个过程在五分钟内即可完成。这种方式将 OpenClaw 直接安装在你的操作系统上，不需要任何容器化层，这意味着更低的资源开销和更简单的调试过程。代价是你需要与其他应用共享系统的 Node.js 环境，而且要让 OpenClaw 24/7 持续运行，就需要 pm2 等进程管理器或 systemd 服务。如果你想在本地做实验、在树莓派上测试，或者希望在 Mac Mini 上进行最简化的部署，就选择这种方式。

Docker Compose 提供了进程隔离、可复现的环境和轻松升级的能力，代价是稍微增加了一些复杂度。Docker 部署会将 OpenClaw 及其自带的 Node.js 运行时打包在一个容器内，将网关映射到 127.0.0.1:18789，并通过 Docker 卷持久化你的配置。更新只需拉取最新镜像并重启容器，而不必手动管理 Node.js 版本。这种方式非常适合生产环境的 VPS 部署、注重安全隔离的用户，以及在同一台服务器上运行多个服务的团队。你需要预先安装 Docker Engine 和 Docker Compose，并对端口映射和卷挂载有基本了解。

原生 npm/pnpm 安装是面向已经熟练管理 Node.js 环境的开发者的折中方案。运行 npm install -g openclaw（或 pnpm 等价命令）可以让你完全控制版本、更新节奏和全局包的安装位置。这种方式最适合在同一台机器上维护多个 Node.js 工具，并且希望通过同一套包管理系统来管理 OpenClaw 的开发者。对大多数用户来说，安装脚本是更好的选择，因为它能自动处理环境检测。

下面的对比表总结了各种方式的关键权衡。如果你正在考虑管理 OpenClaw API 成本的详细策略，需要知道部署方式本身对 API 开支的影响很小——真正的成本驱动因素是你连接了哪个大语言模型以及助手处理消息的频率。

我们的建议：先在本地机器上使用安装脚本，确认一切正常。满意后，再迁移到 VPS（Hetzner、Fly.io 或同类服务商）上的 Docker Compose 部署，以实现可靠的 24/7 运行。这种两步走的方法让你可以在无风险的情况下验证配置，然后再投入托管环境。

在 macOS 和 Linux 上安装 OpenClaw

在 macOS 或 Linux 发行版上安装 OpenClaw 是最直接的路径，因为这两个操作系统原生支持安装脚本和底层的 Node.js 运行时。安装程序会检测你的平台，检查 Node.js 22 或更高版本，如有必要会通过系统包管理器安装它，并在你的 PATH 中配置 OpenClaw 二进制文件。在宽带连接的现代机器上，整个过程通常在三分钟内完成。

第一步：验证你的 Node.js 版本。 打开终端并运行：

bash
node --version

你需要 v22.0.0 或更高版本。如果命令返回较旧的版本或 "command not found"，安装程序会尝试自动安装 Node.js。不过，如果你更喜欢手动管理 Node.js，可以先通过你平台推荐的方式安装。在 macOS 上，brew install node@22 即可。在 Ubuntu 或 Debian 上，NodeSource 仓库提供了最新的 LTS 版本：

bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

第二步：运行安装脚本。 这条命令下载并执行官方安装程序：

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

脚本会自动执行以下操作：验证系统要求、下载最新版 OpenClaw（当前为 v2026.2.6，2026 年 2 月 7 日发布）、安装 openclaw 二进制文件，并在 ~/.openclaw 创建默认配置目录。在 macOS 上，安装程序将二进制文件放置在 /usr/local/bin/openclaw；在 Linux 上，根据权限不同会使用 /usr/local/bin/openclaw 或 ~/.local/bin/openclaw。

第三步：运行引导向导。 安装完成后，onboard 命令会引导你完成初始配置：

bash
openclaw onboard

向导会提示你输入三项关键信息：使用哪个大语言模型提供商（Anthropic Claude、OpenAI GPT、Google Gemini 或本地 Ollama 模型）、该提供商的 API 密钥，以及首先连接哪个消息平台（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams 或 Google Chat）。每个选择都会在 ~/.openclaw/.env 中生成相应的环境变量。

第四步：验证安装。 运行内置的诊断工具，确认所有组件已正确连接：

bash
openclaw doctor

健康的安装会输出确认信息，包括 Node.js 满足最低版本要求、配置文件有效、API 密钥可达、消息桥接正常运行。如果任何检查失败，输出会包含具体的错误信息和建议修复方案。这个阶段最常见的故障是 API 密钥无效或过期——在进一步排查之前，先在提供商的控制台中确认你的密钥是有效的。

macOS 特别说明：在较新版本的 macOS（Sequoia 及更高版本）上，系统可能会提示你允许 OpenClaw 进程的网络访问。请接受这个提示；OpenClaw 需要出站 HTTPS 访问来连接大语言模型 API 和消息平台的 Webhook。如果你在 macOS 上使用 Little Snitch 等第三方防火墙，需要创建规则允许 node 访问 api.anthropic.com、api.openai.com 和 generativelanguage.googleapis.com 的 443 端口。

Linux 守护进程设置：如果你希望 OpenClaw 在开机时自动启动并在崩溃后自动重启，需要创建一个 systemd 服务。这对于无界面服务器和树莓派部署尤为重要，因为你无法依赖终端会话保持打开状态：

bash
sudo tee /etc/systemd/system/openclaw.service > /dev/null <<EOF
[Unit]
Description=OpenClaw AI Assistant
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=/usr/local/bin/openclaw start
Restart=on-failure
RestartSec=10
Environment=HOME=/home/$USER

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable openclaw
sudo systemctl start openclaw

启用服务后，使用 systemctl status openclaw 验证其运行状态。服务日志可通过 journalctl -u openclaw -f 实时查看。

在 Windows WSL2 和 Docker 上安装 OpenClaw

Windows 原生不支持 OpenClaw，因为底层的 Node.js 生态系统和进程管理工具都假设运行在类 Unix 环境中。不过，Windows Subsystem for Linux 2（WSL2）在 Windows 内部提供了一个功能完整的 Linux 内核，使得 OpenClaw 的安装过程与原生 Linux 几乎完全一样。Docker Compose 为偏好容器化部署或需要完全避开 WSL2 的用户提供了替代方案。

Windows WSL2 安装

WSL2 自推出以来已经非常成熟，现在是在 Windows 机器上运行 OpenClaw 的推荐方式。如果你还没有启用 WSL2，只需要以管理员权限在 PowerShell 中运行一条命令，然后重启系统即可。

第一步：安装 WSL2。 以管理员身份打开 PowerShell 并运行：

powershell
wsl --install

这条命令会启用 WSL2 功能、下载并安装默认的 Ubuntu 发行版，以及配置虚拟机。出现提示时重启计算机。重启后，Ubuntu 会自动启动并完成初始设置，要求你创建一个 Linux 用户名和密码。

第二步：更新软件包并安装 Node.js。 在 WSL2 Ubuntu 终端中：

bash
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

第三步：安装 OpenClaw。 用于原生 Linux 的同一安装脚本在 WSL2 中无需任何修改即可使用：

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

引导向导的行为与前一节描述的 macOS/Linux 版本完全一致。WSL2 特有的一个注意事项是，如果你需要从 Windows 浏览器访问 OpenClaw 控制台，WSL2 的网络层会自动映射 localhost 端口，因此在 Edge 或 Chrome 中导航到 http://localhost:3000 就能访问 WSL2 内运行的控制台。

Docker Compose 安装

Docker Compose 是生产环境、管理多个服务的团队以及任何重视容器级隔离的用户的首选部署方式。OpenClaw 项目提供了官方 Docker 镜像，其中包含了正确的 Node.js 版本和所有依赖项，消除了版本冲突，并将升级简化为一条 docker compose pull 命令。

第一步：安装 Docker。 如果你的系统上还没有 Docker，可以使用官方便捷脚本（适用于 Linux 和 WSL2）或 Docker Desktop（适用于 macOS 和 Windows）来安装：

bash
# Linux / WSL2
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# 注销并重新登录以使用户组变更生效

第二步：创建项目目录和配置文件。 OpenClaw 的 Docker 配置使用 docker-compose.yml 文件来定义容器、端口映射、卷挂载和重启策略：

bash
mkdir -p ~/openclaw-docker && cd ~/openclaw-docker

cat > docker-compose.yml <<EOF
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env
    environment:
      - NODE_ENV=production
EOF

端口映射 127.0.0.1:18789:18789 将网关限制为仅本地访问，这是生产部署的安全最佳实践。./data 卷将对话历史、配置和日志持久化在容器外部，确保在更新或重建容器时不会丢失任何数据。

第三步：创建环境变量文件。 在启动容器之前，你需要一个包含 API 密钥和消息平台令牌的 .env 文件。下一节的环境变量参考涵盖了所有可用选项；最低限度你需要：

bash
cat > .env <<EOF
OPENAI_API_KEY=sk-your-key-here
TELEGRAM_BOT_TOKEN=your-bot-token-here
EOF

第四步：启动容器。 以后台模式启动 OpenClaw：

bash
docker compose up -d

验证容器是否正在运行且健康：

bash
docker compose ps
docker compose logs --tail 50

日志应该显示 OpenClaw 正在初始化、连接到你的大语言模型提供商，并向消息平台注册。如果看到连接错误，请检查你的 API 密钥并确保出站 HTTPS 访问没有被防火墙阻止。

Docker 网络说明：如果你在 Nginx 或 Caddy 等反向代理后面运行其他服务，可以将外部流量路由到 OpenClaw 的网关端口。不过，对于大多数个人部署来说，localhost 绑定已经足够，因为消息平台通过容器建立的出站 Webhook 与 OpenClaw 通信。如果你确实需要外部访问（例如，将控制台暴露给网络上的其他设备），可以将端口映射改为 0.0.0.0:18789:18789——但要注意，这会使网关对所有能访问你服务器 IP 的人开放，因此请通过强制认证的反向代理来保护它。

Docker 资源限制：在内存有限的 VPS 实例上，你可以限制容器的内存使用量，防止 OpenClaw 与其他服务争夺资源：

yaml
services:
  openclaw:
    # ... 其他设置
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'

此配置将 OpenClaw 限制在 512 MB RAM 和一个 CPU 核心，对于个人使用来说已经绰绰有余，可以处理所有已连接平台每天 200-300 条消息。

硬件要求与性能优化

OpenClaw 本身非常轻量——Node.js 进程在空闲时通常只使用 150-300 MB RAM 和极少的 CPU。真正的硬件问题不是"我的机器能不能运行 OpenClaw"，而是"我的机器能不能可靠地全天候运行它？"答案取决于你的部署场景、流量大小，以及你是否需要在助手旁边运行其他服务。

以下硬件对比涵盖了基于 OpenClaw 社区论坛和部署指南中报告的真实使用场景的四种最常见部署目标。每个选项代表了成本、性能和可靠性之间不同的平衡。

树莓派 5 已经成为一个热门选择，因为 OpenClaw 的 Node.js 进程即使在持续的消息负载下也能在 300 MB RAM 内舒适运行。8 GB 型号提供了充足的余量，可以同时运行 OpenClaw 和 Pi-hole、Home Assistant 或其他轻量级服务。树莓派部署的主要风险是电源可靠性——意外断电可能损坏 SD 卡。投资一个 USB-C UPS（大约 25-40 美元）并通过 M.2 HAT 使用 NVMe SSD 替代 microSD 卡，可以显著提高可靠性。

Mac Mini M2 对于已经拥有一台或正在考虑购买专用家庭服务器的用户来说，可以说是最具性价比的选择。Apple Silicon 芯片为 Node.js 工作负载提供了出色的单线程性能，同时功耗极低（空闲功耗低于 7 瓦）。在 Mac Mini 上运行 OpenClaw 并配合本地 Ollama 模型，意味着你可以拥有一个完全自托管的 AI 助手，零持续 API 成本。缺点是家庭网络连接的上传速度可能不稳定，偶尔的断网会影响 Webhook 的可靠性。

VPS 托管完全消除了硬件管理的负担，并提供数据中心级别的网络可靠性。对于大多数个人用户来说，Hetzner（约 $5/月）、Fly.io 或同类服务商提供的 2 vCPU / 4 GB RAM 基础实例完全能够胜任 OpenClaw 的工作负载。4 GB RAM 的推荐配置考虑了 OpenClaw 加上操作系统开销再加上日志处理和临时峰值的小缓冲。对于团队或高流量部署（多个消息平台、频繁对话），建议升级到 4 个独享 vCPU 和 8 GB RAM。

性价比最优方案：根据 OpenClaw 社区观察到的部署模式，最受欢迎的生产配置是在 Hetzner CX22 实例（2 共享 vCPU、4 GB RAM、40 GB SSD）上运行 Docker Compose，每月成本约为 4.35 欧元（约 4.70 美元）。这种配置可以轻松处理一个服务于一到三个活跃消息平台的个人助手工作负载，而且欧洲数据中心位置为欧洲、非洲和西亚用户提供了出色的延迟。对于美国用户来说，Fly.io 的免费层级或 DigitalOcean 的 $6/月 Droplet 提供了相当的性能，并具有北美的地理优势。在评估 VPS 服务商时，优先考虑稳定的网络吞吐量而非原始 CPU 速度——OpenClaw 的性能瓶颈几乎总是与大语言模型 API 的往返时间，而非本地计算。

性能调优技巧：无论你选择什么硬件，三项配置调整可以提升 OpenClaw 的响应速度。首先，将 NODE_OPTIONS 环境变量设置为 --max-old-space-size=512，以限制 Node.js 堆内存使用，防止内存泄漏逐渐降低系统性能。其次，在大语言模型提供商配置中启用流式响应，这样助手可以在完整回复生成之前就开始发送消息——这能显著改善长回复的感知延迟。第三，配置日志轮转（通过内置的 openclaw gateway logs 命令加 --rotate 参数，或在 Linux 上使用 logrotate），防止日志文件在数周的持续运行中消耗磁盘空间。一个标准的日志轮转策略保留七天的压缩日志，磁盘开销极小，同时提供了足够的历史记录用于排查任何问题。

环境变量和 API 密钥配置

OpenClaw 的行为几乎完全通过环境变量控制，这些变量存储在 ~/.openclaw/.env（原生安装）或挂载到 Docker 容器中的 .env 文件中。理解这些变量至关重要，因为它们决定了哪个大语言模型驱动你的助手、连接哪些消息平台，以及如何处理安全和速率限制。

大语言模型提供商配置

OpenClaw 支持同时配置多个大语言模型提供商，这意味着你可以将 Claude 设为主模型，GPT 作为备选，或者将不同类型的对话路由到不同的模型。最低要求是配置一个提供商的密钥。

bash
# Anthropic Claude（推荐，对话质量最佳）
ANTHROPIC_API_KEY=sk-ant-your-key-here

# OpenAI GPT
OPENAI_API_KEY=sk-your-key-here

# Google Gemini
GOOGLE_AI_API_KEY=your-google-key-here

# 本地 Ollama（无需 API 密钥，只需端点地址）
OLLAMA_BASE_URL=http://localhost:11434

关于各提供商配置的详细说明，包括模型选择和参数调优，请参阅OpenClaw 大语言模型提供商配置完整指南。如果你想连接自定义或自托管的模型，OpenClaw 自定义模型配置指南涵盖了端点配置和模型别名设置。

API 网关替代方案：如果你更倾向于通过一个统一端点访问多个大语言模型提供商，而不是管理多个独立的 API 密钥，laozhang.ai 等服务提供了一个 API 网关，将 Claude、GPT、Gemini 和其他模型整合在一个密钥下。这可以将你的 .env 文件简化为一个指向网关 URL 的 OPENAI_API_KEY，还能通过批量定价降低成本。

消息平台令牌

每个消息平台都需要自己的认证令牌。OpenClaw 支持八个平台，你可以同时启用任意数量：

bash
# Telegram（个人使用最常见）
TELEGRAM_BOT_TOKEN=123456:ABC-your-bot-token

# WhatsApp（需要 Meta Business API）
WHATSAPP_TOKEN=your-whatsapp-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-id

# Slack
SLACK_BOT_TOKEN=xoxb-your-slack-token
SLACK_SIGNING_SECRET=your-signing-secret

# Discord
DISCORD_BOT_TOKEN=your-discord-token

对于 Telegram，通过 BotFather（Telegram 上的 @BotFather）创建一个机器人，复制令牌，粘贴到 TELEGRAM_BOT_TOKEN 变量中。对于 Slack 和 Discord，你需要在各平台的开发者门户中创建应用、配置 OAuth 权限范围，并提取机器人令牌。OpenClaw 文档提供了平台特定的设置指南，可从 openclaw onboard 向导中链接访问。

凭据安全最佳实践

你的 .env 文件包含敏感凭据，一旦泄露，将授予对你的大语言模型账户和消息平台的访问权限。应该像对待 SSH 私钥或数据库密码一样对待这个文件。在 Linux 服务器上，创建后立即限制文件权限：

bash
chmod 600 ~/.openclaw/.env

永远不要将 .env 文件提交到版本控制系统。如果你使用 Ansible 等配置管理工具进行多服务器部署，请将密钥存储在加密保险库中，而不是明文 Playbook 里。对于 Docker 部署，考虑使用 Docker Secrets 或密钥管理器，而不是直接挂载明文的 .env 文件，尤其是在多人可以访问 Docker 主机的团队环境中。

速率限制与成本控制

OpenClaw 会将每条收到的消息都发送给你的大语言模型提供商处理，这意味着一个活跃的 Telegram 群组或 Discord 频道可能会快速产生大量 API 费用。如果没有速率限制，一个活跃用户每天发送 100 条消息，平均每次回复 500 个 token，使用 Claude 或 GPT-4 级别的模型每天可能产生 3-5 美元的 API 费用。在环境变量中配置速率限制来防止费用失控：

bash
# 每个用户每小时最大消息数
RATE_LIMIT_PER_USER=30

# 每日最大 API 总花费（美元）
DAILY_COST_LIMIT=5.00

# 模型选择（控制每条消息的成本）
DEFAULT_MODEL=claude-3-haiku
# 日常聊天使用便宜的模型，复杂任务使用高级模型

这些限制在你校准预期使用量时提供了安全网。观察运行第一周的实际成本数据，可以帮助你设定永久限制，在可访问性和预算控制之间取得平衡。一个实用的策略是从保守的每日限额开始（$2-3），通过 OpenClaw 控制台观察实际使用模式，然后根据真实数据而非估算值进行上调。

高级配置技巧：OpenClaw 支持模型路由功能，允许你将不同的大语言模型分配给不同的对话类型或用户。例如，你可以将简单的问答路由到 Claude Haiku 等较便宜的模型，而将复杂的分析请求定向到 Claude Sonnet 或 GPT-4o。与对每条消息都使用高级模型相比，这种混合方案可以将 API 成本降低 60-70%，同时不会明显影响日常对话的体验。

首次运行、测试和故障排除

安装和配置完成后，首次运行是确认所有组件（Node.js 运行时、大语言模型提供商、消息桥接和 Web 控制台）作为一个完整系统正常运行的关键时刻。有条理的验证过程可以节省后续数小时的调试时间。

第一步：运行诊断套件。 openclaw doctor 命令会执行全面的健康检查：

bash
openclaw doctor

一个完全健康的系统会产生类似以下的输出：

[OK] Node.js v22.11.0 (minimum: v22.0.0)
[OK] OpenClaw v2026.2.6
[OK] Configuration file found at ~/.openclaw/.env
[OK] Anthropic API key valid (Claude model accessible)
[OK] Telegram bot connected (username: @YourBotName)
[OK] Gateway listening on 127.0.0.1:18789

如果任何检查失败，输出会标识具体问题并建议解决方案。按照从上到下的顺序处理故障，因为后续检查通常依赖于前面的检查结果（例如，如果配置文件无法读取，Telegram 连接检查也会失败）。

第二步：发送测试消息。 打开你在引导过程中配置的消息平台（Telegram、WhatsApp、Discord 或你选择的其他平台），向你的机器人发送一条简单消息，比如"你好，你在工作吗？"正常运行的安装会在 2-5 秒内回复一条由大语言模型生成的回答。响应时间主要取决于大语言模型提供商的延迟：Claude 和 GPT 对简短消息通常在 1-3 秒内响应，而本地 Ollama 模型的速度取决于你的硬件配置。如果消息已送达但 30 秒内没有收到回复，问题几乎总是出在大语言模型 API 连接上，而不是消息桥接——在排查消息平台配置之前，先检查你的 API 密钥有效性和网络连接。

第二步半：测试多轮对话。 连续发送两三条后续消息，验证 OpenClaw 是否能保持对话上下文。让它记住你第一条消息中的某些内容，然后在之后的消息中引用它。这可以确认对话历史系统工作正常，大语言模型接收的是完整的上下文窗口，而不是将每条消息作为独立查询处理。

第三步：打开 Web 控制台。 控制台提供系统状态、近期对话和配置的可视化概览：

bash
openclaw dashboard

这会在默认浏览器中打开本地控制台界面。在控制台中，你可以监控活跃对话、调整模型参数和查看使用统计。

常见错误及解决方案：

错误："ANTHROPIC_API_KEY is invalid or expired" —— 这是新用户报告的最常见问题。确认你的密钥以 sk-ant- 开头，且未在 Anthropic 控制台中被撤销。如果你刚刚生成了密钥，等待 60 秒让其生效后再重试。关于 Anthropic 密钥问题的详细排查，请参阅Anthropic API 密钥配置错误排查指南。

错误：安装期间出现 "EACCES permission denied" —— 安装程序尝试写入一个需要提升权限的目录。在 Linux 上，要么使用 sudo 运行安装程序，要么更改目标目录的所有权。在 macOS 上，Homebrew 前缀（/usr/local/）通常拥有正确的权限，但如果你通过其他方式安装了 Node.js，可能需要创建 ~/.local/bin/ 目录。

错误："Port 18789 already in use" —— 另一个进程占用了网关端口。使用以下命令找到并终止它：

bash
lsof -i :18789
kill -9 <PID>

然后重启 OpenClaw。如果冲突是持久性的（另一个服务确实在合法使用该端口），通过 GATEWAY_PORT 环境变量配置 OpenClaw 使用不同的端口。

错误："429 Too Many Requests" —— 你的大语言模型提供商正在对你的 API 调用进行速率限制。这通常发生在初始测试期间，当你短时间内发送了大量消息。等待几分钟后重试。对于持续性的速率限制问题，请参阅如何解决 OpenClaw 中的速率限制错误。

错误："WebSocket connection failed"(Telegram/Discord) —— 这通常表示出站 WebSocket 连接在网络层被阻止了。企业防火墙、限制性的 VPN 配置以及某些地区的部分 ISP 会阻止 WebSocket 流量。尝试从不同的网络测试，或配置 OpenClaw 使用长轮询模式作为后备方案。

诊断命令参考：当标准排查方法无法解决问题时，以下命令可以提供更深入的可见性：

bash
# 实时日志输出
openclaw gateway logs

# 系统状态摘要
openclaw status

# 检查与所有已配置提供商的连接
openclaw doctor --verbose

# 重置配置（最后手段）
openclaw reset-config

升级、备份与长期维护

安装是一次性的事情，维护则是持续进行的。OpenClaw 频繁发布更新（项目在 2026 年 2 月 7 日发布了 v2026.2.6，就在本指南发布的前一天），保持安装版本更新可以确保你获得安全补丁、性能改进和新功能。同样重要的是在任何更新之前建立备份流程，这样即使升级失败也不会丢失配置或对话历史。

检查更新：OpenClaw 包含一个内置的更新检查器，它会将你安装的版本与最新版本进行比较：

bash
openclaw update --check

这条命令查询 GitHub releases API 并报告是否有更新版本可用。每周运行一次，或者订阅 OpenClaw 的 GitHub releases feed，可以让你及时了解最新动态而无需手动检查。

备份流程：在应用任何更新之前，备份你的配置和数据。关键文件位于两个位置：

bash
# 原生安装备份
cp -r ~/.openclaw ~/openclaw-backup-$(date +%Y%m%d)

# Docker 安装备份
cp -r ~/openclaw-docker/data ~/openclaw-data-backup-$(date +%Y%m%d)
cp ~/openclaw-docker/.env ~/openclaw-env-backup-$(date +%Y%m%d)

备份会捕获你的 .env 文件（API 密钥和令牌）、对话历史、自定义配置以及你已安装的任何插件或扩展。至少保留一份备份在机器之外——U 盘、云存储或另一台服务器——这样硬件故障不会同时带走你的安装和备份。

应用更新：更新命令因安装方式而异：

bash
# 安装脚本方式
openclaw update

# npm 全局安装方式
npm update -g openclaw

# Docker Compose 方式
cd ~/openclaw-docker
docker compose pull
docker compose up -d

对于 Docker 部署，pull 命令下载最新镜像，up -d 用新镜像重建容器并保留你的数据卷。这使得 Docker 成为最顺畅的升级路径，因为不存在 Node.js 版本冲突或依赖问题的风险——新镜像自带了一切所需。

回滚流程：如果更新引入了问题，恢复备份非常简单：

bash
# 原生安装回滚
openclaw stop
rm -rf ~/.openclaw
mv ~/openclaw-backup-YYYYMMDD ~/.openclaw
openclaw start

# Docker 回滚（到上一版本镜像）
docker compose down
docker compose pull openclaw/openclaw:v2026.2.5  # 指定上一版本
docker compose up -d

对于 Docker，你还可以在 docker-compose.yml 中将 image: openclaw/openclaw:latest 改为 image: openclaw/openclaw:v2026.2.5 来固定特定版本，在你准备好之前防止意外升级。

持续监控：健康的维护流程不仅仅是更新。以下命令构成了一个轻量级的监控工作流，可以在问题演变为故障之前发现它们：

bash
# 快速健康检查（每日运行或通过 cron 定时）
openclaw status

# 检查网关连接和 API 密钥有效性
openclaw doctor

# 查看近期日志中的错误或警告
openclaw gateway logs --tail 100

# 打开控制台查看可视化状态概览
openclaw dashboard

对于没有桌面浏览器的无界面服务器，你可以通过 SSH 转发控制台端口（ssh -L 3000:localhost:3000 user@your-server），然后在本地机器上访问它。

日志管理：OpenClaw 在运行期间会持续生成日志。如果不进行轮转，这些日志可能在数月内消耗大量磁盘空间。在 Linux 上，配置 logrotate 来自动管理 OpenClaw 的日志文件：

bash
sudo tee /etc/logrotate.d/openclaw > /dev/null <<EOF
/var/log/openclaw/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}
EOF

对于 Docker 部署，Docker 内置的日志驱动会处理轮转。在 docker-compose.yml 中的 OpenClaw 服务下添加以下配置来限制日志大小：

yaml
logging:
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

安全维护：定期轮换你的 API 密钥和消息平台令牌，尤其是在你怀疑某些密钥可能已经泄露的情况下。更新 .env 文件中的密钥并重启 OpenClaw。此外，保持主机操作系统和 Docker 引擎更新，以获得保护 OpenClaw 运行平台本身的安全补丁。

总结与下一步

你现在拥有了一份在任何平台上部署 OpenClaw 的完整路线图，从五分钟的本地安装到生产级的 Docker VPS 部署。关键决策归结为三个因素：你的硬件情况（自有机器 vs. 租用 VPS）、你对容器化的熟悉程度（原生安装 vs. Docker），以及你的可用性需求（偶尔使用 vs. 全天候运行）。

对于大多数用户来说，最优路径是先在本地使用安装脚本，验证 API 密钥和消息平台连接，然后在确认助手按预期工作后迁移到 Hetzner 或 Fly.io 等经济实惠的 VPS 上的 Docker Compose 部署。这种两阶段的方法最大程度地减少了时间和金钱的浪费，同时为你提供生产级别的部署。

接下来做什么：

安装运行起来之后，接下来自然是深化大语言模型配置和优化成本。OpenClaw 大语言模型提供商配置完整指南会引导你根据任务类型和预算约束在 Claude、GPT、Gemini 和本地模型之间切换。对于 API 预算紧张的用户，管理 OpenClaw API 成本的详细策略指南涵盖了速率限制、模型路由和成本监控技术，让开支保持可预测。

推荐的探索路径：一旦基本功能运行正常，建议按影响力排序考虑以下增强。首先，连接第二个消息平台——如果你从 Telegram 开始，添加 WhatsApp 或 Discord 只需几分钟，就能大幅提升助手在各沟通渠道的实用性。其次，通过将较便宜的模型分配给日常对话、高级模型分配给复杂任务来实验模型路由；仅这一项优化就能将 API 成本降低一半以上。第三，通过 OpenClaw 控制台探索插件生态系统；社区构建的插件无需修改代码即可添加网页搜索、图片生成、文档分析和日历集成等能力。

关注项目动态：OpenClaw 的开发速度令人印象深刻——项目在 2025 年发布了超过 40 个版本，v2026.x 系列继续保持这一节奏。订阅 GitHub releases feed（github.com/openclaw/openclaw/releases）以在新版本发布时收到通知。主要版本升级偶尔会引入破坏性变更，因此在更新前阅读发行说明是值得养成的习惯。OpenClaw 的 Discord 服务器和 GitHub Discussions 是从其他用户和核心开发团队获得帮助的最佳场所。

OpenClaw 的开源社区活跃且友好。无论你是在自动化客户支持、构建个人研究助手，还是在尝试多模型对话，你今天建立的基础都能满足这些目标。最难的部分——选择方式并让第一条消息跑通——已经在你身后了。