OpenClaw 安装与配置全教程（Ubuntu 全新虚拟机版）

脱脱克克2026-03-13 10:52

OpenClaw 安装与配置全教程（Ubuntu 全新虚拟机版）

1. 适用场景

本文适用于以下场景：

  • 你在本地虚拟机中新建了一台全新的 Ubuntu 系统（推荐 Ubuntu 24.04 LTS / 22.04 LTS）。
  • 你希望把 OpenClaw 安装成一个长期运行、相对稳定、便于后续扩展 skills / plugins / channels 的服务。
  • 你希望尽量避免后续常见坑：root 用户安装导致 skill 依赖失败、systemd 用户服务不持久、配置文件和实际运行用户不一致、Dashboard 打不开、skills 装了却不生效等。

2. 先弄清楚 3 件事

在动手之前，先把 OpenClaw 的几个概念分清楚：

2.1 Gateway 是常驻核心进程

OpenClaw 的 Gateway 是长期运行的主进程，负责：

  • 接收来自 Telegram / WhatsApp / Slack / Discord / Feishu 等聊天渠道的消息
  • 调用你配置好的大模型
  • 管理会话、设备、认证、日志、skills、plugins
  • 提供 Web Dashboard / Control UI

2.2 Skills、Tools、Plugins 不是一回事

现代 OpenClaw 里，很多能力已经做成了一等工具（Tools），而不是老式 shell skill；例如 browser、exec、pdf、image、message、cron 等。真正的 Skills 更像"额外能力包"或"任务说明包"；Plugins 则是扩展 OpenClaw 功能、渠道、认证、RPC、工具、命令的模块。

简单理解：

  • Tools：OpenClaw 内置可直接调用的能力
  • Skills：额外能力包 / 工作流说明 / 任务模板
  • Plugins：扩展渠道、认证方式、工具、后台服务等

2.3 模型提供商、聊天渠道、Skills 也不是一回事

很多用户会把下面三类东西混在一起：

  • 模型提供商：OpenAI、Anthropic、Gemini、MiniMax、Moonshot、Z.AI(GLM) 等
  • 聊天渠道：Telegram、WhatsApp、Slack、Discord、Google Chat、Feishu 等
  • Skills：ClawHub 或本地自定义的能力包

后面教程里会分别讲清楚怎么配。

3. 推荐安装策略（非常重要）

对于"本地虚拟机 + 全新 Ubuntu"的场景，我建议直接采用下面这套策略：

  1. 使用全新 Ubuntu LTS
  2. 使用专属普通用户安装和运行 OpenClaw，绝对不要用 root 直接跑
  3. 优先保持 Gateway 只监听本机回环地址 127.0.0.1
  4. 通过 SSH 隧道从宿主机访问 Dashboard
  5. 首次只配置一个模型 + 一个最容易验证的渠道（推荐 Telegram 或 Feishu）
  6. Skills / Plugins 分阶段加，不要一次性全装

这样做的好处是：结构最稳，后续排错最省时间。

4. Ubuntu 虚拟机准备

4.1 推荐虚拟机规格

最低能跑，但不建议长期这么配：

  • 1 vCPU
  • 1 GB RAM
  • 500 MB 以上可用磁盘

更实际的推荐：

  • 2 vCPU
  • 2 GB RAM 或更高
  • 20 GB 磁盘起步

如果你后面会用浏览器自动化、媒体、多个渠道、更多插件，建议直接给 4 GB RAM。

4.2 更新系统并安装基础工具

先用 root 或你创建系统时的管理员用户登录，执行：

bash 复制代码 
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential ca-certificates openssh-server jq

检查 SSH 服务：

bash 复制代码 
sudo systemctl enable --now ssh
sudo systemctl status ssh

5. 创建专属普通用户（强烈推荐）

不要直接用 root 跑 OpenClaw。建议创建一个专门账户，例如 openclaw：

bash 复制代码 
sudo adduser openclaw
sudo usermod -aG sudo openclaw
su - openclaw

你后续所有安装、配置、运行，尽量都在这个普通用户下完成。

6. 安装 OpenClaw：推荐两种方式

6.1 官方推荐方式：安装脚本

bash 复制代码 
curl -fsSL https://openclaw.ai/install.sh | bash
source ~/.bashrc
node --version
openclaw --version

6.2 手动方式：自己装 Node 后再装 OpenClaw

bash 复制代码 
npm install -g openclaw@latest
openclaw onboard --install-daemon

7. 首次引导：openclaw onboard

bash 复制代码 
openclaw onboard --install-daemon

Ubuntu 虚拟机里建议：

  • 模式选 Local
  • bind = loopback
  • port = 18789
  • 鉴权选 token
  • 模型优先走 API key
  • 首次可以先跳过一部分复杂 skills，先保证 Gateway 稳定运行

8. Ubuntu 上 systemd 常驻化

安装后先检查：

bash 复制代码 
openclaw gateway status
openclaw status

启用 linger，避免退出登录后 user service 被系统回收：

bash 复制代码 
sudo loginctl enable-linger openclaw

如果引导阶段提示 systemd user services unavailable 或报 DBus / XDG_RUNTIME_DIR 错误，可在重新登录该用户后手动执行：

bash 复制代码 
openclaw gateway install
systemctl --user daemon-reload
systemctl --user enable --now openclaw-gateway.service
openclaw gateway status

日志查看：

bash 复制代码 
openclaw logs --follow
journalctl --user -u openclaw-gateway.service -f

9. 从宿主机访问 Dashboard / Control UI

在宿主机执行 SSH 隧道：

bash 复制代码 
ssh -N -L 18789:127.0.0.1:18789 openclaw@<VM_IP>

浏览器打开：

text 复制代码 
http://127.0.0.1:18789/

如果要求 token：

bash 复制代码 
openclaw config get gateway.auth.token

10. OpenClaw 的核心目录结构

text 复制代码 
~/.openclaw/
├── openclaw.json
├── .env
├── workspace/
├── skills/
├── extensions/
├── credentials/
├── devices/
└── agents/

建议收紧权限：

bash 复制代码 
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/.env 2>/dev/null || true

11. 推荐的初始配置文件

json5 复制代码 
{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
  },
  gateway: {
    bind: "loopback",
    port: 18789,
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "zai/glm-5",
        fallbacks: ["moonshot/kimi-k2.5"],
      },
    },
  },
  tools: {
    profile: "full",
  },
  skills: {
    load: {
      watch: true,
    },
  },
}

建议把敏感变量放到 ~/.openclaw/.env：

bash 复制代码 
cat > ~/.openclaw/.env <<'ENVFILE'
OPENCLAW_GATEWAY_TOKEN=change-this-token
ZAI_API_KEY=your-zai-key
MOONSHOT_API_KEY=your-moonshot-key
ENVFILE

改完后：

bash 复制代码 
openclaw gateway restart
openclaw doctor
openclaw models status

12. 模型提供商配置：国内外常用平台

12.1 国外常用

Anthropic：

bash 复制代码 
cat >> ~/.openclaw/.env <<'ENVFILE'
ANTHROPIC_API_KEY=your-key
ENVFILE
json5 复制代码 
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-5" }
    }
  }
}

OpenAI：

bash 复制代码 
cat >> ~/.openclaw/.env <<'ENVFILE'
OPENAI_API_KEY=your-key
ENVFILE
json5 复制代码 
{
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.2" }
    }
  }
}

Gemini：

bash 复制代码 
cat >> ~/.openclaw/.env <<'ENVFILE'
GEMINI_API_KEY=your-key
ENVFILE
openclaw configure

12.2 国内常用

Z.AI / GLM：

bash 复制代码 
cat >> ~/.openclaw/.env <<'ENVFILE'
ZAI_API_KEY=your-key
ENVFILE
json5 复制代码 
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" }
    }
  }
}

Moonshot / Kimi：

bash 复制代码 
cat >> ~/.openclaw/.env <<'ENVFILE'
MOONSHOT_API_KEY=your-key
ENVFILE
json5 复制代码 
{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.5" } }
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }]
      }
    }
  }
}

MiniMax：

bash 复制代码 
cat >> ~/.openclaw/.env <<'ENVFILE'
MINIMAX_API_KEY=your-key
ENVFILE
json5 复制代码 
{
  agents: {
    defaults: {
      model: {
        primary: "minimax/MiniMax-M2.5"
      }
    }
  }
}

DeepSeek 常见做法是走 OpenAI 兼容 provider、Together 或 Hugging Face Inference 等兼容平台接入。

13. 聊天渠道配置：国内外常用平台

13.1 优先建议先接入的渠道

Telegram：

json5 复制代码 
{
  channels: {
    telegram: {
      enabled: true,
      token: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

审批：

bash 复制代码 
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Feishu / Lark：

bash 复制代码 
openclaw onboard
# 或
openclaw channels add

WhatsApp：建议在 Telegram / Feishu 跑稳之后再加。

Slack / Discord / Google Chat / Signal：官方支持，但建议分阶段增加。

13.2 亚洲 / 社区常见渠道

WeChat（社区插件）：

bash 复制代码 
openclaw plugins install @icesword760/openclaw-wechat

LINE：官方有插件化渠道文档。

Zalo / Zalo Personal：

bash 复制代码 
openclaw plugins install @openclaw/zalo
openclaw plugins install @openclaw/zalouser

Mattermost：

bash 复制代码 
openclaw plugins install @openclaw/mattermost

14. Skills 怎么装：正确姿势

先看当前状态：

bash 复制代码 
openclaw skills list
openclaw skills check -v
openclaw skills info <skill-name>

Skills 的主要位置：

text 复制代码 
bundled skills
~/.openclaw/skills
<workspace>/skills

优先级：

text 复制代码 
<workspace>/skills > ~/.openclaw/skills > bundled skills

安装 ClawHub CLI：

bash 复制代码 
npm i -g clawhub

搜索与安装：

bash 复制代码 
clawhub search "calendar"
clawhub search "github"
clawhub search "postgres backups"
clawhub install <skill-slug>
clawhub update --all

常见坑：

  • 用 root 跑 OpenClaw
  • skill 装了但 blocked
  • skill 目录放错位置
  • 改完 skill 但没开新 session / 没重启 Gateway

15. Plugins 的安装和启用

先看已有插件：

bash 复制代码 
openclaw plugins list

安装示例：

bash 复制代码 
openclaw plugins install @openclaw/voice-call
openclaw plugins install @openclaw/zalouser
openclaw plugins install @openclaw/zalo
openclaw plugins install @openclaw/feishu

通常装完后要：

bash 复制代码 
openclaw gateway restart

16. 推荐的日常运维命令

bash 复制代码 
openclaw gateway status
openclaw gateway status --deep
openclaw gateway restart
openclaw gateway stop
openclaw logs --follow
openclaw doctor
openclaw models status
openclaw skills list
openclaw skills check -v
openclaw plugins list

Web UI 连不上时优先排查：

bash 复制代码 
openclaw gateway status
openclaw logs --follow
openclaw config get gateway.auth.token

17. 最常见的 8 个坑

  1. 用 root 安装 / 运行
  2. ~/.openclaw/openclaw.json 和运行用户不一致
  3. 忘了启用 linger
  4. Dashboard 要 token 却不知道去哪里找
  5. Skills 装了不生效
  6. 插件装完忘了重启 Gateway
  7. API key 没放进 daemon 可读的位置
  8. 一上来同时配置太多模型 / 渠道 / skills

18. 一套最稳的落地顺序

  1. 新建 Ubuntu VM
  2. 装基础包和 SSH
  3. 创建 openclaw 普通用户
  4. 用该用户执行官方安装脚本
  5. 执行 openclaw onboard --install-daemon
  6. bind=loopback、auth=token
  7. 只接一个模型（例如 zai/glm-5 或 moonshot/kimi-k2.5）
  8. 只接一个渠道（建议 Telegram 或 Feishu）
  9. sudo loginctl enable-linger openclaw
  10. 用 SSH 隧道从宿主机打开 Dashboard
  11. 跑 openclaw doctor
  12. 再逐步加 plugins / channels / skills

19. 最终建议

如果你的目标是"基于本地 Ubuntu 虚拟机，稳定长期使用 OpenClaw，并持续扩展国内外平台能力"，最推荐的组合是：

  • 运行用户 ：openclaw 普通用户
  • 安装方式：官方安装脚本
  • 运行方式：systemd user service + linger
  • 访问方式：SSH tunnel + loopback
  • 首个模型：Z.AI(GLM) / Moonshot(Kimi) / Anthropic API key 三选一
  • 首个渠道：Telegram 或 Feishu
  • Skills 管理 ：openclaw skills check -v + clawhub search/install
  • 插件扩展 ：用 openclaw plugins install ... 分批安装
相关推荐
用户83514140494915 小时前
把日志和寄存器值喂给AI做故障定位，我的实际问法
linux·ubuntu
进击的荆棘15 小时前
MySQL——在ubuntu环境下安装MySQL
数据库·mysql·ubuntu
xzlAwin1 天前
Win10 安装OpenClaw 龙虾
ai·openclaw·龙虾
易点云徐源1 天前
HP 暗影精灵 PRO 16 安装双系统后，开机直接进入 Windows，按 F9 才能进入 Ubuntu：GRUB 菜单不显示的处理方法
linux·运维·ubuntu
Sayai2 天前
Ubuntu 开发环境搭建避坑（一）：网卡 EEE 致 60% 周期性丢包，Realtek RTL8125 网络黑洞排查与修复
linux·运维·网络·ubuntu·性能优化
牢姐与蒯2 天前
WSL2 迁移教程：把Ubuntu+WSL2从C盘挪到别的盘
linux·运维·服务器·网络·ubuntu·1024程序员节
小菜要扣篮2 天前
Ubuntu 下使用 vscode 打开 C++ 项目后，无法通过 F12 定位到定义问题解决
c++·vscode·ubuntu
hhhjhl3 天前
Undici 跨端三方库仓颉适配全流程
java·开发语言·ubuntu
~城南花已开~4 天前
Intel E810 SR-IOV VF Spoofcheck 防伪造测试-KVM3
服务器·网络·笔记·学习·ubuntu·etl工程师
十年磨一剑~4 天前
APT 仓库包查看方法文档
linux·ubuntu
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05几个好用的ip纯净度检测网站06苹果iPA游戏软件资源下载网站07昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战08Android 屏幕适配系列开篇：核心概念、官方机制与主流方案09Dify：一站式AI应用开发平台全解析与Windows部署指南10蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接