1. 为什么我建议用 Docker 装 OpenClaw而不是直接跑安装包OpenClaw 是一个本地优先的 Agent 运行框架能接大模型、跑 Skill、操作文件适合想在自己机器上折腾自动化的人。但它的依赖链比较长Node 运行时、系统库、端口、配置文件路径任何一环出问题都会卡在启动阶段。我见过太多人卡在npm install报错或者启动后浏览器打不开页面最后怀疑是软件本身的问题其实是环境没对齐。这篇教程聚焦一件事用 Docker 把 OpenClaw 从零跑到可用并且把模型通道统一接到 TaoToken 的 Key 上。为什么强调 Docker因为容器把运行时和系统隔离开你不需要在本机装 Node 18、不需要担心 glibc 版本、不需要处理 Python 依赖冲突。镜像拉下来配置挂载进去服务就能起。对新手来说这是失败率最低的路径。适合谁看手上有一台能跑 Docker 的机器Windows 用 WSL2、macOS 用 Docker Desktop、Linux 原生想本地部署 OpenClaw并且希望模型调用走一个统一入口而不是到处配 Key 的人。整篇按“环境检查 → 拉镜像 → 写配置 → 启动 → curl 验证 → 排错”的顺序走每一步都给可复制的命令。先说清楚一个概念OpenClaw 本身不绑定某一家模型。它通过配置里的 Base URL 和 API Key 去调用兼容 OpenAI 协议的服务。TaoToken 提供的就是这样一个统一入口你拿到一个 Key改一下 Base URL就能在 OpenClaw 里切换不同模型不用每个模型单独申请账号。这个设计对本地 Agent 特别友好因为 Agent 经常需要在不同任务里换模型。环境准备这块我不跳过但也不啰嗦。你只需要确认三件事Docker 能跑、内存够、端口没被占。下面逐条给命令。Docker 检查docker --version docker compose version两条都有输出才算 OK。如果docker compose报 command not found说明你装的是老版本 Docker需要单独装 compose 插件或者用docker-compose带横杠命令。Windows 用户如果是在 PowerShell 里跑确认 Docker Desktop 已经启动托盘图标是绿的。内存和磁盘# Linux free -h df -h # macOS 用活动监视器看内存磁盘用 df -hOpenClaw 跑起来本身不重但拉镜像和装 Skill 的时候会占空间。建议留 2GB 以上磁盘内存 4GB 起步8GB 更稳。如果你机器上同时开着 Chrome 几十个标签页启动前关掉一些不然容器可能因为内存不足被 OOM kill。端口检查OpenClaw 默认用 3456# Linux / macOS lsof -i :3456 # Windows PowerShell netstat -ano | findstr 3456有输出说明被占了。要么杀掉占用进程要么等会儿在 compose 里把宿主机端口改成别的比如3457:3456。这个改动只影响你从浏览器访问的端口容器内部还是 3456。网络这块你只要能正常访问 Docker Hub 拉镜像就行。如果拉取慢可以配国内镜像加速器这个在 Docker Desktop 的设置里有入口Linux 改/etc/docker/daemon.json。配完记得重启 Docker 服务。这三项检查做完环境基本就没坑了。接下来进入正题。2. 用 TaoToken 统一 Key 接入前的准备工作在写 docker-compose 之前先把 Key 拿到手。这一步放在前面是因为配置文件和 Key 是绑定的你先有 Key后面写配置就能一次写对不用回头改。TaoToken 的定位是一个模型调用的统一入口。你注册之后在控制台创建一个 API Key这个 Key 可以用于它支持的各种模型。对 OpenClaw 来说你只需要关心三样东西Base URL、API Key、Model ID。这三样凑齐OpenClaw 就能把请求发出去。访问入口我放在这里你按需点官网了解整体能力https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content直接进控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Key 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建 Key 的流程不复杂登录后进控制台找到 API Keys点创建复制出来存好。Key 一般只完整显示一次关掉页面就看不到了所以复制完先贴到记事本或者密码管理器里。如果你不小心弄丢了删掉重建一个就行不影响已有配置只要把新 Key 替换进去。这里要提醒一个常见误区很多人以为 Base URL 填官网地址就行。不是的。OpenClaw 调用模型走的是 API 通道Base URL 要填 API 域名也就是https://taotoken.net/api。这个地址不加任何查询参数直接作为 OpenAI 兼容接口的根路径。你在配置里会看到类似base_url或者OPENAI_BASE_URL的字段填的就是它。Model ID 这块TaoToken 支持多个模型你在控制台或者文档里能看到可用的模型列表。写配置的时候填你实际要用的那个比如某个 Claude 系列或者 GPT 系列的标识。注意 Model ID 是区分大小写的复制的时候别手抖。如果你后面打算长期跑编码类 Agent可以了解一下 Coding Plan它在调用额度和模型选择上有针对性的安排Coding Plan 说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里配置字段有疑问可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentKey 拿到之后先别急着写进 OpenClaw。我建议你单独用 curl 测一下这个 Key 能不能通这样能把“Key 问题”和“OpenClaw 配置问题”分开。测试命令在第四节会给你先记着这个思路先验证通道再验证应用。还有一点OpenClaw 的配置文件里可能会同时出现多个模型的配置项。如果你只想用一个模型其他留空或者删掉都行但别填错字段名。下一节我会给一份完整的 compose 和配置文件你照着改 Key 和 Model ID 就能用。3. 可复制的 docker-compose 与 OpenClaw 配置文件这一节是整篇的核心给你两份可以直接复制的配置一份是docker-compose.yml一份是 OpenClaw 的环境变量文件。路径和字段名我都按实际能跑通的写法给你改三个地方Key、Model ID、可能的端口就能启动。先建目录。我习惯把配置放在用户目录下的.openclaw里这样挂载路径清晰mkdir -p ~/.openclaw cd ~/.openclaw然后创建docker-compose.ymlservices: openclaw: image: nicepkg/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 3456:3456 volumes: - ~/.openclaw:/root/.openclaw environment: - OPENAI_API_KEY${OPENAI_API_KEY} - OPENAI_BASE_URL${OPENAI_BASE_URL} - OPENAI_MODEL${OPENAI_MODEL} env_file: - .env这里有几个点要说明。ports左边是宿主机端口右边是容器端口。如果你本机 3456 被占了把左边改成 3457 就行访问的时候用http://localhost:3457。volumes把宿主机的~/.openclaw挂到容器里的/root/.openclaw这样配置和生成的数据都持久化在本地容器删了重建也不丢。environment和env_file两种方式我都写了实际用env_file就够了environment那几行是给你看清楚变量名用的。真正生效的是.env文件。接着创建.env文件注意文件名就是.env前面有个点没有后缀OPENAI_API_KEY你的TaoTokenKey OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODEL你的ModelID把你的TaoTokenKey换成第二节拿到的 Key你的ModelID换成你要用的模型标识。OPENAI_BASE_URL保持https://taotoken.net/api不变注意结尾没有斜杠。Windows 用户特别注意在资源管理器里创建.env文件时系统可能自动加.txt后缀变成.env.txt。你要先在“查看”里勾上“文件扩展名”确认文件名真的是.env。这个坑我踩过配置死活不生效最后发现是文件名多了后缀。如果你用的是源码方式而不是 Docker配置文件路径是~/.openclaw/.env字段名一样。源码方式还需要 Node 18启动命令是npm run start但我不推荐新手走这条路依赖问题太多。再给一个settings.json形式的配置片段有些 OpenClaw 版本或者 Skill 会读这个文件。放在~/.openclaw/settings.json{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你的TaoTokenKey, modelId: 你的ModelID }, server: { port: 3456, host: 0.0.0.0 } }这份 JSON 和.env不冲突.env是给容器环境变量用的settings.json是给应用内部读的。你两个都放上OpenClaw 会优先读其中一个具体看版本。实测下来两个都配一致最省心。配置写完检查一下目录结构ls -la ~/.openclaw应该看到docker-compose.yml、.env、settings.json三个文件。确认.env里没有多余空格Key 没有换行。启动命令cd ~/.openclaw docker compose up -d-d是后台运行。第一次会拉镜像取决于网速等一两分钟。拉完启动用docker compose logs -f看日志看到类似server listening on 3456就说明起来了。按 CtrlC 退出日志查看容器还在后台跑。如果你改了宿主机端口比如改成 3457那docker-compose.yml里写3457:3456访问地址相应变成http://localhost:3457。容器内部的settings.json里port还是 3456别改错。4. 启动验证curl 请求打通 API 通道服务起来之后先别急着开浏览器。我建议分两步验证先用 curl 直接测 TaoToken 的 API 通道再测 OpenClaw 的本地服务。这样出问题的时候能快速定位是通道问题还是应用问题。第一步测 TaoToken 通道。这条命令直接打 API不经过 OpenClawcurl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer 你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: 你的ModelID, messages: [ {role: user, content: 你好回复一个字} ] }正常返回是一段 JSON里面有choices数组message.content就是模型的回复。如果返回401说明 Key 不对或者没带上返回404检查 Base URL 是不是写成了https://taotoken.net/api别多加路径返回model not found说明 Model ID 写错了回控制台核对。这一步通了说明你的 Key、Base URL、Model ID 三件套是对的。接下来测 OpenClaw 本地服务。第二步测本地端口curl -s http://localhost:3456/health如果 OpenClaw 有健康检查接口会返回{status:ok}之类。没有这个接口的话直接访问首页curl -s -o /dev/null -w %{http_code} http://localhost:3456返回200说明 Web 服务正常。返回000说明端口没通回去看容器日志。第三步在 OpenClaw 里发一条消息。打开浏览器访问http://localhost:3456在对话框输入“你好”发送。如果收到回复整条链路就通了浏览器 → OpenClaw → TaoToken API → 模型 → 返回。如果浏览器里发消息没反应但 curl 测 API 是通的那问题在 OpenClaw 的配置读取上。检查.env有没有被正确加载docker compose exec openclaw env | grep OPENAI应该看到你配的三个变量。如果看不到说明.env没被读到检查文件名和路径。如果看到了但值不对检查有没有多余空格或者引号。再给一个验证模型列表的方法有些兼容接口支持/modelscurl -s https://taotoken.net/api/models \ -H Authorization: Bearer 你的TaoTokenKey返回的列表里能看到可用模型你对照着确认 Model ID 拼写。这个接口不一定所有版本都支持返回 404 就跳过不影响主流程。验证通过之后你可以做一件有意思的事在 OpenClaw 里建一个简单的 Skill让它调用模型做文件操作或者搜索。这一步不是必须的但能帮你确认 Agent 的完整能力。比如让它读一个本地文件然后总结看它能不能正确调用工具。到这里从零到可用的搭建就完成了。下面一节专门讲报错排查因为实际部署中总会遇到几个典型问题。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。我把部署 OpenClaw 接 TaoToken 过程中最常遇到的四类错误列出来每个都给现象、原因、解决步骤。你遇到问题先在这里对号入座别乱试。报错一401 Unauthorized现象curl 测 API 返回{error:{message:invalid api key}}或者 OpenClaw 日志里出现 401。原因基本就三个Key 复制错了、Key 没带上、Key 被删了。排查步骤先确认.env里OPENAI_API_KEY的值和你控制台里的一致注意前后有没有空格。然后确认请求头格式是Authorization: Bearer 你的KeyBearer 和 Key 之间有一个空格。如果都对回控制台看这个 Key 是不是被禁用了或者额度用完了。实在不行就删掉重建一个替换配置后重启容器docker compose down docker compose up -d报错二local proxy failed / connection refused现象OpenClaw 启动时报local proxy failed或者日志里出现connection refused连不上某个地址。这个错误通常和网络配置有关。OpenClaw 内部可能起了一个本地代理进程如果它尝试连接的地址不对就会报这个。检查你的OPENAI_BASE_URL是不是写成了http://localhost或者127.0.0.1。在容器里localhost指的是容器自己不是宿主机。你要连外部 API必须用完整域名https://taotoken.net/api。还有一种情况是容器 DNS 解析失败。测试一下docker compose exec openclaw ping -c 2 taotoken.netping 不通说明容器网络有问题。重启 Docker 服务或者检查 Docker 的网络模式。如果你用了自定义网络确认容器能访问外网。报错三reading choices / cannot read property choices of undefined现象OpenClaw 收到响应后解析失败报reading choices或者undefined is not an object。这个错误说明请求发出去了但返回的结构不是预期的 OpenAI 格式。可能的原因Base URL 写错了打到了某个返回 HTML 的地址或者 Model ID 不对服务返回了错误信息而不是正常的 choices 数组。排查先用第四节的 curl 命令直接测看返回的 JSON 结构里有没有choices。如果没有看返回的完整内容是什么。常见的是返回了{error:...}那就要按错误信息处理。如果 curl 返回正常但 OpenClaw 报这个错检查 OpenClaw 的版本是不是太旧老版本对响应格式的兼容性差升级镜像docker compose pull docker compose up -d报错四OAuth / authentication failed现象日志里出现 OAuth 相关字样或者提示认证失败。OpenClaw 某些版本可能默认走 OAuth 流程而不是 API Key。如果你用的是 API Key 模式需要在配置里明确指定认证方式。检查settings.json里有没有auth相关字段把它设成apiKey或者bearer。有些版本的环境变量名不是OPENAI_API_KEY而是OPENCLAW_API_KEY这个要看具体版本文档。如果你在配置里看到auth.json或者类似的认证文件确认里面的字段和你的 Key 对应。Codex 系的工具常用auth.json格式大致是{ type: api_key, api_key: 你的TaoTokenKey, base_url: https://taotoken.net/api }三件套Base URL、Key、Model ID在任何认证模式下都要齐全缺一个都会失败。通用排查顺序先 curl 测 API 通道 → 再 curl 测本地端口 → 再看容器日志 → 最后检查配置文件。按这个顺序90% 的问题能定位到具体环节。别一上来就重装重装解决不了配置错误。日志怎么看docker compose logs --tail100 openclaw--tail100只看最后 100 行避免刷屏。看到 ERROR 级别的行重点看。6. 装完之后怎么继续用模型对话、Coding Plan 与文档入口OpenClaw 跑起来只是起点。你接下来大概率会做两件事一是调不同模型对比效果二是把它用在编码或者自动化任务上。这两个方向 TaoToken 都有对应的入口我按用途分开说你按需取。想快速试不同模型的效果用模型对话页面最直接不用改本地配置就能切换模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你打算让 OpenClaw 长期跑编码类 Agent比如自动改代码、跑测试、生成提交信息那 Coding Plan 更合适它在调用额度和模型选择上有针对性安排Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content配置过程中遇到字段疑问或者想确认最新的接入方式查文档最准接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content需要新建或者管理 Key 的时候回控制台控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后说一个实用技巧。OpenClaw 的配置文件支持热加载的版本不多改完.env或者settings.json之后稳妥做法是重启容器docker compose restart openclaw重启比down再up快而且不会丢数据。如果你改了docker-compose.yml本身比如端口那就要down再up因为 compose 文件的变化需要重新创建容器。还有定期备份~/.openclaw目录。里面有你所有的配置和 Agent 生成的数据换机器或者重装的时候直接拷过去就能用。这个目录不大但重建起来费时间。装完之后的第一件事我建议你改一下 Agent 的人设文件通常是SOUL.md或者类似名字让它按你的习惯说话和做事。然后装几个常用 Skill比如文件处理、搜索。这些在 OpenClaw 的 Skill 市场里能找到装完在对话里就能调用。整个流程走下来你会发现最花时间的不是安装而是配置对齐。Key、Base URL、Model ID 三样东西在.env、settings.json、docker-compose.yml里保持一致后面就很少出问题。遇到报错先看日志再按第五节的顺序排查基本都能自己解决。