Ubuntu/Mac安装配置教程

简介

OpenClaw 是一个个人 AI 助手，运行在您自己的设备上，支持 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Microsoft Teams、Matrix、Feishu、LINE、WebChat 等多种通信渠道。本教程将详细介绍在 Ubuntu 和 macOS 系统上安装、配置 OpenClaw 的步骤，以及常见问题的解决办法。

前提条件

[!TIP]

Node.js ≥ 22（推荐最新 LTS 版本）

npm 或 pnpm（OpenClaw 支持 npm 和 pnpm 安装）

Git（可选，用于从源码安装）

稳定的网络连接（用于安装依赖和连接通道）

Ubuntu 安装步骤

1. 安装 Node.js 22+（已验证2026-03-07 13:33）

Ubuntu 默认仓库的 Node.js 版本可能较低，建议通过以下方式安装：

方式一：通过 NodeSource 仓库安装

# 安装 curl 和 gnupg
sudo apt update
sudo apt install -y curl gnupg

# 添加 NodeSource 仓库（Node.js 22）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js
sudo apt install -y nodejs

# 验证安装
node --version  # 应输出 v22.x.x
npm --version   # 应输出 10.x.x

方式二：使用NODE版本管理器NVM

# 1. 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 重新加载shell配置
source ~/.bashrc

# 2. 安装Node.js 22
nvm install 22

# 3. 设为默认版本
nvm use 22
nvm alias default 22

# 4. 验证安装
node --version
npm --version

2. 安装 OpenClaw

通过 npm 全局安装 OpenClaw：

sudo npm install -g openclaw@latest
# 或使用 pnpm
sudo pnpm add -g openclaw@latest

3. 运行 Onboarding 向导

Onboarding 向导会引导您完成网关、工作空间、通道和技能的设置：

#必须带--install-daemon参数
openclaw onboard --install-daemon

根据提示完成：

[!TIP]

选择工作空间目录（默认 ~/.openclaw/workspace）

配置模型（如 OpenAI、Anthropic 等）

设置通道（WhatsApp、Telegram 等）

安装系统服务（systemd user service）

网关绑定方式详解（Gateway bind）

暴露模式详解（Tailscale exposure）

网关令牌详解（Gateway token）

四种内置钩子详解（Enable hooks?）

网关服务已安装 - 三个选项详解

4. 配置系统服务（systemd）（注意：通常在VPS环境下使用，系统会默认安装）

OpenClaw 默认安装 systemd 用户服务，如需设置为系统服务（适用于共享服务器），可手动创建服务文件：

创建 ~/.config/systemd/user/openclaw-gateway.service：

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

启用并启动服务：

systemctl --user enable --now openclaw-gateway.service

如需开机自启（即使未登录），需启用 linger：

sudo loginctl enable-linger $USER

5. 验证安装

运行以下命令检查状态：

openclaw status
openclaw gateway status
openclaw channels status --probe

一切正常时，网关状态应为 Runtime: running，通道显示 connected 或 ready。

macOS 安装步骤

1. 安装 Homebrew 和 Node.js 22+

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js 22
brew install node@22
# 将 Node.js 加入 PATH
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
node --version
npm --version

2. 安装 OpenClaw

npm install -g openclaw@latest

3. 运行 Onboarding 向导

openclaw onboard --install-daemon

向导将引导您完成配置，并安装 launchd 服务（macOS 的守护进程）。

4. 使用 macOS 应用（可选）

OpenClaw 提供 macOS 菜单栏伴侣应用，可管理网关、权限和本地节点功能。

下载最新版 OpenClaw.app
拖入 /Applications 文件夹并打开
完成权限请求（通知、辅助功能、屏幕录制等）
应用将自动连接本地网关或启动远程连接

5. 配置启动项

Onboarding 向导已安装 launchd 服务，手动管理命令：

# 启动服务
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

# 停止服务
launchctl bootout gui/$UID/ai.openclaw.gateway

# 查看状态
launchctl list | grep openclaw

6. 验证安装

openclaw status
openclaw gateway status

常见问题与解决办法

1. 网关无法启动

症状：openclaw gateway status 显示 Runtime: stopped 或启动失败。

可能原因：

端口被占用（默认 18789）
配置文件错误
权限不足

解决：

# 检查端口占用
sudo lsof -i :18789

# 终止占用进程（谨慎操作）
sudo kill <PID>

# 使用其他端口启动
openclaw gateway --port 18790

# 检查配置文件
openclaw doctor

2. 通道连接失败

症状：openclaw channels status --probe 显示 disconnected 或 error。

可能原因：

令牌（Token）无效或过期
网络代理问题
通道配置错误

解决：

# 查看详细日志
openclaw logs --follow

# 重新配置通道
openclaw channels login <channel>  # 如 whatsapp、telegram

# 检查通道配置
openclaw channels status --verbose

3. 节点配对失败

症状：iOS/Android 节点无法连接网关。

可能原因：

网关未暴露到本地网络
防火墙阻止连接
配对码错误

解决：

# 查看配对请求
openclaw pairing list <channel>

# 批准配对
openclaw pairing approve <channel> <code>

# 确保网关可访问（本地 IP）
openclaw gateway status  # 查看 Dashboard URL

4. 权限问题（macOS）

症状：相机、屏幕录制、系统执行等工具失败。

可能原因：

TCC 权限未授予
macOS 应用未在前台运行

解决：

打开 系统设置 > 隐私与安全性，授予相应权限
确保 OpenClaw.app 在前台运行
在应用内检查“执行批准”设置

5. 模型认证失败

症状：AI 模型无法调用，返回 401/403 错误。

可能原因：

API 密钥无效或过期
环境变量未设置

解决：

# 检查模型配置
openclaw status --all

# 设置环境变量（如 OpenAI）
export OPENAI_API_KEY='sk-...'

# 或更新配置文件 ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "openai/gpt-4o",
    "env": {
      "OPENAI_API_KEY": "sk-..."
    }
  }
}

6. 服务无法自启动

症状：重启后 OpenClaw 服务未运行。

解决：

Ubuntu：

# 确保 linger 已启用
sudo loginctl enable-linger $USER

# 重新启用服务
systemctl --user enable openclaw-gateway.service

macOS：

# 重新安装 launchd 服务
openclaw gateway install

7. 浏览器工具失败

症状：openclaw browser status 显示错误。

解决：

# 安装 Chrome/Chromium
sudo apt install chromium-browser  # Ubuntu
brew install --cask google-chrome  # macOS

# 检查浏览器配置
openclaw browser status --verbose

进阶配置

使用 Docker 安装

OpenClaw 提供 Docker 镜像，适合隔离环境运行：

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

远程网关（Linux 服务器）

将网关部署在 Linux 服务器，通过 SSH 隧道或 Tailscale 访问：

# 本地 SSH 隧道
ssh -N -L 18789:127.0.0.1:18789 user@server

# 本地浏览器访问
open http://127.0.0.1:18789/

多配置文件

支持多个配置文件（profile），适用于不同场景：

# 使用特定配置文件
OPENCLAW_PROFILE=work openclaw onboard

# 启动对应网关
OPENCLAW_PROFILE=work openclaw gateway

参考链接

总结

OpenClaw 是一个功能强大的个人 AI 助手，通过本教程您应能在 Ubuntu 或 macOS 上顺利完成安装和配置。如遇问题，请参考常见问题部分或查阅官方文档。欢迎加入 Discord 社区获取帮助和分享经验。

最后更新：2026年3月7日
适用版本：OpenClaw 2026.3.x