openclaw 部署指南：手动 Docker 详细版 + TaoToken 统一 Key 接入

1. 为什么我放弃了面板一键装改用手动 Docker 部署 openclawopenclaw 是一个可以跑在自己服务器上的 AI Agent 网关它能接 Telegram、Slack 这类聊天渠道把 Claude、GPT、Kimi 这些模型统一挂到一个入口下适合想长期养一个私人助理的人。我第一次装的时候图省事用 1Panel 面板一键部署结果发现模型 endpoint 写死在面板里改不动想换成自己的统一 Key 通道完全没入口。折腾半天后我删掉重来老老实实走手动 Docker 流程反而一次跑通。这篇就把这套手动流程完整拆开从git clone拉项目、docker-setup.sh初始化、docker-compose.yml编排到.env里把模型调用地址和 API Key 统一改到 TaoToken 通道最后用curl和浏览器做连通性验证。全程命令可直接复制配置片段路径和官方一致你照着敲就能在本地或云服务器上复现一次。需要提前说清楚适用人群你得有一台能跑 Docker 的机器本地电脑或云服务器都行会基本的 Linux 命令能自己编辑文本文件。不需要你懂容器编排原理但遇到报错要愿意看日志。我实测下来云服务器比本地电脑顺利得多本地 Docker Desktop 在文件挂载权限上坑更多后面排障章节会专门讲。openclaw 的核心价值在于渠道 模型的解耦渠道负责你怎么跟它说话模型负责它有多聪明。官方文档把这两块拆得很清楚但模型接入部分默认走的是内置的几个海外通道对国内用户来说延迟和付费都不友好。所以这篇的重点之一就是把这层模型调用统一收口到 TaoToken让 endpoint 和 Key 只维护一份。2. 部署前把 TaoToken 通道准备好统一 Key 与 endpoint 怎么拿在动 Docker 之前先把模型通道这件事定下来否则你装完 openclaw 还得回头改配置等于白装一遍。openclaw 的模型配置本质上是 OpenAI 兼容格式一个 Base URL 加一个 API Key再加一个 Model ID。TaoToken 提供的正是这套兼容接口所以接入逻辑非常直接。第一步去 TaoToken 官网注册账号。地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册完进控制台。控制台里能看到你的账户余额和用量新用户一般有试用额度够你跑通验证。第二步创建 API Key。进 API Keys 页面 https://taotoken.net/console/api-keys 点新建复制出来那串sk-开头的字符串。这串 Key 只显示一次务必先存到安全的地方比如密码管理器。后面.env文件里要填的就是它。第三步确认 Base URL。TaoToken 的 API 根地址是 https://taotoken.net/api 注意这里不带任何查询参数。在 openclaw 的配置里模型 endpoint 通常要写到/v1这一层也就是https://taotoken.net/api/v1具体填法看下一节的配置片段我会把完整路径写清楚避免你少写或多写斜杠。第四步选 Model ID。TaoToken 支持多家模型Model ID 就是你在请求里指定的模型名比如claude-sonnet-4-5、gpt-5这类。你可以在模型对话页面 https://taotoken.net/models 先试聊几句确认这个模型可用、响应正常再把它写进 openclaw 配置。这一步别省我见过有人配置全对但 Model ID 拼错排查了半小时。如果你打算长期跑 Agent 类任务比如让 openclaw 定时整理文件、自动回复消息那 Coding Plan 更划算地址是 https://taotoken.net/coding-plan 包月形式适合高频调用。低频使用就按量付费用多少扣多少验证阶段按量最省。把上面四样东西记在一个临时文本里Base URL、API Key、Model ID、以及你打算用的渠道Telegram 还是别的。接下来进 Docker 环节这些值会分别填进.env和openclaw.json。3. 手动 Docker 部署全流程docker-compose 与 .env 可复制配置这一节是全文核心我把每一步的命令和配置文件都写全你按顺序执行即可。假设你的工作目录是~/openclaw操作系统 Debian 13Docker 和 Docker Compose 已装好。先拉项目并进入目录git clone https://github.com/openclaw/openclaw.git cd openclaw然后跑官方初始化脚本它会在宿主机创建两个关键目录~/.openclaw配置、密钥、记忆文件和~/openclaw/workspaceAgent 可读写的工作区。./docker-setup.sh脚本跑完会生成.env和docker-compose.yml。先别急着up我们要改配置。打开.env把模型通道相关的几行改成 TaoToken# .env 模板路径~/openclaw/.env OPENCLAW_GATEWAY_TOKEN换成脚本生成的令牌保持不动 OPENCLAW_GATEWAY_URLws://openclaw-gateway:18789 # 模型通道统一指向 TaoToken OPENAI_BASE_URLhttps://taotoken.net/api/v1 OPENAI_API_KEYsk-你从TaoToken复制的Key OPENCLAW_DEFAULT_MODELclaude-sonnet-4-5注意OPENCLAW_GATEWAY_TOKEN这行不要动它是网关鉴权用的和模型 Key 是两码事。很多人把这两个搞混结果网关连不上还以为是模型问题。接着改docker-compose.yml重点是给 CLI 容器补上网关地址否则容器内localhost指向自己配对命令会失败# docker-compose.yml 片段路径~/openclaw/docker-compose.yml services: openclaw-gateway: image: openclaw/openclaw:latest env_file: .env ports: - 18789:18789 volumes: - ~/.openclaw:/home/node/.openclaw - ~/openclaw/workspace:/home/node/workspace openclaw-cli: image: openclaw/openclaw:latest depends_on: - openclaw-gateway env_file: .env environment: OPENCLAW_GATEWAY_URL: ws://openclaw-gateway:18789 volumes: - ~/.openclaw:/home/node/.openclaw - ~/openclaw/workspace:/home/node/workspace改完启动docker compose up -d第一次启动会自动进入配置引导。渠道选 Telegram 的话先去 Telegram 搜BotFather建机器人拿 Bot API Token再搜userinfobot拿你自己的用户 ID。引导里 hooks 选session-memory其余可以 Skip。引导结束会打印一串 Token记下来。如果你想把模型配置直接写进openclaw.json而不是靠环境变量可以在~/.openclaw/openclaw.json里加这段{ models: { providers: { taotoken: { baseUrl: https://taotoken.net/api/v1, apiKey: sk-你从TaoToken复制的Key, models: [claude-sonnet-4-5, gpt-5] } }, default: taotoken/claude-sonnet-4-5 }, gateway: { bind: lan } }gateway.bind设成lan是为了让浏览器通过 Docker 桥接网络能访问到网关默认回环地址会连不上。这一步和后面的 1008 报错直接相关。4. 验证请求从 curl 到浏览器确认模型真的通了配置写完不代表通了必须做两层验证先验模型通道再验 openclaw 网关。第一层直接用curl打 TaoToken 的接口确认 Key 和 Model ID 没问题curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你从TaoToken复制的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 只回复两个字通了}] }返回 JSON 里choices[0].message.content是通了说明通道没问题。如果这里就报 401别往下走先回第 2 节检查 Key 有没有复制全、有没有多余空格。第二层验 openclaw 网关。先看容器状态docker compose ps两个服务都Up才算正常。然后进 CLI 容器跑一次模型调用docker compose run --rm openclaw-cli onboard引导里如果模型测试通过会显示模型响应。你也可以直接查网关日志docker compose logs -f openclaw-gateway日志里出现model request ok或类似字样说明 openclaw 已经成功把请求转发到 TaoToken。第三层浏览器访问。本地机器开http://127.0.0.1:18789云服务器开http://你的公网IP:18789。如果页面提示disconnected (1008): control ui requires HTTPS or localhost说明你用的是 HTTP 且非 localhost浏览器出于安全策略拦了设备身份。两个解法一是用 Caddy 配个域名走 HTTPS二是临时在openclaw.json里加controlUi: { allowInsecureAuth: true }仅限调试。配对 Telegram 渠道docker compose run --rm openclaw-cli pairing approve telegram 你的配对码配对码在 Telegram 里给机器人发/start后拿到默认 1 小时过期。成功后会显示paired。到这里一次完整的部署加连通性测试就跑完了。模型走 TaoToken渠道走 Telegram网关在 18789三层都验过。5. 部署常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错对照你遇到哪个查哪个。401 Unauthorized最常见。九成是 API Key 问题。检查.env里OPENAI_API_KEY有没有sk-前缀、有没有换行符混进去、有没有把网关 Token 填到模型 Key 的位置。用第 4 节的curl单独验一次能快速定位是 Key 错还是 openclaw 配置错。local proxy failed / connection refused容器内访问不到网关。原因是 CLI 容器的localhost指向自己。解法就是在docker-compose.yml的openclaw-cli服务里加OPENCLAW_GATEWAY_URL: ws://openclaw-gateway:18789用服务名而不是 localhost。改完docker compose up -d --force-recreate openclaw-gateway重建。reading choices / choices is undefined模型返回体里没有choices字段。通常是 Base URL 写错比如漏了/v1或者 Model ID 不存在。回第 2 节确认https://taotoken.net/api/v1这个路径完整Model ID 在模型对话页面能正常用。OAuth / token expired如果你接的是需要 OAuth 的渠道比如某些企业 IM令牌过期会报这个。重新走一遍渠道授权或者检查~/.openclaw/openclaw.json里对应渠道的 token 字段。openclaw 的渠道 token 和模型 Key 是分开存的别改错地方。EACCES permission denied容器用户 uid1000 写不了 root 拥有的目录。执行chown -R 1000:1000 $HOME/.openclaw docker compose run --rm openclaw-cli onboarddisconnected (1008): pairing required新浏览器首次连网关需要设备配对批准。先docker compose exec openclaw-gateway node dist/index.js devices list看待批准列表再devices approve request-id。如果 CLI 连不上网关就用容器内直接执行的方式绕开网络问题。改完 compose 不生效docker compose restart只重启不重建配置改动不会应用。要用docker compose up -d --force-recreate openclaw-gateway。排查时记住一个原则先分层再定位。模型层用curl验网关层用docker compose logs验浏览器层用开发者工具 Network 面板验。三层分开测比一股脑改配置快得多。6. 把 Key 收口到 TaoToken 之后我的日常维护习惯部署跑通只是开始真正省心的是后续维护。我现在所有 openclaw 实例的模型通道都统一指向 TaoToken好处是换模型只改一个 Model ID不用动 Key也不用重新走一遍渠道授权。日常我会做三件事。第一定期去 API Keys 页面 https://taotoken.net/console/api-keys 轮换 Key旧 Key 删掉新 Key 更新到.env后docker compose up -d --force-recreate重建容器。第二用模型对话页面 https://taotoken.net/models 试新模型确认可用再写进配置避免线上翻车。第三长期跑的 Agent 任务挂 Coding Plan地址 https://taotoken.net/coding-plan 比按量付费稳。如果你在接入过程中卡住接入文档在 https://taotoken.net/doc 里面有各语言的调用示例和错误码说明比到处搜帖子靠谱。openclaw 这边核心文件都在~/.openclaw/workspaceAGENTS.md管行为准则SOUL.md管性格MEMORY.md是长期记忆。重装前把整个~/.openclaw备份一份换机器直接还原Agent 的记忆就带过去了。最后提醒一句Docker 版的 spawn 分身功能目前用不了因为多个 agent 共用同一个会话、互相不可见。想玩多分身得等官方修或者改用非容器部署。这个坑我踩过你别再花时间试了。