安装与初始化

去年十二月我第一次装 OpenClaw，搞半天一直报 ERR_MODULE_NOT_FOUND 之类的错——你猜怎么着？我当时用的 Node 18。坑爹的是报错信息完全没提 Node 版本的事，我对着 Stack Overflow 查了半小时才在 GitHub Issue #4872 里看到有人说"必须 Node >= 22"。所以装之前先确认一下环境，别跟我犯一样的蠢。

环境要求

• Node.js >= 22（推荐用 nvm 管理版本）
• 包管理器：pnpm（推荐）或 npm
• 操作系统：macOS / Linux / Windows（WSL2）
• 网络：需要能访问 LLM API（OpenAI/Claude/Gemini）

两个重要提醒啊：Windows 用户必须使用 WSL2（推荐 Ubuntu），原生 Windows 跑不了的。还有就是别用 Bun——WhatsApp 和 Telegram 连接上有已知 bug，GitHub Issue 里吵过好几回了，到现在也没完全修好呢。

方式一：一键安装（推荐）

macOS / Linux：

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

Windows（WSL2）：

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

这个脚本会自动检测环境、装依赖，基本上跑完就能用。偶尔在某些 Linux 发行版上会报个权限相关的 warning，一般不影响使用——我在 Ubuntu 24.04 上碰到过一次，忽略掉就行了。

方式二：npm 安装

# npm
npm install -g openclaw@latest

# pnpm（推荐）
pnpm add -g openclaw@latest

验证安装：

openclaw --version
# 应输出类似：openclaw v2026.3.x

方式三：Nix 安装

如果你是 NixOS 用户或者习惯用 Nix 管理工具链，OpenClaw 支持声明式配置：

# flake.nix 或 configuration.nix
environment.systemPackages = with pkgs; [
  openclaw
];

Nix 的好处是环境完全可复现，团队统一配置特别方便。不过 Nix 的学习曲线嘛...懂的都懂，新手还是老老实实 npm 吧。

方式四：Docker 部署

适合想在服务器上 24/7 运行的：

docker pull openclaw/openclaw:latest

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

方式五：移动端和桌面客户端

除了命令行安装，OpenClaw 还有原生客户端：

• macOS menu bar app（macOS 15+ beta）——常驻菜单栏，带 push-to-talk 悬浮窗，按住快捷键直接语音下指令。适合不想一直开着终端的人
• iOS app —— 支持 Canvas 交互画布、Voice Wake 语音唤醒、摄像头拍照、屏幕录制，Bonjour 自动配对 Mac 端
• Android app —— 聊天、语音（Talk Mode）、Canvas、摄像头/录屏全套

移动端和桌面端都能和命令行版本协同工作，数据是共享的。我自己是 Mac 上用 menu bar app + 终端混着来，出门就用 iOS app，体验还挺无缝的。

运行引导向导

装好之后跑一下引导向导：

openclaw onboard --install-daemon

向导会引导你完成 4 个步骤。

步骤 1：选择 Gateway 模式

? Select gateway mode:
  ❯ Local (recommended for personal use)
    Tailscale Serve (remote access)
    Tailscale Funnel (public access)

新手选 Local 就行，后续随时可以改。说实话我觉得官方把 Tailscale 放这么前面有点反直觉，毕竟大部分人一开始根本用不上远程访问吧...

步骤 2：配置 AI 模型

? Select your AI provider:
  ❯ OpenAI (recommended)
    Anthropic (Claude)
    Google (Gemini)
    Local LLM (Ollama)
    Custom API endpoint

输入对应的 API Key 就行。密钥存在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 这个路径下。

步骤 3：连接消息平台

? Which platforms would you like to connect?
  ◉ Telegram
  ◉ Discord
  ◯ WhatsApp
  ◯ Slack
  ◯ Feishu (飞书)
  ◯ More...

每个平台需要对应的 Bot Token 或扫码连接（WhatsApp）。这里可以先跳过啊，后面单独配也没问题的。我当时就是先跳过了，后面一个一个慢慢加的。

步骤 4：安装守护进程

? Install daemon for auto-start?
  ❯ Yes (recommended)
    No

选 Yes 会装 launchd（macOS）或 systemd（Linux）服务，开机自动启动。

验证安装

# 检查运行状态
openclaw status

# 检查健康状态
openclaw health

# 查看 Gateway 仪表盘
openclaw gateway status

打开浏览器访问 http://127.0.0.1:18789/，你应该能看到 OpenClaw Dashboard。如果页面打不开——我当时就懵了好一会儿——大概率是 Gateway 没启动成功，赶紧 openclaw logs 看看输出吧。

安全审计

首次安装后建议跑一次深度安全检查：

openclaw security audit --deep

另外强烈推荐跑一下 openclaw doctor，这个命令会自动扫描你的配置，标记出有风险的设置项——比如权限开得太大、不安全的 Skill 配置之类的。我第一次跑的时候还真查出来几个问题，改完踏实多了：

openclaw doctor

还有 openclaw dashboard 可以打开 Control UI——一个图形化的管理面板，比命令行直观多了，适合不想记一堆命令的人：

openclaw dashboard

常用命令速查

目录结构

安装后，关键文件存放在：

~/.openclaw/
├── agents/           # Agent 配置和认证信息
├── credentials/      # OAuth 凭证
├── skills/           # 全局安装的技能
├── workspace/        # 工作区（文件操作的根目录）
│   ├── SOUL.md       # Agent 人设和行为规范
│   ├── USER.md       # 用户偏好记忆
│   └── AGENTS.md     # 多 Agent 配置
└── openclaw.json     # 主配置文件（JSON5 格式）

注意主配置文件是 openclaw.json（JSON5 格式，支持注释），不是 config.json——网上有些老教程还在写 config.json，那是早期版本的叫法，别被误导了。Memory 文件（SOUL.md、USER.md、AGENTS.md）都是普通 Markdown，可以直接编辑，也可以用 Git 管理版本。

环境变量

OpenClaw 支持几个关键的环境变量来覆盖默认路径：

# OpenClaw 主目录（默认 ~/.openclaw）
export OPENCLAW_HOME="/path/to/openclaw"

# 状态数据目录
export OPENCLAW_STATE_DIR="/path/to/state"

# 配置文件路径
export OPENCLAW_CONFIG_PATH="/path/to/openclaw.json"

在 CI/CD 或者多实例部署的场景下这些变量很有用。日常使用的话默认路径就行了。

不同角色怎么装？

开发频道

OpenClaw 有三个发布频道：Stable（最新稳定版）、Beta（预发布版）、Dev（跟 main 分支同步的最新代码）。日常使用选 Stable 就好，想尝鲜可以 openclaw update --channel beta。Dev 频道是给贡献者和愿意踩坑的人准备的，不建议生产环境用。

如果你只是想学习和体验嘛，npm 装在本地 Mac/Linux 就行了。选 OpenAI 做模型（最稳定），先接个 Telegram（最简单）。别一上来就搞 Docker 多平台什么的，没必要。

开发者的话建议从源码构建，方便读代码和改东西。可以配多个模型提供商做 failover，Docker 部署管理测试环境也方便。

企业或团队使用，推荐 Docker + Tailscale Serve 模式。记得配 API Key 轮转和成本监控啊，启用安全审计和 DM pairing。群里有个做 SaaS 的老张踩过这个坑——没配额度上限，团队十几个人用了一周，月底 OpenAI 账单四百多刀...

成本参考

OpenClaw 本身免费，但要付 LLM API 费用。粗略估算一下：轻度使用（日常对话+简单任务）每月大概 ¥5-30；中度使用（文件处理+自动化）大概 ¥30-100；重度使用（全天候 Agent+多平台）大概 ¥100-300 吧。

省钱技巧说白了就一个思路：简单任务用便宜模型（比如 GPT-4o-mini），复杂任务才路由到 GPT-5 或 Claude。OpenClaw 支持按任务复杂度自动选模型，后面配置 LLM 的章节会详细讲。

常见问题

Q: 安装失败提示 Node 版本不够？

nvm install 22
nvm use 22

就这么简单，但这个问题在 Discord 里每周至少被问三次...

Q: Gateway 启动失败端口被占用？

openclaw gateway --port 18790 --verbose

补充一点：macOS 重启后有时候残留进程会占着 18789 端口，lsof -i :18789 查一下然后 kill 掉就好。我自己碰到过两回了。

Q: WhatsApp 扫码连接失败？

确保用的是 Node 而不是 Bun，然后重试：

openclaw channels login whatsapp

---

装好了？试试在终端跑 openclaw status 确认一切正常，然后就可以去接消息平台了。