在 UOS、Kylin、Ubuntu 上把 OpenClaw 装起来跑 Agent 任务真正的坎往往不是 Agent 逻辑本身而是环境初始化这一路Node.js 版本要求硬、npm 源下载慢、ARM 架构兼容性、飞书插件选型另外还有模型 Key 分散的问题。这次我统一交给 TaoToken 收口先去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建 API Key后续在 OpenClaw 里填 Base URL 为 https://taotoken.net/api身份和插件配置照常走 onboard。下面按安装顺序记录这份排查过程。1. 环境准备UOS 上先解决 Node.js 版本和 npm 镜像1.1 nvm 装 Node.js 22 LTS别用 apt 默认包OpenClaw 对 Node.js 版本有硬性要求这一点在国产系统上尤其容易被忽略。UOS 自带 apt 源里的 nodejs 通常很旧部分 Ubuntu 20.04 的镜像里甚至只有 v10跑 openclaw-cn 会在初始化阶段直接失败。不要在系统包里纠结直接用 nvm 管理版本最稳妥。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 --lts nvm use 22 --lts nvm alias default 22装完验证一下node -v npm -v预期是v22.x和10.x以上。如果 UOS 跑在 ARM64 架构上nvm 会自动下载对应架构的 Node不需要手动指定arm64之类的参数。后续所有 OpenClaw 相关命令都保持在这个默认版本下执行避免切换版本后依赖失效。和版本同样重要的一条不要用 sudo 安装任何 npm 全局包。普通用户在 nvm 环境里直接执行npm install安装路径会落在当前用户目录下一旦加 sudonpm 会去找 root 的全局路径装出来的命令当前用户根本调不到连卸载都要再折腾一遍。1.2 npm 镜像源换成 npmmirror不然卡到超时OpenClaw 的依赖包数量不小直接走官方 npm 源在 UOS 的默认网络环境下很容易出现ECONNRESET、ETIMEDOUT。这里没有太多技巧换源就能解决大半问题npm config set registry https://registry.npmmirror.com npm config get registry确认输出是https://registry.npmmirror.com再继续。这个配置只影响 npm不会动系统其它部分后续飞书插件、社区插件也都走同一路径。开始安装前顺手看一眼磁盘df -h建议剩余空间不低于 2GB。openclaw-cn 本体、npm 缓存和依赖包加起来会占不少空间ARM 设备如果磁盘紧张先清理/var/cache和 npm 缓存再装。2. 安装 openclaw-cn国产系统上选中文社区版2.1 官方版和中文社区版的差异第一次装 OpenClaw 的人往往直接npm install -g openclaw然后在后续初始化或插件阶段碰到兼容问题。openclaw-cn 是针对中文环境和国产系统做过适配的社区版本ARM 架构支持更主动日志和配置项都是中文排查问题成本更低。对比维度如下维护方不同官方版由国际社区维护openclaw-cn 由国内社区维护国产系统支持官方版在 UOS/Kylin 上经常要自己调openclaw-cn 针对性更好ARM 架构官方版部分版本有坑openclaw-cn 优先支持中文环境官方版英文为主openclaw-cn 全中文界面和文档。结论就是不要花时间验证官方版在 UOS 上的兼容性直接选中文社区版。2.2 安装命令与下载中断处理npm install -g openclaw-cnlatest全程不要加 sudo。如果安装过程中卡住回头检查两件事第一node -v是否稳定在 v22第二npm registry 是否已经指向 npmmirror。这两个条件满足后多数下载中断的问题都能解决。偶发的网络抖动可以重试一两次不需要重新配置任何东西。装完确认命令可用openclaw-cn --version能输出版本号说明环境阶段已经过关接下来进入初始化环节。3. onboarding 初始化模型配置这一步Key 从 TaoToken 拿3.1 跑 onboard 前先去 TaoToken 创建 API Key环境就绪后执行初始化向导openclaw-cn onboard --install-daemon向导会依次要求配置身份、模型、插件。到了模型配置这一步习惯做法是去各家模型厂商官网申请 Key再抄回各自的 Base URL多模型场景下要在好几个控制台之间来回切额度用完一个还要去另一个充值。这次我把这一环收敛到 TaoToken 上先打开 TaoToken 注册一个账号并创建 API Key把 Key 记下来后面配置时替换YOUR_API_KEY这段占位符。多个模型之间的切换不用再分散到各厂商后台去折腾直接在模型广场选对应 ID 就行。3.2 OpenClaw 模型配置里填入 Base URL 和 Key在onboard过程中选择模型提供方时优先选“自定义模型”或“OpenAI 兼容”这一类选项。生成的配置会落在~/.openclaw/openclaw.json等效的模型片段如下{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY, model: model-id-from-tao-token-model-marketplace } }实际文件里字段名可能随版本略有差异以你机器上生成的为准。重点是下面三个值不能错baseUrl填https://taotoken.net/api末尾不要加/v1apiKey填你在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建的YOUR_API_KEYmodel填模型广场上真实存在的模型 ID以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场当时列表为准不要随手抄网上的模型名。提示baseUrl是给工具内部发请求用的接口地址官网落地页用来注册、看模型广场、看用量两个用途不要混。OpenClaw 会按 OpenAI 兼容格式向这个地址发请求配置正确的情况下飞书或钉钉插件收到的指令Agent 就能正常调用模型处理。4. 初始化后两件事网关令牌和飞书插件4.1 dashboard 生成带令牌的访问地址onboard 完成后浏览器访问http://127.0.0.1:18789时常常会看到disconnected (1008): unauthorized: gateway token missing。这不是服务没启动而是访问 URL 没带令牌。用下面的命令重新生成带令牌的地址openclaw-cn dashboard --no-open它会输出一个带 token 参数的完整地址复制到浏览器打开即可。也可以手动看配置文件里的 tokencat ~/.openclaw/openclaw.json | grep token注意这个 token 是网关访问凭证和模型 API Key 是两回事。API Key 只在模型接口调用时使用网关 token 只用来进入 Web 管理界面不要弄混。4.2 飞书插件选中文社区版Client ID 从开放平台复制安装飞书插件时向导会给出几个选项。国产系统上直接选中文社区版openclaw-cn/feishu它对 UOS/Kylin 和 ARM 架构的适配更主动配置项和日志都是中文排查错误方便底层流程和官方版没有差别。填写 Client ID 和 Client Secret 的时候不要自己编。去飞书开放平台创建一个企业内部应用在“凭证与基础信息”里复制对应的 AppKey 和 AppSecret粘贴进 OpenClaw 配置。另外必须把应用发布一个版本飞书侧配置才会真正生效。钉钉插件同理Client ID 对应钉钉开放平台里的 AppKey逻辑一致。5. UOS 排障清单按顺序自查这几个坑5.1 端口 4008 与浏览器兼容问题遇到过一种情况Web 界面显示不正常怎么看都不像服务挂了最终定位是浏览器强制走了 4008 端口而 OpenClaw 实际端口是 18789。这类问题多出现在某些安全浏览器上它会对页面做额外端口转换但服务本身没有问题。解决办法很简单改用 Chromium 内核浏览器或 Firefox再用下面命令核对实际端口cat ~/.openclaw/openclaw.json | grep port端口数值不需要改只要确认服务监听的端口手动访问正确地址即可。5.2 依赖安装失败ECONNRESET、ETIMEDOUT、lib 缺失依赖下载失败最常见的三个来源注册源没换、Node 版本不对、用了 sudo。顺着查一遍npm config get registry必须显示 npmmirrornode -v必须是 v22 开头安装命令不加 sudo。这三条全部满足后重装基本能过。ARM 架构的 UOS/Kylin 上还可能遇到运行时报error while loading shared libraries: libXXX.so.X。这种是缺基础依赖库不是 OpenClaw 的问题sudo apt update sudo apt install -y build-essential libssl-dev这里用 sudo 安装系统包没问题但不要让 openclaw 命令本身在 sudo 下运行。5.3 模型接口 404先查 Base URL 是否多了 /v1模型配置完成后如果日志里出现 404 或path not found最优先检查 Base URL。填进工具的应该是https://taotoken.net/api不要在末尾自己补/v1也不要误填成不带/api的官网地址。其次检查YOUR_API_KEY是否已经替换成真实值占位符本身不会通过鉴权。6. 一键检查清单然后去控制台对一下这一次调用6.1 装完跑一遍五条检查到这一步环境应该已经完整跑通。在正式派发 Agent 任务前按下面清单快速确认一遍uname -m node -v npm -v npm config get registry df -h分别对应架构是x86_64或aarch64Node 版本 v22 开头npm 10.x 以上registry 指向 npmmirror磁盘剩余 2GB 以上。五条都通过系统这一侧就稳了。6.2 用 TaoToken 验证模型调用再看控制台记录系统侧就绪后先在 TaoToken 模型对话 里用同一把 Key 发一条测试消息确认模型 ID 和 Base URL 都没填错。模型对话页正常返回后再回 OpenClaw 跑第一个正式 Agent 任务比如让 Agent 把飞书频道里的待办抓取下来并生成一份摘要。任务跑完去 TaoToken 控制台 API Keys 看这次调用是否被正确记录。如果准备长期跑代码相关任务可以顺手打开 Coding Plan 看看流量套餐是否够用。这样从 Key 创建、模型调用、Agent 任务执行到用量核对整条链路都收拢到一处UOS 上的 OpenClaw 才算真正跑顺。