首页 › Ubuntu/Debian论坛 › OpenClaw 在 Ubuntu 系统中的完整安装教程（避坑版）

嘉琪爷爷 發表於 2026-2-12 22:39:00

OpenClaw 在 Ubuntu 系统中的完整安装教程（避坑版）

<div data-page-id="TAL9fzPbVd1nDTcdB9vcsuftnkd" data-lark-html-role="root" data-docx-has-block-data="true">
<h1 class="ace-line ace-line old-record-id-TAL9fzPbVd1nDTcdB9vcsuftnkd">OpenClaw 在 Ubuntu 系统中的完整安装教程（避坑版）</h1>
<div class="ace-line ace-line old-record-id-SRJmfUOOTdIJrNcOziEcJX8snIh">OpenClaw 是一款轻量高效的本地个人 AI 助手框架，可实现自动执行任务、调用工具、网页浏览、流程组合等功能，适配 Ubuntu 20.04 LTS 及以上所有主流版本（含 Server 版和 Desktop 版）。本教程整合官方推荐方案与国内环境优化技巧，覆盖“前置准备→多种安装方式→初始化配置→启动使用→常见问题排查”全流程，新手可直接跟着操作，全程规避网络卡顿、依赖缺失、端口无法访问等高频问题。</div>
<h2 class="heading-2 ace-line old-record-id-HpSaf5nWoda2uNcouA6cLb9nnhb">一、前置准备（必做，避免后续安装失败）</h2>
<h3 class="heading-3 ace-line old-record-id-IPOtfetRgdNgTccp380cbIuqnOf">1.1 系统与硬件要求</h3>
<div class="ace-line ace-line old-record-id-J4ePffhKTdYmyCcUjWvcFGQ2nQb">确保你的 Ubuntu 系统满足以下最低要求，推荐配置可提升运行流畅度，适配所有安装方案：</div>
<div>
<table class="ace-table" data-ace-table-col-widths="200;200;200"><colgroup><col width="200"><col width="200"><col width="200"></colgroup>
<tbody>
<tr>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-ZGi8fW8X4dgupOcBRAscJKWxnrg">组件</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-HAJtf4QNAd8EBXcNmExcQ7D7nVb">最低要求</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-Y4Yyf9khWd26Xpc1X2kclyQTnHc">推荐配置</div>
</td>
</tr>
<tr>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-QljkfIugRdm5dMc3QoUcUkShnVb">操作系统</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-RWBXfoQU9dG3Oic2WXeckBjTntc">Ubuntu 20.04 LTS 及以上</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-WA57fSbySd16RYcWawicxn7jnWh">Ubuntu 22.04/24.04 LTS（稳定性最优）</div>
</td>
</tr>
<tr>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-SIG7fqHwud2pGccGNamcqeCJnJH">CPU</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-VMbNfl55adMXElc7zarcUEHgnFf">2 核及以上</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-FBTdfzQUCdWeByckr9jcXDVYnzd">4 核及以上</div>
</td>
</tr>
<tr>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-RmVNfGa8TdhB7zcSXJBcgxVvnqh">内存</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-HycKfR23AdZaiTcaKXwcmHP7n7b">4GB RAM</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-DKbffK5cUdVDK2cu3iPcGxWUnOf">8GB RAM（避免运行卡顿）</div>
</td>
</tr>
<tr>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-KKnXfBmKBdiTwfcvBVLcDqTUnYf">存储</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-IJVofNbaXdiAjHczhUOcSgOlnre">2GB 可用空间</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-NfdHftG5sdxSskcIFlhcEIlqn9d">10GB 可用空间（预留模型与插件存储）</div>
</td>
</tr>
<tr>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-UYOmfFyMnd853JcvFnicfwCFnHh">其他</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-DIjmf63qwd3A4ZcnEVscwgR3ntg">稳定网络、管理员权限（sudo）</div>
</td>
<td rowspan="1" colspan="1">
<div class="ace-line ace-line old-record-id-NpBUfSW2fdRSyucGC9Sc7JyLnsX">kx上网（可选，加速部分依赖下载）</div>
</td>
</tr>
</tbody>
</table>
</div>
<h3 class="heading-3 ace-line old-record-id-EfwAfOwD7dW9Hoc3iLLcnwBgnRf">1.2 系统环境预处理</h3>
<div class="ace-line ace-line old-record-id-OGjgfPPNqdlBJrcGRsEcMjnPnOR">无论选择哪种安装方式，先执行以下命令更新系统、安装基础依赖，解决大部分“依赖缺失”报错：</div>
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;"># 更新系统软件包列表（必做）
sudo apt update &amp;&amp; sudo apt upgrade -y

# 安装基础依赖（编译工具、网络工具等，避免卡在 node-gyp rebuild）
sudo apt install -y curl wget git python3 build-essential libssl-dev ufw</pre>
</div>
<h3 class="heading-3 ace-line old-record-id-M5D3fq3zMdtS3acSKdUcMrP2nrh">1.3 安装 Node.js（核心依赖，必做）</h3>
<div class="ace-line ace-line old-record-id-KhLwfXdzzdkizicZIgHcyfGHnQe">OpenClaw 要求 Node.js 版本 ≥ 22.0.0，推荐使用 NodeSource 源安装（稳定且可快速升级），避免使用 Ubuntu 官方源的低版本 Node.js：</div>
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;"># 导入 NodeSource 22.x 源
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js 和 npm（npm 用于包管理）
sudo apt install -y nodejs

# 验证安装是否成功（显示版本号即正常）
node --version# 需显示 v22.x.x
npm --version   # 需显示 10.x.x 及以上</pre>
</div>
<h3 class="heading-3 ace-line old-record-id-MBj1fvLK6d3gUtcuOkCcozsSnEe">1.4 国内环境优化（可选，解决下载卡顿）</h3>
<div class="ace-line ace-line old-record-id-XdQ2fOkKndQd3ccSpBRcmgFXnUj">国内用户直接下载 OpenClaw 依赖可能卡顿，建议配置 npm 国内镜像（阿里云源），加速下载速度：</div>
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;"># 配置 npm 国内镜像
npm config set registry https://registry.npmmirror.com

# 验证镜像配置是否生效
npm config get registry# 显示 https://registry.npmmirror.com 即成功</pre>
</div>
<h2 class="heading-2 ace-line old-record-id-EJ4Pfuq3VdCdtYcDKqxcHvqUnBi">二、三种安装方式（按需选择，新手首选一键安装）</h2>
<div class="ace-line ace-line old-record-id-AbNCfrVceduGawc3lP1ccWn9nWg">本文提供 3 种安装方案，覆盖不同用户需求：一键安装（新手首选，最简单）、npm 全局安装（灵活可控）、Docker 部署（适合开发者，隔离环境），任选其一即可，安装完成后功能完全一致。</div>
<h3 class="heading-3 ace-line old-record-id-OFnYfGQOtdSso4cHZ1ScT8amncd">方案一：一键安装（官方推荐，新手首选）</h3>
<div class="ace-line ace-line old-record-id-IGaJfFQredZi6LcSU6ZcHx4Wn1c">官方提供一键安装脚本，自动完成所有配置，无需手动操作，适合首次接触 OpenClaw 的新手：</div>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-S9C4fAFN6dSw1lcc4L8cRAaen0f" data-list="number">执行一键安装命令，脚本会自动下载、安装 OpenClaw 及所有依赖（若提示“没有文件”“无法找到install.sh”，核心原因是OpenClaw 2025年末品牌升级后，官方一键脚本路径调整，按以下两种方式解决，优先选方式1）： 方式1：替换为国内可用的一键安装脚本（适配国内网络，解决文件缺失问题）： <code>curl -fsSL https://gitee.com/openclaw-mirror/install-script/raw/main/install.sh | bash</code> 方式2：手动下载安装脚本后执行（彻底解决“没有文件”报错）： <code># 手动下载脚本文件（国内镜像，避免文件缺失） </code><code>wget https://gitee.com/openclaw-mirror/install-script/raw/main/install.sh </code><code># 给脚本添加执行权限 </code><code>chmod +x install.sh </code><code># 执行安装脚本 </code><code>sudo ./install.sh</code></li>
<li class="ace-line ace-line old-record-id-AHevfl0Pgd96Dwcdrumc65Hunyg" data-list="number">安装过程说明：</li>
<li class="ace-line ace-line old-record-id-A4BNfGfXTdSJWVc8GMicFIC2nic" data-list="number">安装过程中会提示确认配置（如模型选择、Channel 配置），默认按 Enter 键即可，后续可在 UI 界面修改；</li>
<li class="ace-line ace-line old-record-id-FDtvf6bYjdlhYhc0e7fcNgSSn7g" data-list="number">若出现“权限不足”报错，在命令前添加 sudo（sudo curl -fsSL ... | bash）；</li>
<li class="ace-line ace-line old-record-id-HUFWfEHrMdzSQgcaxvGcEYPjndh" data-list="number">安装耗时约 3-10 分钟，取决于网络速度，耐心等待，不要中途中断命令。</li>
<li class="ace-line ace-line old-record-id-YD1Wfhm5cd1kpbcev6JcgMm1nhh" data-list="number">验证安装成功：安装完成后，终端会显示“OpenClaw installed successfully”，并给出 Control UI 登录地址（默认 http://127.0.0.1:18789/openclaw），即表示安装成功。</li>
</ol>
<h3 class="heading-3 ace-line old-record-id-JgIFfVWHndEEL3ckj1JcDHhZnGb">方案二：npm 全局安装（灵活可控，适合进阶用户）</h3>
<div class="ace-line ace-line old-record-id-Er9lfDybddAUTbcnGh2ceScFnUc">通过 npm 全局安装，可手动控制版本、灵活配置参数，适合需要自定义安装路径或版本的用户：</div>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-U3cXfL1f4deMfhc9iApcGKG8n4e" data-list="number">执行 npm 安装命令，全局安装最新版 OpenClaw： <code>npm install -g openclaw@latest</code></li>
<li class="ace-line ace-line old-record-id-Auu8frweZdxStEcGXMycoqH5nld" data-list="number">解决下载卡顿问题：</li>
<li class="ace-line ace-line old-record-id-OFdpfyudrd5x9dcOzUBcARGJnHh" data-list="number">若命令执行后卡住（尤其是下载预编译二进制文件时），可中断命令（Ctrl+C），重新执行；</li>
<li class="ace-line ace-line old-record-id-AIuff4DkZdAOq7cCNTzcGerenQb" data-list="number">若仍卡顿，可使用浏览器下载离线安装包（参考国内镜像站），再手动安装。</li>
<li class="ace-line ace-line old-record-id-LbUnfkgaAdk9zjcTOavc1p46nMf" data-list="number">验证安装成功：执行以下命令，显示版本号即正常： <code>openclaw --version</code></li>
</ol>
<h3 class="heading-3 ace-line old-record-id-PIGVf7YHhdLo2EcRkkBcBsoSnV8">方案三：Docker 部署（适合开发者，环境隔离）</h3>
<div class="ace-line ace-line old-record-id-Tp6ef5oxFdogDWcEzQGcEbtLnLg">若你的系统已安装 Docker，可使用容器化部署，避免影响本地系统环境，适合开发、测试场景：</div>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-M9ChfgiHLdIFQMcJ98ecYKewnle" data-list="number">确保 Docker 已安装（未安装可执行以下命令快速安装）： <code># 安装 Docker </code><code>curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun </code><code># 启动 Docker 并设置开机自启 </code><code>sudo systemctl enable --now docker </code><code># 验证 Docker 安装成功 </code><code>sudo docker --version</code></li>
<li class="ace-line ace-line old-record-id-Vp98fsL1CdRwDdcfEEqczEn2nke" data-list="number">克隆 OpenClaw 仓库并启动容器（若执行git clone提示“没有文件”“仓库无法访问”，原因是GitHub海外仓库国内访问受限，替换为国内Gitee镜像仓库，解决文件缺失）： <code># 克隆 OpenClaw 国内Gitee镜像仓库（避免海外仓库文件无法获取） </code><code>git clone https://gitee.com/openclaw-mirror/openclaw.git </code><code># 进入仓库目录 </code><code>cd openclaw </code><code># 启动 OpenClaw Gateway 容器（后台运行） </code><code>sudo docker compose up -d openclaw-gateway</code></li>
<li class="ace-line ace-line old-record-id-YbfzffkEZdx4ExcZSfbcgB76nvb" data-list="number">验证容器启动成功：执行 sudo docker ps，若看到“openclaw-gateway”容器状态为“Up”，即表示部署成功。若启动后容器频繁重启，可执行 <code>sudo docker logs openclaw-gateway</code> 查看错误日志，多数原因是配置文件错误或端口占用。</li>
</ol>
<h2 class="heading-2 ace-line old-record-id-DKsQfcllydunoDcSDMZc9ak0nJe">三、初始化配置（安装完成后必做）</h2>
<div class="ace-line ace-line old-record-id-Le2wfHwT5dmUBScTiEvc41dTneZ">安装完成后，需完成简单初始化配置（模型选择、Channel 配置、端口放行），才能正常使用 OpenClaw 的所有功能，以下步骤适配所有安装方式。</div>
<h3 class="heading-3 ace-line old-record-id-X5NVf1BTid64dlcoMzgcUN7UnNh">3.1 端口放行（必做，解决无法访问 UI 问题）</h3>
<div class="ace-line ace-line old-record-id-VxHvfnwl8d8lBncwGsNchOyzn0e">OpenClaw Gateway 默认监听 18789 端口，Ubuntu 防火墙（ufw）默认会拦截该端口，需手动放行：</div>
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;"># 放行 18789 端口（TCP 协议）
sudo ufw allow 18789/tcp
# 重启防火墙，使配置生效
sudo ufw reload
# 验证端口是否放行成功
sudo ufw status | grep 18789# 显示“ALLOW”即成功</pre>
</div>
<h3 class="heading-3 ace-line old-record-id-U3xif7jgyduIcvc1hHucrcKDnuc">3.2 启动 Gateway 服务</h3>
<div class="ace-line ace-line old-record-id-HLjBfMGS7dNAzWc9iV5cL0PRnmc">Gateway 是 OpenClaw 的核心服务，负责接收请求、调用工具，需确保其正常启动，分两种场景操作：</div>
<h4 class="heading-4 ace-line old-record-id-ZDXNfbfozdJYbwcQqoRc2ORwnCb">场景 1：一键安装/ npm 安装用户</h4>
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;"># 方式 1：前台运行（适合测试，关闭终端即停止）
openclaw gateway --port 18789 --verbose

# 方式 2：后台运行（推荐，持久化启动）
# 安装 PM2 进程管理器（用于后台守护）
npm install -g pm2
# 注意：若已执行过此命令，不要重复执行，避免启动多个openclaw进程（导致端口冲突、UI无法访问）
pm2 start "openclaw gateway" --name openclaw# 仅启动1个进程
pm2 startup
pm2 save

# 验证服务状态（显示“online”且只有1个openclaw进程即正常）
pm2 status openclaw
# 若出现多个openclaw进程，执行以下命令清理（补充）
# pm2 stop openclaw &amp;&amp; pm2 delete openclaw &amp;&amp; pm2 start "openclaw gateway" --name openclaw
# 若服务一直重启，执行 pm2 logs openclaw 查看错误日志，定位重启原因</pre>
</div>
<h4 class="heading-4 ace-line old-record-id-QIbXfBngJdHNB2cbzPtc82xbnee">场景 2：Docker 部署用户</h4>
<div class="ace-line ace-line old-record-id-GjWqfyRnSdWyB9cMcL8ckqrgnrd">Docker 容器启动后会自动运行 Gateway 服务，无需手动启动，若需重启服务：</div>
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;">sudo docker compose restart openclaw-gateway
# 若容器一直重启，查看错误日志（核心排查步骤）
sudo docker logs openclaw-gateway</pre>
</div>
<h3 class="heading-3 ace-line old-record-id-TqF4fWKYUdF4n2cfUDlcUTlfn1c">3.3 配置 Control UI 可远程访问（可选）</h3>
<div class="ace-line ace-line old-record-id-IczkfN0fmdRlIQcMVTVcUg9ynxb">默认情况下，Control UI 仅允许本地（127.0.0.1）访问，若你的 Ubuntu 是 Server 版（无桌面），或想从其他设备访问，需修改配置文件：</div>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-RrPrfEtQ4dBeetcz4TCcZVJPn2f" data-list="number">找到“gateway”配置项，修改为以下内容（自定义 token 和端口可按需调整）：&nbsp;
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;">{
    "agents": {
      "defaults": {
            "workspace": "/home/zhaodt/.openclaw/workspace"
      }
    },
    "meta": {
      "lastTouchedVersion": "2026.2.9",
      "lastTouchedAt": "2026-02-12T13:06:24.900Z"
    },
    "gateway": {
      "port": 18789,
      "mode": "local",
      "bind": "lan",
      "controlUi": {
            "enabled": true,
            "basePath": "/openclaw",
            "allowInsecureAuth": true,
            "dangerouslyDisableDeviceAuth": true
      },
      "auth": {
            "mode": "token",
            "token": "1c20ee2a91f3c4870d1"
      },
      "tailscale": {
            "mode": "off",
            "resetOnExit": false
      },
      "nodes": {
            "allowCommands": [
                "ls",
                "pwd",
                "cat"
            ]
      }
    }
}</pre>
</div>
</li>
<li class="ace-line ace-line old-record-id-UwSXfIXUEdIMtKc2m4sc8ZbdnBh" data-list="number">保存配置并重启 Gateway 服务：
<div class="cnblogs_Highlighter">
<pre class="brush:bash;gutter:true;"># 保存配置（nano 编辑器：Ctrl+O 保存，Ctrl+X 退出）
# 重启服务（npm 安装用户）
pm2 restart openclaw
# 重启服务（Docker 用户）
sudo docker compose restart openclaw-gateway</pre>
</div>
</li>
<li class="ace-line ace-line old-record-id-Kjaxfo6nzdh9BIc1EIqcLFsvnL9" data-list="number">编辑 OpenClaw 配置文件（路径固定，若执行命令提示“没有文件”，核心原因是 OpenClaw 首次安装后未生成配置文件，需先执行配置向导生成，步骤如下）： 第一步：先执行配置向导，生成 /root/.openclaw 目录及 openclaw.json 配置文件（必做）： <code>openclaw setup</code> 执行后按终端提示完成基础配置（如模型选择、Channel 初始化），配置完成后会自动生成配置文件，此步骤是解决文件缺失的核心； 第二步：再执行编辑命令，此时文件已存在，可正常编辑： <code>sudo nano /root/.openclaw/openclaw.json</code> 补充：若执行 openclaw setup 后仍提示无文件，可执行 openclaw configure 重新初始化配置，或手动创建目录后生成文件（命令如下）： <code># 手动创建配置文件目录 </code><code>sudo mkdir -p /root/.openclaw </code><code># 重新生成默认配置文件 </code><code>openclaw config init </code><code># 再次执行编辑命令 </code><code>sudo nano /root/.openclaw/openclaw.json</code></li>
</ol>
<h3 class="heading-3 ace-line old-record-id-XdpMfxNiydl4sBcxmZlc84bun7b">3.4 初始化向导配置</h3>
<div class="ace-line ace-line old-record-id-HjKBfxGRcdu3FWcxGVQcn9EwnHb">访问 Control UI 后，需完成简单向导配置，才能正常使用 AI 功能：</div>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-MVvkfl2IxdoDnXcODnrcNfl5nvc" data-list="number">访问 Control UI：</li>
<li class="ace-line ace-line old-record-id-IGDafujYgdkgFocsAxKc6RXPnsd" data-list="number">本地访问（Ubuntu 有桌面）：打开浏览器，输入 http://127.0.0.1:18789/openclaw（重点提醒：不可只输入127.0.0.1，必须搭配完整端口和路径，否则无法加载UI；若pm2 status显示online但访问无反应，参考5.2节补充排查步骤）；</li>
<li class="ace-line ace-line old-record-id-KlKKftJiYdL3YEc8TfpcKDYonsc" data-list="number">远程访问（其他设备）：输入 http://Ubuntu 服务器 IP:18789/openclaw（服务器 IP 可通过 ip addr show eth0 查看，必须带完整路径）。</li>
<li class="ace-line ace-line old-record-id-GrGyfos3Edr0M5cGRxrc2LyRn0d" data-list="number">完成向导配置：</li>
<li class="ace-line ace-line old-record-id-Dj7vfg3p3dVH1gcgLyvc5gRhnad" data-list="number">模型配置：选择适合自己的 AI 模型（按需选择，后续可修改）；</li>
<li class="ace-line ace-line old-record-id-Uuiffvlh5dbslMcbIYjcWuM3nVg" data-list="number">Channel 配置：Channel 是 OpenClaw 的交互接口，可配置常用聊天工具，实现手机/电脑远程控制；</li>
<li class="ace-line ace-line old-record-id-FUkyfYOQJdHH4acdAsQcTpnCnIg" data-list="number">Skill 配置：安装所需的技能插件（如文件处理、网页浏览等），按需勾选即可。</li>
<li class="ace-line ace-line old-record-id-Z2VpfAlrsdrrU8cE3SWcEUSFn21" data-list="number">登录验证：若配置了 token，在登录界面输入自定义 token，即可进入 Control UI 主界面，完成初始化配置。</li>
</ol>
<h2 class="heading-2 ace-line old-record-id-IqAbfVWj1dCeXYc7Ztsc8oVPnog">四、启动与基础使用（快速上手）</h2>
<h3 class="heading-3 ace-line old-record-id-NQRDfJUgCd86wPcRzx6cJfLCnmd">4.1 启动 OpenClaw</h3>
<ul class="list-bullet1">
<li class="ace-line ace-line old-record-id-PDJNfqvRMdDAW0cUOyScIjYlnWd" data-list="bullet">npm 安装 + PM2 守护：无需手动启动，系统重启后会自动运行，可通过 pm2 status openclaw 查看状态；<strong>重点提醒：不要重复执行 pm2 start 命令，否则会启动多个openclaw进程，导致端口冲突、UI无法访问</strong>；若出现多个进程，执行 <code>pm2 stop openclaw &amp;&amp; pm2 delete openclaw &amp;&amp; pm2 start "openclaw gateway" --name openclaw</code> 清理重启；若服务一直重启，优先执行<code>pm2 logs openclaw</code> 查看错误日志，定位重启原因；</li>
<li class="ace-line ace-line old-record-id-ZvXoffNw9daTwgcvrEjcZcyynsh" data-list="bullet">一键安装用户：默认已配置开机自启，若未启动，执行 openclaw gateway start；若一直重启，执行 <code>openclaw gateway --port 18789 --verbose</code> 前台运行，查看实时报错；</li>
<li class="ace-line ace-line old-record-id-HoRxf2qR4d81Vqc2oWOchtRtnjb" data-list="bullet">Docker 用户：执行 sudo docker compose up -d openclaw-gateway 启动，sudo docker compose stop 停止；若容器一直重启，执行 <code>sudo docker logs openclaw-gateway</code> 查看错误日志，多数为配置错误或端口占用导致。</li>
</ul>
<h3 class="heading-3 ace-line old-record-id-SvQffo4cWdawwzcptp4cjXlDnLc">4.2 基础使用操作</h3>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-BL3ofQgp8dUaRAcXLlvcipQRnTd" data-list="number">进入 Control UI 主界面，点击“New Chat”创建新对话；</li>
<li class="ace-line ace-line old-record-id-Ziyqf59rCdSFf7crHwecbloqnCh" data-list="number">输入指令测试（如“你好，你是？”“检查 Channel 配置是否正确”），OpenClaw 会自动执行并反馈结果；</li>
<li class="ace-line ace-line old-record-id-YhUgfTl8HdJpAMcNWmocaambnXb" data-list="number">配置 Channel 后，可通过常用聊天工具远程发送指令，控制 OpenClaw 执行任务（如文件处理、网页摘要等）；</li>
<li class="ace-line ace-line old-record-id-HzAMf2H26dEXTacLrM0cy8XTnsd" data-list="number">查看日志：执行 openclaw gateway --verbose 可查看实时运行日志，排查使用中的问题（尤其适合排查服务重启问题）。</li>
</ol>
<h2 class="heading-2 ace-line old-record-id-OjkjfaMlzd7D1lcinNScPoVcnCh">五、常见问题排查（避坑重点，解决所有高频报错）</h2>
<h3 class="heading-3 ace-line old-record-id-Wa3Vfdqr3dLviccKEe2cLWHlnmc">1. 安装时卡住，提示“node-gyp rebuild”失败</h3>
<div class="ace-line ace-line old-record-id-CLOUfovLxdFUdPc8Y38cQc71nl4">原因：缺少 Python 和 C++ 编译工具，或 Node.js 版本过低。</div>
<div class="ace-line ace-line old-record-id-AcqgfgW9qdbUV6cLNioclqPIneg">解决方案：重新安装基础依赖，确保 Node.js 版本 ≥22.0.0： <code>sudo apt install -y python3 build-essential </code><code># 重新安装 Node.js（确保版本正确） </code><code>curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - </code><code>sudo apt install -y nodejs</code></div>
<h3 class="heading-3 ace-line old-record-id-Dlhmfgrmrdq2MrckzxKcG0xInp6">2. 启动 Gateway 后，无法访问 18789 端口</h3>
<div class="ace-line ace-line old-record-id-SMttf7WJQdoVJicKynScBxgznIg">原因：防火墙未放行端口，或 Gateway 未正常启动，或配置文件中 bind 未设为 lan。</div>
<div class="ace-line ace-line old-record-id-OpddfWLnldiWfwcNFC9cTJ2en8k">解决方案： <code># 1. 放行端口 </code><code>sudo ufw allow 18789/tcp </code><code>sudo ufw reload </code><code># 2. 检查 Gateway 状态 </code><code>pm2 status openclaw # npm 安装用户，显示online仅代表服务启动，不代表UI正常监听；若出现两个openclaw进程，会导致端口冲突、UI无法访问 </code><code>sudo docker ps # Docker 用户 </code><code># 3. 若未启动，重启服务；若出现两个openclaw进程，先清理冗余进程（核心操作） </code><code>pm2 stop openclaw # 停止所有名为openclaw的进程 </code><code>pm2 delete openclaw # 删除所有名为openclaw的进程（彻底清理冗余） </code><code>pm2 start "openclaw gateway" --name openclaw # 仅启动1个进程 </code><code># 4. 确认配置文件中 bind 为 lan（参考 3.3 节）；若提示无配置文件，先执行 openclaw setup 生成文件 </code><code>openclaw setup # 生成 /root/.openclaw/openclaw.json 配置文件 </code><code>sudo nano /root/.openclaw/openclaw.json # 再编辑配置</code>补充：重点解决「pm2 status 出现两个openclaw进程+UI访问不到」联动问题（高频场景），按以下步骤排查，先解决进程冲突，再排查UI问题： 1. 进程冲突原因：多次执行 pm2 start 命令，导致重复启动openclaw进程，抢占18789端口，进而导致UI无法加载（端口被占用，服务无法正常监听）； 2. 彻底清理冗余进程（必做）：执行上述 pm2 stop + pm2 delete 命令后，再执行 pm2 status 确认只有1个openclaw进程（状态为online）；若仍有多个，执行 <code>pm2 kill</code> 终止所有pm2管理的进程，再重新启动openclaw； 3. 端口冲突排查：清理进程后，执行 <code>sudo lsof -i:18789</code>，确保只有1个node进程（对应openclaw）监听18789端口；若仍有其他进程占用，执行 <code>sudo kill -9 进程ID</code> 释放端口，再重启openclaw； 4. UI访问补充排查：清理进程、重启服务后，必须输入完整地址 http://127.0.0.1:18789/openclaw；若仍无法访问，确认配置中 <code>"controlUi": {"enabled": true, "basePath": "/openclaw"}</code>，执行 <code>npm install -g openclaw@latest --force</code> 修复UI资源，重启服务即可。</div>
<h3 class="heading-3 ace-line old-record-id-WdyJfYEykdy8IVcBe8Vc589mnhY">3. 访问 Control UI 报错，提示“Missing config”</h3>
<div class="ace-line ace-line old-record-id-DYRJf3sa1duKsFcGcPPcXdV7n8j">原因：未完成初始化配置，或配置文件损坏。</div>
<div class="ace-line ace-line old-record-id-Vz8Rftok6dv7tLcyiurcBsxpnN6">解决方案：执行配置向导，重新生成配置文件（同时解决“openclaw.json 没有文件”的问题）：<code>openclaw setup # 启动配置向导，按提示完成配置，自动生成/root/.openclaw/openclaw.json </code><code>openclaw config set gateway.mode local # 设置模式为本地 </code><code>pm2 restart openclaw # 重启服务</code> 补充：若执行 openclaw setup 无反应，可替换为 openclaw configure 命令（功能一致，均能生成配置文件）；若仍无法生成，可手动创建目录后重新执行向导，命令如下： <code>sudo mkdir -p /root/.openclaw </code><code>openclaw config init </code><code>openclaw setup</code></div>
<h3 class="heading-3 ace-line old-record-id-LXPVfbQifdp3J5cVRiocnryBnMe">4. 下载依赖卡顿，无法完成安装</h3>
<div class="ace-line ace-line old-record-id-GRhSfIYwAddW4tc7yKGcJ7Z9nRd">原因：网络问题，或未配置国内镜像。</div>
<div class="ace-line ace-line old-record-id-CV9JfoaCDdH1P6cBYs1cqxHUnBf">解决方案：配置 npm 国内镜像，或使用kx上网，重新执行安装命令（若仍提示“没有文件”，替换为国内镜像命令）： <code>npm config set registry https://registry.npmmirror.com </code><code># 重新安装（npm 安装用户，若提示文件缺失，执行此命令） </code><code>npm install -g openclaw@latest --registry=https://registry.npmmirror.com </code><code># 重新安装（一键安装用户，彻底解决文件缺失，替换原命令） </code><code>curl -fsSL https://gitee.com/openclaw-mirror/install-script/raw/main/install.sh | bash</code></div>
<h3 class="heading-3 ace-line old-record-id-SZJmfg7Yvdk20QcsdXbcmtoYnFh">5. Docker 部署后，容器无法启动</h3>
<div class="ace-line ace-line old-record-id-TMK5fRwG3dujluc88fDcslNon5f">原因：Docker 版本过低，或端口被占用，或配置文件错误。</div>
<div class="ace-line ace-line old-record-id-ABnjfS7HRdqoGpcLUfEcbXY1nqd">解决方案：升级 Docker，释放 18789 端口，排查配置文件错误： <code># 升级 Docker </code><code>curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun </code><code># 查看 18789 端口占用情况，杀死占用进程 </code><code>sudo lsof -i:18789 </code><code>sudo kill -9 进程ID </code><code># 查看容器错误日志，排查配置问题 </code><code>sudo docker logs openclaw-gateway </code><code># 重启容器 </code><code>sudo docker compose up -d openclaw-gateway</code> 补充：若日志提示配置错误，可删除原有配置文件，重新执行初始化配置后重启容器。</div>
<h3 class="heading-3 ace-line old-record-id-SMpbfZa5Id9Es4cl6SFcvS5hn0d">6. OpenClaw 一直重启（高频新增问题）</h3>
<div class="ace-line ace-line old-record-id-OYXjfTBvtdgtstc34QUcLXb3nyd">核心原因：分两种安装场景，共4类高频原因（优先级：日志报错 &gt; 配置错误 &gt; 端口/进程冲突 &gt; 依赖/版本问题），<strong>先查看错误日志，再针对性解决</strong>，避免盲目操作。</div>
<h4 class="heading-4 ace-line old-record-id-LqrtfYwGZdIT0ccZIZAc5xZHnpd">场景 1：npm 安装/一键安装用户（PM2 管理）</h4>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-OsQyfBRCxdUi6dcPUiGcWYhdnOb" data-list="number">
<div>第一步：查看错误日志（核心，必做），定位重启根源： <code># 查看 PM2 管理的 openclaw 错误日志（实时刷新，按 Ctrl+C 退出） </code><code>pm2 logs openclaw </code><code># 若 PM2 异常，用前台启动查看更详细报错（直接显示启动失败原因） </code><code>pm2 stop openclaw &amp;&amp; pm2 delete openclaw </code><code>openclaw gateway --port 18789 --verbose</code> 常见日志报错对应原因：</div>
<ol class="list-number2">
<li class="ace-line ace-line old-record-id-S87EfuxCAdBWZ3cPCJ3cWrxOng0" data-list="bullet">“port in use”：18789 端口被占用（其他进程或重复的 openclaw 进程）；</li>
<li class="ace-line ace-line old-record-id-VL7hf50DHdxWcvcwhKVcm5obnke" data-list="bullet">“invalid config”/“config not found”：配置文件错误（修改后未保存、格式错误）或未生成；</li>
<li class="ace-line ace-line old-record-id-YrbwfMVI9dbDPKc6sbCcFd9nnhh" data-list="bullet">“missing dependency”：依赖缺失（安装不完整，或 Node.js 版本不匹配）；</li>
<li class="ace-line ace-line old-record-id-GgmXfRxk1d6CIqcuV9ZctGROnQh" data-list="bullet">“out of memory”：内存不足（低于 4GB 最低要求，优先扩容或关闭其他占用内存的进程）。</li>
</ol></li>
<li class="ace-line ace-line old-record-id-HT4DfInzeddYMlcaGyocfmn2nVf" data-list="number">
<div>第二步：针对性解决（按日志报错选择，无需全部执行）：</div>
<ol class="list-number2">
<li class="ace-line ace-line old-record-id-HJSefW6JEdXqVCcqrVTcXie3nbg" data-list="bullet">解决端口/进程冲突（最高频）： <code># 1. 查看 18789 端口占用，杀死占用进程 </code><code>sudo lsof -i:18789 </code><code>sudo kill -9 进程ID # 替换为占用端口的进程ID </code><code># 2. 彻底清理 openclaw 冗余进程 </code><code>pm2 kill # 终止所有 PM2 管理的进程 </code><code>pm2 start "openclaw gateway" --name openclaw # 重新启动单个进程 </code><code>pm2 save</code></li>
<li class="ace-line ace-line old-record-id-Iu2PfNZzfdej2Lchvgpc7KN1ngg" data-list="bullet">解决配置文件错误： <code># 删除损坏的配置文件，重新生成 </code><code>sudo rm -rf /root/.openclaw/openclaw.json </code><code>openclaw setup # 重新执行配置向导，生成正确配置 </code><code>pm2 restart openclaw</code></li>
<li class="ace-line ace-line old-record-id-O3Qof15L2d7sync96oHcs7FBnJd" data-list="bullet">解决依赖/版本问题： <code># 重新安装完整依赖，确保 Node.js 版本 ≥22.0.0 </code><code>npm install -g openclaw@latest --force # 强制重新安装，修复缺失依赖 </code><code>node --version # 验证版本，若低于 22.x.x，重新安装 Node.js（参考 1.3 节） </code><code>pm2 restart openclaw</code></li>
<li class="ace-line ace-line old-record-id-PgqCfhzjadCWvrcLppHcAZICnoc" data-list="bullet">解决内存不足： <code># 查看内存占用，关闭无用进程（如大型软件、其他后台服务） </code><code>free -h </code><code>sudo kill -9 占用内存高的进程ID # 谨慎操作，避免杀死系统关键进程 </code><code># 重新启动 openclaw </code><code>pm2 restart openclaw</code></li>
</ol></li>
<li class="ace-line ace-line old-record-id-JG8kftbOidxKAVcsIbqcn5gcnuf" data-list="number">第三步：验证是否恢复正常： <code>pm2 status openclaw # 显示“online”且不再重启即为正常 </code><code>curl http://127.0.0.1:18789/openclaw # 测试完整路径端口是否正常响应</code></li>
</ol>
<h4 class="heading-4 ace-line old-record-id-DnRMf0ribdapSccRi3acVeqVnvc">场景 2：Docker 部署用户（容器重启）</h4>
<ol class="list-number1" start="1">
<li class="ace-line ace-line old-record-id-KySPfVTz0dNg0zcUqRLcallDnye" data-list="number">
<div>第一步：查看容器错误日志（核心，必做），参考 Docker 部署日志排查规范： <code># 查看 openclaw-gateway 容器错误日志（显示启动失败/重启原因） </code><code>sudo docker logs openclaw-gateway </code><code># 查看容器重启记录，确认重启频率 </code><code>sudo docker inspect openclaw-gateway | grep RestartCount</code> 常见日志报错对应原因：</div>
<ol class="list-number2">
<li class="ace-line ace-line old-record-id-Esr8fQ5XvdWVytcTjiocTI9Jntc" data-list="bullet">“port is already allocated”：18789 端口被宿主机其他进程占用；</li>
<li class="ace-line ace-line old-record-id-ATPufaXIddofWHcj6z9cBHKWnpf" data-list="bullet">“config file error”：挂载的配置文件格式错误，或未正确映射；</li>
<li class="ace-line ace-line old-record-id-ZDR8fyvI9dsi7QcQIuZcrD6rnSd" data-list="bullet">“image pull failed”：Docker 镜像拉取不完整（国内网络问题）；</li>
<li class="ace-line ace-line old-record-id-Hm7uf2KyZd7WXDcAaeDc7LzInLA" data-list="bullet">“container exit code 1”：容器启动脚本异常，需重新部署。</li>
</ol></li>
<li class="ace-line ace-line old-record-id-YDP2fYs77drcfCc6QstcMf93nOh" data-list="number">
<div>第二步：针对性解决（按日志报错选择）：</div>
<ol class="list-number2">
<li class="ace-line ace-line old-record-id-Hv6sfjSOhdAosmcXNtncYlAXnlh" data-list="bullet">解决端口占用/容器冲突： <code># 1. 查看端口占用，杀死占用进程 </code><code>sudo lsof -i:18789 </code><code>sudo kill -9 进程ID </code><code># 2. 停止并删除异常容器，重新启动 </code><code>sudo docker compose stop openclaw-gateway </code><code>sudo docker compose rm openclaw-gateway </code><code>sudo docker compose up -d openclaw-gateway</code></li>
<li class="ace-line ace-line old-record-id-AMjhfsEwbdiI4uc5tmscPoyFnGc" data-list="bullet">解决配置文件错误（参考 Docker 部署规范）： <code># 进入容器配置目录，删除错误配置 </code><code>sudo docker exec -it openclaw-gateway /bin/bash </code><code>rm -rf /root/.openclaw/openclaw.json </code><code>exit </code><code># 重新执行初始化配置，重启容器 </code><code>openclaw setup </code><code>sudo docker compose restart openclaw-gateway</code></li>
<li class="ace-line ace-line old-record-id-C9QCfmUHYdnknfccTDmcRgbInof" data-list="bullet">解决镜像/部署问题： <code># 重新拉取国内镜像，重新部署 </code><code>sudo docker compose down </code><code>git pull https://gitee.com/openclaw-mirror/openclaw.git # 更新仓库配置 </code><code>sudo docker compose up -d openclaw-gateway</code></li>
</ol></li>
<li class="ace-line ace-line old-record-id-TUg1fxBHod8JPAcjaZXctvp5nAe" data-list="number">第三步：验证容器是否正常运行： <code>sudo docker ps | grep openclaw-gateway # 状态显示“Up”且无频繁重启即为正常</code></li>
</ol>
<div class="ace-line ace-line old-record-id-PWEYfWW93dlgs7cbcftcUyrGnkt">补充：若以上步骤仍无法解决，执行“彻底重置”操作（备份配置后），重新安装初始化： <code># npm/一键安装用户重置 </code><code>pm2 kill &amp;&amp; npm uninstall -g openclaw </code><code>sudo rm -rf /root/.openclaw </code><code>npm install -g openclaw@latest &amp;&amp; openclaw setup &amp;&amp; pm2 start "openclaw gateway" --name openclaw </code><code># Docker 用户重置 </code><code>sudo docker compose down &amp;&amp; sudo docker rmi openclaw-gateway </code><code>sudo rm -rf openclaw # 删除仓库目录 </code><code>git clone https://gitee.com/openclaw-mirror/openclaw.git &amp;&amp; cd openclaw &amp;&amp; sudo docker compose up -d openclaw-gateway</code></div>
<h2 class="heading-2 ace-line old-record-id-Stg9fq0VudeAYHcSSxsc2aXUnZd">六、总结</h2>
<div class="ace-line ace-line old-record-id-BKtpf5m8YdbPzicKweHcJC7wnbh">本教程覆盖 OpenClaw 在 Ubuntu 系统中的完整安装流程，核心要点的：</div>
<ul class="list-bullet1">
<li class="ace-line ace-line old-record-id-I4c6frZyVdkxUUchksnczIopnkb" data-list="bullet">前置准备重点：更新系统、安装 Node.js 22+、配置国内镜像（国内用户必做）；</li>
<li class="ace-line ace-line old-record-id-KXt3fnVrOdNxKmcMSj0cU17zn4g" data-list="bullet">安装方式选择：新手选一键安装，进阶用户选 npm 安装，开发者选 Docker 部署；</li>
<li class="ace-line ace-line old-record-id-EhgWf6VVAdkGbIcwnPXcP6pYnlh" data-list="bullet">关键配置：放行 18789 端口、启动 Gateway 服务、配置 Control UI 远程访问（按需）；</li>
<li class="ace-line ace-line old-record-id-SVcSfjzaAdUqAXcxJoqcSk7LnFN" data-list="bullet">避坑核心：解决依赖缺失、端口拦截、网络卡顿三大高频问题，新增“一直重启”专项排查，按教程操作可一次性安装成功；</li>
<li class="ace-line ace-line old-record-id-QwwwfDqD9dvKpMc40ydcNIK9nqd" data-list="bullet">重启问题关键：优先查看错误日志（PM2 日志/容器日志），再针对性解决，避免盲目重启，Docker 部署用户可重点参考容器日志排查规范。</li>
</ul>
<div class="ace-line ace-line old-record-id-Llk6f4wsfdTCCCcWJS4ch8jdneb">安装完成后，可根据自身需求配置模型、Channel 和 Skill，实现 AI 自动执行任务、远程控制等功能。若遇到教程未覆盖的问题，可参考 OpenClaw 官方文档（https://docs.openclaw.ai/）或留言排查。</div>
</div><br><br>
来源：https://www.cnblogs.com/databank/p/19610007

查看完整版本: OpenClaw 在 Ubuntu 系统中的完整安装教程（避坑版）