1. openclaw 本地部署为什么卡在模型接入这一步
openclaw 本地部署这件事，真正让人卡住的往往不是安装本身，而是模型接入环节。openclaw 是一个可以跑在自己机器上的智能体网关，它能接飞书、接工具、接各种模型，但默认配置里指向的是云端模型端点。很多开发者 Node.js 和 Git 早就装好了，npm install -g openclaw@latest也跑通了，openclaw gateway start看着也正常，结果一发起对话就报错——要么是local proxy failed，要么是reading choices返回空，要么干脆 401。
问题出在哪？openclaw 的模型调用链是「网关 → provider → 模型端点」三层结构。provider 配置在/root/.openclaw/openclaw.json（Linux）或%USERPROFILE%\.openclaw\openclaw.json（Windows）里，默认走的是 qwen-portal 这类云端 OAuth 端点。你想用 Ollama 跑本地模型，就得把 provider 换成 Ollama 的 OpenAI 兼容端点，同时把 agent 的 primary model 指过去。
这篇面向的是已经有 Node.js 和 Git 环境、想用 Ollama 跑本地模型、并且希望后续能把请求端点统一改到 TaoToken 管理 Key 的开发者。我会给出可复制的环境变量和配置文件片段，演示一次从启动到调用成功的完整验证动作，再把常见报错逐个拆开。Ollama 本地模型调用链这个长尾场景，核心就三件事：Ollama 服务能通、openclaw 配置指向对、agent 默认模型选对。
先说清楚整体链路。Ollama 默认监听http://localhost:11434，它的 OpenAI 兼容端点是/v1，所以 baseUrl 要写http://localhost:11434/v1。openclaw 的 provider 配置里api字段填openai-completions，表示用 OpenAI 的 completions 协议去请求。apiKey 随便填一个非空字符串就行，Ollama 本地不校验，但 openclaw 要求这个字段存在。模型 id 必须和ollama list里显示的完全一致，比如qwen3:1.7b，少一个字符都会导致模型找不到。
我试过在 4GB 内存的机器上直接跑qwen3:1.7b，启动时 openclaw 会加载配置、初始化 provider、建立到 Ollama 的连接。如果 Ollama 没启动，openclaw 不会立刻报错，而是在第一次请求时才抛连接拒绝。所以验证顺序很重要：先确认 Ollama 活着，再确认 openclaw 配置对，最后发一次真实请求。
2. TaoToken 前置准备与 Ollama 环境打通
在动 openclaw 配置之前，先把两个前置条件确认掉：Ollama 服务可用，以及 TaoToken 的 Key 拿到手。这两件事看起来独立，实际上决定了你后面配置能不能一次跑通。
Ollama 这边，安装完之后用ollama serve启动服务，默认监听 11434。你可以用curl http://localhost:11434/v1/models验证，返回 JSON 列表就说明 OpenAI 兼容层是通的。然后拉一个模型，ollama pull qwen3:1.7b，拉完用ollama list确认模型 id。注意模型 id 的大小写和冒号，qwen3:1.7b和Qwen3:1.7B在 Ollama 里是两个不同的东西，配置里必须写ollama list输出的那个。
TaoToken 这边，它的作用是统一管理 Key。你本地 Ollama 不需要 Key，但如果你后面想切换到云端模型、或者想让 openclaw 同时接本地和远程模型，把请求端点统一到 TaoToken 会省很多事。TaoToken 的 API 地址是https://taotoken.net/api，兼容 OpenAI 协议，所以 openclaw 里只要把 baseUrl 改成这个、apiKey 填你在控制台生成的 Key、模型 id 填对应模型名，就能走通。
拿 Key 的路径：打开 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，登录后在控制台创建 API Key。这个 Key 只在创建时显示一次，复制保存好。如果你还没决定用哪些模型，可以先在模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 试一下，确认模型能正常返回再写进配置。
环境变量方面，openclaw 支持通过NODE_OPTIONS调整内存。初始化时如果报内存不足，执行：
export NODE_OPTIONS="--max-old-space-size=4096"Windows PowerShell 里对应：
$env:NODE_OPTIONS="--max-old-space-size=4096"这个设置对 Ollama 本地模型尤其重要，因为 openclaw 加载配置和建立连接时会占用较多内存。4GB 以下的机器建议把模型换成更小的，比如qwen3:1.7b已经算小，再小可以试qwen2.5:0.5b。
Git 配置这块，如果你从 GitHub 拉依赖遇到 SSH 问题，可以全局把 SSH 替换成 HTTPS：
git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"这样npm install -g openclaw@latest拉依赖时就不会卡在 SSH 密钥上。Windows 上装完 Git 后先配用户名和邮箱：
git config --global user.name "yourname" git config --global user.email "you@example.com"这两步不做，后面 openclaw 初始化时如果涉及 Git 操作会报错。
3. 可复制的 openclaw.json 配置片段
openclaw 的配置文件在 Linux 上是/root/.openclaw/openclaw.json，Windows 上是%USERPROFILE%\.openclaw\openclaw.json。这个文件是 JSON 格式，结构分几块：meta、wizard、auth、models、agents、channels、gateway、plugins。模型接入只关心models.providers和agents.defaults.model两块。
先给一个最小可用的 Ollama provider 片段，你可以直接贴进models.providers里：
{ "ollama": { "baseUrl": "http://localhost:11434/v1", "apiKey": "ollama", "api": "openai-completions", "models": [ { "id": "qwen3:1.7b", "name": "Qwen3 1.7B", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 32000, "maxTokens": 4096 } ] } }这里每个字段都有用。baseUrl指向 Ollama 的 OpenAI 兼容端点，注意结尾的/v1不能少。apiKey填ollama只是占位，Ollama 不校验但 openclaw 要求非空。api必须是openai-completions，这是协议标识。models数组里id是模型标识，必须和ollama list一致；contextWindow和maxTokens按模型实际能力填，qwen3:1.7b给 32000 和 4096 是安全的。
然后改agents.defaults.model.primary，把它指向 Ollama：
{ "agents": { "defaults": { "model": { "primary": "ollama/qwen3:1.7b" }, "models": { "ollama/qwen3:1.7b": { "alias": "ollama" } }, "workspace": "/root/.openclaw/workspace", "compaction": { "mode": "safeguard" }, "maxConcurrent": 4, "subagents": { "maxConcurrent": 8 } } } }primary的格式是provider/modelId，所以是ollama/qwen3:1.7b。models里的 alias 是给你自己看的短名，调用时可以用ollama代替完整路径。workspace是 agent 的工作目录，Linux 下默认/root/.openclaw/workspace，Windows 下换成你的用户目录。
如果你想把请求端点统一改到 TaoToken，把 provider 换成这样：
{ "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "你的TaoToken Key", "api": "openai-completions", "models": [ { "id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 200000, "maxTokens": 8192 } ] } }然后把primary改成taotoken/claude-sonnet-4-5。这样本地 Ollama 和远程 TaoToken 可以共存，切换只改primary一行。TaoToken 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的模型 id 列表和参数说明。
完整配置文件的结构是这样的：meta记录版本和时间戳，wizard记录初始化信息，auth管 OAuth profile，models.providers是核心，agents.defaults决定默认行为，channels管飞书等通道，gateway管端口和认证，plugins管插件。你不需要一次写全，openclaw 启动时会合并默认值，只写你要改的部分就行。
改完配置后，用openclaw gateway restart重启网关，或者openclaw gateway stop再start。重启后配置才生效。
4. 验证请求与成功结果
配置写完，接下来是验证。验证分三步：Ollama 服务通、openclaw 网关通、端到端调用通。
第一步，确认 Ollama 活着：
curl http://localhost:11434/v1/models返回类似：
{ "object": "list", "data": [ { "id": "qwen3:1.7b", "object": "model", "created": 1700000000, "owned_by": "library" } ] }看到data数组里有你的模型 id，说明 Ollama 的 OpenAI 兼容层正常。
第二步，确认 openclaw 网关状态：
openclaw gateway status正常输出会显示running和端口18789。如果显示stopped，执行openclaw gateway start。启动后可以用openclaw tool list看内置工具是否加载，工具列表能出来说明网关初始化完成。
第三步，发一次真实请求。openclaw 的调用方式是通过 dashboard 或命令行。先打开控制台：
openclaw dashboard它会输出一个本地地址，通常是http://127.0.0.1:18789。如果你在远程服务器上部署，需要做端口转发：
ssh -N -L 18789:127.0.0.1:18789 root@192.168.44.128这条命令把远程服务器的 18789 端口映射到本地 18789，输入密码后保持终端开着。然后本地浏览器访问http://127.0.0.1:18789，用 gateway 配置里的 token 登录。token 在openclaw.json的gateway.auth.token字段。
登录后在对话框里发一句「你好，用一句话介绍你自己」。如果配置正确，你会看到模型返回内容。返回内容来自qwen3:1.7b，说明本地模型调用链通了。
如果你想用命令行验证，可以走 openclaw 的 API：
curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H "Authorization: Bearer 你的gateway token" \ -H "Content-Type: application/json" \ -d '{ "model": "ollama/qwen3:1.7b", "messages": [{"role": "user", "content": "你好"}] }'返回 JSON 里有choices[0].message.content就说明成功。如果返回 401，检查 token；如果返回local proxy failed，检查 Ollama 是否启动；如果choices为空，检查模型 id 是否匹配。
成功的结果长这样：
{ "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1700000000, "model": "qwen3:1.7b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "你好，我是 Qwen3 1.7B，一个轻量级语言模型。" }, "finish_reason": "stop" } ] }看到这个，本地模型调用链就算打通了。整个过程从启动到调用成功，核心就是配置指向对、服务活着、模型 id 匹配。
5. 本篇常见报错排查
配置过程中最容易撞上的报错有四个，逐个说。
401 Unauthorized。这个报错说明认证没过。如果你走的是 Ollama，apiKey 填ollama就行，Ollama 不校验。但如果你走 TaoToken，apiKey 必须是你控制台生成的真实 Key。检查openclaw.json里models.providers.taotoken.apiKey字段，确认没有多余空格。另外 gateway 的 token 和 provider 的 apiKey 是两回事，dashboard 登录用 gateway token，模型请求用 provider apiKey，别搞混。
local proxy failed。这个报错通常出现在 openclaw 尝试连接 provider 时。最常见原因是 Ollama 没启动。执行ollama serve或systemctl start ollama，然后用curl http://localhost:11434/v1/models确认。如果 Ollama 在另一台机器上，baseUrl 要改成那台机器的 IP，比如http://192.168.1.100:11434/v1，同时确认防火墙放行 11434。还有一种情况是 baseUrl 结尾少了/v1，openclaw 会请求http://localhost:11434/chat/completions，Ollama 不认这个路径。
reading choices 返回空或报错。这个报错说明请求发出去了，但响应结构不对。检查模型 id 是否和ollama list一致。qwen3:1.7b和qwen3:1.7B在 Ollama 里是两个模型，配置里写错就找不到。另外检查api字段是否是openai-completions，写成openai或completions都会导致解析失败。如果模型 id 对、api 对，还是空，看一下 Ollama 的日志ollama logs，可能是模型加载失败。
OAuth 相关报错。如果你之前配过 qwen-portal 的 OAuth，auth.profiles里会有qwen-portal:default。这个 profile 和 Ollama 无关，但 openclaw 启动时会尝试加载。如果 OAuth token 过期，可能报OAuth token expired。解决办法是在auth.profiles里把 qwen-portal 的 profile 删掉，或者执行openclaw channels logout登出。如果你只用 Ollama，auth块可以整个删掉。
还有一个容易忽略的：Windows 上配置文件路径是%USERPROFILE%\.openclaw\openclaw.json，不是/root/.openclaw/。如果你在 Windows 上改了 Linux 路径的配置，openclaw 读不到。确认路径用echo $env:USERPROFILE。
端口冲突也常见。18789 被占用时openclaw gateway start会失败。用netstat -ano | findstr 18789（Windows）或lsof -i:18789（Linux）查占用，改gateway.port换一个端口。
6. 统一管理 Key 与后续接入建议
本地 Ollama 跑通之后，下一步通常是把请求端点统一到 TaoToken。原因很简单：本地模型适合轻量任务，但复杂任务还是需要更强的云端模型。如果每个 provider 都单独配 Key，管理起来很乱。TaoToken 的 OpenAI 兼容端点可以让你用一个 Key 访问多个模型，openclaw 里只需要改 baseUrl 和 apiKey。
具体做法是在models.providers里加一个taotokenprovider，baseUrl 填https://taotoken.net/api，apiKey 填你的 Key，models 数组里列出你要用的模型 id。然后把agents.defaults.model.primary改成taotoken/模型id。这样本地 Ollama 和 TaoToken 可以共存，切换只改一行。
如果你要长期跑编码任务或 Agent，建议看一下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它针对长时间编码场景做了优化。如果你用的是 Claude Code 这类工具，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Base URL、Key、Model ID 三件套的完整说明。
openclaw 的配置文件里还有几个字段值得注意。agents.defaults.compaction.mode设成safeguard可以在上下文过长时自动压缩，避免请求失败。maxConcurrent和subagents.maxConcurrent控制并发，本地模型建议调低，比如 2 和 4，避免内存爆掉。gateway.bind设成loopback只允许本机访问，如果你要远程访问，改成0.0.0.0但一定要配好 token。
最后说一个实际经验：Ollama 的模型加载是懒加载的，第一次请求会慢，因为要把模型读进内存。qwen3:1.7b第一次请求可能要等几秒，之后就快了。如果你在 dashboard 里发消息后没立刻看到回复，等几秒再看，不要急着重启。如果超过 30 秒还没响应，再查 Ollama 日志。
配置改完后记得openclaw gateway restart，不然改的配置不生效。验证的时候先用curl直接打 Ollama，确认服务层没问题，再走 openclaw，这样排障能少走弯路。
