★ FEATURED ARTICLE 1. 为什么要在 Ubuntu/CentOS 上折腾 OpenClaw 一键部署OpenClaw 是一个面向机器人控制与自动化编排的开源框架它把底层驱动、任务调度、模型推理这几层拆开让你可以用配置文件描述「做什么」而不是从零写控制逻辑。适合谁做智能硬件原型的团队、需要把大模型能力接进机械臂或移动底盘的开发者以及想在 Linux 服务器上跑一套可复现控制环境的运维同学。它本身不绑定某一家模型服务模型接入层是开放的这也是后面要接 TaoToken 统一 Key 的原因。真正让人头疼的不是 OpenClaw 本身而是「装」这件事。Ubuntu 和 CentOS 的包管理、Python 版本、CMake 版本、systemd 单元写法都不一样手动一步步来十有八九会卡在某个依赖上。我试过在一台 CentOS 8 上从零编译光 CMake 版本就来回折腾了两次。所以这篇的核心是用一键脚本把系统检测、依赖安装、编译、服务注册串起来再用 TaoToken 的统一 Key 把模型通道一次性配好让「装完就能调」变成现实。这篇会覆盖 Ubuntu 20.04/22.04 和 CentOS 8/9 两条线给出可复制的部署命令、环境变量、openclaw.yaml配置片段以及服务起来之后的连通性验证动作。你不需要提前懂 CMake也不需要理解 systemd 的每个字段照着敲、照着改就行。核心检索词先摆在这Linux 下 OpenClaw 一键部署、Ubuntu/CentOS 双系统、TaoToken 统一 Key 接入这三件事串起来就是完整链路。先说清楚一个前提OpenClaw 的模型调用走的是标准 HTTP 接口所以只要有一个兼容 OpenAI 协议的统一入口就能把模型层接上。TaoToken 提供的就是这样一个入口一个 Key 对应多个模型省去你在每台机器上分别配不同厂商 Key 的麻烦。下面从环境准备开始一步步来。2. TaoToken 前置准备统一 Key 与 API 通道怎么拿在动手装 OpenClaw 之前先把模型通道准备好否则装完了也没法验证。TaoToken 的角色是「统一 Key 统一 Base URL」你只需要一个 Key就能在 OpenClaw 里调用不同模型不用为每个模型单独申请凭证。这对多机部署特别友好——十台机器共用一套环境变量改一处即可。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台找到 API Keys 页面创建一个新的 Key。建议按用途命名比如openclaw-prod方便后面排查是哪个环境在用。创建后立刻复制保存页面刷新后就不再完整显示。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api注意这个地址不带任何查询参数配置时原样填入即可。OpenClaw 的模型配置里通常有一个base_url字段填这个值。第三步确认你要用的 Model ID。在控制台的模型列表里能看到当前可用的模型标识比如常见的对话模型、代码模型。把 Model ID 记下来后面写进openclaw.yaml。这里有个坑Model ID 是区分大小写的复制的时候别手抖。如果你只是想先验证模型通道通不通可以打开模型对话页面直接发一条消息确认 Key 有效、额度正常。这一步花不了一分钟但能省掉后面「服务起来了但调不通」的排查时间。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后直接可用。对于长期跑编码任务或 Agent 的场景可以考虑 Coding Plan它在额度和并发上更适合持续调用。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。不过这一步不是必须的先用按量 Key 跑通链路再决定要不要升级。把这三样东西准备好Key、Base URLhttps://taotoken.net/api、Model ID。接下来进入部署环节。记住Key 不要写进会提交到 Git 的文件里用环境变量或独立的配置文件承载。3. 可复制配置Ubuntu/CentOS 一键脚本与 openclaw.yaml这一节是全文最核心的部分给出可直接复制的脚本和配置。先讲一键部署脚本再讲模型配置文件最后讲环境变量。3.1 Ubuntu 一键部署脚本把下面内容保存为install_openclaw_ubuntu.sh然后chmod x执行。脚本做了发行版检测、架构检测、磁盘空间检测、依赖安装、编译、systemd 注册这一整套。#!/bin/bash set -e echo OpenClaw Ubuntu 一键部署 if [ $EUID -ne 0 ]; then echo 请用 root 或 sudo 运行 exit 1 fi . /etc/os-release if [[ $ID ! ubuntu ]]; then echo 仅支持 Ubuntu当前为 $ID exit 1 fi ARCH$(uname -m) if [ $ARCH ! x86_64 ]; then echo 警告当前架构 $ARCHOpenClaw 官方仅验证 x86_64 fi AVAILABLE$(df -BG / | tail -1 | awk {print $4} | sed s/G//) if [ $AVAILABLE -lt 10 ]; then echo 磁盘空间不足 10GB当前 ${AVAILABLE}GB exit 1 fi apt update apt install -y build-essential python3 python3-pip python3-venv python3-dev \ git cmake libeigen3-dev libyaml-cpp-dev libboost-all-dev libssl-dev mkdir -p /opt/openclaw cd /opt/openclaw if [ ! -d openclaw ]; then git clone https://github.com/openclaw/openclaw.git fi cd openclaw python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt mkdir -p build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j$(nproc) make install cat /etc/profile.d/openclaw.sh EOF export OPENCLAW_HOME/usr/local/openclaw export PATH$OPENCLAW_HOME/bin:$PATH export LD_LIBRARY_PATH$OPENCLAW_HOME/lib:$LD_LIBRARY_PATH EOF chmod x /etc/profile.d/openclaw.sh source /etc/profile.d/openclaw.sh mkdir -p /etc/openclaw cp /usr/local/openclaw/share/openclaw/openclaw.yaml /etc/openclaw/ 2/dev/null || true cat /etc/systemd/system/openclaw.service EOF [Unit] DescriptionOpenClaw Control Service Afternetwork.target [Service] Typesimple Userroot EnvironmentFile/etc/profile.d/openclaw.sh ExecStart/usr/local/openclaw/bin/openclaw start Restarton-failure RestartSec5 [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable openclaw systemctl start openclaw systemctl status openclaw --no-pager3.2 CentOS 一键部署脚本CentOS 的差异主要在包管理器和 CMake 命名cmake3脚本如下#!/bin/bash set -e echo OpenClaw CentOS 一键部署 if [ $EUID -ne 0 ]; then echo 请用 root 或 sudo 运行 exit 1 fi . /etc/os-release if [[ $ID ! centos $ID ! rhel ]]; then echo 仅支持 CentOS/RHEL当前为 $ID exit 1 fi yum install -y epel-release yum groupinstall -y Development Tools yum install -y python3 python3-pip python3-devel git cmake3 \ eigen3-devel yaml-cpp-devel boost-devel openssl-devel alternatives --install /usr/local/bin/cmake cmake /usr/bin/cmake3 20 mkdir -p /opt/openclaw cd /opt/openclaw if [ ! -d openclaw ]; then git clone https://github.com/openclaw/openclaw.git fi cd openclaw python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt mkdir -p build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j$(nproc) make install cat /etc/profile.d/openclaw.sh EOF export OPENCLAW_HOME/usr/local/openclaw export PATH$OPENCLAW_HOME/bin:$PATH export LD_LIBRARY_PATH$OPENCLAW_HOME/lib:$LD_LIBRARY_PATH EOF chmod x /etc/profile.d/openclaw.sh source /etc/profile.d/openclaw.sh mkdir -p /etc/openclaw cp /usr/local/openclaw/share/openclaw/openclaw.yaml /etc/openclaw/ 2/dev/null || true cat /etc/systemd/system/openclaw.service EOF [Unit] DescriptionOpenClaw Control Service Afternetwork.target [Service] Typesimple Userroot EnvironmentFile/etc/profile.d/openclaw.sh ExecStart/usr/local/openclaw/bin/openclaw start Restarton-failure RestartSec5 [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable openclaw systemctl start openclaw systemctl status openclaw --no-pager3.3 openclaw.yaml 模型配置片段这是接入 TaoToken 的关键。编辑/etc/openclaw/openclaw.yaml找到模型相关段落按下面结构填写。注意base_url用 https://taotoken.net/apiapi_key从环境变量读取不要硬编码。model: provider: openai_compatible base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} model_id: your-model-id timeout: 60 max_retries: 3 agent: planner: model_ref: default executor: model_ref: default如果你用的是 JSON 风格的配置部分版本支持等价写法{ model: { provider: openai_compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model_id: your-model-id, timeout: 60 } }3.4 环境变量注入把 Key 写进/etc/profile.d/openclaw.sh这样 systemd 和交互式 shell 都能读到echo export TAOTOKEN_API_KEYsk-你的Key /etc/profile.d/openclaw.sh source /etc/profile.d/openclaw.sh改完配置后重启服务systemctl restart openclaw。到这里部署和模型接入的配置就齐了。三件套记牢Base URL 是 https://taotoken.net/apiKey 是你在控制台创建的Model ID 是模型列表里复制的那个。4. 验证请求服务启动后怎么确认真的通了装完不代表通了必须做连通性验证。分三层服务层、配置层、模型层。第一层服务层。执行systemctl status openclaw --no-pager看到active (running)才算服务起来了。如果显示failed先看journalctl -u openclaw -n 100的日志。常见的是配置文件路径不对或环境变量没加载。第二层配置层。运行openclaw --version确认二进制可用再运行openclaw config check部分版本是openclaw test --config检查openclaw.yaml语法。如果报 YAML 解析错误多半是缩进或引号问题用python3 -c import yaml; yaml.safe_load(open(/etc/openclaw/openclaw.yaml))快速定位。第三层模型层。这是最关键的一步。用 curl 直接打 TaoToken 的接口确认 Key 和 Base URL 没问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [{role: user, content: ping}] }如果返回里有choices字段和内容说明模型通道是通的。如果返回 401说明 Key 不对或没带上如果返回 404检查 Base URL 是不是多写了路径。模型层通了之后再回到 OpenClaw 里跑一次端到端调用。可以用openclaw test --unit跑单元测试或者用openclaw run --task hello触发一次简单任务。观察日志里有没有model request success之类的记录。实测下来只要 curl 通了OpenClaw 里基本不会再有模型层的问题剩下的都是配置字段名对不上的小问题。验证通过后建议把验证命令写成一个脚本方便以后换机器时复用#!/bin/bash echo 1. 服务状态; systemctl is-active openclaw echo 2. 版本; openclaw --version echo 3. 模型通道; curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY第三个命令返回 200 就说明通道正常。这套验证动作跑一遍不超过 30 秒但能帮你把问题定位到具体层。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth部署过程中最容易撞上的几类报错这里逐个对照。401 Unauthorized。这是最高频的。原因通常是 Key 没读到、Key 写错、或者环境变量没生效。排查顺序先echo $TAOTOKEN_API_KEY看有没有值再看openclaw.yaml里是不是写成了${TAOTOKEN_API_KEY}而不是硬编码最后确认 systemd 的EnvironmentFile指向的脚本里确实 export 了这个变量。注意systemd 不会自动读~/.bashrc所以必须放在/etc/profile.d/下并通过EnvironmentFile引入。local proxy failed。这个报错通常出现在 OpenClaw 尝试走本地代理但代理没起来的时候。检查openclaw.yaml里有没有proxy相关字段被误开。如果没有特殊需求把proxy段删掉或设为null。另外确认base_url是直连的 https://taotoken.net/api不要填成带端口的本地地址。reading choices 报错。典型表现是日志里出现cannot read property choices of undefined或类似。这说明请求发出去了但返回体结构不对。原因一般是 Model ID 填错或者 Base URL 少了/v1。TaoToken 的完整路径是 https://taotoken.net/api/v1/chat/completions配置里如果只填到/apiOpenClaw 会自己拼/v1但不同版本行为不一致。稳妥做法是先用 curl 确认完整路径能通再对照配置。OAuth 相关报错。如果你在配置里看到OAuth token expired或invalid_grant说明误用了 OAuth 流程。OpenClaw 接 TaoToken 用的是 API Key 模式不需要 OAuth。检查配置里有没有auth_type: oauth之类的字段改成api_key。同时确认没有引入额外的认证中间件。服务启动失败但日志为空。这种情况多半是ExecStart路径不对。用ls -la /usr/local/openclaw/bin/openclaw确认二进制存在。如果不存在说明make install没成功回到 build 目录重新make install。编译阶段 CMake 版本过低。CentOS 上尤其常见。cmake --version如果低于 3.15用alternatives把cmake3链过去或者手动装新版 CMake。Ubuntu 上如果版本低可以加 deadsnakes PPA 或直接下官方二进制。Python 依赖装不上。多数是python3-dev没装导致编译 C 扩展失败。Ubuntu 上apt install python3-devCentOS 上yum install python3-devel。另外确认 venv 是激活状态再pip install。排查的核心思路是分层先确认服务层再确认配置层最后确认模型层。每一层都有对应的命令不要跳步。把 curl 验证放在最前面能省掉大量在 OpenClaw 内部瞎找的时间。6. 接入文档与后续调用入口链路跑通之后日常使用主要围绕三件事改配置、重启服务、看日志。改openclaw.yaml后systemctl restart openclaw看日志用journalctl -u openclaw -f。如果要做更细的接入定制比如换模型、加超时、调重试次数参考接入文档里的字段说明入口在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。文档里对 Base URL、Model ID、鉴权头的写法有完整示例照着改不会错。如果你需要管理多个 Key或者给不同机器分配不同权限控制台的 API Keys 页面可以创建多个 Key 并分别命名。入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。建议生产环境和测试环境用不同的 Key方便排查和限额。对于长期跑 Agent 任务的场景Coding Plan 在并发和额度上更合适入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果只是偶尔调用按量 Key 就够了。最后给一个实用技巧把openclaw.yaml里的api_key始终写成${TAOTOKEN_API_KEY}Key 只存在于/etc/profile.d/openclaw.sh。这样配置文件可以安全地备份、分享、提交到内部仓库不会泄露凭证。换 Key 的时候只改一个文件重启服务即可不用碰 OpenClaw 本身的配置。这套做法在多机部署时尤其省事——把脚本和配置文件复制过去改一下环境变量里的 Key就能跑起来。
阅读完成 · 觉得有帮助？
