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 ... 分批安装
相关推荐
圥忈&&丅佽&&扗虖1 小时前
ubuntu启用root账号并登陆
ubuntu
susu10830189113 小时前
ubuntu重做系统后无法apt update
linux·运维·ubuntu
程序大视界3 小时前
Mac电脑详细养小龙虾教程
人工智能·ai·openclaw
MintonLee复现侠3 小时前
保姆级教程：Win+openclaw+阿里百炼大模型+飞书
飞书·openclaw·百炼大模型
每天都在健身的程序员3 小时前
OpenClaw 部署 + 飞书对接完整教程【防踩坑版】
python·openclaw
Sinokap4 小时前
OpenClaw 大更新：支持 GPT-5.4、记忆热插拔，GitHub Star 突破 28 万
openclaw·gpt-5.4
杨云龙UP5 小时前
ODA服务器RAC节点2/u01分区在线扩容操作记录及后续处理流程（Linux LVM + ext4 文件系统在线扩容操作手册）_20260307
linux·运维·服务器·数据库·ubuntu·centos
jyfool12 小时前
Ubuntu 远程桌面配置踩坑实录：从 TightVNC 到 x11vnc 的折腾之旅
linux·运维·ubuntu
He19550114 小时前
openclaw配置飞书
飞书·openclaw·openclaw配置飞书
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03本地部署 OpenClaw + DeepSeek-R1 完全指南04OpenClaw 飞书机器人不回复消息？3 小时踩坑总结05得物前端部门，没了06OpenClaw macOS 完整安装与本地模型配置教程（实战版）07Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南08OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录09Window 10部署openclaw报错node.exe : npm error code 12810OpenClaw 接入 QQ Bot 完整实践指南