当前位置：

文章详情

OpenClaw 在 Debian服务器上的安装、重装、排错与自启动教程

本文奔着只为利人毫不利己的态度和原则半夜起草，重点在于教会各位一些毫无用处的三脚猫功夫。师傅领进门，修行靠个人，能不能会全靠自己（这都手把手了再不会我也没招），本文长短未计，但总共消耗了一盒红塔山，一瓶冰红茶，都是自费！有钱的撒点碎银子，没钱的捧个人场，大佬就别看了，雕虫小技岂敢班门弄斧，有啥错误欢迎指出。

--------------->插个广告试试水

--------------->插入完毕！

如果实在看不懂，直接把本篇全文复制扔给AI，让AI以此文进行分步指导即可。

基于本次实际安装过程整理的可复现操作手册

适用对象：Debian 13 服务器新手运维 / 测试机部署
安装目标：在 Debian 13 上完成 OpenClaw CLI、Gateway、Web 配置与开机自启
本报告原则：优先采用官方支持路径；所有关键命令均以本次成功路径为准；对曾经踩过的坑逐条给出避免办法。

一、执行摘要

本次 Debian 13 服务器安装 OpenClaw 的过程，最初经历了旧环境残留、npm 依赖走 Git SSH、手工编辑配置导致空文件、以及 SSH 断线中断 apt 下载等多个问题。最终验证成功的稳定路线是：清理旧版 nvm / npm / OpenClaw 残留 → 使用 NodeSource 安装系统级 Node 24 → 直接用 npm 全局安装最新 OpenClaw → 运行 onboarding 安装 Gateway 服务 → 检查 root 的 systemd user service 与 lingering。

结论：对于 Debian 13 服务器，最稳的安装方式不是在旧 nvm 环境里反复升级，而是用系统级 Node 24 + npm 全局安装的方式，从干净环境重新部署。

二、官方原则与本次报告采用的正确路线

· 官方 Linux 文档支持 Node 22+，并将 Linux 下的 Gateway 默认安装为 systemd user service。

· 官方推荐安装方式是安装脚本；但在本次环境中，经过多轮排错后，最终成功且可复现的路径是“系统级 Node 24 + npm install -g openclaw@latest + openclaw onboard --install-daemon”。

· root 安装并不等于 systemd system service。默认仍可能是 root 的 systemd user service，因此必须检查 enable 状态和 Linger 状态。

· web search 的 Kimi 配置属于独立工具配置；tools.profile = coding 属于默认工具档案，不是垃圾字段，不能因为看到 warning 就误删，后期可改为full提升权限，否则会有提示无权限调用工具。

三、最推荐的安装流程（新手直接照做）

下面这套流程按“全新或已决定彻底重装”的情况编写。每一步都经过本次实测路径校对。

1. 先清理旧环境（如果机器上装过 OpenClaw、nvm、旧版 Node）

如果是在一台干净的机器上第一次安装，可以跳过本小节。

如果机器上已经试装过 OpenClaw，强烈建议先清理干净再继续。

1、执行系统清理残留（整组命令直接复制粘贴）：

openclaw gateway stop || true
systemctl --user disable --now openclaw-gateway.service 2>/dev/null || true
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload || true
npm rm -g openclaw || true
rm -rf ~/.openclaw
rm -rf ~/.nvm

2、如果以前用过 nvm，还要检查 shell 启动文件里是否残留 nvm 或 openclaw 补全配置。残留不删，重新开 shell 时可能持续报错。

grep -n 'nvm|openclaw.bash|completions/openclaw' /root/.bashrc /root/.profile /root/.bash_profile 2>/dev/null

如果查到残留，手工删除对应行后再执行：

exec bash

2. 安装基础依赖

apt-get update && apt-get install -y curl ca-certificates gnupg git

这一步必须完成后，再添加 NodeSource 的 Node 24 软件源。

3. 安装系统级 Node 24

curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt-get install -y nodejs

安装完成后立即验证版本：

node -v
npm -v

本次验证成功的版本是 Node 24.14.0 与 npm 11.9.0。只要 Node 24 与可用 npm 正常返回版本号，就可以继续。

4. 安装 OpenClaw

npm install -g openclaw@latest
openclaw --version

本次最终成功安装的版本为 OpenClaw 2026.3.13。

5. 初始化并安装 Gateway 服务

openclaw onboard --install-daemon

第一次部署的朋友对于全篇的各种选项不要害怕，先走一遍流程，看看大概什么意思，走完流程肯定有遗漏的、配置错误的情况，都属于正常，这时候再执行一遍 openclaw onboard --install-daemon“就可以重新开始配置。

向导中如果只是先把主程序跑起来，建议优先完成主流程，技能依赖与额外 API Key 可以后补。Debian 服务器上如果看到 Homebrew 提示，不要误以为必须先装 brew。Linux 上 Homebrew 不是主路径。

6. 验证服务状态与是否可开机自启

systemctl --user status openclaw-gateway.service --no-pager
systemctl --user is-enabled openclaw-gateway.service
loginctl show-user root -p Linger

正确结果应当同时满足：服务状态为 active (running)，is-enabled 返回 enabled，Linger=yes。只要这三项成立，root 这套 user service 就会在系统启动后自动拉起。

四、如果 SSH 断线或 apt 安装中断，正确恢复方法

本次安装过程中，apt 下载 Node.js 包时曾因 SSH 断线而中断。遇到这种情况，不要立刻乱重试多条命令，先把包管理状态修正到干净。

dpkg --configure -a
apt-get -f install
apt-get clean

然后确认没有半安装的 nodejs 残留：

dpkg -l | grep -E '^i.|^rc' | grep nodejs

如果没有输出，再重新执行：

apt-get install -y nodejs

五、常见错误与本次实测结论

错误现象

npm install -g openclaw@latest 报 git@github.com: Permission denied (publickey)

根因

旧环境或依赖链触发了 Git SSH 访问 GitHub；机器未配置对应 SSH key。

正确处理方式

不要优先去给 root 配 GitHub SSH key。先清理旧 nvm / 旧 npm 环境，改走系统级 Node 24 + 新 npm 安装。必要时才用 HTTPS insteadOf 规则做临时兜底。

错误现象

openclaw gateway restart 报 JSON5: invalid end of input at 1:1

根因

openclaw.json 在本机实际变成了空文件或写坏了，不是 provider 大小写问题。

正确处理方式

先检查 /root/.openclaw/openclaw.json 的文件大小与内容；若为空，立即用正确配置覆盖回去。

错误现象

重新开 shell 时提示 /root/.openclaw/completions/openclaw.bash 不存在

根因

shell 启动文件残留了旧补全 source 行。

正确处理方式

从 /root/.bashrc 等文件中删除 source "/root/.openclaw/completions/openclaw.bash" 相关行。

错误现象

日志出现 tools.profile (coding) allowlist contains unknown entries

根因

这是 coding 默认工具档案与当前版本内部工具注册的兼容告警，不等于 tools.profile 没用。

正确处理方式

保留 tools.profile = coding；不要因为看到 warning 就删掉系统默认工具配置。

错误现象

服务运行正常，但担心开机不自启

根因

Linux 默认是 systemd user service；必须同时检查 enable 与 linger。

正确处理方式

确认 systemctl --user is-enabled 返回 enabled，loginctl show-user root -p Linger 返回 Linger=yes。

六、建议的新手安装顺序（务必照此顺序）

1. 先确认是否要重装。如果此前已折腾过旧版 nvm、旧版 OpenClaw、空配置文件，优先彻底清理。

2. 先装基础依赖，再装 NodeSource 的 Node 24；不要急着先装 OpenClaw。

3. Node 与 npm 验证通过后，再执行 npm install -g openclaw@latest。

4. OpenClaw CLI 装好后，先看版本，再执行 openclaw onboard --install-daemon。

5. 向导里先完成主流程，技能依赖、额外 API Key、Homebrew 提示都不要喧宾夺主。

6. 安装结束后，立刻检查服务状态、enable 状态、Linger 状态。

7. 如果后续手改 openclaw.json，改完第一时间先检查文件是否非空，再重启 gateway。

七、推荐的安装后自检清单

openclaw --version
node -v
npm -v
systemctl --user status openclaw-gateway.service --no-pager
systemctl --user is-enabled openclaw-gateway.service
loginctl show-user root -p Linger
openclaw gateway status || true

只要 CLI 版本正常、服务 active、is-enabled 为 enabled、Linger=yes，就说明安装主体已经合格。

八、附录：本次验证通过的最简完整命令清单

# 1) 清理旧环境（如曾经装过）
openclaw gateway stop || true
systemctl --user disable --now openclaw-gateway.service 2>/dev/null || true
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload || true
npm rm -g openclaw || true
rm -rf ~/.openclaw
rm -rf ~/.nvm

# 2) 基础依赖
apt-get update && apt-get install -y curl ca-certificates gnupg git

# 3) Node 24
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt-get install -y nodejs
node -v
npm -v

# 4) 安装 OpenClaw
npm install -g openclaw@latest
openclaw --version

# 5) 安装 Gateway 服务
openclaw onboard --install-daemon

# 6) 检查自启动
systemctl --user status openclaw-gateway.service --no-pager
systemctl --user is-enabled openclaw-gateway.service
loginctl show-user root -p Linger