Linux 安装 OpenClaw 速成：15 分钟上手

「Linux 安装 OpenClaw 速成指南」，目标非常明确：

👉 15 分钟内把 OpenClaw 跑起来，先能用，再慢慢折腾。

目前已经有不少集成版本可选，如果你是第一次接触 OpenClaw，也可以优先考虑这些一体化方案，本文就不展开了。

考虑到 Ubuntu 在 Linux 发行版中对 OpenClaw 的支持相对更顺滑，本文将以 Ubuntu 24.04 LTS 为例进行说明。
默认环境为 Ubuntu / Debian 系，如果你使用的是 CentOS / RHEL 系，把 apt 替换成 yum 或 dnf 即可。

⏱️ 总流程（先看一眼）

  1. 更新系统并安装必要工具
  2. 安装 Node.js
  3. 下载 OpenClaw
  4. 初始化 OpenClaw 环境
  5. 完成第一次对话
  6. 接入消息平台
  7. 配置权限
  8. 浏览器访问 Control UI 配置

① 更新系统并安装必要工具

先更新系统：

1
sudo apt update -y && sudo apt upgrade -y

如果更新过程中出现红色提示框，一般是询问是否覆盖配置文件。
不确定时保持默认选项即可，直接回车继续。

接着安装常用依赖工具：

1
sudo apt install -y curl wget git unzip build-essential

② 安装 Node.js（必须）

OpenClaw 是一个 Node.js 程序，如果没有安装 Node.js，就无法正常运行。

推荐版本

  • Node.js 21 LTS 或 24 LTS
  • 你也可以根据自己的环境选择其他版本
  • 推荐使用 https://github.com/nvm-sh/nvm 管理 Node.js 版本

安装NVM

1
2
3
4
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# 如果当前环境无法直接访问外网，可以尝试国内镜像
curl -o- https://ghfast.top/https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

重新加载环境

1
2
3
4
5
6
7
# 直接加载文件
source ~/.bashrc

# 或者手动操作
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

安装 NodeJS

1
nvm install v24

验证是否安装成功：

1
2
node -v
npm -v

只要能看到版本号，说明安装成功。

国内网络可配置 npm 镜像（可选）

1
2
3
4
npm config set registry https://registry.npmmirror.com

# 验证镜像配置是否生效
npm config get registry

如果输出为：

1
https://registry.npmmirror.com

就说明配置完成了。

③ 下载 OpenClaw

相关链接如下：

官方安装命令

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

安装过程耗时取决于你的网络情况，耐心等它跑完即可。

国内社区安装方式（附带 npm 源）

1
curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry https://registry.npmmirror.com

其他安装方式

Docker 安装（适合有 Docker 经验的用户）

1
2
3
4
5
6
7
# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

源码安装（适合开发者）

1
2
3
4
5
6
7
8
9
# 克隆项目
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

# 启动
npm run start

④ 初始化 OpenClaw 环境

安装完成后，通常会自动进入初始化流程。
如果没有进入，可以手动执行下面的命令：

1
openclaw onboard

初始化向导大致会引导你完成以下配置

1）免责声明

初始化时会先询问你是 个人使用 还是 多人共享使用。
默认是“个人使用模式”，如果你准备部署到共享或多用户环境，还需要额外做安全加固。

提示大致如下：

1
I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?

默认选项通常是 No，需要切换到 Yes 才能继续。

2）配置模式

一般会有两种：

  • QuickStart：快速开始（推荐）
  • Manual：手动自定义

如果你只是先把服务跑起来，建议直接选 QuickStart。

3）端口设置

  • 在快速模式下，这一步可能会跳过
  • 默认端口通常是 18789
  • 网关默认可以绑定到 LAN，方便局域网内其他设备访问

4）模型配置

这一部分需要你选择模型厂商并填写对应的 API Key。

  • 这一步通常不能跳过
  • 如果你使用的是第三方接口服务，选择 Custom Provider 即可

5）通道配置

如果你暂时不接入 Telegram、飞书等消息平台，可以先选择：

1
Skip for now

6）搜索能力配置

例如：

  • Brave Search
  • Gemini
  • Grok
  • Kimi
  • Perplexity Search
  • Skip for now

如果你只是先验证 OpenClaw 能不能跑起来，建议先选：

1
Skip for now

7）技能配置

系统通常会询问：

1
Configure skills now? (recommended)

默认一般是 Yes，但如果你是第一次安装，建议先选 No，后面再慢慢补。

8）Hooks 配置

这一项也可以先跳过。

9）选择启动方式

系统会问你希望如何启动机器人：

  • Hatch in TUI（推荐）
  • Open the Web UI
  • Do this later

如果你只是想尽快开始对话，建议直接选：

1
Hatch in TUI

⑤ 完成第一次对话

启动 OpenClaw

在服务器上执行：

1
2
3
4
5
6
7
8
# 启动 OpenClaw
openclaw gateway start

# 重启 OpenClaw
openclaw gateway restart

# 进入 TUI 对话界面
openclaw tui

退出 TUI 的方式：

  • 连按两次 Ctrl + C
  • 或输入 /exit

如果你更喜欢网页界面，也可以使用：

1
openclaw dashboard

TUI 和 Dashboard 二选一即可，不必同时启动。

⑥ 接入消息平台

下面以 Telegram 为例。

在 Telegram 中搜索 @BotFather，然后发送：

1
/newbot

按照提示创建一个新的机器人。

2）获取 Bot Token

创建完成后，你会拿到一个 Token。
Telegram 的 Token 一般长这样：

1
84421511:AAGIrPAV-ODU5_6zVtlFwoQJpLPVcQ

3）配置 Telegram 通道

执行配置命令，进入本地设备配置，找到 channels，选择 Telegram，填入刚才拿到的 Token。

4）重启 OpenClaw

1
openclaw gateway restart

5）完成配对

在 Telegram 中给机器人发送一条消息，或者直接发送：

1
/start

如果还没有完成授权，你大概率会看到类似下面的提示：

1
2
3
4
5
6
7
8
OpenClaw: access not configured.

Your Telegram user id: 602888888

Pairing code: 92YRJA89

Ask the bot owner to approve with:
openclaw pairing approve telegram 92YRJA89

此时回到服务器，执行对应的配对命令：

1
openclaw pairing approve telegram 92YRJA89

完成后，你就可以正常和机器人通信了。

⑦ 配置权限

关于新版 OpenClaw 的默认权限

如果你使用的是较新的 OpenClaw 版本，默认权限通常会收得比较紧。

很多人安装完成后发现：
虽然程序能跑、也能聊天，但 无法读写文件、不能执行命令、不能用浏览器，也不能正常跑 skills。
这通常是因为默认 tools.profile 被设置成了：messaging

也就是说，系统只保留了最基础的消息能力。

常见的 profile 类型

目前常见的 profile 有 4 类：

  • minimal：最严格，仅保留极少量能力
  • messaging：只保留聊天功能
  • coding：适合开发场景，可读写文件、执行命令、改代码
  • full：权限最完整，开放更多能力

如果你只是本地测试

如果是自己在隔离环境中学习和测试，很多人会直接切到 full，配置示例如下：

1
2
3
4
5
6
7
openclaw config set tools.profile "full"
openclaw config set tools.sessions.visibility "all"
openclaw config set tools.agentToAgent.enabled true
openclaw config set tools.exec.host "gateway"
openclaw config set tools.exec.security "full"
openclaw config set tools.exec.ask "off"
openclaw config set tools.fs.workspaceOnly false

或者直接编辑配置文件

你也可以直接编辑配置文件：

1
nano ~/.openclaw/openclaw.json

参考配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "tools": {
    "profile": "full",
    "sessions": {
      "visibility": "all"
    },
    "agentToAgent": {
      "enabled": true
    },
    "exec": {
      "host": "gateway",
      "security": "full",
      "ask": "off"
    },
    "fs": {
      "workspaceOnly": false
    }
  }
}

一个提醒

如果你只是为了快速学习和验证功能，把权限先放开确实省事。
但也正因为权限比较大，更建议你在测试机、云服务器或隔离环境中操作，不要一上来就在日常主力机器上全开权限。

等你熟悉之后，再按需把权限逐步收紧，会更稳妥。

检查配置是否正确

可以执行：

1
openclaw config validate

如果输出显示配置文件校验通过，一般就没有明显语法问题。

最后记得重启 OpenClaw：

1
openclaw gateway restart

然后在聊天软件中发送：

1
/new

新建一个对话，顺手测试一下文件、命令、会话等功能是否已经正常。

⑧ 浏览器访问 Control UI 配置

本节专门解决 “服务明明跑着，但浏览器就是进不去 Control UI” 的问题。

1. 只想公网 HTTP 能访问页面

适合：

  • 测试 / 学习
  • 临时调试
  • 不考虑安全性

结论：

  • 显式放行 Origin + 关闭 Device Identity 校验即可

最小可用配置：

1
2
3
4
5
6
7
8
"controlUi": {
  "allowedOrigins": [
    "http://localhost:18789",
    "http://127.0.0.1:18789",
    "http://你的公网IP:18789"
  ],
  "dangerouslyDisableDeviceAuth": true
}

说明:

  • allowedOrigins：告诉 Gateway “这个来源是合法的”
  • dangerouslyDisableDeviceAuth：绕过浏览器对 Secure Context 的限制

✅ 公网 HTTP 可直接访问

2. 只在本机 / 内网访问

适合：

  • localhost
  • 局域网开发
  • 不想折腾 HTTPS
    最小可用配置：
1
2
3
4
5
6
7
"controlUi": {
  "allowedOrigins": [
    "http://localhost:18789",
    "http://127.0.0.1:18789"
  ],
  allowInsecureAuth": true
}

说明:

  • 仅对 localhost / 127.0.0.1 生效
  • 不适用于公网 IP
  • 不会关闭 Device Identity 校验

3. 长期公网使用

适合：

  • 正式部署
  • 长期使用
  • 多人访问

推荐做法:

  • 使用 Nginx 或 Caddy
  • 配置 HTTPS（自签或 Let’s Encrypt）
  • 不要使用任何 dangerously 配置

4. 常见误区澄清

  • allowInsecureAuth 不能替代 allowedOrigins

  • allowInsecureAuth 对公网 IP 无效

  • 公网 HTTP 想跑通，必须关闭 Device Identity 校验

  • 校验顺序简化理解

1
Origin 校验 → Secure Context → Device Identity → Token

  • Gateway Token 不匹配问题（最安全解决方式）

    • 报错:

      1
      unauthorized: gateway token mismatch

    • 解决方式:

      • 在服务器执行命令刷新Token

        1
        openclaw dashboard --no-open

结语

到这里，你已经完成了一个最小可用版的 OpenClaw 安装流程：

  • 环境准备
  • Node.js 安装
  • OpenClaw 下载与初始化
  • 首次对话
  • Telegram 接入
  • 权限配置
  • 远程访问

如果你的目标只是 “先把它跑起来”，那么这套流程基本已经够用了。

后续你可以再慢慢折腾这些内容：

  • 更细的权限控制
  • 搜索能力接入
  • 多平台通道配置
  • Skills / Hooks 的进一步扩展
  • Docker 或源码方式的长期维护

龙虾安装