我的文档

主题

OpenClaw 是一款强大的开源个人 AI 助手，它可以在你的本地机器上运行，并与你常用的聊天应用（如 WhatsApp、Telegram、Discord 等）以及本地系统工具（如文件、浏览器、shell 命令）无缝集成，从而实现自动化任务和智能交互。它旨在提供一个“始终在线”的个人 AI 代理体验，能够自主执行多步骤工作流，并具备持久记忆和自我学习能力。

本教程将详细介绍如何在 macOS、Windows 和 Linux 上安装和使用 OpenClaw。

一、OpenClaw 简介 ​

OpenClaw 被描述为一款自主的、开源的 AI 助理，它可以在你的设备上运行并存在于你的聊天应用程序中。 与 ChatGPT 或 Claude 的网页界面不同，OpenClaw 不仅仅回答问题，它还可以：

  • 多渠道集成：支持 WhatsApp, Telegram, Slack, Discord, iMessage, Signal, WebChat 等20多种消息平台。
  • 本地优先：Gateway、工具和内存都存储在你的机器上，而不是由供应商托管的 SaaS 服务。 会话、长期记忆和技能以 Markdown 和 YAML 文件形式存储在你的工作区和 ~/.openclaw 目录下。
  • 多模型支持：模型是模型无关的，可以配置云端模型（Anthropic, OpenAI, Google）或本地模型（通过 Ollama, LM Studio 等）。
  • 强大的自动化能力：可以运行 shell 命令、控制浏览器、读写文件、管理日历、发送电子邮件，甚至能自主编写代码来创建新的技能。
  • Web 控制 UI：提供一个浏览器仪表板，用于聊天、配置、会话和节点管理。
  • 心跳调度器：以可配置的间隔唤醒，使其无需提示即可运行。

二、安装前准备 ​

在开始安装之前，请确保你的系统满足以下基本要求：

  • 操作系统：macOS、Linux 或 Windows (推荐使用 WSL2)。
  • Node.js：OpenClaw 需要 Node.js 22 或更高版本（推荐 Node.js 24）。安装脚本通常会自动处理 Node.js 的安装。
  • Git：用于拉取和更新 OpenClaw 核心文件。
  • AI 模型提供商账户：你需要至少一个 AI 模型提供商（如 Anthropic、OpenAI、Google 或 OpenRouter）的 API 密钥，用于云端模型使用。或者，你可以安装 Ollama 并拉取本地模型以实现完全本地化、离线使用。
  • 命令行基础知识：熟悉终端或 PowerShell 的基本操作。
  • 可用端口：确保端口 18789 可用，这是 Web 控制 UI 的默认端口。

三、OpenClaw 安装教程（跨平台） ​

OpenClaw 官方推荐使用 openclaw onboard 命令进行引导式安装，因为它会指导你完成 Gateway、工作区、渠道和技能的设置，并且适用于 macOS, Linux, 和 Windows (强烈推荐通过 WSL2) 。

1. 推荐安装方式：一体化安装脚本 ​

这是最快、最简单的安装方法，脚本会自动检测你的操作系统，安装缺失的依赖项（包括 Node.js），并启动引导向导。

macOS 和 Linux ​

在终端中运行以下命令：

bash
curl -fsSL https://openclaw.ai/install.sh | bash
  • 该脚本会检测你的操作系统，更新本地包索引，安装 Node.js 22.22+（如果需要），安装 git, curl, gnupg, ca-certificates 等必备软件包，然后安装 OpenClaw 并启动引导设置。
  • 在 macOS 上，可能会要求你提供管理员密码以安装 Homebrew 和 Node.js。

Windows (PowerShell) ​

在 管理员权限的 PowerShell 中运行以下命令：

powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
  • 首次运行 PowerShell 脚本时，你可能会遇到安全警告，因为代理需要本地文件访问权限。选择“是”以确认。
  • 此脚本会检查并安装 Node.js（如果需要），然后安装 OpenClaw CLI 并启动引导程序。

2. 特定平台安装指南 ​

2.1 macOS ​

macOS 是 OpenClaw 支持最好的平台之一。

通过一体化脚本安装 (推荐):

bash
curl -fsSL https://openclaw.ai/install.sh | bash
  • 该脚本会自动处理 Node.js 和其他依赖项的安装，然后引导你完成 OpenClaw 的设置。

手动安装 (如果一体化脚本遇到问题):

  1. 安装 Homebrew (如果尚未安装):
bash
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  1. 安装 Node.js (推荐使用 Node.js 24 或 22.19+):
bash
  brew install node
验证安装：`node -v` 和 `npm -v`。
  1. 通过 npm 全局安装 OpenClaw CLI:
bash
  npm install -g openclaw@latest
  # 或使用 pnpm: pnpm add -g openclaw@latest
  1. 运行引导向导以安装 Gateway 守护程序:
bash
  openclaw onboard --install-daemon
`--install-daemon` 标志将 OpenClaw 安装为后台服务，并在启动时自动运行。

2.2 Windows ​

OpenClaw 官方强烈推荐在 Windows 上通过 WSL2 (Windows Subsystem for Linux 2) 进行安装，因为它更稳定。

2.2.1 推荐方式：WSL2 + Ubuntu ​
  1. 安装 WSL2 和 Ubuntu: 在 管理员权限的 PowerShell 中运行： 如果 Windows 要求，请重启系统。
  2. 启用 Systemd (Gateway 安装必需): 在你的 WSL Ubuntu 终端中运行： 然后从 PowerShell 关闭 WSL： 重新打开 Ubuntu 终端，并验证 Systemd 状态：systemctl --user status。
  3. 在 WSL 内部安装 OpenClaw: 在你的 WSL Ubuntu 终端中运行一体化安装脚本： 此脚本会处理 Node.js 及 OpenClaw 的安装和引导过程。
  4. 可选：Gateway 在 Windows 登录前自动启动: 在 WSL 内部运行： 然后，安装 OpenClaw gateway 用户服务： 配置 Windows 自动启动 WSL。
2.2.2 原生 Windows 安装 ​

原生 Windows CLI 功能正在改进，但 WSL2 仍是推荐路径。

  1. 安装 Node.js (版本 22 或更高): 从 1 下载最新 LTS 版本并安装。 在管理员权限的 PowerShell 中验证：node -v。
  2. 安装 Git: 从 2 下载 Windows 64 位安装程序并使用默认设置安装。 在终端中验证：git --version。
  3. 运行 PowerShell 安装脚本: 在 管理员权限的 PowerShell 中运行： 该脚本会安装 OpenClaw 并启动引导向导。

2.3 Linux ​

与 macOS 类似，Linux 也推荐使用一体化安装脚本。

通过一体化脚本安装 (推荐):

bash
curl -fsSL https://openclaw.ai/install.sh | bash
  • 该脚本会检测你的 Linux 发行版，安装 Node.js 和其他必需的依赖项，然后启动 OpenClaw 的引导设置。
  • 注意：在运行此脚本之前，你可能需要先安装 curl 和 git：
    bash
    sudo apt update && sudo apt install -y curl git # Debian/Ubuntu
# 对于其他发行版，请使用相应的包管理器，例如 dnf 或 yum。

手动安装 (如果一体化脚本遇到问题):

  1. 安装 Node.js (推荐使用 Node.js 24 或 22.19+):
  • Ubuntu/Debian:
  • Fedora/CentOS:
    bash
    sudo dnf install -y nodejs
    验证安装：node -v 和 npm -v。
  1. 通过 npm 全局安装 OpenClaw CLI:
bash
  npm install -g openclaw@latest
  # 或使用 pnpm: pnpm add -g openclaw@latest
  1. 运行引导向导以安装 Gateway 守护程序:
bash
  openclaw onboard --install-daemon
`--install-daemon` 标志将 OpenClaw 安装为 `systemd` 用户服务。

四、初次设置和引导 (Onboarding) ​

无论你选择哪种安装方式，一旦 OpenClaw CLI 安装完成，都会启动或建议你运行 openclaw onboard 命令。

bash
openclaw onboard [--install-daemon]

--install-daemon 标志会安装 OpenClaw 作为一个后台服务，在系统启动时自动运行（macOS 为 LaunchAgent，Linux/WSL2 为 systemd 用户服务，Native Windows 为 Scheduled Task）。

引导向导将指导你完成以下步骤：

  1. 身份验证:
  • 选择你的 AI 提供商 (如 Anthropic, OpenAI, Google)。
  • 输入你的 API 密钥。
  • 注意: AI 模型的使用通常会产生费用，具体取决于你的使用量。
  1. 安全警告: OpenClaw 是一个个人项目且仍处于测试阶段，并需要本地文件访问权限，请阅读并接受安全警告。
  2. 选择模型: 选择你偏好的模型（例如 Anthropic/Claude Opus 4.6 或 OpenAI GPT-4）。
  3. 配置消息渠道 (可选，但推荐):
  • 向导会引导你连接你喜欢的消息应用，如 Telegram、WhatsApp、Discord 等。
  • 例如，连接 Telegram 需要你使用 @BotFather 创建一个机器人并获取 API token，然后将其粘贴到向导中。
  1. 安装 Gateway 服务: 同意安装 Gateway 作为后台服务。
  2. 孵化你的 Bot：选择 "Hatch in TUI" 来个性化你的代理。

五、OpenClaw 基本使用 ​

1. 验证 Gateway 状态 ​

安装完成后，你可以检查 Gateway 的运行状态：

bash
openclaw gateway status

如果 Gateway 未运行，可以手动启动：

bash
openclaw gateway start
# 或直接运行：
openclaw gateway --port 18789

2. 访问 Web 控制 UI (Dashboard) ​

OpenClaw 提供了一个基于浏览器的控制 UI，作为整个系统的中央仪表板。 运行以下命令打开仪表板：

bash
openclaw dashboard

这将在你的浏览器中打开 http://127.0.0.1:18789/。如果页面加载成功，说明 Gateway 运行正常，你就可以直接在浏览器中与 OpenClaw 聊天了。 在 Web UI 中，你可以：

  • 直接与代理聊天。
  • 查看所有旧消息。
  • 浏览并启用技能。
  • 查看实时日志以了解 OpenClaw 的操作。
  • 管理你的 cron 任务和计划任务。
  • 检查活动会话和子代理。
  • 调整模型配置。

3. 连接消息渠道 ​

通过 openclaw onboard 流程可以配置消息渠道。如果你想稍后添加或修改，可以通过 Web UI 或再次运行 openclaw onboard。

  • Telegram：通常是最快设置的渠道，只需要一个 Bot Token。
    1. 在 Telegram 中搜索 @BotFather。
    2. 发送 /newbot 并按照提示创建一个机器人。
    3. BotFather 会给你一个 API Token，复制它。
    4. 在终端中运行 openclaw onboard，选择 Telegram 并在提示时粘贴你的 Bot Token。
    5. 向你的新机器人发送消息即可开始聊天。
  • 其他渠道如 WhatsApp, Discord, Slack 等，在文档中也有详细的设置步骤。

4. 发送你的第一条消息 ​

在 Web 控制 UI 的聊天界面中输入一条消息，或通过你连接的消息应用向你的 OpenClaw 机器人发送消息，你应该会收到 AI 的回复。

六、OpenClaw 核心概念 ​

  • Gateway：本地运行的控制平面，用于管理会话、渠道、工具和事件。
  • Agent (代理)：具有自己身份、工具和工作区的独立 AI 实体。
  • Skills (技能)：OpenClaw 可以利用和自行安装技能、API 和 CLI 来与系统和外部世界交互。
  • Memory (记忆)：OpenClaw 将配置数据和交互历史存储在本地的 Markdown 文件中，具备持久记忆能力。
  • Channels (渠道)：OpenClaw 可以通过你已在使用的消息应用进行交互，无需安装新应用。

七、常见问题与故障排除 ​

  • Gateway 未响应或“0 tokens used”:
    • 可能是守护程序停止或 API 身份验证失败。
    • 尝试运行 openclaw gateway restart 并验证你的 API 密钥是否正确。
  • “RPC probe: failed”:
    • 通常表示端口 18789 被占用。
    • 使用 sudo lsof -i :18789 查找冲突进程并终止它。
  • “Access not configured”:
    • 你的用户 ID 未被允许。
    • 使用消息机器人提供的代码运行 pairing approve 命令。
  • 安装时 Node.js 版本问题:
    • 安装脚本通常会处理 Node.js 的安装。如果遇到问题，请手动检查 Node.js 版本（node -v），确保其为 22 或更高。
    • 如果需要，使用 nvm (Node Version Manager) 来管理 Node.js 版本。
  • 高 API 成本:
    • 检查哪些代理消耗了最多的 token。
    • 禁用详细日志记录。
    • 对于不需要 Opus 级别推理的子任务，使用更经济的模型（例如 Sonnet）。
  • 代理重启后无响应:
    • 检查守护进程是否正在运行：openclaw gateway status。
    • 如果未运行，请手动启动：openclaw gateway start。
    • 检查代理用户是否启用了自动登录。 [cite: 1手动启动：openclaw gateway start。
    • 检查代理用户是否启用了自动登录。