1. Ubuntu 上用 Docker 跑 OpenClaw 到底解决了什么问题OpenClaw 是一个可以本地部署、通过浏览器 UI 交互的 AI Agent 网关它能挂载工具、执行任务、对接多家模型通道。很多人第一次在 Ubuntu 上装它卡住的地方往往不是 Docker 本身而是容器里的模型通道怎么配、统一 Key 怎么填、容器到 API 的请求到底通没通。这篇就围绕「ubuntu 安装 openclaw docker」这条主线把 Docker 部署、config.toml 骨架、TaoToken 统一 Key 接入、以及一次真实对话验证连通性全部走一遍目标是一次跑通。先说清楚它适合谁如果你手上有一台 Ubuntu Server物理机、云主机、家里的小主机都行想用一个隔离环境跑 OpenClaw不想在宿主机上手动装 Node.js、npm 那一堆依赖那 Docker 方案就是最省心的。容器把运行时和系统库全打包进去宿主机保持干净同时容器对宿主机文件系统的访问是受限的除非你显式挂载目录这在授权 AI 执行操作时多了一层边界。我用的环境是 Ubuntu Server 24.04 LTSDocker 版本 29.x这个版本里docker compose已经作为插件自动安装命令直接写docker compose就行不用再单独装 compose。下面所有命令都可以直接复制路径按你自己的习惯改。核心检索词先摆出来OpenClaw 是什么——一个本地 AI Agent 网关能做什么——浏览器 UI 对话、挂工具、接多模型通道适合谁——想在 Ubuntu 上用 Docker 隔离部署、又需要统一模型 Key 的开发者。把这三点记住后面配置就不会迷路。2. 部署前把 TaoToken 统一 Key 准备好OpenClaw 本身不带模型能力它需要一个模型通道。这里用 TaoToken 做统一入口好处是一个 Key 就能覆盖多种模型不用在 OpenClaw 里为每家模型分别填 base_url 和 key。你需要在 TaoToken 控制台创建一个 API Key然后拿到两个关键信息Base URL 和 Key。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。Key 在控制台的 API Keys 页面生成形如sk-开头的一串字符。生成后先复制到本地记事本后面要写进 OpenClaw 的配置文件。模型 ID 这块TaoToken 的模型列表在文档里有对照表常见的有claude-sonnet-4-20250514、gpt-4o这类。你在 OpenClaw 的 config.toml 里填的 model 字段要和 TaoToken 侧支持的模型 ID 完全一致大小写都别错。我试过把模型名写错一个字母请求直接返回 404排查了半天才发现是拼写问题。这里有个容易忽略的点OpenClaw 容器内的网络请求是走容器自己的网络栈出去的不是宿主机。所以 Base URL 必须是公网可解析的域名不能写127.0.0.1或localhost否则容器里请求的是它自己必然失败。TaoToken 的https://taotoken.net/api是公网地址容器能直接访问这点没问题。创建 Key 的时候建议单独建一个给 OpenClaw 用方便后面按项目排查用量。控制台里可以给 Key 加备注写上「openclaw-ubuntu-docker」以后看日志一眼就知道是谁在调。Key 生成后只显示一次务必先存好再关页面。如果你还没建 Key可以先去控制台操作https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 建完再回来继续。文档地址在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 模型 ID 对照表就在里面。3. 可复制的 Docker 与 config.toml 配置先建部署目录所有文件都放这里方便挂载和备份mkdir -p ~/openclaw-server1 cd ~/openclaw-server1 mkdir -p datadata目录是 OpenClaw 的持久化目录容器里对应/home/node/.openclaw。第一次启动前先把这个目录的属主改成 1000:1000否则容器里的 node 用户没权限写文件会一直重启sudo chown -R 1000:1000 ./data接着写docker-compose.yml。这里用官方镜像ghcr.io/openclaw/openclaw版本固定到一个具体 tag避免 latest 漂移。端口映射把宿主机的 18789 映射到容器内的 18789OpenClaw 默认绑定 127.0.0.1容器外访问不到所以这里直接映射出来配合bind lan让它监听所有网卡version: 3.8 services: openclaw-gateway: image: ghcr.io/openclaw/openclaw:2026.3.23-2 container_name: openclaw-gateway restart: always ports: - 18789:18789 environment: - TZAsia/Shanghai - OPENCLAW_PORT18789 volumes: - ./data:/home/node/.openclaw mem_limit: 4g cpus: 2.0启动docker compose up -d第一次启动后data目录里会自动生成openclaw.json。这个文件是 OpenClaw 的主配置模型通道就写在这里。先停掉容器再改避免写入冲突docker compose stop然后编辑./data/openclaw.json在gateway节点里补上监听和鉴权配置同时加上models节点接入 TaoToken。完整骨架如下把sk-你的Key换成你自己的{ gateway: { auth: { mode: token, token: 你的登录token }, bind: lan, mode: local, trustedProxies: [ 192.168.0.0/16, 172.16.0.0/12, 10.0.0.0/8 ], controlUi: { allowedOrigins: [ http://127.0.0.1:18789, http://192.168.1.50:18789 ], allowInsecureAuth: true, dangerouslyDisableDeviceAuth: true } }, models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, api: openai-completions, models: [ { id: claude-sonnet-4-20250514, name: Claude Sonnet 4 } ] } } }, agents: { defaults: { model: taotoken/claude-sonnet-4-20250514, compaction: { mode: safeguard }, maxConcurrent: 4 } } }几个关键字段说明。gateway.bind设成lanOpenClaw 才会监听 0.0.0.0否则只绑 127.0.0.1容器外访问不到。controlUi.allowedOrigins里要填你实际访问的地址比如你用http://192.168.1.50:18789打开就得把这个地址写进去否则浏览器会报origin not allowed。models.providers.taotoken.api填openai-completions这是 TaoToken 兼容的接口类型。agents.defaults.model的写法是provider名/模型ID这里就是taotoken/claude-sonnet-4-20250514。provider 名要和models.providers下的 key 一致模型 ID 要和 TaoToken 侧支持的完全一致。改完保存重新启动docker compose up -d如果之前容器因为权限问题一直重启改完data属主后重启一次就好。启动后确认两个容器都在跑docker ps看到openclaw-gateway状态是Up就对了。4. 验证容器到 TaoToken 的连通性配置写完后最关键的一步是验证容器真的能请求到 TaoToken。有两种方式一种是从浏览器 UI 发一条对话另一种是直接在容器里用 curl 打一次 API。先看容器内 curl 的方式这个最直接。进容器docker exec -it openclaw-gateway sh然后在容器里执行curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有choices字段说明容器到 TaoToken 的网络是通的Key 和模型 ID 也都对。如果返回 401是 Key 错了返回 404多半是模型 ID 拼错返回连接超时检查容器 DNS 和出网。浏览器 UI 验证更贴近真实使用。打开http://你的服务器IP:18789会看到登录页把openclaw.json里gateway.auth.token的值填进去登录。进去后新建一个对话发一句「你好用一句话介绍你自己」。如果模型正常返回说明整条链路——浏览器到容器、容器到 TaoToken、模型响应回传——全部打通。我实测下来第一次请求会稍微慢一点因为要建立连接和加载模型上下文后面就快了。如果 UI 里一直转圈不出结果先看容器日志docker logs --tail50 -f openclaw-gateway日志里会打印请求的 provider、model 和错误信息。常见的是model not found那就是模型 ID 和 TaoToken 侧不一致如果是ECONNREFUSED检查 Base URL 是不是写成了127.0.0.1。验证通过后你可以在 UI 里切换模型只要在models.providers.taotoken.models数组里加更多模型 ID然后在对话界面选择就行。一个 Key 覆盖多个模型这就是统一 Key 的好处。5. 常见报错与排查对照部署过程中最容易撞上的几个报错这里按真实日志对照着说。EACCES: permission denied, open /home/node/.openclaw/openclaw.json.15.aaaaaa.tmp这是data目录属主不对。容器里的 node 用户 UID 是 1000宿主机上如果data目录属于 root 或其他 UID就写不进去。解决sudo chown -R 1000:1000 ./data docker restart openclaw-gatewayorigin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)浏览器访问的地址不在allowedOrigins白名单里。比如你用http://192.168.1.50:18789打开但配置里只写了http://127.0.0.1:18789就会报这个。把实际访问地址加进去重启容器。401 UnauthorizedTaoToken 的 Key 错了或者Authorization头没带对。检查openclaw.json里apiKey字段是不是完整的sk-开头字符串有没有多余空格。容器内 curl 测试时Bearer后面跟一个空格再跟 Key。404 model not found模型 ID 和 TaoToken 侧不一致。去文档里核对模型 ID 的完整拼写注意日期后缀和大小写。claude-sonnet-4-20250514和claude-sonnet-4是两个不同的 ID填错就 404。local proxy failed / connection refusedBase URL 写成了127.0.0.1或localhost。容器里的 127.0.0.1 是容器自己不是宿主机。改成https://taotoken.net/api。reading choices 相关报错一般是响应体解析失败可能是 Key 无效导致返回了错误 JSON或者模型 ID 不对返回了非预期结构。先用容器内 curl 确认原始响应再对照配置。OAuth 相关报错如果你在 OpenClaw 里启用了需要 OAuth 的 provider但没配回调地址会报这个。用 TaoToken 的 API Key 模式不涉及 OAuth确认api字段是openai-completions而不是 OAuth 类型。排查顺序建议先docker ps看容器是否在跑再docker logs看报错再进容器 curl 测 API最后看 UI。大部分问题集中在权限、Base URL、模型 ID 这三处。6. 后续怎么用与 Key 管理跑通之后日常使用就是打开浏览器 UI 对话。如果你要长期跑 Agent 任务、挂多个工具、或者做批量调用建议单独规划一下 Key 和额度。TaoToken 的 Coding Plan 适合长期编码和 Agent 场景地址在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 可以按需看。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 想快速试模型效果可以直接用。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 给 OpenClaw 单独建一个 Key方便按项目看用量。配置文件openclaw.json建议纳入版本管理但 Key 不要提交到公开仓库。可以用环境变量或者单独的 secrets 文件启动时注入。Docker Compose 里可以用env_file加载避免 Key 硬编码在 JSON 里。最后提醒一点OpenClaw 的data目录是持久化的容器删了重建配置和会话记录还在。升级镜像时先docker compose down改imagetag再docker compose up -d数据不会丢。如果遇到新版本配置结构变化先备份openclaw.json再升级。