第 3 章 · 环境准备与快速体验

从零到第一次对话，大约需要 10 分钟。但本章会带你走得更远——理解每一步在做什么、为什么这样做、出了问题怎么排查。

本章你将学到

在 macOS、Windows（WSL2）和 Linux 上安装 OpenClaw 的完整步骤
引导向导的每个步骤及其背后的配置含义
配置文件的结构和关键配置项
接入第一个消息通道
发送第一条消息并得到 AI 回复

3.1 安装前的准备

3.1.1 系统要求

OpenClaw 的系统要求很朴素：

Node.js 24（推荐）或 Node 22.14+（仍然支持）
操作系统：macOS、Linux、Windows（原生或 WSL2）
磁盘空间：安装本身约 200MB，运行时需要额外的空间存储会话和日志
内存：至少 512MB 可用内存（Agent 运行时额外消耗取决于模型和工具使用）
网络：需要能访问你选择的模型提供商的 API

不需要 GPU。OpenClaw 不在本地运行模型——它通过 API 调用远程模型。你需要的只是一台能运行 Node.js 的机器。

3.1.2 检查 Node.js 版本

打开终端，运行：

node -v

预期输出类似：

v24.0.0

如果版本号以 v24. 开头，你已经满足推荐要求。如果以 v22.1 开头且小版本号 >= 14，也行。如果 Node.js 没有安装或版本太老，按下一节的指引安装。

3.1.3 安装 Node.js

macOS（推荐使用 Homebrew）：

brew install node
# 验证
node -v

Linux（Ubuntu/Debian）：

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证
node -v

Linux（Fedora/RHEL）：

sudo dnf install nodejs
# 验证
node -v

Windows（推荐使用 winget）：

winget install OpenJS.NodeJS.LTS
# 验证（在新的 PowerShell 窗口中）
node -v

使用版本管理器（如果你需要在多个 Node 版本之间切换）：

# fnm（快速，跨平台）
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24
fnm use 24

# nvm（广泛使用于 macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24
nvm use 24

⚠️ 踩坑记录

问题：安装了 Node.js，但终端提示 node: command not found。

原因：Node.js 的可执行文件目录不在系统的 PATH 环境变量中。

解决：
如果使用 Homebrew 安装（macOS），运行 brew link node

如果使用版本管理器，确保它已添加到你的 shell 启动文件（~/.zshrc 或 ~/.bashrc）
如果使用 npm 全局安装后 openclaw 找不到，运行：
export PATH="$(npm prefix -g)/bin:$PATH"
把这行加到你的 ~/.zshrc 或 ~/.bashrc 里使其永久生效。

3.2 安装 OpenClaw

3.2.1 方法一：安装脚本（推荐）

这是最快的安装方式。脚本会自动检测你的操作系统、安装 Node.js（如果缺失）、安装 OpenClaw，并启动引导向导。

macOS / Linux / WSL2：

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

Windows（PowerShell）：

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

脚本运行后，你会看到安装进度。安装完成后，它会自动启动引导向导（onboarding）。

如果你只想安装不运行引导向导：

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

# Windows
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

3.2.2 方法二：npm / pnpm

如果你已经自己管理 Node.js，可以直接用 npm 或 pnpm 安装：

# npm
npm install -g openclaw@latest

# pnpm（需要额外一步批准构建脚本）
pnpm add -g openclaw@latest
pnpm approve-builds -g

安装完成后，验证：

openclaw --version

预期输出类似：

1.2.3

⚠️ 踩坑记录

问题：npm 安装时报 sharp 构建错误。

原因：系统安装了全局的 libvips，与 npm 包内的 sharp 冲突。

解决：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

3.2.3 方法三：从源码构建

适用于贡献者或需要最新开发版本的用户：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
# 验证
openclaw --version

或者不 link 到全局，直接在仓库目录里用 pnpm openclaw ... 运行。

3.2.4 方法四：Docker

Docker 适合想要隔离环境或在没有 Node.js 的主机上运行 OpenClaw 的场景。Docker 的完整配置在 3.6 节详细说明。

3.2.5 验证安装

无论用哪种方式安装，运行以下命令验证：

openclaw --version      # 确认 CLI 可用
openclaw doctor         # 检查配置问题

如果 openclaw 命令找不到，参考 3.1.3 节的 PATH 排查步骤。

3.3 引导向导（Onboarding）

安装完成后，运行引导向导是配置 OpenClaw 最简单的方式。向导会引导你完成模型选择、API Key 配置、工作空间设置、通道连接等步骤。

openclaw onboard --install-daemon

--install-daemon 参数会在引导完成后把 Gateway 安装为系统服务（macOS 的 LaunchAgent 或 Linux 的 systemd unit），确保它在后台持续运行。

3.3.1 QuickStart 模式 vs Advanced 模式

引导向导首先问你选择哪种模式：

QuickStart（默认）——使用合理的默认值，适合大多数用户。默认配置包括：

本地 Gateway（loopback 绑定）
默认工作空间（~/.openclaw/workspace）
Gateway 端口 18789
自动生成 Token 认证（即使在本机也要求认证）
工具策略默认为 coding（允许文件操作和命令执行，但不是完全开放）
DM 隔离默认为 per-channel-peer
Telegram 和 WhatsApp DM 默认使用 allowlist

Advanced——暴露每一个配置步骤，让你完全控制。适合有特殊需求的用户。

3.3.2 步骤一：模型和认证

向导会让你选择一个模型提供商并输入 API Key。OpenClaw 支持 35+ 提供商，包括：

Anthropic（Claude 系列）
OpenAI（GPT 系列）
Google（Gemini 系列）
自定义提供商（任何 OpenAI 兼容或 Anthropic 兼容的端点）
本地模型（Ollama、vLLM、SGLang）

选择提供商后，你需要输入 API Key。这个 Key 会被安全地存储在 Agent 的认证配置文件中：

~/.openclaw/agents/main/agent/auth-profiles.json

💡 提示

如果你使用的是本地模型（如 Ollama），不需要 API Key。向导会自动跳过这一步。

如果你不想在引导向导中输入 API Key（比如在 CI/CD 环境中），可以使用非交互模式：
openclaw onboard --non-interactive --secret-input-mode ref

3.3.3 步骤二：工作空间

向导会问你工作空间的位置。默认是 ~/.openclaw/workspace。你可以接受默认值，也可以指定一个自定义路径。

如果你接受默认值，向导会自动创建工作空间目录并生成 Bootstrap 文件：SOUL.md、AGENTS.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。这些文件是 Agent 的"出厂设置"——你可以之后随时修改它们来塑造 Agent 的人格。

如果你已经有一个预配置的工作空间（比如从 Git 仓库克隆的），可以设置 agent.skipBootstrap: true 来跳过自动创建。

3.3.4 步骤三：Gateway 配置

向导会配置 Gateway 的网络和认证参数：

端口：默认 18789
绑定地址：默认 loopback（仅本机访问）
认证方式：默认 Token（自动生成一个随机令牌）
Tailscale 暴露：默认关闭

自动生成的 Token 会在引导完成后显示在终端。请记下这个 Token——你需要在 Web 控制面板和 CLI 中使用它来认证。

3.3.5 步骤四：消息通道

向导会问你想要连接哪些消息通道。可选的通道包括：

WhatsApp
Telegram
Discord
Google Chat
Mattermost
Signal
BlueBubbles（iMessage 桥接）
iMessage（macOS 原生）

你可以选择"稍后配置"来跳过这一步。通道可以在任何时候通过 CLI 或配置文件添加。

3.3.6 步骤五：守护进程

--install-daemon 参数会让向导把 Gateway 安装为系统服务。安装完成后，Gateway 会在后台自动运行，即使你关闭终端也不会停止。

macOS：安装为 LaunchAgent。标签是 ai.openclaw.gateway。

openclaw gateway status    # 检查状态
openclaw gateway restart   # 重启
openclaw gateway stop      # 停止

Linux：安装为 systemd user unit。

openclaw gateway status    # 检查状态
sudo loginctl enable-linger $USER  # 确保注销后服务不停止

⚠️ 踩坑记录

问题：Linux 上 Gateway 在注销后停止运行。

原因：systemd user service 默认在用户注销时停止。OpenClaw 的引导向导会尝试自动启用 lingering，但如果失败了，你需要手动执行：
sudo loginctl enable-linger $USER
替代方案：如果不想启用 lingering，可以安装为系统级服务（需要 root 权限）。

3.3.7 步骤六：健康检查

引导完成后，向导会自动启动 Gateway 并验证它是否正常运行。

你也可以手动验证：

openclaw gateway status

健康输出应该包含：

Runtime: running
RPC probe: ok

3.3.8 步骤七：技能安装

向导最后会询问是否安装推荐的技能（Skills）。技能是预构建的功能包，让 Agent 能做特定的事情——比如 Web 搜索、Home Assistant 控制等。

你可以跳过这一步，之后通过 ClawHub 社区市场或 CLI 手动安装。

3.4 配置文件深度解析

引导向导完成后，你的所有配置都存储在 ~/.openclaw/openclaw.json 中。理解这个文件的结构，是你掌控 OpenClaw 的关键。

3.4.1 配置文件位置

路径	用途
`~/.openclaw/openclaw.json`	主配置文件（JSON5 格式）
`~/.openclaw/.env`	环境变量（不覆盖已存在的环境变量）
`~/.openclaw/workspace/`	Agent 工作空间
`~/.openclaw/credentials/`	通道认证凭据
`~/.openclaw/agents/<agentId>/`	Agent 状态目录
`~/.openclaw/agents/<agentId>/sessions/`	会话记录

你可以通过环境变量覆盖默认路径：

OPENCLAW_CONFIG_PATH — 覆盖配置文件路径
OPENCLAW_STATE_DIR — 覆盖状态目录
OPENCLAW_HOME — 覆盖主目录

3.4.2 最小配置

一个能跑起来的最小配置：

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],  // 只允许这个号码发消息
    },
  },
}

这就是你需要的全部。Gateway 会使用默认端口 18789、默认模型（你在引导中配置的）、默认工作空间。

3.4.3 完整配置结构

下面是一个涵盖了主要配置项的完整配置示例，附带详细注释：

{
  // ===== Gateway 配置 =====
  gateway: {
    port: 18789,                    // 监听端口
    bind: "loopback",               // 绑定模式: loopback | lan | custom | tailnet | auto
    auth: {
      token: "your-secure-token",   // 认证令牌（强烈建议设置）
    },
    reload: {
      mode: "hybrid",               // 热重载模式: hybrid | hot | restart | off
      debounceMs: 300,              // 防抖时间（毫秒）
    },
  },

  // ===== Agent 配置 =====
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-4-6",  // 默认模型
      workspace: "~/.openclaw/workspace",    // 工作空间路径
      timeoutSeconds: 600,                   // Agent 超时（秒）
      thinkingDefault: "high",               // 默认思考深度
      heartbeat: {
        every: "30m",              // 心跳间隔（"0m" 禁用）
        target: "last",            // 心跳目标: last | whatsapp | telegram | none
      },
    },
    // 多 Agent 列表（可选）
    // list: [
    //   { id: "work", workspace: "~/.openclaw/workspace-work" },
    // ],
  },

  // ===== 通道配置 =====
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-DEF...",  // Telegram Bot Token
      dmPolicy: "allowlist",          // DM 策略: pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],    // allowlist 模式下的允许列表
    },
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },  // 群组中需要 @mention 才响应
      },
    },
  },

  // ===== 会话配置 =====
  session: {
    scope: "per-sender",           // 会话隔离级别
    resetTriggers: ["/new", "/reset"],  // 触发会话重置的命令
    reset: {
      mode: "daily",               // 自动重置模式: daily | idle | manual
      atHour: 4,                   // 每天几点重置
      idleMinutes: 10080,          // 空闲多少分钟后重置（7天）
    },
  },

  // ===== 路由配置 =====
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],  // 群组 @mention 模式
    },
  },

  // ===== 日志配置 =====
  logging: {
    level: "info",                 // 日志级别: debug | info | warn | error
  },
}

3.4.4 编辑配置的四种方式

方式一：引导向导

openclaw configure    # 交互式配置向导

方式二：CLI 单行命令

openclaw config get agents.defaults.workspace    # 读取配置
openclaw config set agents.defaults.heartbeat.every "2h"  # 修改配置
openclaw config unset plugins.entries.brave.config.webSearch.apiKey  # 删除配置

方式三：Web 控制面板

打开 http://127.0.0.1:18789，在 Config 标签页中编辑。控制面板渲染一个表单，也有 Raw JSON 编辑器作为兜底。

方式四：直接编辑文件

用任何文本编辑器编辑 ~/.openclaw/openclaw.json。Gateway 会自动检测文件变化并热应用。

⚠️ 踩坑记录

问题：修改了配置文件后，Gateway 报错并拒绝启动。

原因：OpenClaw 对配置文件进行严格校验。未知的键、错误的类型、无效的值都会导致 Gateway 拒绝启动。这是有意的——宁可启动失败也不使用错误的配置。

解决：
openclaw doctor       # 查看具体的配置问题
openclaw doctor --fix # 自动修复常见问题

3.4.5 配置文件分割

当配置变得很大时，可以用 $include 指令把配置拆分到多个文件：

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },                    // 单文件替换
  channels: { $include: ["./channels-whatsapp.json5",        // 数组：按顺序深度合并
                          "./channels-telegram.json5"] },
}

嵌套 include 最多支持 10 层。路径相对于包含文件的位置解析。

3.4.6 环境变量在配置中的使用

OpenClaw 支持在配置值中引用环境变量：

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",  // 引用环境变量
    },
  },
}

规则：

只匹配大写名称：[A-Z_][A-Z0-9_]*
环境变量缺失或为空会在加载时报错
用 $${VAR} 转义为字面量

环境变量的来源优先级（从高到低）：

进程已有的环境变量
当前工作目录下的 .env 文件
~/.openclaw/.env 文件

3.4.7 密钥引用（SecretRef）

对于 API Key 等敏感信息，OpenClaw 支持 SecretRef 对象，从环境变量、文件或命令输出中读取密钥：

{
  models: {
    providers: {
      openai: {
        // 从环境变量读取 API Key
        apiKey: {
          source: "env",
          provider: "default",
          id: "OPENAI_API_KEY",
        },
      },
    },
  },
  channels: {
    googlechat: {
      // 从文件读取 Service Account
      serviceAccountRef: {
        source: "file",
        provider: "filemain",
        id: "/path/to/service-account.json",
      },
    },
  },
}

3.5 第一次对话

3.5.1 打开 Web 控制面板

引导完成后，打开控制面板：

openclaw dashboard

这会在默认浏览器中打开 http://127.0.0.1:18789。如果提示需要认证，输入引导向导生成的 Token。

Web 控制面板

控制面板的布局大致如下：

左侧：会话列表，显示所有对话
中间：聊天区域，输入消息并查看回复
右侧：配置面板，可以查看和修改配置

3.5.2 发送第一条消息

在聊天输入框中输入任何内容，比如：

你好，请介绍一下你自己。

按回车发送。几秒钟后，你应该能看到 Agent 的回复。

回复的内容取决于你的 SOUL.md 和 AGENTS.md 的配置。如果你没有修改过这些文件，Agent 会使用默认的"出厂人格"——一个通用的、有礼貌的 AI 助手。

第一次对话

3.5.3 理解第一次对话背后发生了什么

当你发送那条消息时，以下是幕后发生的事情（对应第二章的 Agent Loop）：

Web 控制面板通过 WebSocket 把消息发送给 Gateway
Gateway 把消息路由到默认 Agent（main）
Agent Runtime 检查是否有现有会话——这是第一条消息，所以创建新会话
加载 Bootstrap 文件（SOUL.md、AGENTS.md 等）注入上下文
构建 Prompt，发送给你配置的模型提供商
模型生成回复，流式返回
回复通过 WebSocket 推送到 Web 控制面板
会话记录保存到 ~/.openclaw/agents/main/sessions/<sessionId>.jsonl

3.5.4 会话管理命令

在聊天中，你可以使用斜杠命令来管理会话：

命令	作用
`/new` 或 `/reset`	重置当前会话（开始新对话）
`/compact [指令]`	压缩当前会话上下文（保留关键信息，释放 Token 空间）
`/model`	查看可用模型列表
`/model <模型名>`	切换到指定模型

3.6 接入消息通道

Web 控制面板适合在电脑前使用，但 Agent 的真正价值在于在你日常使用的消息应用中随时可用。这一节介绍如何接入最常用的两个通道：Telegram 和 WhatsApp。

3.6.1 接入 Telegram（推荐新手从这里开始）

Telegram 是最容易接入的通道——只需要一个 Bot Token，不需要扫码，不需要额外的手机号。

步骤一：创建 Telegram Bot

在 Telegram 中搜索 @BotFather
发送 /newbot
按提示输入 Bot 的名称和用户名
BotFather 会给你一个 Token，格式类似 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

步骤二：配置 OpenClaw

openclaw channels add --channel telegram --token "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

或者直接编辑配置文件：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "allowlist",
      allowFrom: ["tg:你的TelegramID"],
    },
  },
}

步骤三：获取你的 Telegram ID

在 Telegram 中搜索 @userinfobot，发送任意消息，它会回复你的用户 ID（纯数字）。

步骤四：重启 Gateway 并验证

openclaw gateway restart
openclaw channels status --probe

预期输出包含 telegram: connected 或类似的状态信息。

步骤五：在 Telegram 中对话

打开 Telegram，找到你创建的 Bot，发送一条消息。如果配置正确，Agent 会在几秒内回复。

⚠️ 踩坑记录

问题：Telegram Bot 没有回复，但 openclaw channels status 显示已连接。

原因：最常见的原因是 allowFrom 列表中的 Telegram ID 格式不正确。Telegram ID 应该是纯数字，不需要加 @ 符号。在配置中使用 tg: 前缀："tg:123456789"。

另一个常见原因：Bot 的 Privacy Mode 默认开启，导致 Bot 在群组中收不到所有消息。如果需要在群组中使用，需要在 BotFather 中关闭 Privacy Mode：发送 /setprivacy，选择你的 Bot，然后选择 Disable。

3.6.2 接入 WhatsApp

WhatsApp 的接入比 Telegram 复杂一些，因为需要扫码配对。OpenClaw 使用 Baileys 库来管理 WhatsApp Web 连接。

重要前提：双手机设置

强烈建议使用一个专用的手机号码来运行 Agent，而不是你个人的 WhatsApp 号码。如果你把个人 WhatsApp 连接到 OpenClaw，每一条发给你的消息都会变成 Agent 的输入——这通常不是你想要的。

你的手机（个人）          专用手机（Agent）
┌──────────────┐        ┌──────────────┐
│ 你的 WhatsApp │ 消息 → │ Agent 的     │
│ +1-555-YOU   │        │ WhatsApp     │
└──────────────┘        │ +1-555-ASSIST│
                        └──────┬───────┘
                               │
                               │ QR 配对
                               ▼
                        ┌──────────────┐
                        │ 你的电脑     │
                        │ (OpenClaw)   │
                        └──────────────┘

步骤一：WhatsApp 配对

openclaw channels login --channel whatsapp

终端会显示一个 QR 码。用 Agent 的 WhatsApp 扫描这个 QR 码（WhatsApp → 设置 → 已关联设备 → 关联设备）。

配对成功后，终端会显示确认信息。WhatsApp 的认证凭据保存在：

~/.openclaw/credentials/whatsapp/default/creds.json

步骤二：配置 allowFrom

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],  // 你的个人手机号（E.164 格式）
    },
  },
}

步骤三：重启 Gateway 并验证

openclaw gateway restart
openclaw channels status --probe

步骤四：测试

从你的个人手机发送一条消息给 Agent 的 WhatsApp 号码。Agent 应该在几秒内回复。

⚠️ 踩坑记录

问题：WhatsApp 配对后，Agent 收不到消息。

原因 1：allowFrom 没有配置或配置错误。手机号必须是 E.164 格式（带国际区号，如 +15555550123），不能有空格或破折号。

原因 2：WhatsApp 会话过期。Baileys 的 WhatsApp Web 会话有时效性，长时间不活跃可能会断开。运行 openclaw channels status --probe 检查连接状态，如果显示断开，重新运行 openclaw channels login。

原因 3：Gateway 没有运行。检查 openclaw gateway status，确保 Runtime: running。

3.6.3 接入 Discord

Discord 的接入需要一个 Bot Token 和一些 Discord 开发者面板的配置。

步骤一：创建 Discord Bot

打开 Discord 开发者门户
点击 "New Application"，输入名称
在左侧导航栏点击 "Bot"
点击 "Add Bot"
在 Bot 页面，开启 "Message Content Intent"（重要！不开这个 Bot 收不到消息内容）
点击 "Reset Token" 获取 Bot Token

步骤二：邀请 Bot 到服务器

在 "OAuth2 → URL Generator" 中：

Scopes: 勾选 bot
Bot Permissions: 勾选 Send Messages、Read Message History、Read Messages/View Channels
复制生成的 URL，在浏览器中打开，选择你的服务器

步骤三：配置 OpenClaw

{
  channels: {
    discord: {
      enabled: true,
      token: "你的Discord Bot Token",
      groupPolicy: "allowlist",
      guilds: {
        "你的服务器ID": {
          channels: {
            "频道ID": { allow: true, requireMention: false },
          },
        },
      },
    },
  },
}

获取服务器 ID 和频道 ID：在 Discord 中开启开发者模式（设置 → 高级 → 开发者模式），然后右键点击服务器/频道名称 → 复制 ID。

3.7 Docker 部署

如果你想要一个完全隔离的运行环境，或者你的主机上没有 Node.js，Docker 是一个不错的选择。

3.7.1 前提条件

Docker Desktop 或 Docker Engine
Docker Compose v2
至少 2GB 内存（构建镜像时 pnpm install 可能需要）

3.7.2 快速部署

使用官方脚本：

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 运行设置脚本（构建镜像 + 引导配置 + 启动）
./scripts/docker/setup.sh

设置脚本会：

构建 Docker 镜像（或拉取预构建镜像）
运行引导向导（配置模型、API Key、Token）
通过 Docker Compose 启动 Gateway
生成 .env 文件保存 Token

3.7.3 使用预构建镜像

如果不想本地构建，可以使用 GitHub Container Registry 上的预构建镜像：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

可用标签：main、latest、<version>（如 2026.2.26）。

3.7.4 手动部署

如果不想用脚本，可以手动操作：

# 构建镜像
docker build -t openclaw:local -f Dockerfile .

# 运行引导
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

# 配置绑定地址（Docker 需要用 lan 而不是 loopback）
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.mode local
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.bind lan

# 启动
docker compose up -d openclaw-gateway

3.7.5 Docker 中的通道配置

# WhatsApp（QR 配对）
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

3.7.6 健康检查

# 容器存活检查
curl -fsS http://127.0.0.1:18789/healthz

# 容器就绪检查
curl -fsS http://127.0.0.1:18789/readyz

3.7.7 持久化存储

Docker Compose 默认挂载以下目录：

OPENCLAW_CONFIG_DIR → /home/node/.openclaw（配置和凭据）
OPENCLAW_WORKSPACE_DIR → /home/node/.openclaw/workspace（工作空间）

这些挂载确保容器重启后数据不丢失。

⚠️ 踩坑记录

问题：Docker 容器中报权限错误（EACCES）。

原因：容器以 node 用户（uid 1000）运行，但挂载的目录属于 root。

解决：
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
问题：镜像构建时 OOM 被杀（exit 137）。

原因：虚拟机内存不足，pnpm install 需要较多内存。

解决：使用至少 2GB 内存的虚拟机。

3.8 远程访问

默认情况下，Gateway 只监听 loopback（127.0.0.1），只能从本机访问。如果你需要从其他设备访问（比如从手机连接到家里的 Mac 上运行的 Gateway），有几种方式。

3.8.1 方式一：Tailscale（推荐）

Tailscale 是最简单、最安全的远程访问方案。它创建一个虚拟局域网，所有设备都在同一个虚拟网络中，无需端口转发。

# 1. 在所有设备上安装 Tailscale 并登录
# 2. 在 Gateway 配置中设置绑定模式为 tailnet
openclaw config set gateway.bind tailnet
# 3. 重启 Gateway
openclaw gateway restart

在 Tailscale 网络中，OpenClaw 把 Tailscale IP 视为"本地"连接，可以自动配对设备。

3.8.2 方式二：SSH 隧道

如果你已经能通过 SSH 访问 Gateway 主机：

ssh -N -L 18789:127.0.0.1:18789 user@host

这条命令在本地创建一个隧道，把本地的 18789 端口转发到远程主机的 18789 端口。之后，你在本地用 ws://127.0.0.1:18789 连接的就是远程的 Gateway。

⚠️ 注意：即使通过 SSH 隧道访问，Gateway 认证仍然有效。你仍然需要 Token 或 Password。

3.8.3 方式三：直接暴露 LAN

如果你在同一局域网内：

openclaw config set gateway.bind lan
openclaw gateway restart

这会让 Gateway 监听 0.0.0.0，局域网内的所有设备都可以访问。必须配置 Token 认证——不配置的话，局域网内的任何人都可以连接你的 Gateway。

3.9 常见问题排查

3.9.1 Gateway 无法启动

openclaw gateway status

常见错误和解决方案：

错误信息	原因	解决
`refusing to bind gateway ... without auth`	非 loopback 绑定但没有认证	设置 `gateway.auth.token`
`another gateway instance is already listening` / `EADDRINUSE`	端口被占用	`openclaw gateway --force` 或修改端口
`Gateway start blocked: set gateway.mode=local`	配置了 remote 模式	设置 `gateway.mode` 为 `local`
配置校验失败	配置文件有错误	`openclaw doctor --fix`

3.9.2 Agent 没有回复

排查步骤：

# 1. 检查 Gateway 是否在运行
openclaw gateway status

# 2. 检查通道是否连接
openclaw channels status --probe

# 3. 检查 API Key 是否有效
openclaw health

# 4. 查看日志
openclaw logs --follow

3.9.3 CLI 命令不可用

# 检查 openclaw 是否在 PATH 中
which openclaw

# 如果找不到，检查 npm 全局路径
npm prefix -g

# 确保全局 bin 目录在 PATH 中
echo $PATH | grep "$(npm prefix -g)/bin"

3.9.4 Doctor 命令

openclaw doctor 是你的好朋友。它会检查配置文件、认证状态、文件权限等常见问题，并给出修复建议。

openclaw doctor       # 检查并报告问题
openclaw doctor --fix # 检查并自动修复

3.10 下一阶段建议

你现在已经有了一个能跑的 OpenClaw 实例，可以在 Web 控制面板或消息通道中跟 Agent 对话。接下来做什么？

立即可以做的事：

修改 SOUL.md，给 Agent 一个独特的人格
修改 AGENTS.md，定义 Agent 的行为规则
修改 USER.md，告诉 Agent 你是谁

短期目标：

接入第二个消息通道
尝试在对话中使用 /model 切换模型
配置心跳（Heartbeat），让 Agent 定期检查某些事情

中期目标：

安装几个 Skills，扩展 Agent 的能力
配置 Cron 定时任务
尝试浏览器自动化

这些内容会在后续章节中详细介绍。

本章小结

OpenClaw 需要 Node.js 22.14+ 或 24，安装方式有脚本、npm/pnpm、源码构建、Docker 四种
引导向导（openclaw onboard）是配置 OpenClaw 最简单的方式，包含 QuickStart 和 Advanced 两种模式
配置文件 ~/.openclaw/openclaw.json 使用 JSON5 格式，支持热重载、环境变量引用、文件分割
Telegram 是最易接入的通道（只需 Bot Token），WhatsApp 需要扫码配对和专用手机号
Docker 部署适合隔离环境，需要至少 2GB 内存
远程访问推荐 Tailscale 或 SSH 隧道
openclaw doctor 是排查问题的第一工具

下一步

环境准备好了，通道接入了，第一条消息也发了。下一卷"实战篇"会带你深入每个功能领域——从塑造 Agent 人格到构建复杂的多 Agent 系统，从工具和技能的开发到自动化工作流的搭建。认知篇的任务到此完成。

💡 经验之谈

很多人的 OpenClaw 之旅是这样的：安装 → 跑通 → 用了两天默认配置 → 觉得"不过如此" → 停用。问题出在他们没有花时间去定制 Agent。

OpenClaw 的默认人格是一个"礼貌但无趣的通用助手"。它不会主动帮你做事，不会记住你的偏好，不会有任何"个性"。但这些恰恰是 OpenClaw 的强项——通过修改几个 Markdown 文件，你可以把它变成一个真正懂你的、有记忆的、有主动性的助手。

我的建议是：跑通之后，花 30 分钟修改 SOUL.md 和 AGENTS.md。哪怕只是写几句话——"我喜欢简洁的回复"、"用中文回答"、"记住我喜欢早起"——都会让体验有一个质的飞跃。