1. Ubuntu22.04 部署 Openclaw 前先理清这套链路到底在装什么Openclaw 是一个跑在本地或云主机上的 AI Agent 运行框架你可以把它理解成一个「常驻后台的智能体网关」它负责接收你的指令、调度模型、管理会话与工具调用最后把结果通过 TUI 或 Dashboard 反馈给你。适合谁用适合手里有一台 Ubuntu22.04 机器、想自己掌控模型调用链路、又不想被各家 SDK 反复折腾的开发者。它本身不绑定某一家模型服务模型通道可以自由替换这也是后面我会用 TaoToken 统一 Key 来接管模型调用的原因。很多人第一次在 Ubuntu22.04 上装 Openclaw卡点往往不在 Openclaw 本身而在前置环境apt 源太慢、Node.js 版本不对、curl 拉不到安装脚本、装完发现 gateway 起不来。这篇教程按「apt 依赖 → Node.js 环境 → Openclaw 安装 → 模型通道接入 → 启动验证 → 报错排查」的顺序走一遍每一步都给可复制命令和预期结果目标是一次跑通。需要提前说明Openclaw 的安装脚本会从官方地址拉取如果你的机器网络到该地址不稳定命令会卡住或超时这属于网络连通性问题不是 Openclaw 的 bug。遇到这种情况先确认机器能正常访问外网再重试。整篇教程假设你用的是 Ubuntu22.04Jammy有 sudo 权限能 SSH 登录。我试过在一台 2C4G 的云主机上从零走完整套流程全程大约 15 分钟其中 apt 更新和 Node.js 安装占了大头。下面按步骤拆开讲你可以边看边敲。2. apt 依赖与 Node.js 环境准备Ubuntu22.04 安装 Openclaw 的底座这一节解决的是「装 Openclaw 之前系统里必须有什么」。Openclaw 的安装脚本依赖 curl、git运行依赖 Node.js。Ubuntu22.04 自带的 Node.js 版本偏旧直接用 apt 装很可能版本不够所以推荐用 nvm 管理 Node.js 版本这样后面切换版本也方便。先更新软件源并升级已有包sudo apt update sudo apt upgrade -y如果 apt 更新特别慢可以换成国内镜像源。注意这一步会覆盖/etc/apt/sources.list操作前建议先备份sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo tee /etc/apt/sources.list EOF deb http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse deb http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse EOF sudo apt update接着安装基础工具sudo apt install -y curl git build-essentialbuild-essential不是每个场景都必需但部分 Node.js 原生模块编译时会用到提前装上省得后面报gyp ERR之类的错。然后装 nvm 并加载curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc如果source ~/.bashrc后nvm命令仍提示找不到检查~/.bashrc末尾是否被写入了 nvm 的初始化片段没有的话手动补上export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh装 Node.js 22Openclaw 对较新 Node.js 支持更好nvm install 22 nvm use 22 nvm alias default 22验证node -v npm -v预期输出类似v22.x.x和10.x.x。到这里底座就搭好了。这一步的关键是 Node.js 版本别太低否则 Openclaw 安装或启动阶段可能报语法或 API 不兼容的错。3. Openclaw 安装与 TaoToken 模型通道配置可复制的 settings 片段环境就绪后开始装 Openclaw。官方提供了一键安装脚本curl -fsSL https://openclaw.ai/install.sh | bash装完验证openclaw --version openclaw --help能打印版本号和帮助信息说明二进制已就位。接下来是配置环节也是整篇最关键的一步——把模型调用通道接到 TaoToken 上这样你只需要维护一套 Key 和 Base URL就能统一调用不同模型。先跑初始化向导openclaw onboard --install-daemon向导里会依次问你几个问题是否知晓风险选 yes、安装模式选 QuickStart、模型服务商。这里不要选具体厂商而是走自定义/兼容 OpenAI 协议的通道把 Base URL 指向 TaoToken 的 API 地址Key 填你在 TaoToken 控制台生成的 Key。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制台的 API Keys 页面创建。模型 ID 按你实际要用的填比如claude-sonnet-4-5或gpt-4o这类具体以控制台模型列表为准。Openclaw 的配置文件通常落在~/.openclaw/目录下模型通道部分可以写成类似这样的 JSON 片段路径和字段名以你本地实际生成的为准下面给出结构参考{ models: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-sonnet-4-5 } }如果你用的是 TOML 风格的配置等价写法[models] provider openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoTokenKey model claude-sonnet-4-5三件套记牢Base URL 填https://taotoken.net/apiKey 填 TaoToken 控制台生成的Model ID 填你要用的模型名。这三者缺一不可任何一个填错都会在调用时报错。向导后续会问 channel、skills、hooks初次部署全部选 No 或跳过先把主链路跑通这些扩展后面再按需加。最后选择 TUI 进入聊天界面输入Hello测试能收到模型回复就说明通道打通了。4. 启动 gateway 并验证请求确认 Openclaw 服务真的在跑配置完成后Openclaw 的核心服务是 gateway它负责常驻后台处理请求。查看状态openclaw gateway status成功标志是输出里有高亮的active (running)。如果显示inactive手动启动openclaw gateway start再查一次状态确认。接着获取 Dashboard 地址openclaw dashboard它会打印一个带端口和 token 的 URL默认端口常见是 18789。如果要从外部浏览器访问需要放行端口sudo ufw allow 18789然后在浏览器输入http://你的服务器IP:18789带上 dashboard 输出的 token 即可进入管理界面。验证模型调用是否真的走通除了 TUI 里发消息还可以直接对 gateway 发一次请求。假设 gateway 监听本地 18789可以用 curl 测curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 你好回复一句话}] }如果返回结构里有choices字段且包含模型回复内容说明从 Openclaw 到 TaoToken 再到模型的整条链路是通的。这一步能过基本就宣告部署成功。实测下来最容易出问题的不是 Openclaw 本身而是 Key 或 Base URL 填错导致 401或者模型 ID 写错导致找不到模型。下面一节专门列常见报错。5. 常见报错排查401、local proxy failed、reading choices 怎么解部署过程中遇到的报错大多集中在模型调用环节这里按真实报错对照排查。401 Unauthorized最常见。原因通常是 Key 填错、Key 前后有空格、或者 Key 已失效。检查配置文件里的apiKey字段确认是 TaoToken 控制台里有效的那把 Key。注意别把 Base URL 和 Key 搞混Base URL 是https://taotoken.net/apiKey 是sk-开头的那串。local proxy failed / connection refused说明 Openclaw 尝试连本地代理或本地服务失败。先确认 gateway 是否在跑openclaw gateway status再确认配置文件里的 Base URL 没有指向一个不存在的本地地址。如果你之前配过本地代理把它清掉直接指向 TaoToken 的 API 地址。reading choices 报错如 cannot read property choices of undefined这通常意味着返回体不是预期的 OpenAI 兼容结构可能是 Base URL 路径不对或者模型 ID 不被识别。检查 Base URL 是否带了多余的路径后缀正确写法就是https://taotoken.net/api不要自己拼/v1之类。模型 ID 也要和控制台里列出的完全一致。OAuth 相关报错如果你在向导里误选了需要 OAuth 的登录方式会卡在授权环节。回到配置里改成 API Key 方式用 TaoToken 的 Key 直接鉴权不走 OAuth。Node.js 版本相关报错如果启动时报语法错误或optional chaining之类不支持多半是 Node.js 版本太低。用node -v确认低于 18 就nvm install 22 nvm use 22切上去。端口占用openclaw gateway start报端口被占用sudo lsof -i:18789查占用进程或者改 gateway 监听端口。排查思路统一先看 gateway 状态再看配置文件三件套Base URL、Key、Model ID最后看网络连通性。大部分问题都出在前两步。6. 把模型通道固定下来TaoToken 统一 Key 的长期用法一次跑通之后建议把模型通道固定成 TaoToken 统一 Key 的方式而不是每次换模型都改一堆配置。这样做的好处是你只需要在 TaoToken 控制台管理 Key 和额度Openclaw 侧只认一个 Base URL 和一个 Key换模型只改 Model ID 一个字段。如果你后面要长期跑编码类 Agent 任务可以了解下 Coding Plan它更适合高频、长时间的模型调用场景。需要看模型实际对话效果可以直接进模型对话页面试。Key 的创建和管理在控制台的 API Keys 页面接入细节可以对照接入文档。把这几件事做完你的 Ubuntu22.04 Openclaw 环境就算稳定落地了。后面加 channel、skills、hooks 都是在这个底座上叠加主链路不会再动。
1. Ubuntu22.04 部署 Openclaw 前先理清这套链路到底在装什么Openclaw 是一个跑在本地或云主机上的 AI Agent 运行框架你可以把它理解成一个「常驻后台的智能体网关」它负责接收你的指令、调度模型、管理会话与工具调用最后把结果通过 TUI 或 Dashboard 反馈给你。适合谁用适合手里有一台 Ubuntu22.04 机器、想自己掌控模型调用链路、又不想被各家 SDK 反复折腾的开发者。它本身不绑定某一家模型服务模型通道可以自由替换这也是后面我会用 TaoToken 统一 Key 来接管模型调用的原因。很多人第一次在 Ubuntu22.04 上装 Openclaw卡点往往不在 Openclaw 本身而在前置环境apt 源太慢、Node.js 版本不对、curl 拉不到安装脚本、装完发现 gateway 起不来。这篇教程按「apt 依赖 → Node.js 环境 → Openclaw 安装 → 模型通道接入 → 启动验证 → 报错排查」的顺序走一遍每一步都给可复制命令和预期结果目标是一次跑通。需要提前说明Openclaw 的安装脚本会从官方地址拉取如果你的机器网络到该地址不稳定命令会卡住或超时这属于网络连通性问题不是 Openclaw 的 bug。遇到这种情况先确认机器能正常访问外网再重试。整篇教程假设你用的是 Ubuntu22.04Jammy有 sudo 权限能 SSH 登录。我试过在一台 2C4G 的云主机上从零走完整套流程全程大约 15 分钟其中 apt 更新和 Node.js 安装占了大头。下面按步骤拆开讲你可以边看边敲。2. apt 依赖与 Node.js 环境准备Ubuntu22.04 安装 Openclaw 的底座这一节解决的是「装 Openclaw 之前系统里必须有什么」。Openclaw 的安装脚本依赖 curl、git运行依赖 Node.js。Ubuntu22.04 自带的 Node.js 版本偏旧直接用 apt 装很可能版本不够所以推荐用 nvm 管理 Node.js 版本这样后面切换版本也方便。先更新软件源并升级已有包sudo apt update sudo apt upgrade -y如果 apt 更新特别慢可以换成国内镜像源。注意这一步会覆盖/etc/apt/sources.list操作前建议先备份sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo tee /etc/apt/sources.list EOF deb http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse deb http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse EOF sudo apt update接着安装基础工具sudo apt install -y curl git build-essentialbuild-essential不是每个场景都必需但部分 Node.js 原生模块编译时会用到提前装上省得后面报gyp ERR之类的错。然后装 nvm 并加载curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc如果source ~/.bashrc后nvm命令仍提示找不到检查~/.bashrc末尾是否被写入了 nvm 的初始化片段没有的话手动补上export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh装 Node.js 22Openclaw 对较新 Node.js 支持更好nvm install 22 nvm use 22 nvm alias default 22验证node -v npm -v预期输出类似v22.x.x和10.x.x。到这里底座就搭好了。这一步的关键是 Node.js 版本别太低否则 Openclaw 安装或启动阶段可能报语法或 API 不兼容的错。3. Openclaw 安装与 TaoToken 模型通道配置可复制的 settings 片段环境就绪后开始装 Openclaw。官方提供了一键安装脚本curl -fsSL https://openclaw.ai/install.sh | bash装完验证openclaw --version openclaw --help能打印版本号和帮助信息说明二进制已就位。接下来是配置环节也是整篇最关键的一步——把模型调用通道接到 TaoToken 上这样你只需要维护一套 Key 和 Base URL就能统一调用不同模型。先跑初始化向导openclaw onboard --install-daemon向导里会依次问你几个问题是否知晓风险选 yes、安装模式选 QuickStart、模型服务商。这里不要选具体厂商而是走自定义/兼容 OpenAI 协议的通道把 Base URL 指向 TaoToken 的 API 地址Key 填你在 TaoToken 控制台生成的 Key。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制台的 API Keys 页面创建。模型 ID 按你实际要用的填比如claude-sonnet-4-5或gpt-4o这类具体以控制台模型列表为准。Openclaw 的配置文件通常落在~/.openclaw/目录下模型通道部分可以写成类似这样的 JSON 片段路径和字段名以你本地实际生成的为准下面给出结构参考{ models: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-sonnet-4-5 } }如果你用的是 TOML 风格的配置等价写法[models] provider openai-compatible baseUrl https://taotoken.net/api apiKey sk-你的TaoTokenKey model claude-sonnet-4-5三件套记牢Base URL 填https://taotoken.net/apiKey 填 TaoToken 控制台生成的Model ID 填你要用的模型名。这三者缺一不可任何一个填错都会在调用时报错。向导后续会问 channel、skills、hooks初次部署全部选 No 或跳过先把主链路跑通这些扩展后面再按需加。最后选择 TUI 进入聊天界面输入Hello测试能收到模型回复就说明通道打通了。4. 启动 gateway 并验证请求确认 Openclaw 服务真的在跑配置完成后Openclaw 的核心服务是 gateway它负责常驻后台处理请求。查看状态openclaw gateway status成功标志是输出里有高亮的active (running)。如果显示inactive手动启动openclaw gateway start再查一次状态确认。接着获取 Dashboard 地址openclaw dashboard它会打印一个带端口和 token 的 URL默认端口常见是 18789。如果要从外部浏览器访问需要放行端口sudo ufw allow 18789然后在浏览器输入http://你的服务器IP:18789带上 dashboard 输出的 token 即可进入管理界面。验证模型调用是否真的走通除了 TUI 里发消息还可以直接对 gateway 发一次请求。假设 gateway 监听本地 18789可以用 curl 测curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 你好回复一句话}] }如果返回结构里有choices字段且包含模型回复内容说明从 Openclaw 到 TaoToken 再到模型的整条链路是通的。这一步能过基本就宣告部署成功。实测下来最容易出问题的不是 Openclaw 本身而是 Key 或 Base URL 填错导致 401或者模型 ID 写错导致找不到模型。下面一节专门列常见报错。5. 常见报错排查401、local proxy failed、reading choices 怎么解部署过程中遇到的报错大多集中在模型调用环节这里按真实报错对照排查。401 Unauthorized最常见。原因通常是 Key 填错、Key 前后有空格、或者 Key 已失效。检查配置文件里的apiKey字段确认是 TaoToken 控制台里有效的那把 Key。注意别把 Base URL 和 Key 搞混Base URL 是https://taotoken.net/apiKey 是sk-开头的那串。local proxy failed / connection refused说明 Openclaw 尝试连本地代理或本地服务失败。先确认 gateway 是否在跑openclaw gateway status再确认配置文件里的 Base URL 没有指向一个不存在的本地地址。如果你之前配过本地代理把它清掉直接指向 TaoToken 的 API 地址。reading choices 报错如 cannot read property choices of undefined这通常意味着返回体不是预期的 OpenAI 兼容结构可能是 Base URL 路径不对或者模型 ID 不被识别。检查 Base URL 是否带了多余的路径后缀正确写法就是https://taotoken.net/api不要自己拼/v1之类。模型 ID 也要和控制台里列出的完全一致。OAuth 相关报错如果你在向导里误选了需要 OAuth 的登录方式会卡在授权环节。回到配置里改成 API Key 方式用 TaoToken 的 Key 直接鉴权不走 OAuth。Node.js 版本相关报错如果启动时报语法错误或optional chaining之类不支持多半是 Node.js 版本太低。用node -v确认低于 18 就nvm install 22 nvm use 22切上去。端口占用openclaw gateway start报端口被占用sudo lsof -i:18789查占用进程或者改 gateway 监听端口。排查思路统一先看 gateway 状态再看配置文件三件套Base URL、Key、Model ID最后看网络连通性。大部分问题都出在前两步。6. 把模型通道固定下来TaoToken 统一 Key 的长期用法一次跑通之后建议把模型通道固定成 TaoToken 统一 Key 的方式而不是每次换模型都改一堆配置。这样做的好处是你只需要在 TaoToken 控制台管理 Key 和额度Openclaw 侧只认一个 Base URL 和一个 Key换模型只改 Model ID 一个字段。如果你后面要长期跑编码类 Agent 任务可以了解下 Coding Plan它更适合高频、长时间的模型调用场景。需要看模型实际对话效果可以直接进模型对话页面试。Key 的创建和管理在控制台的 API Keys 页面接入细节可以对照接入文档。把这几件事做完你的 Ubuntu22.04 Openclaw 环境就算稳定落地了。后面加 channel、skills、hooks 都是在这个底座上叠加主链路不会再动。
