OpenClaw这个项目最近在圈子里讨论度确实高但多数教程默认你有一台干净的 Ubuntu 服务器或者干脆在 Windows 上玩。真到了国产 Linux 环境——UOS、Kylin 这种问题就全冒出来了源不通、依赖版本对不上、Node 装不上、系统还在登录界面卡死。我是在三台不同设备上分别装了 UOS 家庭版、Kylin V10 SP1 和 Ubuntu 22.04把 OpenClaw 和 OpenClaw-CN 都跑了一遍期间踩的坑比预想多得多。这篇文章就把整个过程中最关键的排查路径、版本选择和实操细节整理出来包括从系统安装到 OpenClaw 跑通的全链路给正打算在国产 Linux 上部署的同学一份可以直接照着做的避坑清单。这篇文章适合三类人一类是单位要求使用国产系统、但需要在上面跑 AI Agent 服务的工程人员一类是手里只有一台 UOS/Kylin 设备、不想再折腾 Windows 双系统的个人开发者还有一类是已经在 Ubuntu 上跑通过 OpenClaw、想知道国产系统差异点在哪的老手。不管你是哪一类建议先把这篇文章通读一遍再动手因为有些坑一旦踩了重装系统的成本远高于提前规划。1. 先搞清楚 OpenClaw 和 OpenClaw-CN 到底是什么1.1 两个版本的核心差异OpenClaw 是一个基于 Node.js 生态的智能体运行框架核心能力是让大模型通过工具调用去操作真实环境——读写文件、执行命令、调用 API、处理数据。它跟单纯的聊天机器人最大的区别在于它能“动手做事”而不是只“动嘴回答”。OpenClaw-CN 则是针对中文场景优化的分支版本主要改进了中文交互界面的显示、内置了对国内大模型服务的接入配置以及对国产芯片平台的兼容适配。两个版本在 Linux 安装上的主体流程是一样的都用 npm 做包管理都依赖 Node.js 运行时也都支持 Docker 方式部署。差异集中在运行后的配置层OpenClaw 的默认配置文件里大模型接入写的都是 OpenAI 风格的国际厂商端点而 OpenClaw-CN 开箱就带 DeepSeek、通义千问、智谱等国内模型的配置模板。你要是准备在 UOS/Kylin 这类机器上部署我建议直接选 OpenClaw-CN省去后面替换配置的时间。1.2 两种部署方式怎么选OpenClaw 提供源码运行和 Docker 运行两种主流部署方式。源码运行就是 git clone 代码仓库、npm install 装依赖、然后直接 node 启动好处是灵活、好调试、出问题能直接看堆栈Docker 部署则是拉镜像、起容器好处是环境隔离、不污染宿主系统卸载也干净。在国产 Linux 上的选择逻辑不太一样。UOS 和 Kylin 的系统库版本普遍偏老系统自带的 node 版本可能停在 12.x 甚至 10.x直接跑源码很可能起不来。这种情况下 Docker 反而更省心——镜像里的环境是固定的和宿主系统耦合度低。但 Docker 在 UOS/Kylin 上也有自己的坑默认的 storage-driver 在某些内核版本上会报 overlay fs 错误docker-compose 版本也可能偏旧。所以我的结论是Ubuntu 上用源码方式没问题UOS/Kylin 上优先试 Docker但要做好手动处理 Docker 本身故障的准备。2. 安装 OpenClaw 之前的系统环境准备2.1 三大发行版的实际差异和选型建议先把三个系统在同一张桌上对比一下Ubuntu 22.04 LTS软件源最完整NodeSource 源、Docker 官方源都能直接加OpenClaw 的前置依赖几乎一键装齐适合当标准环境用。UOS 家庭版 21.3基于 Debian 的底子但软件源被深度定制过很多软件包版本落后一到两个大版本apt 源里连 nodejs 都可能还是 12.x。系统权限管理比较严格默认非 root 用户下 sudo 权限组配置和标准 Debian 有差异。Kylin V10 SP1这里要区别对待——桌面版 Kylin银河麒麟桌面版和服务器版 Spartan/Halberd 的软件源策略完全不同。桌面版可以临时切到 Ubuntu 的源来装缺失依赖服务器版则建议直接离线包方式处理。选型建议很简单如果你是拿一台旧电脑自己折腾优先装 Ubuntu如果是单位统一下发的国产机器大概率是 UOS 或 Kylin那就先看清楚系统的 CPU 架构——x86_64 的好办如果是飞腾、鲲鹏这类 ARM 架构OpenClaw 本身大多能跑但很多原生 Node 模块需要重新编译坑会多一层。2.2 Node.js 版本选择的关键逻辑OpenClaw 对 Node.js 版本有明确要求社区官方建议是 18.x 或 20.x LTS。这里有个容易忽略的点OpenClaw 的依赖树里包含一些原生编译模块版本过高比如 Node 23会导致 node-gyp 编译不兼容版本过低Node 14-则缺少某些原生 API。在 Ubuntu 上装 Node 20 很简单用 NodeSource 官方源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejsUOS/Kylin 上 NodeSource 源不一定能用或者源列表版本远滞后。一个实际可行的替代方案是用 nvm 装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm alias default 20nvm 不需要改系统源只是把 Node 装到用户目录这个思路在国产系统上加白名单限制时反而更容易通过。装完之后用node -v和npm -v验证注意 npm 版本别低于 9。2.3 网络与软件源问题的两种处理方式国产系统安装软件最大的痛点是源。UOS 商店里的软件不完整Kylin 有些服务器版的源需要授权才能访问。这里有两种解决路径一种是把软件源切换到国内开源镜像站。以 UOS 为例它的源文件在/etc/apt/sources.list和/etc/apt/sources.list.d/里你要确认当前的源地址然后用可用的镜像源地址替换。注意 UOS 的仓库路径和 Debian 不完全一样不能无脑拿 Ubuntu 的源替换否则依赖解析会出问题。另一种方式是离线包安装。在能联网的机器上用apt download下载依赖包或者用npm pack把需要的 npm 包打包再拷贝到离线机器上安装。OpenClaw 的依赖量不小npm install 会拉几百个包离线安装建议直接用npm ci --offline前提是你有一份完整的 package-lock.json 和 npm 缓存目录。这个方案比较折腾但确实是从零部署离线环境时最稳的路。提示在 UOS/Kylin 上执行任何安装命令之前先用uname -a确认架构用cat /etc/os-release确认系统版本。这两个命令的输出决定了你后续所有源配置和包选择的方向别省这一步。3. 系统层的坑登录、密码、输入法和磁盘3.1 UOS 登录界面进不去和密码锁定问题UOS 家庭版一个高频故障是开机后卡在登录界面输入密码无限循环回到登录界面或者干脆提示密码错误。我在一台 UOS 家庭版 21.3 上遇到过这个问题输入正确密码也进不去桌面。排查顺序很重要。先切到 tty 终端CtrlAltF2用同一个账号尝试命令行登录。如果命令行能登录说明密码本身是对的问题出在图形会话层——多半是 .Xauthority 文件权限错乱或者桌面组件崩溃。处理方式是删除当前用户目录下的.Xauthority和.ICEauthority然后重启图形会话sudo rm -f ~/.Xauthority ~/.ICEauthority sudo systemctl restart lightdmKylin 桌面版用的是 UKUI对应的显示管理器可能是 lightdm 或 sddm重启服务的命令要以实际进程为准。如果是密码被锁定报错提示“密码锁定 1440 分钟”这是系统安全策略里的防暴力破解机制——连续输错密码后锁定账户。1440 分钟就是整整一天等是等不起的。这个锁定时间在/etc/security/faillock.conf或者通过 pam 模块配置不同版本路径不一样。最快的解除方式是切换到 root 用户执行faillock --user 你的用户名 --reset如果没有 faillock 命令较老的版本里是pam_tally2 --user你的用户名 --reset。重置后立即回图形界面重新登录。3.2 中文输入法配置是绕不开的一步装好系统之后第一件事不是装 OpenClaw而是把输入法搞定。UOS 默认带 fcitxKylin 自带搜狗输入法授权版Ubuntu 则默认是 ibus。OpenClaw 的配置文件和后端交互基本全用英文但你要在终端里输入中文路径、中文文件名或者后续让 Agent 处理中文内容输入法就必须能正常工作。Ubuntu 22.04 上配置中文输入法最快的路径是装 fcitx5 和中文输入引擎sudo apt install fcitx5 fcitx5-chinese-addons fcitx5-config-qt装完后在系统设置里把输入法框架切到 Fcitx 5注销重新登录再通过 fcitx5-configtool 把拼音添加进来。这里容易忘的一步是有些桌面环境还需要设置环境变量export GTK_IM_MODULEfcitx export QT_IM_MODULEfcitx export XMODIFIERSimfcitx如果不设置终端里可能怎么也切不出中文。这个环境变量的配置要写到~/.xprofile或~/.pam_environment只写在当前 shell 里是没用的。UOS 和 Kylin 上如果系统自带的输入法框架和 OpenClaw 的终端工具冲突最直接的办法是确认fcitx或者ibus守护进程是否已经启动用ps -ef | grep fcitx看进程状态。输入法进程没起来任何输入法工具装了也白搭。3.3 系统盘满了怎么处理OpenClaw 本身不算大但它的运行日志、模型缓存、npm 的 node_modules 会持续占空间。国产系统默认分区经常把根目录分得很小装几个软件就满了。我在 UOS 上遇到过/分区 100% 占满连 OpenClaw 的日志都写不进去。先看看到底是什么占满了df -h sudo du -sh /var/log /var/cache /home/*/node_modules 2/dev/null常见的占空间大头是/var/log/journal里的系统日志以及 apt 的缓存包。可以清理sudo journalctl --vacuum-size100M sudo apt clean还有 npm 的缓存目录~/.npm/_cacache如果之前安装失败次数多这个目录可能膨胀到几个 G直接清掉npm cache clean --force如果是根目录分区本身太小那只能从分区层面解决——用 GParted 调整分区大小或者把 OpenClaw 的数据目录软连接到另一块硬盘上。我后来把 OpenClaw 的整个工作目录迁移到独立数据盘并用ln -s做软链接才彻底解决空间问题。注意不要轻易删/home下不认识的目录。有些国产系统的文件管理器会生成隐藏缓存目录名字很难猜删错可能导致桌面配置丢失。删之前先用du确认目录大小和用途。4. OpenClaw 核心安装流程从源码拉取到首次启动4.1 官方源安装路径的完整命令序列假设你已经准备好了 Node.js 20 和 npm接下来是在 Ubuntu 上跑通 OpenClaw 主流程的标准步骤。以 OpenClaw-CN 为例# 第一步拉取代码 git clone https://github.com/你的源地址/OpenClaw-CN.git cd OpenClaw-CN # 第二步安装依赖这一步最耗时 npm install # 第三步初始化配置 npm run setup # 第四步检查环境 npm run checknpm run setup是核心交互环节它会问你要不要自动下载模型、要不要配置工具链、是不是需要开启 WebUI 等。这里的关键是根据你的实际场景回答不要图省事全部默认。首次启动 OpenClawnpm start启动成功后终端里会看到运行信息包括 WebUI 的访问地址和 API 服务端口。浏览器打开对应地址能看到聊天和任务管理界面到这里 OpenClaw 就跑通了。4.2 使用 pm2 管理后台运行的配置方法OpenClaw 开发模式下直接npm start没问题但真正的使用场景是长期运行——你得保证它开机自启、崩溃自动拉起。pm2 是 Node 生态最常用的进程守护工具。npm install -g pm2 pm2 start npm --name openclaw -- start pm2 save pm2 startuppm2 save保存当前进程列表pm2 startup会生成一条 systemd 开机自启服务。这个操作在 Ubuntu 和 UOS/Kylin 上都能用。注意在某些国产桌面系统上pm2 生成的 systemd 服务脚本可能需要手动执行一次systemctl enable pm2-root才能真正启用。后面要时刻关注 OpenClaw 的状态就用pm2 logs openclaw pm2 status日志文件默认在~/.pm2/logs/下排查问题直接看这个目录。4.3 OpenClaw-CN 中文配置的差异点OpenClaw-CN 安装完成后配置文件在 config 目录下常见的是一个 JSON 或 YAML 配置文件。全局配置主要包括模型列表、Agent 参数、工具开关。一个容易忽略的细节是OpenClaw-CN 默认配置里的模型服务指向的是国内模型供应商需要你填入 API Key。如果留空程序会在启动时报错或直接找不到可用模型。填 Key 的方式不是改配置文件里某个固定字段而是看项目文档里指定的环境变量前缀通常类似DEEPSEEK_API_KEY或ZHIPU_API_KEY。填好之后重启pm2 restart openclawOpenClaw-CN 相对原版还有一个明显差异就是默认内置了中文技能包。技能Skill在 OpenClaw 生态里相当于给 Agent 预置的一批工具函数比如文件批量处理、网页内容抓取、定时任务执行。这些技能包在skills/目录下你可以直接编辑里面的 prompt 模板和脚本让 Agent 更贴合自己的业务。5. 运行环境的选型Docker 与宿主进程的纠葛5.1 在 UOS/Kylin 上跑 Docker 的实际坑我最初的想法很简单既然国产系统环境杂那就上 Docker用容器把 OpenClaw 关起来和系统环境隔离开。但真实操作下来Docker 在国产系统上并没有那么“省心”。第一步装 Docker 就遇到障碍。UOS 的 apt 源里 docker.io 版本可能很老而且 docker-ce 官方源和 UOS 的源有冲突。用官方安装脚本curl -fsSL https://get.docker.com | sh这条命令在 Ubuntu 上好使但在 UOS/Kylin 上可能因为源地址不可达而失败。替代方案是用阿里云的镜像源手动添加 docker-ce 的 apt 源然后 apt install docker-ce。注意这里添加的源要和你的系统版本匹配不要照抄别人的配置。装完之后还有一关启动 Docker 服务时如果报overlayfs相关的错误说明当前内核的 overlay 模块和 Docker 的 storage-driver 不对付。改 Docker 的 daemon.json把存储驱动切成 vfs{ storage-driver: vfs }vfs 驱动性能差一些但兼容性最好。在国产系统上先求能用再求性能。5.2 Docker Compose 方式部署 OpenClaw 的模板Docker 环境就绪后OpenClaw 官方仓库里通常带一份 docker-compose.yml 作为参考。核心内容就是把配置目录和数据目录用 volume 挂载出来再把端口映射到宿主机。一个实测好用的思路是把 OpenClaw 的配置目录用卷的方式共享出去这样你可以在宿主机上改配置容器里自动生效。Compose 文件的关键部分services: openclaw: image: openclaw-cn:latest container_name: openclaw ports: - 3000:3000 volumes: - ./config:/app/config - ./data:/app/data restart: unless-stopped用docker compose up -d启动后docker logs -f openclaw看日志。这里的一个坑是容器内的时区和宿主机不一致时OpenClaw 的计划任务会按错误时间触发。解决方式是挂载/etc/localtime进容器volumes: - /etc/localtime:/etc/localtime:ro这个细节教程里很少提但定时任务功能早晚会用到。5.3 无 Docker 环境下的进程级隔离方案如果 Docker 在你的国产设备上怎么都装不起来退一步的做法是用 systemd 单独管理 OpenClaw 进程做简单的资源限制。创建一个 systemd 服务文件/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Agent Service Afternetwork.target [Service] User你的普通用户名 WorkingDirectory/home/你的用户名/OpenClaw-CN ExecStart/usr/bin/npm start Restarton-failure RestartSec10 LimitNOFILE65535 [Install] WantedBymulti-user.target启用sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw这个方案的好处是逻辑清晰服务随系统启动崩溃自动拉起日志也统一走 journalctl。要修改进程的资源限制就在[Service]段加MemoryMax2048M、CPUQuota200%之类的参数。还有一个隐藏技巧如果想在ps里快速分辨 OpenClaw 相关进程可以在 ExecStart 里用exec -a改名ExecStart/bin/bash -c exec -a openclaw-agent npm start这样进程列表里显示为openclaw-agent排查问题时一眼就能找到。6. 大模型接入配置Ollama 和 API 两种路径6.1 Ollama 本地模型部署与 OpenClaw 的对接在很多内网环境里OpenClaw 要对接的是本地模型不走云端 API。最常配套使用的就是 Ollama。Ollama 的安装在 Linux 上一条命令curl -fsSL https://ollama.com/install.sh | sh但在国产系统上这个脚本同样可能因为网络原因失败。替代方案是下载离线安装包或者直接下载 Ollama 的二进制文件手动安装。安装成功后先拉一个轻量模型做测试ollama pull qwen2.5:7b模型拉取要确保磁盘空间充足——7B 量化模型大约 4-5GB直接用默认的量化版本会更小一点。OpenClaw 要连接 Ollama关键是在 OpenAI 兼容层配置里把 base URL 指向本地 Ollama 服务。Ollama 默认监听11434端口而且默认提供 OpenAI 兼容的 API 路径。OpenClaw 偏好设置里模型服务端点填http://127.0.0.1:11434/v1模型名称填你在 Ollama 里拉取的模型名比如qwen2.5:7b。改完配置手动用命令行发一条消息测试而不是直接进 WebUI 傻等这样能更快定位是配置问题还是连接问题。6.2 云端 API 与国产模型的适配细节如果你有云端模型 API 的 Key路径更简单但有一个细节值得注意OpenClaw-CN 里内置的模型模板虽然多但不同家模型的调用参数差异很大——有的要求temperature范围不能超过 1有的额外支持thinking参数有的不支持top_p。我的经验是宁可在配置文件里多保留几个模型槽位先用一个已经明确兼容的模型跑通全流程再测其他模型。不要一上来就追求“一次配好多个模型”排查问题的时候都不知道问题出在哪个环节。OpenClaw 里常见的配置项包括模型名称要和模型服务商 API 文档里的标识一致温度参数控制生成随机性Agent 做任务建议 0.1-0.3降低乱执行概率最大 token处理长文档任务时要调大否则超长内容会被截断tool_choice是否强制指定工具提示OpenClaw 的 Agent 功能依赖工具调用能力选模型时优先挑函数调用Function Calling支持好的模型。之前用某个模型时 Agent 总是“答非所问”换成支持函数调用的模型后基本零问题。7. 常见问题排查与错误实录7.1 安装阶段常见报错速查表错误现象可能原因解决办法npm install 卡在某个包不动网络源问题或包版本冲突切换 npm 镜像源npm config set registry https://registry.npmmirror.comnode-gyp 编译报 python 版本错误缺少 Python 或版本过高Ubuntu 上sudo apt install python3 python3-pip并确保 python3 可用提示Error: Cannot find modulenode_modules 目录不完整删除 node_modules 和 package-lock.json重新npm installgit clone 很慢或失败网络原因或仓库不存在确认仓库地址真实有效可用镜像站或离线包方式启动时端口被占用上次进程没退干净lsof -i:3000找到进程后 kill或用 pm2 管理统一处理浏览器访问报 SSL 证书错误本地服务证书不被信任用 http:// 访问或在浏览器里安全例外不要随意关系统安全设置7.2 运行期典型故障的排查思路运行期最常遇到的一个故障是 OpenClaw 分配了任务之后长时间没有响应既不出结果也不报错。优先检查日志里的模型请求耗时——如果卡在模型调用环节说明要么模型服务不可达要么请求超时设置太短。在配置里把超时时间适当调大。另一个故障是 Agent 执行命令时报权限不足尤其是在 UOS/Kylin 这类权限管控严格的系统上。OpenClaw 默认以普通用户身份执行命令当它尝试写系统目录或操作 /etc 下的文件时会被拒绝。处理方式是配置允许以 sudo 方式执行指定命令注意只放行少量特异性命令不要开放所有命令不然安全风险太大。UOS 特有的一个问题某些省级桌面环境下OpenClaw 的 WebUI 服务被系统防火墙拦截。虽然桌面系统的防火墙默认通常关闭但单位统配机器可能有安全策略。检查防火墙状态sudo ufw status sudo systemctl status firewalld如果开启就把 OpenClaw 的端口加入放行列表。这类环境下直接临时关闭防火墙也能跑通但建议只放行端口。还有一个细节系统休眠和待机。国产桌面设备默认可能开启自动挂起OpenClaw 在挂起恢复后经常出问题——npm 进程僵死、WebSocket 断开。改掉电源管理配置把自动挂起关掉或者设置成永不挂起。7.3 WSL 场景下交叉运行注意点虽然本文主题是 Linux 原生环境但实际很多人是先在一台 Windows 机器上把 OpenClaw 配好再往国产 Linux 上迁移。这里涉及一个经常被误解的点WSL 里装的 Linux 和原生 Linux 在运行 OpenClaw 上没有本质区别区别在于资源调用方式——WSL 默认不共享宿主机的 GPU除非配置了 GPU 直通所以本地模型跑 Ollama 的话性能会打折。从 Windows 侧访问 WSL 里跑起来的 OpenClaw WebUI直接在浏览器里访问http://localhost:端口多半可以通因为 WSL2 默认有 localhost 转发。如果访问不到先检查 WSL 状态wsl --status这个命令能确认 WSL 版本和默认发行版是否正常。另一个常见问题是 WSL 里跑npm install时因为文件系统跨盘/mnt/c 路径导致性能极差——代码目录不要放在 Windows 盘上把它迁移到 WSL 的 Linux 文件系统内部速度和稳定性都能上一个台阶。8. 进阶方向技能扩展、NAS 挂载和持续使用建议8.1 让 OpenClaw 自动操作 NAS 存储很多使用者准备把 OpenClaw 当作个人数据助手让它管理家庭 NAS 上的文件。Linux 挂载 NAS 用 NFS 或 CIFS/SMB 都行。以 SMB 为例安装挂载工具后手动挂载sudo apt install cifs-utils sudo mkdir -p /mnt/nas sudo mount -t cifs //NAS地址/共享目录 /mnt/nas -o username用户,password密码,vers3.0挂载成功之后OpenClaw 的技能脚本里就可以直接读写/mnt/nas下的文件。这里有个容易踩的坑重启后挂载会失效OpenClaw 启动时如果技能正好访问 NAS 路径会报文件不存在。解决方法是把挂载写进/etc/fstab并配置自动挂载//NAS地址/共享目录 /mnt/nas cifs username用户,password密码,vers3.0,noauto,x-systemd.automount 0 0用x-systemd.automount让系统在真正访问时才挂载比开机直接挂载更抗网络延迟。8.2 技能库的组织和备份小技巧OpenClaw 的技能扩展机制值得单独说。每个技能其实就是一个目录包含描述文件、执行脚本和 prompt 模板。自己写技能时建议按“输入输出格式规范、错误处理兜底、日志记录”三件套来组织代码。技能脚本把每一步的关键操作写进日志OpenClaw 主进程才能在你不在场的时候准确汇报任务进度。技能目录的备份建议同步到 Git 仓库或者 NAS因为技能是你真正在 OpenClaw 上积累的资产模型配置丢了可以重新填 Key技能包丢了等于从零开始。我个人的习惯是每周自动把skills/目录和配置文件打包加密再上传到 NAS任务计划用系统自带的 cron 就行。定期备份相当于给整个 Agent 系统上了保险。写在最后的一些体会几次搭建折腾下来我最深的感觉是OpenClaw 本身并不难装真正的成本都在“环境适配”上——国产系统的软件源、权限策略、中文习惯、分区规划、存储挂载每一步都在挑战你在标准 Ubuntu 上养成的惯性思维。如果你准备在 UOS 或者 Kylin 上部署提前留出半天时间专门处理系统层问题不要想着“系统装完就能直接跑”那几乎是不可能的。我最后还想分享一个小技巧无论你最终选择了源码方式还是 Docker 方式都在安装完成、一切正常之后把完整的安装命令和配置变更记录写成一个笔记文件放在 OpenClaw 的数据目录里。等三个月后系统出问题、需要重装时这份笔记的价值会超过任何教程。我自己就是靠这份笔记在第二台机器上把安装时间压缩到了半小时以内。项目后续再增加新技能、换新模型时笔记同步更新长期下来你的 OpenClaw 会越来越顺手而不是越来越难维护。 
长河君 · 2026/10/5 10:43:38 · 阅读 1.2k 国产Linux部署OpenClaw全指南：UOS与Kylin避坑实操
OpenClaw这个项目最近在圈子里讨论度确实高但多数教程默认你有一台干净的 Ubuntu 服务器或者干脆在 Windows 上玩。真到了国产 Linux 环境——UOS、Kylin 这种问题就全冒出来了源不通、依赖版本对不上、Node 装不上、系统还在登录界面卡死。我是在三台不同设备上分别装了 UOS 家庭版、Kylin V10 SP1 和 Ubuntu 22.04把 OpenClaw 和 OpenClaw-CN 都跑了一遍期间踩的坑比预想多得多。这篇文章就把整个过程中最关键的排查路径、版本选择和实操细节整理出来包括从系统安装到 OpenClaw 跑通的全链路给正打算在国产 Linux 上部署的同学一份可以直接照着做的避坑清单。这篇文章适合三类人一类是单位要求使用国产系统、但需要在上面跑 AI Agent 服务的工程人员一类是手里只有一台 UOS/Kylin 设备、不想再折腾 Windows 双系统的个人开发者还有一类是已经在 Ubuntu 上跑通过 OpenClaw、想知道国产系统差异点在哪的老手。不管你是哪一类建议先把这篇文章通读一遍再动手因为有些坑一旦踩了重装系统的成本远高于提前规划。1. 先搞清楚 OpenClaw 和 OpenClaw-CN 到底是什么1.1 两个版本的核心差异OpenClaw 是一个基于 Node.js 生态的智能体运行框架核心能力是让大模型通过工具调用去操作真实环境——读写文件、执行命令、调用 API、处理数据。它跟单纯的聊天机器人最大的区别在于它能“动手做事”而不是只“动嘴回答”。OpenClaw-CN 则是针对中文场景优化的分支版本主要改进了中文交互界面的显示、内置了对国内大模型服务的接入配置以及对国产芯片平台的兼容适配。两个版本在 Linux 安装上的主体流程是一样的都用 npm 做包管理都依赖 Node.js 运行时也都支持 Docker 方式部署。差异集中在运行后的配置层OpenClaw 的默认配置文件里大模型接入写的都是 OpenAI 风格的国际厂商端点而 OpenClaw-CN 开箱就带 DeepSeek、通义千问、智谱等国内模型的配置模板。你要是准备在 UOS/Kylin 这类机器上部署我建议直接选 OpenClaw-CN省去后面替换配置的时间。1.2 两种部署方式怎么选OpenClaw 提供源码运行和 Docker 运行两种主流部署方式。源码运行就是 git clone 代码仓库、npm install 装依赖、然后直接 node 启动好处是灵活、好调试、出问题能直接看堆栈Docker 部署则是拉镜像、起容器好处是环境隔离、不污染宿主系统卸载也干净。在国产 Linux 上的选择逻辑不太一样。UOS 和 Kylin 的系统库版本普遍偏老系统自带的 node 版本可能停在 12.x 甚至 10.x直接跑源码很可能起不来。这种情况下 Docker 反而更省心——镜像里的环境是固定的和宿主系统耦合度低。但 Docker 在 UOS/Kylin 上也有自己的坑默认的 storage-driver 在某些内核版本上会报 overlay fs 错误docker-compose 版本也可能偏旧。所以我的结论是Ubuntu 上用源码方式没问题UOS/Kylin 上优先试 Docker但要做好手动处理 Docker 本身故障的准备。2. 安装 OpenClaw 之前的系统环境准备2.1 三大发行版的实际差异和选型建议先把三个系统在同一张桌上对比一下Ubuntu 22.04 LTS软件源最完整NodeSource 源、Docker 官方源都能直接加OpenClaw 的前置依赖几乎一键装齐适合当标准环境用。UOS 家庭版 21.3基于 Debian 的底子但软件源被深度定制过很多软件包版本落后一到两个大版本apt 源里连 nodejs 都可能还是 12.x。系统权限管理比较严格默认非 root 用户下 sudo 权限组配置和标准 Debian 有差异。Kylin V10 SP1这里要区别对待——桌面版 Kylin银河麒麟桌面版和服务器版 Spartan/Halberd 的软件源策略完全不同。桌面版可以临时切到 Ubuntu 的源来装缺失依赖服务器版则建议直接离线包方式处理。选型建议很简单如果你是拿一台旧电脑自己折腾优先装 Ubuntu如果是单位统一下发的国产机器大概率是 UOS 或 Kylin那就先看清楚系统的 CPU 架构——x86_64 的好办如果是飞腾、鲲鹏这类 ARM 架构OpenClaw 本身大多能跑但很多原生 Node 模块需要重新编译坑会多一层。2.2 Node.js 版本选择的关键逻辑OpenClaw 对 Node.js 版本有明确要求社区官方建议是 18.x 或 20.x LTS。这里有个容易忽略的点OpenClaw 的依赖树里包含一些原生编译模块版本过高比如 Node 23会导致 node-gyp 编译不兼容版本过低Node 14-则缺少某些原生 API。在 Ubuntu 上装 Node 20 很简单用 NodeSource 官方源curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejsUOS/Kylin 上 NodeSource 源不一定能用或者源列表版本远滞后。一个实际可行的替代方案是用 nvm 装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm alias default 20nvm 不需要改系统源只是把 Node 装到用户目录这个思路在国产系统上加白名单限制时反而更容易通过。装完之后用node -v和npm -v验证注意 npm 版本别低于 9。2.3 网络与软件源问题的两种处理方式国产系统安装软件最大的痛点是源。UOS 商店里的软件不完整Kylin 有些服务器版的源需要授权才能访问。这里有两种解决路径一种是把软件源切换到国内开源镜像站。以 UOS 为例它的源文件在/etc/apt/sources.list和/etc/apt/sources.list.d/里你要确认当前的源地址然后用可用的镜像源地址替换。注意 UOS 的仓库路径和 Debian 不完全一样不能无脑拿 Ubuntu 的源替换否则依赖解析会出问题。另一种方式是离线包安装。在能联网的机器上用apt download下载依赖包或者用npm pack把需要的 npm 包打包再拷贝到离线机器上安装。OpenClaw 的依赖量不小npm install 会拉几百个包离线安装建议直接用npm ci --offline前提是你有一份完整的 package-lock.json 和 npm 缓存目录。这个方案比较折腾但确实是从零部署离线环境时最稳的路。提示在 UOS/Kylin 上执行任何安装命令之前先用uname -a确认架构用cat /etc/os-release确认系统版本。这两个命令的输出决定了你后续所有源配置和包选择的方向别省这一步。3. 系统层的坑登录、密码、输入法和磁盘3.1 UOS 登录界面进不去和密码锁定问题UOS 家庭版一个高频故障是开机后卡在登录界面输入密码无限循环回到登录界面或者干脆提示密码错误。我在一台 UOS 家庭版 21.3 上遇到过这个问题输入正确密码也进不去桌面。排查顺序很重要。先切到 tty 终端CtrlAltF2用同一个账号尝试命令行登录。如果命令行能登录说明密码本身是对的问题出在图形会话层——多半是 .Xauthority 文件权限错乱或者桌面组件崩溃。处理方式是删除当前用户目录下的.Xauthority和.ICEauthority然后重启图形会话sudo rm -f ~/.Xauthority ~/.ICEauthority sudo systemctl restart lightdmKylin 桌面版用的是 UKUI对应的显示管理器可能是 lightdm 或 sddm重启服务的命令要以实际进程为准。如果是密码被锁定报错提示“密码锁定 1440 分钟”这是系统安全策略里的防暴力破解机制——连续输错密码后锁定账户。1440 分钟就是整整一天等是等不起的。这个锁定时间在/etc/security/faillock.conf或者通过 pam 模块配置不同版本路径不一样。最快的解除方式是切换到 root 用户执行faillock --user 你的用户名 --reset如果没有 faillock 命令较老的版本里是pam_tally2 --user你的用户名 --reset。重置后立即回图形界面重新登录。3.2 中文输入法配置是绕不开的一步装好系统之后第一件事不是装 OpenClaw而是把输入法搞定。UOS 默认带 fcitxKylin 自带搜狗输入法授权版Ubuntu 则默认是 ibus。OpenClaw 的配置文件和后端交互基本全用英文但你要在终端里输入中文路径、中文文件名或者后续让 Agent 处理中文内容输入法就必须能正常工作。Ubuntu 22.04 上配置中文输入法最快的路径是装 fcitx5 和中文输入引擎sudo apt install fcitx5 fcitx5-chinese-addons fcitx5-config-qt装完后在系统设置里把输入法框架切到 Fcitx 5注销重新登录再通过 fcitx5-configtool 把拼音添加进来。这里容易忘的一步是有些桌面环境还需要设置环境变量export GTK_IM_MODULEfcitx export QT_IM_MODULEfcitx export XMODIFIERSimfcitx如果不设置终端里可能怎么也切不出中文。这个环境变量的配置要写到~/.xprofile或~/.pam_environment只写在当前 shell 里是没用的。UOS 和 Kylin 上如果系统自带的输入法框架和 OpenClaw 的终端工具冲突最直接的办法是确认fcitx或者ibus守护进程是否已经启动用ps -ef | grep fcitx看进程状态。输入法进程没起来任何输入法工具装了也白搭。3.3 系统盘满了怎么处理OpenClaw 本身不算大但它的运行日志、模型缓存、npm 的 node_modules 会持续占空间。国产系统默认分区经常把根目录分得很小装几个软件就满了。我在 UOS 上遇到过/分区 100% 占满连 OpenClaw 的日志都写不进去。先看看到底是什么占满了df -h sudo du -sh /var/log /var/cache /home/*/node_modules 2/dev/null常见的占空间大头是/var/log/journal里的系统日志以及 apt 的缓存包。可以清理sudo journalctl --vacuum-size100M sudo apt clean还有 npm 的缓存目录~/.npm/_cacache如果之前安装失败次数多这个目录可能膨胀到几个 G直接清掉npm cache clean --force如果是根目录分区本身太小那只能从分区层面解决——用 GParted 调整分区大小或者把 OpenClaw 的数据目录软连接到另一块硬盘上。我后来把 OpenClaw 的整个工作目录迁移到独立数据盘并用ln -s做软链接才彻底解决空间问题。注意不要轻易删/home下不认识的目录。有些国产系统的文件管理器会生成隐藏缓存目录名字很难猜删错可能导致桌面配置丢失。删之前先用du确认目录大小和用途。4. OpenClaw 核心安装流程从源码拉取到首次启动4.1 官方源安装路径的完整命令序列假设你已经准备好了 Node.js 20 和 npm接下来是在 Ubuntu 上跑通 OpenClaw 主流程的标准步骤。以 OpenClaw-CN 为例# 第一步拉取代码 git clone https://github.com/你的源地址/OpenClaw-CN.git cd OpenClaw-CN # 第二步安装依赖这一步最耗时 npm install # 第三步初始化配置 npm run setup # 第四步检查环境 npm run checknpm run setup是核心交互环节它会问你要不要自动下载模型、要不要配置工具链、是不是需要开启 WebUI 等。这里的关键是根据你的实际场景回答不要图省事全部默认。首次启动 OpenClawnpm start启动成功后终端里会看到运行信息包括 WebUI 的访问地址和 API 服务端口。浏览器打开对应地址能看到聊天和任务管理界面到这里 OpenClaw 就跑通了。4.2 使用 pm2 管理后台运行的配置方法OpenClaw 开发模式下直接npm start没问题但真正的使用场景是长期运行——你得保证它开机自启、崩溃自动拉起。pm2 是 Node 生态最常用的进程守护工具。npm install -g pm2 pm2 start npm --name openclaw -- start pm2 save pm2 startuppm2 save保存当前进程列表pm2 startup会生成一条 systemd 开机自启服务。这个操作在 Ubuntu 和 UOS/Kylin 上都能用。注意在某些国产桌面系统上pm2 生成的 systemd 服务脚本可能需要手动执行一次systemctl enable pm2-root才能真正启用。后面要时刻关注 OpenClaw 的状态就用pm2 logs openclaw pm2 status日志文件默认在~/.pm2/logs/下排查问题直接看这个目录。4.3 OpenClaw-CN 中文配置的差异点OpenClaw-CN 安装完成后配置文件在 config 目录下常见的是一个 JSON 或 YAML 配置文件。全局配置主要包括模型列表、Agent 参数、工具开关。一个容易忽略的细节是OpenClaw-CN 默认配置里的模型服务指向的是国内模型供应商需要你填入 API Key。如果留空程序会在启动时报错或直接找不到可用模型。填 Key 的方式不是改配置文件里某个固定字段而是看项目文档里指定的环境变量前缀通常类似DEEPSEEK_API_KEY或ZHIPU_API_KEY。填好之后重启pm2 restart openclawOpenClaw-CN 相对原版还有一个明显差异就是默认内置了中文技能包。技能Skill在 OpenClaw 生态里相当于给 Agent 预置的一批工具函数比如文件批量处理、网页内容抓取、定时任务执行。这些技能包在skills/目录下你可以直接编辑里面的 prompt 模板和脚本让 Agent 更贴合自己的业务。5. 运行环境的选型Docker 与宿主进程的纠葛5.1 在 UOS/Kylin 上跑 Docker 的实际坑我最初的想法很简单既然国产系统环境杂那就上 Docker用容器把 OpenClaw 关起来和系统环境隔离开。但真实操作下来Docker 在国产系统上并没有那么“省心”。第一步装 Docker 就遇到障碍。UOS 的 apt 源里 docker.io 版本可能很老而且 docker-ce 官方源和 UOS 的源有冲突。用官方安装脚本curl -fsSL https://get.docker.com | sh这条命令在 Ubuntu 上好使但在 UOS/Kylin 上可能因为源地址不可达而失败。替代方案是用阿里云的镜像源手动添加 docker-ce 的 apt 源然后 apt install docker-ce。注意这里添加的源要和你的系统版本匹配不要照抄别人的配置。装完之后还有一关启动 Docker 服务时如果报overlayfs相关的错误说明当前内核的 overlay 模块和 Docker 的 storage-driver 不对付。改 Docker 的 daemon.json把存储驱动切成 vfs{ storage-driver: vfs }vfs 驱动性能差一些但兼容性最好。在国产系统上先求能用再求性能。5.2 Docker Compose 方式部署 OpenClaw 的模板Docker 环境就绪后OpenClaw 官方仓库里通常带一份 docker-compose.yml 作为参考。核心内容就是把配置目录和数据目录用 volume 挂载出来再把端口映射到宿主机。一个实测好用的思路是把 OpenClaw 的配置目录用卷的方式共享出去这样你可以在宿主机上改配置容器里自动生效。Compose 文件的关键部分services: openclaw: image: openclaw-cn:latest container_name: openclaw ports: - 3000:3000 volumes: - ./config:/app/config - ./data:/app/data restart: unless-stopped用docker compose up -d启动后docker logs -f openclaw看日志。这里的一个坑是容器内的时区和宿主机不一致时OpenClaw 的计划任务会按错误时间触发。解决方式是挂载/etc/localtime进容器volumes: - /etc/localtime:/etc/localtime:ro这个细节教程里很少提但定时任务功能早晚会用到。5.3 无 Docker 环境下的进程级隔离方案如果 Docker 在你的国产设备上怎么都装不起来退一步的做法是用 systemd 单独管理 OpenClaw 进程做简单的资源限制。创建一个 systemd 服务文件/etc/systemd/system/openclaw.service[Unit] DescriptionOpenClaw Agent Service Afternetwork.target [Service] User你的普通用户名 WorkingDirectory/home/你的用户名/OpenClaw-CN ExecStart/usr/bin/npm start Restarton-failure RestartSec10 LimitNOFILE65535 [Install] WantedBymulti-user.target启用sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw这个方案的好处是逻辑清晰服务随系统启动崩溃自动拉起日志也统一走 journalctl。要修改进程的资源限制就在[Service]段加MemoryMax2048M、CPUQuota200%之类的参数。还有一个隐藏技巧如果想在ps里快速分辨 OpenClaw 相关进程可以在 ExecStart 里用exec -a改名ExecStart/bin/bash -c exec -a openclaw-agent npm start这样进程列表里显示为openclaw-agent排查问题时一眼就能找到。6. 大模型接入配置Ollama 和 API 两种路径6.1 Ollama 本地模型部署与 OpenClaw 的对接在很多内网环境里OpenClaw 要对接的是本地模型不走云端 API。最常配套使用的就是 Ollama。Ollama 的安装在 Linux 上一条命令curl -fsSL https://ollama.com/install.sh | sh但在国产系统上这个脚本同样可能因为网络原因失败。替代方案是下载离线安装包或者直接下载 Ollama 的二进制文件手动安装。安装成功后先拉一个轻量模型做测试ollama pull qwen2.5:7b模型拉取要确保磁盘空间充足——7B 量化模型大约 4-5GB直接用默认的量化版本会更小一点。OpenClaw 要连接 Ollama关键是在 OpenAI 兼容层配置里把 base URL 指向本地 Ollama 服务。Ollama 默认监听11434端口而且默认提供 OpenAI 兼容的 API 路径。OpenClaw 偏好设置里模型服务端点填http://127.0.0.1:11434/v1模型名称填你在 Ollama 里拉取的模型名比如qwen2.5:7b。改完配置手动用命令行发一条消息测试而不是直接进 WebUI 傻等这样能更快定位是配置问题还是连接问题。6.2 云端 API 与国产模型的适配细节如果你有云端模型 API 的 Key路径更简单但有一个细节值得注意OpenClaw-CN 里内置的模型模板虽然多但不同家模型的调用参数差异很大——有的要求temperature范围不能超过 1有的额外支持thinking参数有的不支持top_p。我的经验是宁可在配置文件里多保留几个模型槽位先用一个已经明确兼容的模型跑通全流程再测其他模型。不要一上来就追求“一次配好多个模型”排查问题的时候都不知道问题出在哪个环节。OpenClaw 里常见的配置项包括模型名称要和模型服务商 API 文档里的标识一致温度参数控制生成随机性Agent 做任务建议 0.1-0.3降低乱执行概率最大 token处理长文档任务时要调大否则超长内容会被截断tool_choice是否强制指定工具提示OpenClaw 的 Agent 功能依赖工具调用能力选模型时优先挑函数调用Function Calling支持好的模型。之前用某个模型时 Agent 总是“答非所问”换成支持函数调用的模型后基本零问题。7. 常见问题排查与错误实录7.1 安装阶段常见报错速查表错误现象可能原因解决办法npm install 卡在某个包不动网络源问题或包版本冲突切换 npm 镜像源npm config set registry https://registry.npmmirror.comnode-gyp 编译报 python 版本错误缺少 Python 或版本过高Ubuntu 上sudo apt install python3 python3-pip并确保 python3 可用提示Error: Cannot find modulenode_modules 目录不完整删除 node_modules 和 package-lock.json重新npm installgit clone 很慢或失败网络原因或仓库不存在确认仓库地址真实有效可用镜像站或离线包方式启动时端口被占用上次进程没退干净lsof -i:3000找到进程后 kill或用 pm2 管理统一处理浏览器访问报 SSL 证书错误本地服务证书不被信任用 http:// 访问或在浏览器里安全例外不要随意关系统安全设置7.2 运行期典型故障的排查思路运行期最常遇到的一个故障是 OpenClaw 分配了任务之后长时间没有响应既不出结果也不报错。优先检查日志里的模型请求耗时——如果卡在模型调用环节说明要么模型服务不可达要么请求超时设置太短。在配置里把超时时间适当调大。另一个故障是 Agent 执行命令时报权限不足尤其是在 UOS/Kylin 这类权限管控严格的系统上。OpenClaw 默认以普通用户身份执行命令当它尝试写系统目录或操作 /etc 下的文件时会被拒绝。处理方式是配置允许以 sudo 方式执行指定命令注意只放行少量特异性命令不要开放所有命令不然安全风险太大。UOS 特有的一个问题某些省级桌面环境下OpenClaw 的 WebUI 服务被系统防火墙拦截。虽然桌面系统的防火墙默认通常关闭但单位统配机器可能有安全策略。检查防火墙状态sudo ufw status sudo systemctl status firewalld如果开启就把 OpenClaw 的端口加入放行列表。这类环境下直接临时关闭防火墙也能跑通但建议只放行端口。还有一个细节系统休眠和待机。国产桌面设备默认可能开启自动挂起OpenClaw 在挂起恢复后经常出问题——npm 进程僵死、WebSocket 断开。改掉电源管理配置把自动挂起关掉或者设置成永不挂起。7.3 WSL 场景下交叉运行注意点虽然本文主题是 Linux 原生环境但实际很多人是先在一台 Windows 机器上把 OpenClaw 配好再往国产 Linux 上迁移。这里涉及一个经常被误解的点WSL 里装的 Linux 和原生 Linux 在运行 OpenClaw 上没有本质区别区别在于资源调用方式——WSL 默认不共享宿主机的 GPU除非配置了 GPU 直通所以本地模型跑 Ollama 的话性能会打折。从 Windows 侧访问 WSL 里跑起来的 OpenClaw WebUI直接在浏览器里访问http://localhost:端口多半可以通因为 WSL2 默认有 localhost 转发。如果访问不到先检查 WSL 状态wsl --status这个命令能确认 WSL 版本和默认发行版是否正常。另一个常见问题是 WSL 里跑npm install时因为文件系统跨盘/mnt/c 路径导致性能极差——代码目录不要放在 Windows 盘上把它迁移到 WSL 的 Linux 文件系统内部速度和稳定性都能上一个台阶。8. 进阶方向技能扩展、NAS 挂载和持续使用建议8.1 让 OpenClaw 自动操作 NAS 存储很多使用者准备把 OpenClaw 当作个人数据助手让它管理家庭 NAS 上的文件。Linux 挂载 NAS 用 NFS 或 CIFS/SMB 都行。以 SMB 为例安装挂载工具后手动挂载sudo apt install cifs-utils sudo mkdir -p /mnt/nas sudo mount -t cifs //NAS地址/共享目录 /mnt/nas -o username用户,password密码,vers3.0挂载成功之后OpenClaw 的技能脚本里就可以直接读写/mnt/nas下的文件。这里有个容易踩的坑重启后挂载会失效OpenClaw 启动时如果技能正好访问 NAS 路径会报文件不存在。解决方法是把挂载写进/etc/fstab并配置自动挂载//NAS地址/共享目录 /mnt/nas cifs username用户,password密码,vers3.0,noauto,x-systemd.automount 0 0用x-systemd.automount让系统在真正访问时才挂载比开机直接挂载更抗网络延迟。8.2 技能库的组织和备份小技巧OpenClaw 的技能扩展机制值得单独说。每个技能其实就是一个目录包含描述文件、执行脚本和 prompt 模板。自己写技能时建议按“输入输出格式规范、错误处理兜底、日志记录”三件套来组织代码。技能脚本把每一步的关键操作写进日志OpenClaw 主进程才能在你不在场的时候准确汇报任务进度。技能目录的备份建议同步到 Git 仓库或者 NAS因为技能是你真正在 OpenClaw 上积累的资产模型配置丢了可以重新填 Key技能包丢了等于从零开始。我个人的习惯是每周自动把skills/目录和配置文件打包加密再上传到 NAS任务计划用系统自带的 cron 就行。定期备份相当于给整个 Agent 系统上了保险。写在最后的一些体会几次搭建折腾下来我最深的感觉是OpenClaw 本身并不难装真正的成本都在“环境适配”上——国产系统的软件源、权限策略、中文习惯、分区规划、存储挂载每一步都在挑战你在标准 Ubuntu 上养成的惯性思维。如果你准备在 UOS 或者 Kylin 上部署提前留出半天时间专门处理系统层问题不要想着“系统装完就能直接跑”那几乎是不可能的。我最后还想分享一个小技巧无论你最终选择了源码方式还是 Docker 方式都在安装完成、一切正常之后把完整的安装命令和配置变更记录写成一个笔记文件放在 OpenClaw 的数据目录里。等三个月后系统出问题、需要重装时这份笔记的价值会超过任何教程。我自己就是靠这份笔记在第二台机器上把安装时间压缩到了半小时以内。项目后续再增加新技能、换新模型时笔记同步更新长期下来你的 OpenClaw 会越来越顺手而不是越来越难维护。