1. 本地 Ubuntu 服务器部署 OpenClaw 到底难在哪OpenClaw 是一个可以跑在自己服务器上的 AI 编码助手网关它把模型调用、会话管理、Web UI 都收拢到一个本地服务里适合想在自己机器上长期挂一个编码 Agent 的人。这篇教程聚焦的场景很具体你有一台本地 Ubuntu 服务器物理机、虚拟机、局域网小主机都行想从零把 OpenClaw 跑起来并且用 TaoToken 的统一 Key 把模型通道接进去最后通过 SSH 端口转发在本地浏览器里验证整条链路是通的。真正卡人的地方通常不是 OpenClaw 本身而是三件事叠在一起Node.js 版本不对导致npm install -g openclaw报错服务器没有图形界面Web UI 打不开模型 API 的 Key 和 Base URL 散落在各个工具里配一次忘一次。我试过在一台 2C4G 的 Ubuntu 22.04 上反复重装最后发现 80% 的失败都出在 Node 版本和 SSH 转发这两个点上。所以下面按「环境准备 → 装 OpenClaw → 接 TaoToken 统一 Key → SSH 验证 → 排错」的顺序走每一步都给可复制的命令和配置片段。你不需要有前端经验只要能 SSH 登录服务器、会复制粘贴命令就能跟下来。整篇的核心检索词就是 ubuntu、openclaw、部署、node.js、ssh遇到问题可以直接跳到第 5 节对照报错。2. 前置准备Node.js 22、SSH 与 TaoToken 统一 Key2.1 确认 Ubuntu 版本和基础工具先登录服务器确认系统版本和基础依赖。OpenClaw 对系统要求不苛刻Ubuntu 20.04 及以上都能跑但 Node.js 必须是 22 或更高这是唯一的硬性依赖。# 登录服务器 ssh ubuntu192.168.2.199 # 查看系统版本 lsb_release -a # 更新包索引并装基础工具 sudo apt update sudo apt install -y curl git build-essentialbuild-essential建议装上某些 npm 原生模块编译时会用到缺了会在安装阶段报gyp ERR之类的错。2.2 用 nvm 装 Node.js 22不要用apt install nodejsUbuntu 源里的版本通常太旧。用 nvm 管理最省心也方便以后切换版本。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 让 nvm 在当前终端生效 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装 Node.js 22 nvm install 22 # 设为默认版本 nvm alias default 22 # 验证 node -v npm -vnode -v输出v22.x.x就对了。如果输出的是v18或更低说明 nvm 没生效重开一个终端再试或者把上面两行 export 写进~/.bashrc。2.3 为什么用 TaoToken 统一 KeyOpenClaw 支持自定义模型通道你可以填任意兼容 OpenAI 协议的 Base URL 和 Key。问题在于如果你同时用 Cline、CC Switch、OpenClaw 好几个工具每个都单独配一遍 Key改一次要改好几处很容易漏。TaoToken 的做法是给你一个统一的 API 入口和 Key所有工具都指向同一个地址换模型、换额度只在一个地方改。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式所以 OpenClaw、Cline 这类工具都能直接接。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 Key 即可。注意Key 只生成一次页面关掉就看不到了记得先复制存好。后面所有配置都复用这一个 Key。3. 安装 OpenClaw 并写入 config.toml 配置骨架3.1 全局安装 OpenClawNode 环境就绪后安装本身只有一条命令npm install -g openclawlatest # 验证安装 openclaw --version看到版本号就说明装好了。如果卡在下载阶段多半是网络问题可以换 npm 镜像重试npm config set registry https://registry.npmmirror.com npm install -g openclawlatest3.2 初始化配置目录OpenClaw 的配置默认放在~/.openclaw/下主配置文件是config.toml。先手动建好目录避免 onboard 时权限报错mkdir -p ~/.openclaw cd ~/.openclaw3.3 可复制的 config.toml 骨架下面这份config.toml是接 TaoToken 统一 Key 的最小可用骨架直接复制到~/.openclaw/config.toml把api_key换成你自己的即可# ~/.openclaw/config.toml [server] host 127.0.0.1 port 18789 [model] # TaoToken 统一 API 入口 base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 # 按需替换成你账号下可用的模型名 model claude-sonnet-4-5 provider openai-compatible [agent] name openclaw-local max_tokens 8192 temperature 0.7 [ui] # 服务器无图形界面仅监听本地靠 SSH 转发访问 enabled true几个关键点说明一下。base_url填https://taotoken.net/api不要多加/v1OpenClaw 会自己拼接路径。provider用openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议。host保持127.0.0.1服务器上不要暴露到0.0.0.0否则同网段任何人都能访问你的网关。3.4 用 onboard 引导补齐配置如果你不想手写也可以跑官方引导命令它会交互式地问你模型地址、Key、端口等信息openclaw onboard --install-daemon引导过程中选择「自定义安装本地 LLM」或「自定义 API 通道」在 Base URL 处填https://taotoken.net/apiKey 填 TaoToken 的 Key。--install-daemon会把 OpenClaw 注册成 systemd 服务服务器重启后自动拉起省得每次手动openclaw start。引导完成后检查服务状态systemctl --user status openclaw4. SSH 端口转发与 API 调用验证4.1 为什么必须做 SSH 转发OpenClaw 的 Web UI 默认只监听127.0.0.1:18789这是服务器本机地址。你的笔记本和服务器不在同一台机器上直接访问http://192.168.2.199:18789是打不开的。解决办法是用 SSH 本地端口转发把服务器的 18789 端口映射到你笔记本的 18789 端口。在本地电脑Windows 用 CMD 或 PowerShellMac/Linux 用终端执行ssh -N -L 18789:127.0.0.1:18789 ubuntu192.168.2.199输入密码后窗口保持空白、没有报错就说明转发成功了。这个窗口不要关关了转发就断。4.2 打开 Web UI转发建立后在本地浏览器访问http://localhost:18789如果 OpenClaw 启动时输出了带 Token 的完整链接形如http://127.0.0.1:18789/#/tokenxxxx把里面的127.0.0.1换成localhost再粘贴访问http://localhost:18789/#/token你的最新TokenToken 每次openclaw start都可能变以终端最新输出为准。4.3 用 curl 验证 TaoToken 通道Web UI 能打开只说明服务活着还要确认模型通道真的通。在服务器上直接 curl 一次 TaoToken 的接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字通了}] }返回 JSON 里choices[0].message.content有内容就说明 Key 和通道都没问题。如果返回 401是 Key 错了返回 404多半是base_url多写了或漏写了/v1。4.4 在 OpenClaw 里发一条测试消息回到 Web UI新建一个会话随便问一句「你好帮我写个 Python 快排」。能正常流式返回就说明 OpenClaw → TaoToken → 模型这条链路完整跑通了。这一步是整个部署的验收点过了就基本稳了。5. 部署 OpenClaw 常见报错排查5.1 node 版本过低导致安装失败报错长这样openclaw requires Node.js 22。原因是系统里默认 node 还是旧版本。解决nvm install 22 nvm alias default 22 node -v # 确认是 v22 npm install -g openclawlatest如果node -v还是旧的检查~/.bashrc里有没有 nvm 的初始化代码没有就补上。5.2 SSH 转发后浏览器打不开先确认转发窗口没关、没报错。然后在服务器上确认服务在监听ss -tlnp | grep 18789应该看到127.0.0.1:18789。如果服务没起来执行openclaw start或systemctl --user restart openclaw。还有一种情况是本地 18789 端口被占用换个本地端口转发即可ssh -N -L 18888:127.0.0.1:18789 ubuntu192.168.2.199 # 然后访问 http://localhost:188885.3 API 返回 401 / 403401 是 Key 无效或没带。检查config.toml里api_key有没有多余空格curl 测试时Bearer后面有没有漏空格。403 通常是 Key 权限或额度问题去 TaoToken 控制台确认 Key 状态和余额。5.4 返回 404 或 model not foundbase_url写错是最常见原因。正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/v1也不要漏掉https。另外确认model字段填的模型名在你账号下确实可用不同账号开放的模型可能不一样。5.5 服务器重启后 Web UI 打不开如果 onboard 时加了--install-daemon服务会自启你只需要重新做 SSH 转发。如果没加每次重启后手动openclaw start然后复制终端输出的新 Dashboard 链接本地重新转发、替换127.0.0.1为localhost访问。6. 把 OpenClaw 接进 Cline 和 CC Switch6.1 Cline 接入示例Cline 是 VS Code 里的编码插件它支持 OpenAI 兼容接口。在 Cline 设置里选「OpenAI Compatible」填配置项值Base URLhttps://taotoken.net/apiAPI Keysk-你的TaoToken密钥Model IDclaude-sonnet-4-5这样 Cline 和 OpenClaw 共用同一个 TaoToken Key改额度、换模型只在一个地方动。6.2 CC Switch 接入示例CC Switch 用来在多个模型通道间切换。新增一个 provider类型选 OpenAI 兼容Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 Key保存后即可在 OpenClaw 和 CC Switch 之间共享同一套凭证。6.3 长期跑编码 Agent 的建议如果你打算让 OpenClaw 长期挂着跑编码任务建议用 Coding Plan 这类按周期计费的方案比按量付费更可控适合 Agent 这种高频调用的场景。配置入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Key 管理在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。6.4 验证模型是否可用想快速确认某个模型名能不能调不用改配置文件直接在模型对话页试一句就行https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。能出结果再把模型名写进config.toml省得反复重启服务。6.5 收尾把转发做成脚本每次手敲 SSH 转发命令太烦本地建个tunnel.sh#!/bin/bash ssh -N -L 18789:127.0.0.1:18789 ubuntu192.168.2.199chmod x tunnel.sh后双击或命令行运行即可。服务器那边把openclaw start也写进~/.bashrc的登录钩子或者干脆用 systemd 托管重启后基本不用管。整套跑顺之后你就有了一台本地 Ubuntu 上的 OpenClaw 网关配一个 TaoToken 统一 KeyCline、CC Switch、Web UI 全部复用后面换模型只改一行配置。
1. 本地 Ubuntu 服务器部署 OpenClaw 到底难在哪OpenClaw 是一个可以跑在自己服务器上的 AI 编码助手网关它把模型调用、会话管理、Web UI 都收拢到一个本地服务里适合想在自己机器上长期挂一个编码 Agent 的人。这篇教程聚焦的场景很具体你有一台本地 Ubuntu 服务器物理机、虚拟机、局域网小主机都行想从零把 OpenClaw 跑起来并且用 TaoToken 的统一 Key 把模型通道接进去最后通过 SSH 端口转发在本地浏览器里验证整条链路是通的。真正卡人的地方通常不是 OpenClaw 本身而是三件事叠在一起Node.js 版本不对导致npm install -g openclaw报错服务器没有图形界面Web UI 打不开模型 API 的 Key 和 Base URL 散落在各个工具里配一次忘一次。我试过在一台 2C4G 的 Ubuntu 22.04 上反复重装最后发现 80% 的失败都出在 Node 版本和 SSH 转发这两个点上。所以下面按「环境准备 → 装 OpenClaw → 接 TaoToken 统一 Key → SSH 验证 → 排错」的顺序走每一步都给可复制的命令和配置片段。你不需要有前端经验只要能 SSH 登录服务器、会复制粘贴命令就能跟下来。整篇的核心检索词就是 ubuntu、openclaw、部署、node.js、ssh遇到问题可以直接跳到第 5 节对照报错。2. 前置准备Node.js 22、SSH 与 TaoToken 统一 Key2.1 确认 Ubuntu 版本和基础工具先登录服务器确认系统版本和基础依赖。OpenClaw 对系统要求不苛刻Ubuntu 20.04 及以上都能跑但 Node.js 必须是 22 或更高这是唯一的硬性依赖。# 登录服务器 ssh ubuntu192.168.2.199 # 查看系统版本 lsb_release -a # 更新包索引并装基础工具 sudo apt update sudo apt install -y curl git build-essentialbuild-essential建议装上某些 npm 原生模块编译时会用到缺了会在安装阶段报gyp ERR之类的错。2.2 用 nvm 装 Node.js 22不要用apt install nodejsUbuntu 源里的版本通常太旧。用 nvm 管理最省心也方便以后切换版本。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 让 nvm 在当前终端生效 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装 Node.js 22 nvm install 22 # 设为默认版本 nvm alias default 22 # 验证 node -v npm -vnode -v输出v22.x.x就对了。如果输出的是v18或更低说明 nvm 没生效重开一个终端再试或者把上面两行 export 写进~/.bashrc。2.3 为什么用 TaoToken 统一 KeyOpenClaw 支持自定义模型通道你可以填任意兼容 OpenAI 协议的 Base URL 和 Key。问题在于如果你同时用 Cline、CC Switch、OpenClaw 好几个工具每个都单独配一遍 Key改一次要改好几处很容易漏。TaoToken 的做法是给你一个统一的 API 入口和 Key所有工具都指向同一个地址换模型、换额度只在一个地方改。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式所以 OpenClaw、Cline 这类工具都能直接接。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 Key 即可。注意Key 只生成一次页面关掉就看不到了记得先复制存好。后面所有配置都复用这一个 Key。3. 安装 OpenClaw 并写入 config.toml 配置骨架3.1 全局安装 OpenClawNode 环境就绪后安装本身只有一条命令npm install -g openclawlatest # 验证安装 openclaw --version看到版本号就说明装好了。如果卡在下载阶段多半是网络问题可以换 npm 镜像重试npm config set registry https://registry.npmmirror.com npm install -g openclawlatest3.2 初始化配置目录OpenClaw 的配置默认放在~/.openclaw/下主配置文件是config.toml。先手动建好目录避免 onboard 时权限报错mkdir -p ~/.openclaw cd ~/.openclaw3.3 可复制的 config.toml 骨架下面这份config.toml是接 TaoToken 统一 Key 的最小可用骨架直接复制到~/.openclaw/config.toml把api_key换成你自己的即可# ~/.openclaw/config.toml [server] host 127.0.0.1 port 18789 [model] # TaoToken 统一 API 入口 base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 # 按需替换成你账号下可用的模型名 model claude-sonnet-4-5 provider openai-compatible [agent] name openclaw-local max_tokens 8192 temperature 0.7 [ui] # 服务器无图形界面仅监听本地靠 SSH 转发访问 enabled true几个关键点说明一下。base_url填https://taotoken.net/api不要多加/v1OpenClaw 会自己拼接路径。provider用openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议。host保持127.0.0.1服务器上不要暴露到0.0.0.0否则同网段任何人都能访问你的网关。3.4 用 onboard 引导补齐配置如果你不想手写也可以跑官方引导命令它会交互式地问你模型地址、Key、端口等信息openclaw onboard --install-daemon引导过程中选择「自定义安装本地 LLM」或「自定义 API 通道」在 Base URL 处填https://taotoken.net/apiKey 填 TaoToken 的 Key。--install-daemon会把 OpenClaw 注册成 systemd 服务服务器重启后自动拉起省得每次手动openclaw start。引导完成后检查服务状态systemctl --user status openclaw4. SSH 端口转发与 API 调用验证4.1 为什么必须做 SSH 转发OpenClaw 的 Web UI 默认只监听127.0.0.1:18789这是服务器本机地址。你的笔记本和服务器不在同一台机器上直接访问http://192.168.2.199:18789是打不开的。解决办法是用 SSH 本地端口转发把服务器的 18789 端口映射到你笔记本的 18789 端口。在本地电脑Windows 用 CMD 或 PowerShellMac/Linux 用终端执行ssh -N -L 18789:127.0.0.1:18789 ubuntu192.168.2.199输入密码后窗口保持空白、没有报错就说明转发成功了。这个窗口不要关关了转发就断。4.2 打开 Web UI转发建立后在本地浏览器访问http://localhost:18789如果 OpenClaw 启动时输出了带 Token 的完整链接形如http://127.0.0.1:18789/#/tokenxxxx把里面的127.0.0.1换成localhost再粘贴访问http://localhost:18789/#/token你的最新TokenToken 每次openclaw start都可能变以终端最新输出为准。4.3 用 curl 验证 TaoToken 通道Web UI 能打开只说明服务活着还要确认模型通道真的通。在服务器上直接 curl 一次 TaoToken 的接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字通了}] }返回 JSON 里choices[0].message.content有内容就说明 Key 和通道都没问题。如果返回 401是 Key 错了返回 404多半是base_url多写了或漏写了/v1。4.4 在 OpenClaw 里发一条测试消息回到 Web UI新建一个会话随便问一句「你好帮我写个 Python 快排」。能正常流式返回就说明 OpenClaw → TaoToken → 模型这条链路完整跑通了。这一步是整个部署的验收点过了就基本稳了。5. 部署 OpenClaw 常见报错排查5.1 node 版本过低导致安装失败报错长这样openclaw requires Node.js 22。原因是系统里默认 node 还是旧版本。解决nvm install 22 nvm alias default 22 node -v # 确认是 v22 npm install -g openclawlatest如果node -v还是旧的检查~/.bashrc里有没有 nvm 的初始化代码没有就补上。5.2 SSH 转发后浏览器打不开先确认转发窗口没关、没报错。然后在服务器上确认服务在监听ss -tlnp | grep 18789应该看到127.0.0.1:18789。如果服务没起来执行openclaw start或systemctl --user restart openclaw。还有一种情况是本地 18789 端口被占用换个本地端口转发即可ssh -N -L 18888:127.0.0.1:18789 ubuntu192.168.2.199 # 然后访问 http://localhost:188885.3 API 返回 401 / 403401 是 Key 无效或没带。检查config.toml里api_key有没有多余空格curl 测试时Bearer后面有没有漏空格。403 通常是 Key 权限或额度问题去 TaoToken 控制台确认 Key 状态和余额。5.4 返回 404 或 model not foundbase_url写错是最常见原因。正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/v1也不要漏掉https。另外确认model字段填的模型名在你账号下确实可用不同账号开放的模型可能不一样。5.5 服务器重启后 Web UI 打不开如果 onboard 时加了--install-daemon服务会自启你只需要重新做 SSH 转发。如果没加每次重启后手动openclaw start然后复制终端输出的新 Dashboard 链接本地重新转发、替换127.0.0.1为localhost访问。6. 把 OpenClaw 接进 Cline 和 CC Switch6.1 Cline 接入示例Cline 是 VS Code 里的编码插件它支持 OpenAI 兼容接口。在 Cline 设置里选「OpenAI Compatible」填配置项值Base URLhttps://taotoken.net/apiAPI Keysk-你的TaoToken密钥Model IDclaude-sonnet-4-5这样 Cline 和 OpenClaw 共用同一个 TaoToken Key改额度、换模型只在一个地方动。6.2 CC Switch 接入示例CC Switch 用来在多个模型通道间切换。新增一个 provider类型选 OpenAI 兼容Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 Key保存后即可在 OpenClaw 和 CC Switch 之间共享同一套凭证。6.3 长期跑编码 Agent 的建议如果你打算让 OpenClaw 长期挂着跑编码任务建议用 Coding Plan 这类按周期计费的方案比按量付费更可控适合 Agent 这种高频调用的场景。配置入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Key 管理在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。6.4 验证模型是否可用想快速确认某个模型名能不能调不用改配置文件直接在模型对话页试一句就行https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。能出结果再把模型名写进config.toml省得反复重启服务。6.5 收尾把转发做成脚本每次手敲 SSH 转发命令太烦本地建个tunnel.sh#!/bin/bash ssh -N -L 18789:127.0.0.1:18789 ubuntu192.168.2.199chmod x tunnel.sh后双击或命令行运行即可。服务器那边把openclaw start也写进~/.bashrc的登录钩子或者干脆用 systemd 托管重启后基本不用管。整套跑顺之后你就有了一台本地 Ubuntu 上的 OpenClaw 网关配一个 TaoToken 统一 KeyCline、CC Switch、Web UI 全部复用后面换模型只改一行配置。
