在 Ubuntu 22.04 用 npm 部署 OpenClaw 并接入本地 Ollama：TaoToken 统一 Key 配置实战

1. Ubuntu 22.04 上 OpenClaw 对接本地 Ollama 的真实场景OpenClaw 是一个跑在终端里的 AI Agent 框架能读文件、跑命令、调模型适合把它当成一个住在服务器里的助手。Ollama 则是本地跑大模型最省心的方案一条ollama run就能拉起 qwen、llama 系列。把这两个东西拼在一起你就能在 Ubuntu 22.04 上拥有一套完全本地推理、不依赖外部网络的 Agent 环境。但真正动手时卡点往往不在安装而在模型通道怎么配。OpenClaw 默认走的是云端模型供应商配置项散落在~/.openclaw/openclaw.json里字段名和 Ollama 的 OpenAI 兼容接口对不上很多人装完openclaw onboard之后发现模型列表是空的或者启动日志里一直报 provider 连接失败。这篇就聚焦 Ubuntu 22.04 npm 全局安装 OpenClaw 本地 Ollama 这条链路把 TaoToken 作为统一 Key/API 通道接进来给出可直接复制的openclaw.json骨架、base_url 与 api_key 的填写位置以及用 curl 验证 Ollama 连通性、用启动日志确认对接成功的完整步骤。适合已经在 Ubuntu 上跑着 Ollama、想再叠一层 Agent 能力的运维和开发同学。2. 前置准备Node 环境、Ollama 与 TaoToken 通道2.1 确认系统与 Node 版本Ubuntu 22.04.5 LTS 是这次的目标系统。OpenClaw 对 Node 版本有要求建议 Node 22.x LTS 起步npm 10.x。先更新系统并装好基础工具sudo apt update sudo apt install -y curl git接着添加 NodeSource 仓库并安装 Node.jsnpm 会随包一起装上curl -fsSL https://deb.nodesource.com/setup_22.x | bash - sudo apt install -y nodejs node -v npm -v正常输出类似v22.22.0和10.9.4。如果node -v报 command not found多半是仓库没加成功重跑第二行即可。2.2 本地 Ollama 服务确认Ollama 默认监听127.0.0.1:11434提供 OpenAI 兼容的/v1接口。先确认它在跑systemctl status ollama curl http://127.0.0.1:11434/api/tags第二条命令会返回已拉取的模型列表。如果服务没起sudo systemctl start ollama拉起来。注意如果你的 Ollama 跑在另一台机器上比如172.16.113.20要把OLLAMA_HOST设成0.0.0.0:11434并放行端口否则 OpenClaw 连不上。2.3 TaoToken 统一 Key 的作用TaoToken 在这里扮演的是统一 API 通道的角色。它提供一个稳定的 base_url 和 api_key让 OpenClaw 不用为每个模型供应商单独维护一套凭证。你可以在控制台生成 Key然后在 OpenClaw 的 provider 配置里把 base_url 指向 TaoToken 的 API 地址api_key 填生成的 Key。这样即使后面切换模型也只需要改模型 id不用动通道配置。需要先拿到 Key 的话去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite3. 安装 OpenClaw 并写入 config 骨架3.1 npm 全局安装npm install -g openclawlatest --force openclaw --version--force是为了避免旧版本残留导致的依赖冲突。装完后执行初始化openclaw onboard --install-daemon这一步会生成~/.openclaw/目录和默认配置同时注册一个 user 级别的 systemd 服务openclaw-gateway。初始化过程中如果提示选择模型供应商先随便选一个跳过后面我们直接改配置文件。3.2 openclaw.json 的 provider 骨架配置文件路径是~/.openclaw/openclaw.json。核心是models.providers这一段每个 provider 是一个独立通道。下面给出对接本地 Ollama 的骨架注意baseUrl和apiKey两个字段{ models: { mode: merge, providers: { local-ollama: { baseUrl: http://127.0.0.1:11434/v1, apiKey: ollama, api: ollama, models: [ { id: qwen2.5-coder:0.5b-instruct-q4_K_M, name: qwen2.5-coder-0.5b, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 32000, maxTokens: 4096 }, { id: llama3.2, name: llama3.2, reasoning: false, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 16000, maxTokens: 4096 } ] } } } }几个字段说明baseUrl必须带/v1后缀这是 OpenAI 兼容接口的约定apiKey对本地 Ollama 来说随便填Ollama 不校验但字段不能缺否则 OpenClaw 会报 provider 配置不完整api字段填ollama告诉 OpenClaw 用哪套适配器。3.3 接入 TaoToken 统一通道如果你希望走 TaoToken 的统一通道而不是直连本地把 provider 换成下面这样baseUrl指向 TaoToken 的 API 地址apiKey填控制台生成的 Key{ models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, api: openai, models: [ { id: claude-sonnet-4-5, name: claude-sonnet-4-5, reasoning: true, input: [text], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 } ] } } } }注意api字段这里填openai因为 TaoToken 走的是 OpenAI 兼容协议。本地 Ollama 和 TaoToken 两个 provider 可以同时存在mode: merge会把它们合并到同一个模型列表里你在 Agent 里按provider/model-id的格式引用即可。3.4 agents 默认模型绑定光有 provider 还不够得告诉 OpenClaw 默认用哪个模型。在agents.defaults里指定{ agents: { defaults: { model: { primary: local-ollama/qwen2.5-coder:0.5b-instruct-q4_K_M }, models: { local-ollama/qwen2.5-coder:0.5b-instruct-q4_K_M: { alias: qwen-coder }, local-ollama/llama3.2: { alias: llama3.2 } }, workspace: /root/.openclaw/workspace, compaction: { mode: safeguard }, maxConcurrent: 4, subagents: { maxConcurrent: 8 } } } }primary的格式是provider名/模型id必须和上面 providers 里定义的完全一致大小写敏感。alias是给你在对话里用的短名方便切换。4. 验证请求与启动日志确认4.1 curl 验证 Ollama 连通性改配置之前先用 curl 确认 Ollama 的 OpenAI 兼容接口是通的curl http://127.0.0.1:11434/v1/models正常会返回一个 JSONdata数组里列出所有模型 id。如果返回Connection refused说明 Ollama 没监听在这个地址如果返回 404检查是不是漏了/v1。再测一次对话接口curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-coder:0.5b-instruct-q4_K_M, messages: [{role: user, content: say hi}] }能拿到choices[0].message.content就说明模型侧没问题。4.2 重启 gateway 并看日志配置改完后重启服务systemctl --user restart openclaw-gateway systemctl --user status openclaw-gatewaystatus显示active (running)是第一步。接着看日志确认 provider 加载成功tail -f /tmp/openclaw/openclaw-$(date %Y-%m-%d).log日志里会打印已注册的 provider 和模型列表。看到类似registered provider: local-ollama和loaded model: qwen2.5-coder:0.5b-instruct-q4_K_M就说明对接成功。如果日志里出现provider config invalid或model not found回到第 3 节检查字段拼写。4.3 发起一次真实请求日志确认后直接在终端跑一次对话openclaw chat --model qwen-coder 列出当前目录下的文件如果 Agent 返回了文件列表说明整条链路——OpenClaw → provider → Ollama → 模型——全部打通。这一步能跑通后面接 TaoToken 通道也是同样的验证逻辑把--model换成taotoken/claude-sonnet-4-5即可。5. 本篇常见错排查5.1 provider 配置不生效最常见的原因是 JSON 语法错误。openclaw.json对格式很敏感多一个逗号、少一个引号都会导致整个 provider 被跳过。用python3 -m json.tool ~/.openclaw/openclaw.json校验一下能正常输出格式化 JSON 就说明语法没问题。另一个坑是mode字段。如果写成replace而不是merge你自定义的 provider 会覆盖掉默认配置导致内置模型全部消失。除非你确定只要自己的 provider否则保持merge。5.2 模型 id 对不上Ollama 的模型 id 是带 tag 的比如qwen2.5-coder:0.5b-instruct-q4_K_M少写一个冒号或 tag 就找不到。用ollama list看准确 id然后原样复制到配置里。OpenClaw 不会帮你做模糊匹配id 必须完全一致。5.3 服务重启后配置丢失systemctl --user restart只重启进程不会重读配置文件——实际上它会重读但如果你改的是/root/.openclaw/而服务是以另一个用户跑的就会读错路径。确认systemctl --user status里的Loaded行指向的配置文件路径和你编辑的是同一个。5.4 TaoToken 通道返回 401如果走 TaoToken 通道时报 401先检查 api_key 有没有带sk-前缀以及有没有多余空格。Key 是在控制台生成的复制时容易带上换行。另外确认baseUrl是https://taotoken.net/api不要自己加/v1TaoToken 的路径规则和本地 Ollama 不同。6. 后续怎么用模型对话、Coding Plan 与接入文档链路打通之后日常使用有几个方向。想快速验证模型效果、对比不同模型的回答质量可以直接用模型对话页面不用每次都在终端敲命令https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你打算把 OpenClaw 长期挂在服务器上跑编码任务、定时运维脚本或者接多个 Agent 协作Coding Plan 会更划算额度按编码场景优化过https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite需要新建或轮换 Key 的时候去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite配置字段记不清、想查完整的 provider 参数说明接入文档里有逐字段解释https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后提一个我踩过的坑OpenClaw 的 Agent 默认不会直接在你机器上执行 shell 命令它只做建议和文件读写。想让它在服务器上跑命令得在 workspace 里配置工具权限或者用 subagent 模式显式授权。这不是 bug是设计上的安全边界配之前先想清楚要给多大权限。