OpenClaw 配置教程

写Cpp的小黑黑
0 阅读25分钟

OpenClaw 配置教程

文档更新：2026-03-07

目录

一、OpenClaw 简介

1.1 项目概述

OpenClaw（曾用名 Clawdbot、Moltbot）是一个开源的、可自托管的 AI 智能体/数字员工平台。它如同一个「有手脚的 AI 管家」，能理解自然语言，并直接在您的电脑或服务器上执行真实任务，如读写文件、运行脚本、收发邮件、操作浏览器等。

1.2 核心特点

  • 开源与本地优先：项目采用 MIT 协议，代码开放。支持在个人电脑或私有服务器上部署，数据和配置由用户掌控，保障隐私安全。
  • 多模型兼容：可接入 Claude、GPT、通义千问、DeepSeek 等多种大语言模型，也支持本地模型。
  • 多渠道接入：能通过 WhatsApp、Telegram、Slack、Discord 及企业微信、钉钉等聊天工具接收指令，无需安装独立 App。
  • 技能插件化 (Skills)：通过「技能」扩展功能，官方和社区已提供数千个插件，覆盖办公、开发、运维、生活服务等领域，并支持用户自定义开发。

1.3 主要功能

  • 办公自动化：自动整理邮件、生成周报、汇总文档、安排日程、跨应用同步数据。
  • 开发与运维：编写/修改代码、执行脚本、自动化部署、监控系统状态、分析日志。
  • 生活与内容：比价购物、自动订票、整理个人知识库、生成文章草稿、翻译内容。
  • 团队协作：可作为「7×24 小时在线员工」，负责跨系统数据同步、工单处理、定时报表分发等。

1.4 技术架构

OpenClaw 的架构主要分为四层：

层级说明
Gateway（网关）连接聊天平台与智能体，负责消息的收发和路由。
Agent（智能体）作为「大脑」，负责理解指令、规划任务、调用工具和记忆管理。
Skills（技能）作为「手脚」，封装具体操作能力，如文件管理、浏览器自动化、API 调用等。
Memory（记忆）将对话历史、用户偏好等信息持久化存储，使 AI 行为具有连续性。

1.5 发展简史

  • 2025 年底：项目以 Clawdbot 之名问世。
  • 2026 年 1 月：因商标问题，先后更名为 Moltbot 和 OpenClaw。
  • 2026 年 2 月：创始人 Peter Steinberger 加入 OpenAI，项目转为开源基金会形式运作。
  • 2026 年 3 月：在国内引发「云上养虾」热潮，多家云厂商相继提供一键部署方案。

二、部署方式与运行环境

OpenClaw 并非完全在云端、通过网页直接操作的 SaaS 服务，其核心程序需要部署在您的电脑或服务器上运行。您可以选择以下任一方式。

2.1 本地部署

将 OpenClaw 直接安装在个人电脑（支持 Windows、macOS、Linux）上。程序需要在此设备上运行，才能执行读写文件、执行命令等操作。

2.2 云端部署

将 OpenClaw 安装在云服务器（如阿里云、腾讯云 ECS）上。云服务器在物理上仍是「一台电脑」，只是不在您身边；部分云厂商也提供了 OpenClaw 的一键部署方案。

2.3 小结

OpenClaw 不是「网页版工具」，而是一个需要您自行部署（在本地电脑或云服务器）才能使用的软件。

三、所需凭证与依赖

运行 OpenClaw 主要需要两类凭证，其中大模型 API Key 为必需；聊天平台 Token 为可选。此外需准备相应的运行环境。

3.1 必需：大模型 API Key

OpenClaw 本身是「调度大脑」，不自带大模型，因此必须接入至少一家大模型服务商的 API 才能工作。可选方案包括：

国内常用模型：

  • 通义千问 (Qwen / 阿里云百炼)：推荐直接按阿里云官方教程配置，包含开通百炼、获取 API Key、在 OpenClaw 中配置 Base URL / 模型及默认模型等完整步骤：
    OpenClaw 接入阿里云百炼（通义千问）
    要点：在 OpenClaw 中 provider 名为 bailian，Base URL 按地域选（北京为 https://dashscope.aliyuncs.com/compatible-mode/v1），模型 ID 如 qwen3.5-plus、qwen3-coder-next，需设置 reasoning: false，默认模型在 agents.defaults.model.primary 中设为 bailian/qwen3.5-plus 等；支持 Web 控制台配置与直接编辑 openclaw.json 两种方式。
  • MiniMax：在其官网开通 Coding Plan 后获取 API Key。
  • Kimi、DeepSeek：在各自开放平台注册并创建应用以获取 Key。

海外常用模型：

  • OpenAI GPT：获取其 API Key。
  • Anthropic Claude：获取其 API Key。

免费/低成本方案：

  • 可使用讯飞星辰 MaaS 平台提供的免费 Token 计划，或阿里云百炼的新用户免费额度。

3.2 可选：聊天平台 Token

若希望通过特定聊天工具（如飞书、钉钉、企业微信、Telegram 等）与 OpenClaw 互动，需为相应平台创建机器人并获取凭证。这些并非运行 OpenClaw 的硬性要求。

平台所需凭证
飞书App ID + App Secret
钉钉Client ID(AppKey) + Client Secret(AppSecret)
TelegramBot Token
DiscordBot Token

3.3 运行环境

  • 本地部署：一台电脑（Windows/macOS/Linux），并安装 Node.js 22+、Git 等依赖。
  • 云端部署：一台云服务器及登录账号。

四、推荐方案：Ubuntu 虚拟机

在虚拟机中运行 OpenClaw 是当前非常主流且推荐的做法：与主力系统隔离，安全性更高。对于环境搭建，首选 Ubuntu 虚拟机，其支持度、稳定性和社区资源都优于 Windows 原生环境。

4.1 为何首选 Ubuntu

  1. 官方主力支持：OpenClaw 的官方安装脚本主要针对 Linux/macOS 设计。在 Windows 上，官方也推荐使用 WSL2（本质是在 Windows 内运行 Ubuntu 环境），说明开发团队的主要支持方向是 Linux 系。
  2. 社区方案统一：目前中英文社区中最主流、文档最齐全的教程几乎都基于 Ubuntu，包括在云上部署、使用 VirtualBox/VMware 创建虚拟机或 Docker 部署。
  3. 兼容性与稳定性更佳：OpenClaw 基于 Node.js 生态，许多依赖和脚本为 Unix/Linux 环境编写。在原生 Windows 上常会遇到路径、权限、脚本执行失败等问题；在 Ubuntu 中这些问题会大幅减少，安装过程更接近官方文档描述。

4.2 系统方案对比

特性Ubuntu 虚拟机（推荐）Windows 原生
官方支持主力支持，脚本和文档最完善兼容性差，非官方推荐方式
安装体验稳定流畅，问题少，接近官方教程问题较多，需自行解决依赖和兼容性
社区资源极其丰富，教程、案例和排错方案多相对较少，多为非官方经验分享
本质原生 Linux 环境需通过 WSL2 模拟 Linux 环境

4.3 虚拟机推荐配置

以在本地电脑的 VMware 或 VirtualBox 中运行 Ubuntu 为例，稳妥配置如下：

  • 系统：Ubuntu 22.04/24.04 LTS（桌面版或服务器版均可）
  • CPU：2～4 核（宿主机性能充足时可分配更多）
  • 内存：至少 4GB，推荐 8GB 以保证流畅运行
  • 磁盘：至少 40～60GB，为系统和后续文件留出空间

推荐部署路径简述：

  1. 在 Windows 上使用 VirtualBox 或 VMware 创建 Ubuntu 22.04/24.04 LTS 虚拟机。
  2. 为虚拟机分配至少 4GB 内存和 40GB 硬盘空间。
  3. 在 Ubuntu 内打开终端，执行官方一键安装：curl -fsSL https://openclaw.ai/install.sh | bash
  4. 按提示完成初始化配置。

4.4 核心前提与安全建议

在虚拟机中运行仍需满足：

  1. 网络通畅：虚拟机需能访问互联网，以下载依赖、连接大模型 API 和聊天平台。
  2. API Key：仍需提供大模型服务（如通义千问、OpenAI、Kimi 等）的 API Key。虚拟机仅提供隔离环境，不替代对 Key 的需求。

安全建议：将 OpenClaw 置于虚拟机中是一种安全实践，因其具备读写文件和执行系统命令的权限；隔离可有效降低对主力电脑的影响。

五、WSL2 图形界面（可选）

若使用 WSL2 而非独立虚拟机，WSL2 中的 Ubuntu 默认无图形界面，仅命令行。可通过以下方式为其添加图形界面。

5.1 方案一：WSLg（Windows 11）

Windows 11 的 WSL2 内置 WSLg，可直接运行 Linux 图形应用，无需额外配置 X 服务器。

  1. 确认环境：系统为 Windows 11，且 WSL 版本 ≥ 0.50.0。
  2. 安装桌面：在 Ubuntu 终端中安装轻量桌面，如 Xfce：
sudo apt update
sudo apt install xfce4 xfce4-goodies -y
  1. 启动桌面：执行 startxfce4，即可在当前窗口中弹出 Xfce 桌面。

5.2 方案二：Xrdp 远程桌面

适用于 Windows 10/11，通过「远程桌面连接」访问 Ubuntu 桌面。

  1. 安装桌面与 Xrdp：
sudo apt update
sudo apt install xfce4 xfce4-goodies xrdp -y
  1. 配置 Xrdp：将默认桌面设为 Xfce，并修改端口（避免与 Windows 远程桌面冲突）：
echo "startxfce4" > ~/.xsession
sudo sed -i 's/port=3389/port=3390/' /etc/xrdp/xrdp.ini
sudo service xrdp restart
  1. 连接：在 Windows 打开「远程桌面连接」(mstsc)，地址输入 localhost:3390，使用 Ubuntu 用户名和密码登录。

5.3 方案三：X11 转发

仅需运行单个图形程序（如 gedit、xclock）时可使用。

  1. Windows 端：安装并运行 X 服务器（如 VcXsrv 或 Xming）。
  2. Ubuntu 端：安装图形应用并设置 DISPLAY：
sudo apt install x11-apps
echo "export DISPLAY=$(awk '/nameserver / {print $2; exit}' /etc/resolv.conf):0" >> ~/.bashrc
source ~/.bashrc
  1. 启动 X 服务器后，在 Ubuntu 终端运行如 xclock 等程序，窗口将显示在 Windows 桌面上。

5.4 与 OpenClaw 的搭配建议

  • 首选：在 Ubuntu 虚拟机中安装完整桌面，最稳定、最接近原生 Linux，教程资源也最丰富。
  • 备选：若坚持使用 WSL2，可采用 WSLg + Xfce 组合，比 Xrdp 更轻量，能满足 OpenClaw 类应用的运行需求。

六、Ubuntu/Linux 本机直接部署（脚本与实战）

本节基于在 Ubuntu 本机（含以 root 运行）的实战整理：使用本文档提供的一键脚本解决国内网络下 NodeSource 连不上的问题，并说明配置向导中常见选项、root 下 systemd 用户服务不可用时的替代方案。

6.1 适用场景与脚本说明

  • 适用：已是 Ubuntu 或其他 Linux，不想用虚拟机，直接在本机装 OpenClaw。
  • 国内网络：若使用 NodeSource（deb.nodesource.com）安装 Node.js 时出现「连接被拒绝」，可用本文档 6.2 节的 nvm + 国内镜像 一键脚本。
  • 本文档内置的脚本（见 9.8 文档内附脚本说明）：
    • 一键部署脚本：安装系统依赖、nvm、Node 22、OpenClaw 官方安装脚本（见 6.2 下方完整脚本）。
    • Gateway 系统服务脚本与 unit：在 root 下让 Gateway 以 systemd 系统服务 后台运行（见 6.5 下方完整内容）。

6.2 一键脚本部署

1. 若之前用过 NodeSource 且安装失败，可先移除其源（可选）：

sudo rm -f /etc/apt/sources.list.d/nodesource.list
sudo apt-get update -qq

2. 将下面「一键部署脚本」保存为 deploy-openclaw.sh，在终端执行（会请求 sudo 密码）：

chmod +x deploy-openclaw.sh
./deploy-openclaw.sh

脚本会依次：安装系统依赖（curl、git、build-essential）→ 用 nvm + 国内镜像 安装 Node.js 22（避免直连 NodeSource）→ 配置 npm 镜像 → 执行官方 https://openclaw.ai/install.sh。遇到安全免责声明时输入 Yes 并回车。

一键部署脚本（复制整段保存为 deploy-openclaw.sh）：

#!/usr/bin/env bash
# OpenClaw 本机部署脚本（Ubuntu/Linux）
# 请在终端执行: bash deploy-openclaw.sh

set -e
echo "========== 1/4 安装系统依赖与 Node.js 22 =========="
sudo apt-get update -qq
sudo apt-get install -y curl git build-essential ca-certificates

# 优先用 nvm + 国内镜像安装 Node 22（避免 deb.nodesource.com 连接失败）
install_node_nvm() {
  export NVM_DIR="$HOME/.nvm"
  if [ -s "$NVM_DIR/nvm.sh" ]; then
    . "$NVM_DIR/nvm.sh"
  else
    echo "安装 nvm..."
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
  fi
  export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
  nvm install 22
  nvm use 22
  nvm alias default 22
}

if command -v node &>/dev/null && [ "$(node -v | cut -d. -f1 | tr -d v)" -ge 22 ] 2>/dev/null; then
  echo "已检测到 Node.js 22+，跳过安装"
else
  echo "使用 nvm + 国内镜像安装 Node.js 22..."
  install_node_nvm
fi

# 确保当前 shell 有 node/npm（若用 nvm）
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
echo "Node 版本: $(node -v)"
echo "npm 版本: $(npm -v)"

echo ""
echo "========== 2/4 配置 npm 镜像（国内加速） =========="
npm config set registry https://registry.npmmirror.com

echo ""
echo "========== 3/4 安装 OpenClaw（官方一键脚本） =========="
echo "遇到安全免责声明时请输入 Yes 并回车"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
curl -fsSL https://openclaw.ai/install.sh | bash

# 确保 PATH 包含 npm 全局 bin 与 nvm
NPM_GLOBAL_BIN="$(npm config get prefix 2>/dev/null)/bin"
export PATH="$PATH:$NPM_GLOBAL_BIN:$HOME/.local/share/npm/bin:$HOME/.npm-global/bin"
if ! command -v openclaw &>/dev/null; then
  [ -s "$NVM_DIR/nvm.sh" ] && echo '[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"' >> ~/.bashrc
  echo "export PATH=\"\$PATH:$NPM_GLOBAL_BIN:\$HOME/.local/share/npm/bin:\$HOME/.npm-global/bin\"" >> ~/.bashrc
  echo "已把 nvm 与 npm 全局 bin 加入 PATH，请执行: source ~/.bashrc"
fi

echo ""
echo "========== 4/4 验证安装 =========="
openclaw --version || true

echo ""
echo "=============================================="
echo "安装阶段完成。请在本终端依次执行："
echo "  1) 配置向导: openclaw onboard --install-daemon"
echo "  2) 登出后仍运行: sudo loginctl enable-linger \$USER"
echo "  3) 打开 Web 控制台: openclaw dashboard"
echo "=============================================="

3. 若提示找不到 openclaw 命令：

source ~/.bashrc
openclaw --version

6.3 配置向导步骤说明（实战）

执行 openclaw onboard --install-daemon 后，按提示操作即可，以下为实战中常见选项说明：

步骤建议选择说明
安全警告Yes确认已阅读并继续。
安装模式QuickStart快速开始，端口 18789、本机绑定。
Model/auth provider有 Key 选对应厂商，没有选 Skip for now选 Skip 可先不配模型，后续在配置或 openclaw onboard 中再加。
Filter models by providerAll providers保持「所有厂商」，后续选模型更灵活。
Default modelKeep current 或 Enter model manually未配 API 时选 Keep current 即可，配好 Key 后再在配置里改默认模型。
Select channelSkip for now 或 Telegram/飞书等仅用 Web 控制台选 Skip；用机器人再选对应渠道并填 Token。
Configure skills now?No（推荐首次选 No）选 Yes 会安装多项技能依赖（如 gh、Homebrew 等），国内/root 下易失败；可后续按需再配。
Enable hooks?Skip for now按需后续再配。
  • 若向导中途退出：重新执行 openclaw onboard --install-daemon 即可，已有配置会保留。
  • Skills 依赖安装失败（如 github 提示 brew not installed）：可忽略，选 No 跳过技能配置；或在 Ubuntu 上需要时手动 sudo apt install gh 等，再通过配置启用对应技能。

6.4 启动 Gateway 与访问控制台

  • 以 root 或未配置 systemd 用户服务时：向导会提示「Systemd user services are unavailable」，不会自动安装后台服务，需要手动启动 Gateway：

    openclaw gateway
# 或
openclaw gateway --port 18789

    保持该终端不关，再用浏览器打开向导最后给出的链接（带 token 的 http://127.0.0.1:18789/...#token=xxx）。

  • Health check failed / Gateway: not detected：说明此时 Gateway 未在运行，先执行上面命令启动后再访问控制台。

  • 未配置大模型 API Key 时：打开控制台发消息会报错 No API key found for provider "anthropic"（默认模型为 Claude）。解决：运行 openclaw onboard 在向导里添加一个模型提供商并填 Key，或执行 openclaw agents add main 按提示配置；配置后无需重启 Gateway 即可使用。

6.5 root 下 systemd 不可用：改为系统服务

在以 root 运行的环境中，systemd 用户服务不可用，向导会跳过「安装守护进程」。若希望 Gateway 开机自启、后台常驻，可改用 systemd 系统服务。按下面步骤操作即可（脚本与 unit 均写在本文档中，无需额外文件）。

1. 保存启动脚本

将下面整段保存为 openclaw-gateway.sh，然后复制到 root 家目录并赋予执行权限：

#!/usr/bin/env bash
# OpenClaw Gateway 启动脚本（供 systemd 调用）

export OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/.openclaw}"
export OPENCLAW_CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

if [ -s "$HOME/.nvm/nvm.sh" ]; then
  . "$HOME/.nvm/nvm.sh"
  nvm use 22 2>/dev/null || nvm use default 2>/dev/null
fi

if command -v openclaw &>/dev/null; then
  exec openclaw gateway --port 18789
fi

for node_dir in "$HOME/.nvm/versions/node"/v22.*/bin; do
  if [ -x "$node_dir/openclaw" ]; then
    export PATH="$node_dir:$PATH"
    exec "$node_dir/openclaw" gateway --port 18789
  fi
done

echo "错误: 未找到 openclaw 命令，请先安装并确保 PATH 或 nvm 正确。" >&2
exit 1

执行（请把 /path/to/ 换成你保存脚本的目录）：

sudo cp /path/to/openclaw-gateway.sh /root/
sudo chmod +x /root/openclaw-gateway.sh

2. 保存 systemd 服务单元

将下面整段保存为 openclaw-gateway.service，然后复制到 systemd 目录：

# OpenClaw Gateway systemd 系统服务（以 root 运行）
[Unit]
Description=OpenClaw Gateway
Documentation=https://docs.openclaw.ai/gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
ExecStart=/root/openclaw-gateway.sh
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-gateway

[Install]
WantedBy=multi-user.target

执行（请把 /path/to/ 换成你保存 unit 的目录）：

sudo cp /path/to/openclaw-gateway.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

3. 检查状态

sudo systemctl status openclaw-gateway

若显示 active (running)，则 Gateway 已在后台运行。用浏览器打开之前的控制台链接（带 token 的 http://127.0.0.1:18789/...#token=xxx）即可使用。

4. 常用命令

命令说明
sudo systemctl start openclaw-gateway启动
sudo systemctl stop openclaw-gateway停止
sudo systemctl restart openclaw-gateway重启（改完配置后可用）
sudo journalctl -u openclaw-gateway -f看实时日志

5. 若启动失败

  • 先确认手动能跑：在 root 终端执行 openclaw gateway --port 18789，能起来再试服务。
  • 看日志：sudo journalctl -u openclaw-gateway -n 50 --no-pager
  • 若报错「未找到 openclaw」：编辑 /root/openclaw-gateway.sh，把 exec openclaw gateway --port 18789 改成你本机 which openclaw 的绝对路径，例如： 
    exec /root/.nvm/versions/node/v22.21.0/bin/openclaw gateway --port 18789
    （将 v22.21.0 换成 ls /root/.nvm/versions/node/ 显示的实际版本。）

七、VirtualBox + Windows 从零部署

以下引导您使用 VirtualBox 在 Windows 上从零部署 OpenClaw，请按步骤操作。

7.1 准备工作

1. VirtualBox 7.x

  • 前往官网 www.virtualbox.org/ 下载并安装。
  • 安装时按默认选项「下一步」即可。

2. Ubuntu 22.04/24.04 镜像

3. 主机 BIOS 设置

  • 重启进入 BIOS，开启虚拟化技术（Intel VT-x / AMD-V），保存并退出，否则虚拟机可能无法正常启动。

7.2 创建 Ubuntu 虚拟机

  1. 新建虚拟机：打开 VirtualBox →「新建」。名称填 OpenClaw-Ubuntu，类型选 Linux，版本选 Ubuntu (64-bit)，下一步。
  2. 分配内存：最低 4GB，推荐 8GB（主机内存 ≥ 16GB 时），下一步。
  3. 创建虚拟硬盘：选择「创建虚拟硬盘」，类型默认 VDI，存储方式选「动态分配」，大小至少 40GB（推荐 60GB 以上），创建。
  4. 挂载镜像：选中该虚拟机 →「设置」→「存储」→ 在「控制器: IDE」下点击光盘图标 →「选择虚拟光盘文件」→ 选中下载的 Ubuntu ISO，确定。
  5. 配置网络：「设置」→「网络」→ 连接方式选 桥接网卡 (Bridged Adapter)，以便虚拟机获得与主机同网段的 IP，确定。
  6. 安装 Ubuntu：启动虚拟机 → 引导菜单选「Try or install Ubuntu」→ 安装向导选「正常安装」，时区选「上海」，磁盘选「清除整个磁盘并安装 Ubuntu」→ 设置用户名和密码（请牢记）→ 等待安装完成并重启，登录进入桌面。

7.3 配置 Ubuntu 基础环境

1. 更新系统并安装基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential ca-certificates

2. 安装 Node.js 22+

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

验证版本（应为 v22.x.x）：

node -v
npm -v

3.（可选）配置国内 NPM 镜像

npm config set registry https://registry.npmmirror.com

若使用 NodeSource 时出现「无法连接 deb.nodesource.com」，可改用 6.2 一键脚本部署 中的 nvm + 国内镜像方式安装 Node（将脚本在虚拟机内执行即可）。

7.4 安装 OpenClaw

1. 执行一键安装

在终端中**以普通用户（非 root）**执行：

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

遇到安全免责声明时，输入 Yes 并回车继续。

2. 验证安装

openclaw --version

若提示 command not found，将 npm 全局目录加入 PATH 后重试：

echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.bashrc
source ~/.bashrc

（若安装脚本提示了其他路径，请以实际路径为准。）

7.5 初始化配置

执行配置向导并安装守护进程（便于开机自启）：

openclaw onboard --install-daemon

按终端提示依次完成：

  • 安全警告：输入 Yes 确认。
  • 安装模式：选 QuickStart（快速开始）。
  • 模型提供商：根据已有 API Key 选择（如 dashscope 通义千问、openai 等）；暂无 Key 可先选 Skip，后续再配。
  • 配置模型（未跳过时）：填写 baseUrl、apiKey、model ID。
  • 消息渠道：可先选 Skip，后续再配置飞书、Web 等。
  • Skills：选 No，后续按需安装。
  • Hooks：选 Skip for now。
  • 完成后向导会自动安装依赖并启动 Gateway 服务。

7.6 访问 Web 控制台

1. 获取链接和 Token

openclaw dashboard
# 或
openclaw dashboard --no-open

终端会输出形如 http://127.0.0.1:18789/?token=xxxxxx 的 URL。

2. 在虚拟机内访问

在 Ubuntu 的 Firefox 或 Chrome 中打开上述链接，即可看到 OpenClaw 聊天界面。

3. 从 Windows 主机访问

  • 虚拟机使用桥接网卡（Bridged）时：在 Ubuntu 执行 ip a 或 hostname -I 查看虚拟机 IP，在 Windows 浏览器打开 http://<虚拟机IP>:18789/#token=<你的Token>；若无法访问，在 Ubuntu 中执行 sudo ufw allow 18789 && sudo ufw reload 放行端口。
  • 虚拟机使用 NAT（网络地址转换）时：需完成 Gateway 监听地址、端口转发与设备配对，详见 7.7 从 Windows 主机访问（NAT + 端口转发）。

7.7 从 Windows 主机访问虚拟机内的 OpenClaw（NAT + 端口转发）

当虚拟机网络为 NAT 时，需完成以下步骤方可在 Windows 浏览器中访问虚拟机内的 OpenClaw 控制台。

1. 让 Gateway 监听所有网卡

默认 Gateway 只监听本机（loopback），外部无法连接。在 虚拟机内打开 OpenClaw 控制台（或先在本机浏览器访问一次），在 Gateway 设置 中找到 Gateway Bind Mode（Network bind profile）：

  • 将 loopback 或 auto 改为 lan（推荐），保存后重启 Gateway（手动启动则重新执行 openclaw gateway；若为 systemd 服务则 sudo systemctl restart openclaw-gateway）。
  • 若选择 custom，必须同时设置 Custom Bind Host 为 0.0.0.0，否则会报错 gateway.bind=custom requires gateway.customBindHost。

2. 配置 VirtualBox 端口转发

  • 在 Windows 上关闭该 Ubuntu 虚拟机（完全关机）。
  • 打开 VirtualBox → 选中该虚拟机 → 设置 → 网络 → 网卡 1，确认连接方式为 NAT。
  • 展开 高级 → 端口转发，添加一条规则：
    • 协议：TCP
    • 主机端口：18789
    • 子系统端口：18789
    • 主机 IP / 子系统 IP 可留空。
  • 确定后启动虚拟机。

3. 获取带 Token 的链接

在 Ubuntu 虚拟机终端执行：

openclaw dashboard

复制输出的链接（形如 http://127.0.0.1:18789/#token=xxxxxx），在 Windows 浏览器中打开时保持使用 127.0.0.1（不要改成虚拟机 IP），即：http://127.0.0.1:18789/#token=<你的Token>。

4. 若出现「已断开与网关的连接 / pairing required」

从 Windows 访问会被视为新设备，需在虚拟机内先批准该设备：

# 在 Ubuntu 终端执行，查看待批准设备
openclaw devices list
# 按输出中的 requestId 批准（替换为实际 ID）
openclaw devices approve <requestId>

批准后在 Windows 浏览器中刷新页面即可正常连接。

5. 可选：放行防火墙

若仍无法访问，在 Ubuntu 中执行：

sudo ufw allow 18789
sudo ufw reload

八、常见问题与后续配置

8.1 常见问题排查

现象原因与处理
openclaw: command not foundnpm 全局路径未加入 PATH，将全局 bin 目录（或 nvm 的 node/bin）加入 PATH 并 source ~/.bashrc；本机部署时见 6.2 一键脚本部署。
NodeSource 安装 Node 失败（无法连接 deb.nodesource.com）国内网络常见。改用本文档 6.2 的一键部署脚本（nvm + 国内镜像）安装 Node 22；或先移除 nodesource.list 再执行该脚本。
Systemd user services are unavailable / 未安装 Gateway 服务以 root 运行时用户级 systemd 不可用。需手动执行 openclaw gateway 启动；长期后台运行见 6.5 root 下 systemd 不可用 配置系统服务。
Health check failed / Gateway: not detectedGateway 未在运行。先执行 openclaw gateway 或 openclaw gateway --port 18789，再打开控制台链接。
No API key found for provider "anthropic"（或其它 provider）未配置大模型 API Key。运行 openclaw onboard 在向导中添加模型并填 Key，或 openclaw agents add main 配置；配置后无需重启 Gateway。
Web 控制台提示 unauthorized: gateway token missing访问链接中缺少或填错 Token，使用 openclaw dashboard 重新获取带 Token 的链接。
Gateway 启动失败或卡在 Starting...多为模型 apiKey 或 baseUrl 配置错误。执行 openclaw logs --tail 50 查看日志；用 openclaw config view 检查 models 配置；修改后执行 openclaw gateway restart。
虚拟机内浏览器无法启动OpenClaw 默认以无沙箱模式启动 Chrome，配置不当会失败。安装 Chrome：sudo apt install -y google-chrome-stable；编辑 ~/.openclaw/openclaw.json，在 browser 部分配置为："executablePath": "/usr/bin/google-chrome"，"args": ["--no-sandbox", "--disable-setuid-sandbox", "--headless=new"]；然后 openclaw gateway restart。
Gateway failed to start: gateway.bind=custom requires gateway.customBindHost将 Bind Mode 改为 lan（推荐），或在配置中为 gateway.customBindHost 填写 "0.0.0.0" 后重启 Gateway。
已断开与网关的连接 / pairing required从非本机（如 Windows 主机）访问时需设备配对。在虚拟机内执行 openclaw devices list 查看待批准设备，再执行 openclaw devices approve <requestId> 批准后，在浏览器中刷新即可。详见 7.7。

8.2 后续步骤

  • 接入通义千问（阿里云百炼）：按阿里云官方教程操作即可：OpenClaw 接入阿里云百炼（含 Web 控制台与配置文件两种配置方式、默认模型与切换说明）。
  • 接入飞书：在 Web 控制台或执行 openclaw plugins install @openclaw/feishu，按引导完成飞书应用创建与权限配置。
  • 切换模型：编辑 ~/.openclaw/openclaw.json 中的 agents.defaults.model.primary 或 models 部分，改为目标模型（如 bailian/qwen3.5-plus）后重启 Gateway。

九、安全提醒

OpenClaw 通常需要较高系统权限，配置不当或暴露于公网可能带来安全风险。建议：

  • 避免不必要的公网暴露。
  • 严格控制访问权限和 API 密钥。
  • 及时更新和加固系统。

十、补充说明与参考

9.1 官方资源与参考链接

部署与排错时建议以官方文档为准，便于获取最新要求与变更：

文档中的安装命令、端口（默认 18789）、配置路径等均与官方一致，若遇不一致请以官方当前说明为准。

9.2 其他安装方式

除文档中的一键脚本外，还可按需选择：

  • npm 全局安装（需已安装 Node.js 22+）： 
    npm install -g openclaw
  • Windows 原生：若在 Windows 上不采用 WSL/虚拟机，可使用官方 PowerShell 安装脚本（以管理员身份运行 PowerShell 后执行）： 
    iwr -useb https://openclaw.ai/install.ps1 | iex
  • Docker：官方支持通过 Docker 进行容器化部署及沙箱化 Skills，详见官方 Docker 安装文档。

9.3 配置与数据目录

自定义配置与数据集中在用户目录下，便于备份和迁移：

路径说明
~/.openclaw/openclaw.json主配置文件（模型、网关、渠道等）
~/.openclaw/workspace工作区（Skills、提示词、记忆等，可单独做 Git 备份）
~/.openclaw/credentials/各渠道与账号凭证存放位置
~/.openclaw/agents/*/sessions/会话状态

修改配置后一般需重启 Gateway：openclaw gateway restart。

9.4 Linux 常驻运行（systemd）

  • 普通用户：OpenClaw 通过 systemd 用户服务运行。若希望登出后仍保持运行，可启用「linger」：

    sudo loginctl enable-linger $USER

    完成后无需保持登录，Gateway 也会在后台持续运行。

  • root 用户：用户级 systemd 对 root 不可用，向导不会安装守护进程。若需开机自启与后台常驻，请使用 systemd 系统服务：本文档 6.5 中写明了 openclaw-gateway.sh 与 openclaw-gateway.service 的完整内容及安装步骤，按说明保存并启用即可。

9.5 常用命令速查

命令说明
openclaw onboard --install-daemon首次/重新运行配置向导并安装守护进程
openclaw gateway status查看 Gateway 是否在运行
openclaw gateway restart重启 Gateway（改配置后常用）
openclaw gateway --port 18789前台启动 Gateway（便于排错看日志）
openclaw dashboard打开 Web 控制台并输出带 Token 的链接
openclaw health健康检查，确认服务与配置是否正常
openclaw config view查看当前配置（便于核对模型、baseUrl 等）
openclaw logs --tail 50查看最近 50 行日志，用于排错

9.6 网络与代理（国内用户）

若部署环境在国内，可能遇到：

  • 访问 openclaw.ai / 官方安装脚本：若无法直连，需在终端配置 HTTP/HTTPS 代理后再执行 curl ... install.sh。
  • npm 安装依赖：文档中已建议配置国内镜像（如 registry.npmmirror.com），可减少超时与失败。
  • 大模型 API：选用国内可访问的模型（如通义、DeepSeek、Kimi 等）并填写正确的 baseUrl（若厂商要求），避免 Gateway 连不上模型。

以上仅为常见情况，具体以本机网络与所用模型服务商为准。

9.7 安装脚本安全提示

执行「一键安装」前建议注意：

  • 脚本会从互联网下载并执行代码，请确保来源可信（官方域名：openclaw.ai）。
  • 若希望先审阅再执行，可先下载脚本查看内容后再决定是否运行： 
    curl -fsSL https://openclaw.ai/install.sh -o install.sh
cat install.sh   # 审阅后再执行: bash install.sh
  • 安装过程会写入 ~/.openclaw/、npm 全局包等，建议在虚拟机或专用环境中操作，避免与主力系统混用。

9.8 文档内附脚本说明

为便于仅凭本文档即可完成部署，脚本与 systemd 内容已全部写在正文中，无需单独下载文件：

内容在文档中的位置用途
一键部署脚本6.2 一键脚本部署 下方代码块保存为 deploy-openclaw.sh 后执行，用于安装系统依赖、nvm、Node 22、OpenClaw；适用于国内网络下 NodeSource 连不上的环境。
Gateway 启动脚本6.5 root 下 systemd 不可用 下方保存为 openclaw-gateway.sh，复制到 /root/ 并 chmod +x，供 systemd 调用。
systemd 服务单元同上 6.5 节保存为 openclaw-gateway.service，复制到 /etc/systemd/system/，执行 systemctl enable --now openclaw-gateway 即可开机自启、后台运行。

使用顺序建议：先用 6.2 的一键脚本完成安装与 openclaw onboard；若以 root 运行且希望 Gateway 常驻，再按 6.5 配置系统服务。

以上内容供本地部署参考，请以官方文档及实际环境为准。

avatar
文章
阅读
粉丝