1. Ubuntu 上 OpenClaw 部署前先把 SSH 连接失败和权限报错解决掉很多人第一次在 Ubuntu 上装 OpenClaw卡住的地方根本不是 OpenClaw 本身而是 SSH 和权限。你打开终端敲下ssh -T gitgithub.com结果返回一句Permission denied (publickey)然后npm install也跟着报错整个部署流程直接停摆。这个场景我见得太多了尤其是用云服务器或者虚拟机跑 Ubuntu 的朋友SSH 密钥没配好后面所有依赖 GitHub 的步骤都会连锁失败。先说清楚 OpenClaw 是什么。它是一个可以跑在本地或服务器上的 AI 智能体框架能对接多种模型通道支持命令行交互和后台守护进程。适合谁适合想在 Ubuntu 上拥有一个私有 AI 助手、又不想被 Token 账单追着跑的开发者。它的安装依赖 Node.js 和 npm而 npm 在拉取某些包时会走 GitHub 的 SSH 通道所以 SSH 权限是前置条件。1.1 定位 Permission denied (publickey) 的真实原因这个报错的意思是GitHub 不认识你当前这台机器上的 SSH 密钥。常见原因有三个。第一你根本没生成过密钥对。第二你生成了但公钥没上传到 GitHub。第三你上传了但 ssh-agent 没加载私钥或者加载了错误的私钥。先检查本地有没有密钥ls -al ~/.ssh如果你看到id_ed25519和id_ed25519.pub说明密钥存在。如果只有known_hosts那就要生成ssh-keygen -t ed25519 -C your_emailexample.com一路回车即可密码短语可以留空方便自动化。生成后查看公钥内容cat ~/.ssh/id_ed25519.pub输出类似ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFuMxNh7zLlAxydTuj77Lss5DKPD5UE... your_emailexample.com这一整行就是你要复制的东西。1.2 把公钥挂到 GitHub 并验证登录 GitHub进入 Settings → SSH and GPG keys → New SSH key把上面那行完整粘贴进去标题随便写比如“Ubuntu OpenClaw”。保存后回到终端测试ssh -T gitgithub.com成功的话会返回Hi yourname! Youve successfully authenticated, but GitHub does not provide shell access.看到successfully authenticated和你的用户名SSH 权限问题就彻底解决了。这一步过了后面npm install拉 GitHub 依赖才不会断。1.3 防火墙和 sshd 排查别让端口把你挡在外面如果你是从另一台机器 SSH 连到 Ubuntu 服务器连不上可能是 sshd 没跑或者防火墙拦了 22 端口。先看服务状态sudo systemctl status ssh如果显示 inactive启动并设开机自启sudo systemctl start ssh sudo systemctl enable ssh再看防火墙规则。Ubuntu 默认用 ufwsudo ufw status如果 22 端口没放行sudo ufw allow 22/tcp sudo ufw reload还要确认 sshd 监听地址没被改。检查配置文件sudo grep -E ^Port|^ListenAddress /etc/ssh/sshd_config默认是Port 22如果被改成别的端口你连接时要用ssh -p 端口号 userhost。改完配置记得sudo systemctl restart ssh1.4 文件权限报错EACCES 和 ownership 问题有时候 SSH 通了但 npm 全局安装时报EACCES: permission denied。这是因为 npm 默认往/usr/lib/node_modules写普通用户没权限。别用sudo npm install -g那样会把文件属主搞乱。正确做法是给 npm 配一个用户级全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样以后npm install -g都装到你自己家目录不需要 sudo也不会出现权限混乱。这个坑我在云服务器上踩过改完 prefix 之后所有全局命令都正常了。2. TaoToken 前置准备统一 Key 和 API 通道收口模型调用OpenClaw 支持多种模型通道你可以接本地 Ollama也可以接云端 API。但如果你想让配置更统一、后续切换模型不用改一堆环境变量建议用 TaoToken 做统一入口。TaoToken 提供兼容 OpenAI 格式的 API 通道一个 Key 就能管理多个模型的调用适合在 OpenClaw 里做收口配置。2.1 为什么要在 OpenClaw 里用统一 API 通道OpenClaw 的模型配置散落在环境变量和 onboard 向导里。如果你同时用本地 Ollama 和云端模型每次切换都要改 Base URL、API Key、Model Name 三个地方很容易漏。用 TaoToken 的好处是Base URL 固定Key 固定只需要换 Model ID 就能切换不同模型。这样你的 OpenClaw 配置文件可以保持稳定减少出错概率。另外TaoToken 的 API 通道兼容 OpenAI 的/v1/chat/completions格式OpenClaw 在选择 “OpenAI Compatible” 或 “Custom” 提供商时可以直接对接不需要额外写适配层。2.2 获取 Key 和确认 Base URL先到 TaoToken 控制台创建 API Key。访问 console 页面https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite登录后进入 API Keys 管理创建一个新 Key复制保存。这个 Key 只显示一次丢了就要重建。Base URL 用https://taotoken.net/api注意这个地址不加 UTM 参数直接作为 API 端点使用。在 OpenClaw 里填 Base URL 时通常需要带/v1后缀具体看 OpenClaw 的提供商类型。如果是 “OpenAI Compatible”一般填https://taotoken.net/api/v1。2.3 确认可用模型 IDTaoToken 支持多种模型具体 Model ID 以控制台或文档为准。你可以先通过模型对话页面测试一下 Key 是否可用https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite在对话页面选择模型发一条消息如果能正常回复说明 Key 和通道都没问题。记下你用的 Model ID后面填到 OpenClaw 配置里。2.4 环境变量模板准备OpenClaw 读取环境变量来配置模型通道。你可以先在~/.bashrc或单独的.env文件里写好模板export OPENCLAW_API_BASEhttps://taotoken.net/api/v1 export OPENCLAW_API_KEYsk-你的TaoTokenKey export OPENCLAW_MODEL你的ModelID这样在运行openclaw onboard时向导会读取这些变量作为默认值减少手动输入。注意不要把 Key 提交到 Git 仓库.env要加到.gitignore。3. 可复制配置Ollama 本地模型 OpenClaw 环境变量完整片段这一章给你可以直接复制的配置片段。先装 Ollama 跑本地模型再把 OpenClaw 的模型通道指向本地或 TaoToken最后用配置文件固定下来。3.1 安装 Ollama 并拉取本地模型Ollama 是本地模型推理工具一条命令安装curl -fsSL https://ollama.com/install.sh | sh安装完成后确认服务在跑sudo systemctl status ollama如果没启动sudo systemctl start ollama sudo systemctl enable ollama然后拉取模型。根据你的内存选# 低配 4G-8G 内存 ollama pull qwen2.5:1.5b # 中配 8G 以上 ollama pull qwen2.5:7b拉完后测试ollama run qwen2.5:7b输入一句话能回复就说明本地推理通了。输入/bye退出服务保持后台运行。3.2 OpenClaw 的 JSON 配置文件片段OpenClaw 的配置通常放在~/.openclaw/config.json或项目目录下的openclaw.config.json。下面是一个对接 Ollama 的配置片段{ modelProvider: openai-compatible, baseUrl: http://localhost:11434/v1, apiKey: local-key, modelName: qwen2.5:7b, temperature: 0.7, maxTokens: 2048 }如果你要用 TaoToken 作为云端通道把 baseUrl 和 apiKey 换掉{ modelProvider: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的TaoTokenKey, modelName: 你的ModelID, temperature: 0.7, maxTokens: 2048 }注意baseUrl里的/v1不能少Ollama 的 OpenAI 兼容端点就是http://localhost:11434/v1少了会 404。3.3 环境变量模板完整版如果你不想用 JSON 文件也可以用环境变量。把下面内容写到~/.openclaw/env# OpenClaw 模型通道配置 OPENCLAW_MODEL_PROVIDERopenai-compatible OPENCLAW_BASE_URLhttp://localhost:11434/v1 OPENCLAW_API_KEYlocal-key OPENCLAW_MODEL_NAMEqwen2.5:7b # 如果要切到 TaoToken 云端通道注释上面三行启用下面三行 # OPENCLAW_BASE_URLhttps://taotoken.net/api/v1 # OPENCLAW_API_KEYsk-你的TaoTokenKey # OPENCLAW_MODEL_NAME你的ModelID然后在~/.bashrc里加载echo source ~/.openclaw/env ~/.bashrc source ~/.bashrc这样每次开终端都会自动加载配置。3.4 安装 OpenClaw 并跳过 llama.cpp 下载在虚拟机或低配环境里OpenClaw 安装时可能会尝试下载 llama.cpp 预编译包容易卡住。用这个命令跳过NODE_LLAMA_CPP_SKIP_DOWNLOADtrue npm install -g openclawlatest --ignore-scripts安装完成后验证openclaw --version能输出版本号就说明安装成功。4. 验证请求确认本地化调用零成本跑通配置写好了接下来要验证。验证分两步先确认 Ollama 本地端点能正常响应再确认 OpenClaw 能通过配置调用模型并返回结果。4.1 用 curl 直接测 Ollama 的 OpenAI 兼容端点Ollama 启动后用 curl 测一下/v1/chat/completionscurl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-key \ -d { model: qwen2.5:7b, messages: [{role: user, content: 你好请回复一句话}], max_tokens: 50 }如果返回 JSON 里有choices字段和模型回复内容说明本地端点正常。这一步过了OpenClaw 对接就没有底层障碍。4.2 启动 OpenClaw 并测试对话前台启动方便看日志openclaw start启动后打开浏览器访问http://127.0.0.1:18789在聊天框输入“你好你是哪个版本的大模型” 如果收到回复说明 OpenClaw 已经成功调用本地 Ollama 模型。整个过程不消耗任何云端 Token完全离线零成本。4.3 验证 TaoToken 通道是否通如果你想验证 TaoToken 通道把配置切到 TaoToken 的 Base URL 和 Key重启 OpenClawopenclaw restart再发一条消息如果能回复说明云端通道也通了。你可以通过模型对话页面单独测试 Keyhttps://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite在页面里选模型发消息能回复就说明 Key 有效。4.4 后台守护进程运行生产环境建议用后台守护openclaw daemon start openclaw daemon enabledaemon enable会设置开机自启。查看状态openclaw daemon status日志一般在~/.openclaw/logs/下出问题先看日志。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一章对照真实报错给你排查路径。这些错误我在部署过程中都遇到过按顺序检查基本能解决。5.1 401 Unauthorized报错长这样Error: 401 Unauthorized原因通常是 API Key 不对或没传。检查三件事。第一Key 有没有复制完整前后有没有空格。第二Base URL 和 Key 是否匹配Ollama 本地通道 Key 随便填但必须传TaoToken 通道必须用真实 Key。第三配置文件里的apiKey字段名是否正确有些版本用api_key。用 curl 单独测 Keycurl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key如果返回模型列表说明 Key 有效。如果 401去控制台重新创建 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite5.2 local proxy failed报错Error: local proxy failed to connect这通常是 OpenClaw 尝试连接本地代理或本地模型端点失败。检查 Ollama 是否在跑curl http://localhost:11434/v1/models如果连不上重启 Ollamasudo systemctl restart ollama还要确认 Base URL 里的端口是 11434不是 11435 或其他。如果你改了 Ollama 监听端口配置也要同步改。5.3 reading choices 报错报错TypeError: Cannot read properties of undefined (reading choices)这说明 API 返回的 JSON 里没有choices字段。常见原因有两个。第一Base URL 少了/v1请求打到了错误端点。第二模型名称不对Ollama 返回了错误信息而不是正常补全结果。检查modelName是否和ollama list输出一致ollama list确保配置里的模型名完全匹配包括标签。5.4 OAuth 相关报错如果你在 onboard 向导里选了需要 OAuth 的提供商可能会遇到Error: OAuth callback failedOpenClaw 的某些云端提供商需要浏览器回调。在无头服务器或 SSH 环境下回调地址打不开。解决办法是改用 API Key 方式或者用 TaoToken 的 OpenAI Compatible 通道不需要 OAuth。在 onboard 里选 “Custom” 或 “OpenAI Compatible”手动填 Base URL 和 Key。5.5 终端渲染延迟方向键没反应这个不算报错但很多人以为是卡死。在openclaw onboard向导里按方向键光标不动。真相是按键已经生效但终端没重绘。解决办法按一下方向键然后轻轻滚一下鼠标滚轮强制终端刷新画面你会看到光标跳到了新位置。确认后再按回车。这个技巧在低配虚拟机和 SSH 远程环境里特别有用。6. 语义一致 CTA把 Key、文档和长期编码方案收口配置跑通之后你需要把 Key 管理、接入文档和长期使用方案固定下来。下面按场景分流。6.1 排障和接入API Keys 接入文档如果你还在排查 401 或通道问题先去 API Keys 页面确认 Key 状态https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档里有完整的 Base URL、请求格式和模型列表https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite文档里会说明 OpenAI Compatible 通道的完整参数对照检查你的配置文件。6.2 验证模型模型对话页面想快速验证某个 Model ID 是否可用用模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite选模型发消息能回复就说明通道和 Key 都没问题。这个页面适合在改配置前先确认模型可用性。6.3 长期编码和 AgentCoding Plan如果你打算长期用 OpenClaw 做编码助手或跑 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteCoding Plan 适合需要稳定调用、长期运行的场景。配合 OpenClaw 的 daemon 模式可以做到开机自启、后台常驻。6.4 控制台统一管理所有 Key、用量、模型配置都在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite建议把 OpenClaw 用的 Key 单独建一个方便追踪用量。如果 Key 泄露直接在这个页面吊销重建。最后说一个实用技巧OpenClaw 的配置文件改完后不用重启整个服务用openclaw reload就能热加载。但如果你改的是环境变量还是要source ~/.bashrc再重启。本地 Ollama 模型跑起来后内存占用会持续存在低配机器建议用qwen2.5:1.5b响应快、占用低。
Ubuntu 部署 OpenClaw 终极指南：从 SSH 排错到零成本本地化
1. Ubuntu 上 OpenClaw 部署前先把 SSH 连接失败和权限报错解决掉很多人第一次在 Ubuntu 上装 OpenClaw卡住的地方根本不是 OpenClaw 本身而是 SSH 和权限。你打开终端敲下ssh -T gitgithub.com结果返回一句Permission denied (publickey)然后npm install也跟着报错整个部署流程直接停摆。这个场景我见得太多了尤其是用云服务器或者虚拟机跑 Ubuntu 的朋友SSH 密钥没配好后面所有依赖 GitHub 的步骤都会连锁失败。先说清楚 OpenClaw 是什么。它是一个可以跑在本地或服务器上的 AI 智能体框架能对接多种模型通道支持命令行交互和后台守护进程。适合谁适合想在 Ubuntu 上拥有一个私有 AI 助手、又不想被 Token 账单追着跑的开发者。它的安装依赖 Node.js 和 npm而 npm 在拉取某些包时会走 GitHub 的 SSH 通道所以 SSH 权限是前置条件。1.1 定位 Permission denied (publickey) 的真实原因这个报错的意思是GitHub 不认识你当前这台机器上的 SSH 密钥。常见原因有三个。第一你根本没生成过密钥对。第二你生成了但公钥没上传到 GitHub。第三你上传了但 ssh-agent 没加载私钥或者加载了错误的私钥。先检查本地有没有密钥ls -al ~/.ssh如果你看到id_ed25519和id_ed25519.pub说明密钥存在。如果只有known_hosts那就要生成ssh-keygen -t ed25519 -C your_emailexample.com一路回车即可密码短语可以留空方便自动化。生成后查看公钥内容cat ~/.ssh/id_ed25519.pub输出类似ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFuMxNh7zLlAxydTuj77Lss5DKPD5UE... your_emailexample.com这一整行就是你要复制的东西。1.2 把公钥挂到 GitHub 并验证登录 GitHub进入 Settings → SSH and GPG keys → New SSH key把上面那行完整粘贴进去标题随便写比如“Ubuntu OpenClaw”。保存后回到终端测试ssh -T gitgithub.com成功的话会返回Hi yourname! Youve successfully authenticated, but GitHub does not provide shell access.看到successfully authenticated和你的用户名SSH 权限问题就彻底解决了。这一步过了后面npm install拉 GitHub 依赖才不会断。1.3 防火墙和 sshd 排查别让端口把你挡在外面如果你是从另一台机器 SSH 连到 Ubuntu 服务器连不上可能是 sshd 没跑或者防火墙拦了 22 端口。先看服务状态sudo systemctl status ssh如果显示 inactive启动并设开机自启sudo systemctl start ssh sudo systemctl enable ssh再看防火墙规则。Ubuntu 默认用 ufwsudo ufw status如果 22 端口没放行sudo ufw allow 22/tcp sudo ufw reload还要确认 sshd 监听地址没被改。检查配置文件sudo grep -E ^Port|^ListenAddress /etc/ssh/sshd_config默认是Port 22如果被改成别的端口你连接时要用ssh -p 端口号 userhost。改完配置记得sudo systemctl restart ssh1.4 文件权限报错EACCES 和 ownership 问题有时候 SSH 通了但 npm 全局安装时报EACCES: permission denied。这是因为 npm 默认往/usr/lib/node_modules写普通用户没权限。别用sudo npm install -g那样会把文件属主搞乱。正确做法是给 npm 配一个用户级全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc这样以后npm install -g都装到你自己家目录不需要 sudo也不会出现权限混乱。这个坑我在云服务器上踩过改完 prefix 之后所有全局命令都正常了。2. TaoToken 前置准备统一 Key 和 API 通道收口模型调用OpenClaw 支持多种模型通道你可以接本地 Ollama也可以接云端 API。但如果你想让配置更统一、后续切换模型不用改一堆环境变量建议用 TaoToken 做统一入口。TaoToken 提供兼容 OpenAI 格式的 API 通道一个 Key 就能管理多个模型的调用适合在 OpenClaw 里做收口配置。2.1 为什么要在 OpenClaw 里用统一 API 通道OpenClaw 的模型配置散落在环境变量和 onboard 向导里。如果你同时用本地 Ollama 和云端模型每次切换都要改 Base URL、API Key、Model Name 三个地方很容易漏。用 TaoToken 的好处是Base URL 固定Key 固定只需要换 Model ID 就能切换不同模型。这样你的 OpenClaw 配置文件可以保持稳定减少出错概率。另外TaoToken 的 API 通道兼容 OpenAI 的/v1/chat/completions格式OpenClaw 在选择 “OpenAI Compatible” 或 “Custom” 提供商时可以直接对接不需要额外写适配层。2.2 获取 Key 和确认 Base URL先到 TaoToken 控制台创建 API Key。访问 console 页面https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite登录后进入 API Keys 管理创建一个新 Key复制保存。这个 Key 只显示一次丢了就要重建。Base URL 用https://taotoken.net/api注意这个地址不加 UTM 参数直接作为 API 端点使用。在 OpenClaw 里填 Base URL 时通常需要带/v1后缀具体看 OpenClaw 的提供商类型。如果是 “OpenAI Compatible”一般填https://taotoken.net/api/v1。2.3 确认可用模型 IDTaoToken 支持多种模型具体 Model ID 以控制台或文档为准。你可以先通过模型对话页面测试一下 Key 是否可用https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite在对话页面选择模型发一条消息如果能正常回复说明 Key 和通道都没问题。记下你用的 Model ID后面填到 OpenClaw 配置里。2.4 环境变量模板准备OpenClaw 读取环境变量来配置模型通道。你可以先在~/.bashrc或单独的.env文件里写好模板export OPENCLAW_API_BASEhttps://taotoken.net/api/v1 export OPENCLAW_API_KEYsk-你的TaoTokenKey export OPENCLAW_MODEL你的ModelID这样在运行openclaw onboard时向导会读取这些变量作为默认值减少手动输入。注意不要把 Key 提交到 Git 仓库.env要加到.gitignore。3. 可复制配置Ollama 本地模型 OpenClaw 环境变量完整片段这一章给你可以直接复制的配置片段。先装 Ollama 跑本地模型再把 OpenClaw 的模型通道指向本地或 TaoToken最后用配置文件固定下来。3.1 安装 Ollama 并拉取本地模型Ollama 是本地模型推理工具一条命令安装curl -fsSL https://ollama.com/install.sh | sh安装完成后确认服务在跑sudo systemctl status ollama如果没启动sudo systemctl start ollama sudo systemctl enable ollama然后拉取模型。根据你的内存选# 低配 4G-8G 内存 ollama pull qwen2.5:1.5b # 中配 8G 以上 ollama pull qwen2.5:7b拉完后测试ollama run qwen2.5:7b输入一句话能回复就说明本地推理通了。输入/bye退出服务保持后台运行。3.2 OpenClaw 的 JSON 配置文件片段OpenClaw 的配置通常放在~/.openclaw/config.json或项目目录下的openclaw.config.json。下面是一个对接 Ollama 的配置片段{ modelProvider: openai-compatible, baseUrl: http://localhost:11434/v1, apiKey: local-key, modelName: qwen2.5:7b, temperature: 0.7, maxTokens: 2048 }如果你要用 TaoToken 作为云端通道把 baseUrl 和 apiKey 换掉{ modelProvider: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的TaoTokenKey, modelName: 你的ModelID, temperature: 0.7, maxTokens: 2048 }注意baseUrl里的/v1不能少Ollama 的 OpenAI 兼容端点就是http://localhost:11434/v1少了会 404。3.3 环境变量模板完整版如果你不想用 JSON 文件也可以用环境变量。把下面内容写到~/.openclaw/env# OpenClaw 模型通道配置 OPENCLAW_MODEL_PROVIDERopenai-compatible OPENCLAW_BASE_URLhttp://localhost:11434/v1 OPENCLAW_API_KEYlocal-key OPENCLAW_MODEL_NAMEqwen2.5:7b # 如果要切到 TaoToken 云端通道注释上面三行启用下面三行 # OPENCLAW_BASE_URLhttps://taotoken.net/api/v1 # OPENCLAW_API_KEYsk-你的TaoTokenKey # OPENCLAW_MODEL_NAME你的ModelID然后在~/.bashrc里加载echo source ~/.openclaw/env ~/.bashrc source ~/.bashrc这样每次开终端都会自动加载配置。3.4 安装 OpenClaw 并跳过 llama.cpp 下载在虚拟机或低配环境里OpenClaw 安装时可能会尝试下载 llama.cpp 预编译包容易卡住。用这个命令跳过NODE_LLAMA_CPP_SKIP_DOWNLOADtrue npm install -g openclawlatest --ignore-scripts安装完成后验证openclaw --version能输出版本号就说明安装成功。4. 验证请求确认本地化调用零成本跑通配置写好了接下来要验证。验证分两步先确认 Ollama 本地端点能正常响应再确认 OpenClaw 能通过配置调用模型并返回结果。4.1 用 curl 直接测 Ollama 的 OpenAI 兼容端点Ollama 启动后用 curl 测一下/v1/chat/completionscurl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer local-key \ -d { model: qwen2.5:7b, messages: [{role: user, content: 你好请回复一句话}], max_tokens: 50 }如果返回 JSON 里有choices字段和模型回复内容说明本地端点正常。这一步过了OpenClaw 对接就没有底层障碍。4.2 启动 OpenClaw 并测试对话前台启动方便看日志openclaw start启动后打开浏览器访问http://127.0.0.1:18789在聊天框输入“你好你是哪个版本的大模型” 如果收到回复说明 OpenClaw 已经成功调用本地 Ollama 模型。整个过程不消耗任何云端 Token完全离线零成本。4.3 验证 TaoToken 通道是否通如果你想验证 TaoToken 通道把配置切到 TaoToken 的 Base URL 和 Key重启 OpenClawopenclaw restart再发一条消息如果能回复说明云端通道也通了。你可以通过模型对话页面单独测试 Keyhttps://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite在页面里选模型发消息能回复就说明 Key 有效。4.4 后台守护进程运行生产环境建议用后台守护openclaw daemon start openclaw daemon enabledaemon enable会设置开机自启。查看状态openclaw daemon status日志一般在~/.openclaw/logs/下出问题先看日志。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一章对照真实报错给你排查路径。这些错误我在部署过程中都遇到过按顺序检查基本能解决。5.1 401 Unauthorized报错长这样Error: 401 Unauthorized原因通常是 API Key 不对或没传。检查三件事。第一Key 有没有复制完整前后有没有空格。第二Base URL 和 Key 是否匹配Ollama 本地通道 Key 随便填但必须传TaoToken 通道必须用真实 Key。第三配置文件里的apiKey字段名是否正确有些版本用api_key。用 curl 单独测 Keycurl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key如果返回模型列表说明 Key 有效。如果 401去控制台重新创建 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite5.2 local proxy failed报错Error: local proxy failed to connect这通常是 OpenClaw 尝试连接本地代理或本地模型端点失败。检查 Ollama 是否在跑curl http://localhost:11434/v1/models如果连不上重启 Ollamasudo systemctl restart ollama还要确认 Base URL 里的端口是 11434不是 11435 或其他。如果你改了 Ollama 监听端口配置也要同步改。5.3 reading choices 报错报错TypeError: Cannot read properties of undefined (reading choices)这说明 API 返回的 JSON 里没有choices字段。常见原因有两个。第一Base URL 少了/v1请求打到了错误端点。第二模型名称不对Ollama 返回了错误信息而不是正常补全结果。检查modelName是否和ollama list输出一致ollama list确保配置里的模型名完全匹配包括标签。5.4 OAuth 相关报错如果你在 onboard 向导里选了需要 OAuth 的提供商可能会遇到Error: OAuth callback failedOpenClaw 的某些云端提供商需要浏览器回调。在无头服务器或 SSH 环境下回调地址打不开。解决办法是改用 API Key 方式或者用 TaoToken 的 OpenAI Compatible 通道不需要 OAuth。在 onboard 里选 “Custom” 或 “OpenAI Compatible”手动填 Base URL 和 Key。5.5 终端渲染延迟方向键没反应这个不算报错但很多人以为是卡死。在openclaw onboard向导里按方向键光标不动。真相是按键已经生效但终端没重绘。解决办法按一下方向键然后轻轻滚一下鼠标滚轮强制终端刷新画面你会看到光标跳到了新位置。确认后再按回车。这个技巧在低配虚拟机和 SSH 远程环境里特别有用。6. 语义一致 CTA把 Key、文档和长期编码方案收口配置跑通之后你需要把 Key 管理、接入文档和长期使用方案固定下来。下面按场景分流。6.1 排障和接入API Keys 接入文档如果你还在排查 401 或通道问题先去 API Keys 页面确认 Key 状态https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档里有完整的 Base URL、请求格式和模型列表https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite文档里会说明 OpenAI Compatible 通道的完整参数对照检查你的配置文件。6.2 验证模型模型对话页面想快速验证某个 Model ID 是否可用用模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite选模型发消息能回复就说明通道和 Key 都没问题。这个页面适合在改配置前先确认模型可用性。6.3 长期编码和 AgentCoding Plan如果你打算长期用 OpenClaw 做编码助手或跑 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteCoding Plan 适合需要稳定调用、长期运行的场景。配合 OpenClaw 的 daemon 模式可以做到开机自启、后台常驻。6.4 控制台统一管理所有 Key、用量、模型配置都在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite建议把 OpenClaw 用的 Key 单独建一个方便追踪用量。如果 Key 泄露直接在这个页面吊销重建。最后说一个实用技巧OpenClaw 的配置文件改完后不用重启整个服务用openclaw reload就能热加载。但如果你改的是环境变量还是要source ~/.bashrc再重启。本地 Ollama 模型跑起来后内存占用会持续存在低配机器建议用qwen2.5:1.5b响应快、占用低。
