1. 国内 Ubuntu 部署 OpenClaw 大龙虾卡点到底在哪OpenClaw 是一个用 TypeScript 写的开源个人 AI 智能体框架社区里习惯叫它“大龙虾”核心定位是让 AI 真正去执行任务而不是只聊天。它适合想在自己机器上跑一个可编排、可接工具、可换模型的本地 Agent 的同学尤其是手里有 Ubuntu 服务器或本地虚拟机、又希望统一管理模型 Key 的人。国内环境部署它难点通常不在代码本身而在三件事Node.js 版本要够新、npm 拉包要稳、模型通道要能通。前两个是环境问题第三个是配置问题。我这篇按“能跟着敲完就能跑起来”的节奏来写先确认系统与 Node.js再拉取并启动 OpenClaw然后重点给出一份基于 TaoToken 统一 Key 的config.toml配置骨架最后用一次真实请求验证连通性并把国内环境最容易踩的报错逐条拆开。整套流程在 Ubuntu 24.04 上实测可复现命令和参数都写全你照着替换自己的 Key 即可。需要先说明一点OpenClaw 的模型接入走的是标准 API 通道TaoToken 在这里扮演的是统一 Key 与统一入口的角色你不需要为每个模型厂商单独维护一套鉴权逻辑配置集中在一个文件里换模型只改几行。这对后面做多模型对比、做 Agent 工具调用会省很多事。2. 前置准备Ubuntu 系统确认与 Node.js 22 安装2.1 确认系统版本先看一眼系统避免在过老的发行版上折腾依赖。执行cat /etc/os-release输出里关注VERSION_ID本文以 Ubuntu 24.04 LTS 为例。如果你的是 22.04 也完全可以命令一致。低于 20.04 的建议先升级否则后面 Node.js 22 的源可能装不上。PRETTY_NAMEUbuntu 24.04.4 LTS NAMEUbuntu VERSION_ID24.04 VERSION_CODENAMEnoble IDubuntu ID_LIKEdebian2.2 安装 Node.js 22 与 npmOpenClaw 的核心由 TypeScript 编写运行要求 Node.js ≥ 22。Ubuntu 自带的 apt 源里 Node 版本往往偏低所以用 NodeSource 的源来装curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs装完立刻验证这一步别跳过版本不对后面全局安装会直接失败node --version # 期望 v22.x.x npm --version # 期望 10.x.x如果node --version还是旧版本说明 PATH 里存在旧的 node用which -a node看一下有几个把旧的软链或旧安装清掉再重试。我试过在一台装过 nvm 的机器上nvm 的 shim 优先级更高导致新装的 22 被遮住nvm use system切回来就好了。2.3 配置 npm 国内镜像源国内直连 npm 官方源拉包经常超时先切镜像npm config set registry https://registry.npmmirror.com npm config get registry # 确认已生效这一步只影响包下载速度不影响后面模型 API 的调用两者是分开的别混淆。3. TaoToken 统一 Key 与 API 通道准备3.1 为什么用统一 KeyOpenClaw 支持多种 provider如果你每个厂商都单独配一遍 base URL 和 key配置文件会越来越乱换模型时容易改错。TaoToken 提供的是统一 Key 加统一 API 入口你只需要在config.toml里维护一份鉴权信息模型名按需切换即可。对做 Agent 的人来说这意味着工具调用、多轮对话、模型对比都走同一条通道排障时变量更少。3.2 获取 Key 与确认入口先到控制台创建 API Key入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后复制那串 Key注意它只在创建时完整显示一次先存到安全的地方。API 的基础地址是https://taotoken.net/api这个地址后面要填进config.toml的base_url字段。如果你用的是 OpenAI 兼容协议路径通常拼到/v1具体以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意Key 属于敏感凭据不要提交到 Git 仓库也不要在截图里露出完整字符串。建议用环境变量注入配置文件里只写变量引用。4. 拉取并启动 OpenClaw 项目4.1 全局安装 OpenClaw镜像源配好后直接全局安装npm install -g openclawlatest openclaw --version能打印出版本号就说明 CLI 装好了。如果卡在idealTree阶段很久多半是镜像源没生效回头确认npm config get registry。4.2 初始化项目进入你打算放项目的目录执行初始化mkdir -p ~/openclaw-demo cd ~/openclaw-demo openclaw onboard --install-daemon--install-daemon会把 OpenClaw 注册成后台服务方便开机自启。交互过程里会让你选 provider、填 base URL、填 key、选模型这里先随便选一个能过的因为下一步我们要用config.toml覆盖成 TaoToken 的配置。4.3 项目结构速览初始化完成后目录里会出现配置文件核心是config.toml。用编辑器打开ls -la cat config.toml如果初始化没生成这个文件手动建一个即可OpenClaw 启动时会读取它。下面给出完整的配置骨架。5. config.toml 配置骨架TaoToken 统一 Key5.1 完整配置骨架把下面这份骨架贴进config.toml字段按你的实际情况替换。我用的是 OpenAI 兼容协议模型名先填一个通用值你按接入文档里支持的模型列表替换# OpenClaw 主配置 [agent] name dalongxia language zh-CN workspace /root/openclaw-demo/workspace # 模型通道统一走 TaoToken [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key ${TAOTOKEN_API_KEY} model_id your-model-id temperature 0.7 max_tokens 4096 timeout_seconds 60 # 工具与执行 [tools] enabled true shell_timeout 30 allow_network true # 日志 [log] level info file /root/openclaw-demo/logs/openclaw.log关键点说明base_url指向 TaoToken 的 API 入口api_key用环境变量引用而不是明文model_id按你实际要用的模型填。provider写openai-compatible是因为 TaoToken 走的是兼容协议这样 OpenClaw 内部用同一套请求逻辑。5.2 用环境变量注入 Key不要把 Key 写死在文件里。在 shell 里导出export TAOTOKEN_API_KEY你的Key echo export TAOTOKEN_API_KEY你的Key ~/.bashrc source ~/.bashrc如果你用 systemd 跑 daemon环境变量要写进 service 文件否则 daemon 读不到。编辑sudo systemctl edit openclaw在[Service]段加一行[Service] EnvironmentTAOTOKEN_API_KEY你的Key然后重载sudo systemctl daemon-reload sudo systemctl restart openclaw5.3 参数对照表字段作用建议值provider协议类型openai-compatiblebase_urlAPI 入口https://taotoken.net/api/v1api_key鉴权环境变量引用model_id模型标识按文档填timeout_seconds请求超时60temperature随机性0.76. 连通性验证与成功结果6.1 用 CLI 发一次请求配置写好后先做一次最小验证确认通道是通的openclaw run --prompt 用一句话说明你当前使用的模型通道如果返回了正常文本说明 Key、base URL、模型名三者都对上了。返回内容里如果出现鉴权错误或 404直接跳到下一节排障。6.2 用 curl 单独验证 API 通道为了把“OpenClaw 配置问题”和“API 通道问题”分开建议单独用 curl 打一次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}] }返回 JSON 里带choices字段就说明通道没问题。这一步能过、而 OpenClaw 报错那问题一定在config.toml的字段拼写上比如base_url少了/v1或者model_id写成了别的名字。6.3 验证 Agent 工具调用OpenClaw 的价值在于执行任务所以再跑一个带工具的例子确认它能真的动手openclaw run --prompt 查看当前磁盘使用率超过80%就提醒我正常情况它会调用 shell 工具执行df -h然后根据结果给出判断。这一步跑通说明模型通道加工具执行链路都活了。7. 本篇常见报错排查7.1 Node 版本不符报错长这样Error: OpenClaw requires Node.js 22原因就是系统里跑的还是旧 Node。用which -a node找出所有 node把旧版本清掉或者用nvm use system切到系统安装的 22。7.2 npm 安装超时npm ERR! network request to https://registry.npmjs.org failed镜像源没生效。重新执行npm config set registry https://registry.npmmirror.com然后npm cache clean --force再装。7.3 401 鉴权失败401 Unauthorized三种可能Key 复制时带了空格环境变量没导出成功echo $TAOTOKEN_API_KEY验证daemon 没读到环境变量需要按 5.2 写进 service 文件。7.4 404 模型不存在404 model not foundmodel_id写错了或者base_url路径不对。对照接入文档确认模型名和路径注意/v1是否要带。7.5 daemon 启动失败sudo systemctl status openclaw journalctl -u openclaw -n 50看日志里第一条错误通常是配置文件语法问题。TOML 对引号和缩进敏感用openclaw config validate先校验一遍再重启。8. 后续怎么用模型对话、Coding Plan 与接入文档部署跑通只是起点。日常想快速验证某个模型的表现可以直接用模型对话页面省去本地起服务的步骤https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你打算把 OpenClaw 长期挂在服务器上做编码助手或 Agent 任务建议看一下 Coding Plan它更适合高频、长周期的调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteKey 的管理和轮换在控制台完成接入细节和字段说明以文档为准https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后给一个实用习惯把config.toml里的model_id和base_url做成可切换的两套配置一套日常对话、一套编码任务切换时只改这两行其余不动。这样你在 OpenClaw 里做多模型对比时排障范围永远只有两个变量出问题一眼就能定位。