Linux 下 OpenClaw 安装全记录：从零到一的保姆级图文教程（TaoToken 配置篇）

1. 为什么 Linux 装 OpenClaw 总在最后一步卡住OpenClaw 是一个开源的多模型智能体运行框架能在本地起一个 Gateway 服务再通过 Dashboard 面板把模型、技能、通道串起来用。它适合想在 Linux 服务器或开发机上跑 Agent、又不想被单一厂商绑死的开发者。很多人装它的时候前面 Node.js、git、npm 一路顺风顺水结果卡在「模型配置」这一环要么是各家平台的 Key 散落在不同配置文件里要么是 baseUrl 写错导致请求 401要么是改完 config.toml 忘了重启 Gateway对着聊天框发呆。我自己在 Ubuntu 上反复装过几轮踩过的坑基本都集中在「安装完成之后」这一段。安装本身其实就三条命令真正费时间的是把模型通道接对、把配置写对、把服务验证通。这篇就把 Linux 下从零安装 OpenClaw 的完整流程走一遍重点补上安装后如何用 TaoToken 统一 Key 和 API 通道完成配置文件对接交付可直接复制的 config.toml 骨架和 settings.json 示例再给出验证调用是否生效的具体命令和排查动作。你跟着走一遍应该能一次跑通从安装到接入的全链路。需要提前说明的是本文所有操作都在 Linux 终端里完成涉及的命令、路径、配置项都以实际可执行为准。如果你用的是 Ubuntu 22.04 或 Debian 12基本可以原样照抄其他发行版把 apt 换成对应包管理器即可。2. 前置准备Node.js、git 与 TaoToken 通道2.1 确认 Node.js 版本OpenClaw 对 Node.js 版本有要求低于 v22 会在安装依赖时报错。先查一下node -v如果输出 v22 及以上直接跳到 2.2。如果提示 command not found 或版本偏低用 nvm 装一个curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash . $HOME/.nvm/nvm.sh nvm install 24 node -v看到 v24 就说明 Node.js 就绪。nvm 的好处是版本隔离后面如果 OpenClaw 升级要求更高版本直接nvm install切换即可不会污染系统自带的 Node。2.2 安装 gitsudo apt update sudo apt install -y git git --versiongit 主要用于 OpenClaw 拉取技能仓库和部分依赖。版本号能正常输出就行不用纠结具体数字。2.3 安装 OpenClaw先把 npm 源切到国内镜像避免安装时长时间卡住npm config set registry https://registry.npmmirror.com npm install -g openclawlatest出现added xxx packages in就说明装完了。如果中途 timeout可以补一条 git 的镜像重定向再重试git config --global url.https://hub.yzuu.cf/.insteadOf https://github.com/ npm install -g openclawlatest装完后重开一个终端让环境变量生效然后验证openclaw --version openclaw --help两条命令都能正常输出安装这一步就算过了。2.4 为什么用 TaoToken 统一通道OpenClaw 默认支持多家模型 provider每家都要单独填 baseUrl 和 apiKey。如果你同时用两三个平台配置文件里就会散落好几组 Key换机器、换项目时特别容易漏。TaoToken 提供的是一个统一的 API 通道把模型调用收敛到一个 baseUrl 和一把 Key 上OpenClaw 里只需要配一个 provider 就能切换不同模型。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的 completions 协议所以 OpenClaw 里api字段填openai-completions就能对接。Key 在控制台的 API Keys 页面生成生成后复制出来后面写进配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册和文档都在里面。注意Key 只在生成时完整显示一次复制后先存到本地密码管理器或临时文件别直接贴在聊天记录里。3. 可复制配置config.toml 骨架与 settings.json 示例3.1 初始化 OpenClaw 配置安装完成后先跑初始化生成默认配置目录openclaw setup openclaw onboardonboard 过程中会问一堆选项按下面这样选能最快进入可配置状态配置项建议选择personal-by-default 确认YesOnboarding modeQuickStartConfig handlingUse existing valuesModel/auth providerSkip for nowFilter models by providerAll providersDefault modelKeep currentSelect channelSkip for nowSearch providerSkip for nowConfigure skills nowNoEnable hooks按空格选中后回车hatch your botDo this later走完之后配置目录一般在~/.openclaw/下里面会有config.toml和settings.json两个关键文件。下面给出可直接复制的骨架。3.2 config.toml 骨架# ~/.openclaw/config.toml [gateway] host 127.0.0.1 port 18789 [models] mode merge [models.providers.taotoken] baseUrl https://taotoken.net/api apiKey sk-你的TaoTokenKey api openai-completions [[models.providers.taotoken.models]] id claude-sonnet-4-5 name Claude Sonnet 4.5 api openai-completions reasoning false input [text] contextWindow 200000 maxTokens 8192 [agents.defaults.model] primary taotoken/claude-sonnet-4-5 [agents.defaults.models.claude-sonnet-4-5] alias sonnet这里baseUrl用的是 TaoToken 的 API 地址apiKey换成你在控制台生成的那把。models数组里可以放多个模型 idOpenClaw 启动时会按primary指定的那个作为默认模型。alias是给模型起个短名字聊天时用sonnet就能指代。3.3 settings.json 示例settings.json主要管运行时行为和 config.toml 配合使用{ gateway: { autoStart: false, logLevel: info }, agents: { defaults: { maxConcurrent: 4, subagents: { maxConcurrent: 8 } } }, ui: { theme: dark, language: zh-CN } }autoStart设为 false 是为了手动控制 Gateway 启停方便排查问题。maxConcurrent控制并发请求数机器配置一般的话保持 4 就行调太高反而容易触发限流。3.4 启动 Gateway 与 Dashboard配置写完后先起核心服务。这个窗口会一直占用别关openclaw gateway看到Gateway listening on ws://127.0.0.1:18789就说明起来了。然后新开一个终端起 Dashboardopenclaw dashboard终端会输出一个带 token 的 URL复制到浏览器打开就能看到可视化管理界面。左侧菜单里Config Authentication可以核对刚才写的 provider 是否被正确加载。4. 验证请求确认 OpenClaw 调用真的生效4.1 用 CLI 直接发一条测试请求Dashboard 起来之后最直接的验证方式是用 OpenClaw 自带的 CLI 发一条消息openclaw chat --model sonnet 用一句话说明你现在用的是哪个模型如果配置正确终端会流式输出模型回复。如果报 401说明 apiKey 不对如果报 connection refused说明 Gateway 没起来或端口被占。4.2 用 curl 验证 TaoToken 通道本身有时候问题不在 OpenClaw而在通道本身。可以绕过 OpenClaw 直接打 TaoToken 的接口curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}], max_tokens: 16 }返回里有choices字段就说明通道通。这一步能帮你快速区分是 OpenClaw 配置问题还是 Key/通道问题。4.3 在 Dashboard 里做端到端验证打开 Dashboard 的 Chat 页面选刚才配的sonnet模型输入一句话。能正常流式返回就说明从 OpenClaw 到 TaoToken 再到模型的整条链路都通了。这时候你可以再切一个模型 id 试试确认多模型切换也正常。5. 本篇常见错排查5.1 Gateway failed to start: another gateway instance is already listening这个报错说明 18789 端口已经被一个 Gateway 占用了。先查一下lsof -i :18789如果有输出说明之前起的 Gateway 还在跑。要么直接复用那个实例新开终端跑openclaw dashboard就行要么先杀掉再重启kill -9 PID openclaw gateway5.2 配置改了但模型没变OpenClaw 的 config.toml 是启动时加载的改完必须重启 Gateway 才生效。很多人改完配置直接去 Chat 页面测发现还是旧模型就是漏了重启这一步。顺序是改配置 → CtrlC 停掉 Gateway → 重新openclaw gateway→ 再开 Dashboard。5.3 401 Unauthorized 或 invalid api key先确认 config.toml 里apiKey没有多余空格或换行。然后确认baseUrl结尾没有多写/v1——TaoToken 的地址是https://taotoken.net/apiOpenClaw 会自己拼/v1/chat/completions如果你手动加了/v1就会变成/api/v1/v1/...直接 404 或 401。用 4.2 的 curl 命令单独验证 Key 是否有效能快速定位。5.4 error: externally-managed-environment这个报错一般出现在用 pip 装依赖的时候是系统 Python 的环境保护机制。解决办法是加--break-system-packages参数或者用 venv 隔离python3 -m venv ~/.openclaw-venv source ~/.openclaw-venv/bin/activate pip install 需要的包5.5 模型列表里看不到配的模型检查 config.toml 里[[models.providers.taotoken.models]]的层级有没有写错。TOML 里数组表用双中括号如果写成单中括号解析会失败但 OpenClaw 不一定报错只是模型不加载。改完重启 Gateway再在 Dashboard 的 Config 页面确认 provider 下能看到模型条目。6. 后续使用与接入入口日常重启机器后只需要两步先openclaw gateway起核心服务再新开终端openclaw dashboard拿 URL 进面板。配置不用重写Key 也不用重新填。如果你后面要长期跑编码任务或 Agent 工作流建议把模型通道固定成 TaoToken 的统一入口这样换模型只改 config.toml 里的primary字段不用动 Key。需要生成或轮换 Key 的话去控制台的 API Keys 页面操作https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入细节和字段说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先在网页里试模型效果可以直接用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期编码和 Agent 场景可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个实用习惯每次改完 config.toml先用 4.2 的 curl 确认通道通再重启 Gateway最后在 Dashboard 里发一条消息。这三步走完基本不会再出现「配置看着对但就是不通」的情况。