Docker 部署 OpenClaw 踩坑实录：Web UI 访问、飞书配对及自定义模型配置

1. Docker 部署 OpenClaw 后 Web UI 打不开的真实场景Docker 部署 OpenClaw 这件事看起来就是把镜像拉下来、容器跑起来但真正卡人的地方往往在容器启动之后。我见过太多人在终端里看到容器状态是 Up日志也没有明显报错结果浏览器一打开http://127.0.0.1:18789直接连接被重置换成局域网 IP192.168.5.30:18789还是无法访问。这时候大多数人第一反应是防火墙、代理、端口映射挨个排查一圈最后发现根因跟这些都没关系。OpenClaw 的 Web UI 访问问题核心在于它的网关层有一套跨域访问控制机制。你可以把它理解成小区门禁容器确实在跑端口也确实映射出来了但网关只允许「从特定地址打开的网页」来连接它并下发控制指令。如果你的访问来源不在白名单里网关会直接拒绝表现就是连接被重置或者无法访问。这个机制默认比较严格尤其在 Docker 环境下容器内外网络视图不一致很容易触发。除了 Web UI飞书配对和自定义模型配置也是高频卡点。飞书这边机器人发消息没反应、系统提示未配对、配对码还一直变很多人不知道去哪里拿正确的配对码。自定义模型配置则是另一个坑公司自建的大模型节点要接进来Base URL、API Key、模型 ID 三样东西填错一个就调不通而且报错信息往往不直观。这篇内容聚焦 Docker 环境下 OpenClaw 的完整落地流程覆盖 Web UI 无法访问、飞书配对失败、自定义模型接入这三类问题。我会给出可复制的 docker-compose 配置、端口与反向代理排查清单、飞书应用凭证填写位置以及自定义模型 Base URL 与 Key 的配置示例每一步都附上验证动作。如果你正在用 Docker 跑 OpenClaw或者准备把公司自建模型节点接进来这篇可以帮你少走几个小时的弯路。2. TaoToken 前置准备模型接入的 Base URL 与 Key 怎么拿在讲 OpenClaw 的模型配置之前先把模型接入这一层说清楚。OpenClaw 本身是一个 Agent 框架它需要调用一个大模型来完成对话和任务。你可以用公司自建节点也可以用兼容 OpenAI 接口的模型服务。不管用哪种你都需要三样东西Base URL、API Key、Model ID。这三样缺一不可而且格式必须对。如果你手头没有现成的模型节点或者想先用一个稳定的兼容接口把 OpenClaw 跑通可以走 TaoToken 这条路径。它的接口格式兼容 OpenAI 的openai-completions正好是 OpenClaw 配置里推荐用的 API 格式。你需要先去官网注册并拿到 API Key地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册完成后在控制台里创建 API Key这个 Key 就是后面填到apiKey字段里的值。拿到 Key 之后Base URL 用 https://taotoken.net/api 注意这个地址后面不加 UTM 参数直接作为baseUrl填进去。Model ID 则根据你在控制台里选择的模型来填比如MiniMax-M2.7-highspeed这类名称。这里要提醒一句Base URL 和 Model ID 必须匹配不能拿 A 服务的地址去调 B 服务的模型否则会报模型不存在的错误。如果你用的是公司自建节点逻辑是一样的找运维或平台负责人要 Base URL、API Key 和 Model ID。自建节点通常会把 API 格式做成 OpenAI 兼容这样 OpenClaw 配置起来最省事。如果自建节点用的是其他格式比如 Anthropic 原生格式那配置字段会不一样需要单独处理。这篇主要讲openai-completions这种兼容性最好的方式。还有一个容易忽略的点API Key 的权限。有些平台的 Key 是分权限的只能调特定模型或者有 IP 白名单限制。你在本地 Docker 环境里调试时如果 Key 绑定了固定 IP而容器出口 IP 和宿主机不一致也会导致 401。所以拿到 Key 之后先确认它的调用范围再往 OpenClaw 里填。把这三样东西准备好后面的配置就是填空题。我建议你先把 Base URL、API Key、Model ID 写在一个临时文本里确认没有多余空格和换行再往 JSON 里粘贴。很多配置失败不是逻辑问题而是复制粘贴时带进了不可见字符。3. 可复制配置docker-compose 与 openclaw.json 完整片段这一节直接给可复制的配置。先看 docker-compose 部分。OpenClaw 的容器需要把配置目录挂载出来这样你改openclaw.json之后重启容器就能生效不用重新构建镜像。下面是一个可用的 docker-compose 片段端口映射和卷挂载都写清楚了。services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 18789:18789 volumes: - ~/.openclaw:/root/.openclaw environment: - TZAsia/Shanghai command: [openclaw, gateway, --config, /root/.openclaw/openclaw.json] openclaw-cli: image: openclaw/openclaw:latest container_name: openclaw-cli profiles: [cli] volumes: - ~/.openclaw:/root/.openclaw entrypoint: [openclaw]这里有两个服务openclaw是常驻的网关服务openclaw-cli是用来执行一次性命令的比如飞书配对审批。openclaw-cli用了profiles: [cli]默认不启动需要的时候用docker compose run --rm openclaw-cli来跑。卷挂载把宿主机的~/.openclaw映射到容器内的/root/.openclaw这样配置文件在宿主机上改容器里能直接读到。接下来是~/.openclaw/openclaw.json的核心配置。这个文件分几块gateway 控制网关和 Web UI 访问agents 控制默认模型models 控制模型提供方。下面是一个完整示例把 Web UI 白名单、自定义模型节点都写进去了。{ gateway: { port: 18789, mode: local, bind: lan, controlUi: { allowedOrigins: [*], dangerouslyDisableDeviceAuth: true } }, agents: { defaults: { model: taotoken/MiniMax-M2.7-highspeed } }, models: { mode: merge, providers: { taotoken: { api: openai-completions, baseUrl: https://taotoken.net/api, apiKey: 你的APIKey, models: [ { id: MiniMax-M2.7-highspeed, name: MiniMax2.7highspeed } ] } } } }配置解析一下。gateway.controlUi.allowedOrigins里填[*]是通配符表示允许所有来源访问 Web UI。这在本地调试阶段最省事但如果你要把服务暴露到公网建议改成具体的域名或 IP比如[http://192.168.5.30:18789]。dangerouslyDisableDeviceAuth设为 true 是关闭设备认证同样只建议在受信任的内网环境用。agents.defaults.model里的值格式是提供方名称/模型ID这里写的是taotoken/MiniMax-M2.7-highspeed对应下面models.providers.taotoken里声明的节点。models.mode设为merge表示合并模式你可以在 providers 下声明多个节点OpenClaw 会把它们合并到可用模型列表里。models.providers.taotoken里的api字段固定写openai-completions这是兼容性最好的格式。baseUrl填 https://taotoken.net/api apiKey填你从控制台拿到的 Key。models数组里声明这个节点下有哪些模型可用id是调用时用的标识name是显示名称。如果你用的是公司自建节点把taotoken换成公司节点名称baseUrl和apiKey换成公司提供的值models数组里的id换成公司节点的模型 ID 就行。结构完全一样不用改其他字段。改完配置后重启容器让配置生效docker compose down docker compose up -d openclaw docker compose logs -f openclaw日志里看到网关启动成功、端口监听在 18789就说明配置被正确加载了。如果日志里报 JSON 解析错误多半是配置文件里有语法问题比如多了逗号、少了引号可以用python -m json.tool ~/.openclaw/openclaw.json来校验。4. 验证请求Web UI 访问、飞书配对与模型调用逐步验证配置写完之后不能只看容器状态要逐步验证三个环节Web UI 能不能打开、飞书配对能不能通过、模型能不能正常调用。这一节给具体的验证动作和预期结果。先验证 Web UI。在浏览器里打开http://127.0.0.1:18789如果之前遇到连接被重置改完allowedOrigins之后应该能正常打开控制台页面。如果还是打不开换局域网 IP 试比如http://192.168.5.30:18789。两个地址都试一遍因为bind设为lan时容器会监听所有网络接口但宿主机防火墙可能只放行了部分来源。验证的时候可以同时看容器日志docker compose logs -f openclaw | grep -i origin\|cors\|control如果日志里出现 origin 被拒绝的记录说明allowedOrigins没生效检查一下配置文件路径是不是挂载对了以及容器有没有重启。有时候改了宿主机文件但没重启容器配置不会热加载。Web UI 能打开之后验证飞书配对。飞书这边的问题是配对码一直变因为每次发消息都会生成新的配对请求。正确的做法是不要反复发消息而是通过 CLI 查看最新的配对请求然后手动审批。先查看当前配对列表docker compose run --rm openclaw-cli pairing list feishu输出会是一个表格里面有配对码、发送者 ID、时间戳。找到最新的一条记下配对码比如ZLX3M556。然后执行审批docker compose run --rm openclaw-cli pairing approve feishu ZLX3M556日志输出Approved feishu sender ou_...就表示授权成功。这时候再在飞书里给机器人发消息应该能收到回复了。如果审批时报配对码不存在说明你拿到的码已经过期重新跑一次pairing list feishu拿最新的。飞书应用凭证的填写位置在openclaw.json的 channels 节点下需要填 App ID 和 App Secret。这两个值从飞书开放平台的应用管理后台拿。填完之后重启容器再用pairing list feishu确认通道状态是 connected。最后验证模型调用。最直接的方式是在 Web UI 里发一条消息看有没有回复。如果回复正常说明模型配置生效了。如果报错看容器日志里的具体错误信息。常见的错误有 401、模型不存在、连接超时。也可以用 CLI 直接测试模型docker compose run --rm openclaw-cli agent run --message 你好测试一下模型如果返回正常的文本回复说明agents.defaults.model指向的模型节点工作正常。如果报model not found检查agents.defaults.model里的提供方名称和模型 ID 是否和models.providers里声明的一致。如果报 401检查apiKey是否正确、有没有多余空格。三个环节都验证通过后整个部署就算跑通了。建议把验证命令记下来以后换环境或者改配置时可以快速回归测试。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错来排查。OpenClaw 在 Docker 环境下常见的错误就那么几类每一类都有明确的排查方向。401 Unauthorized。这个错误出现在模型调用环节说明 API Key 无效或者权限不够。先检查openclaw.json里apiKey字段的值确认没有多余空格、没有换行、没有把 Key 截断。然后确认这个 Key 在对应平台上是否有效有没有过期。如果用的是 TaoToken 的 Key去控制台确认 Key 状态是启用。如果 Key 绑定了 IP 白名单确认容器出口 IP 在白名单里。Docker 默认用 bridge 网络出口 IP 是宿主机 IP但如果你改了网络模式出口 IP 可能不一样。local proxy failed。这个错误通常出现在容器启动阶段说明 OpenClaw 尝试连接本地代理但失败了。检查 docker-compose 里有没有设置HTTP_PROXY或HTTPS_PROXY环境变量如果有确认代理地址在容器内可达。如果不需要代理把这些环境变量删掉。另外检查openclaw.json里有没有配置 proxy 相关字段不需要的话也删掉。reading choices 报错。这个错误出现在模型返回解析阶段说明 OpenClaw 收到了响应但响应格式不符合预期。常见原因是api字段填错了比如填成了anthropic但实际节点是 OpenAI 兼容格式。确认api字段是openai-completions。另一个原因是模型返回了非标准格式比如流式响应被截断。可以先用 CLI 直接调模型看原始返回是什么样。OAuth 相关错误。如果配置里用了需要 OAuth 认证的模型服务但没完成授权流程会报 OAuth 错误。OpenClaw 支持 OAuth 的设备码流程需要先在 CLI 里执行授权命令拿到 token 后再配置。如果用的是 API Key 方式就不需要 OAuth确认配置里没有混用两种认证方式。除了这些具体报错还有几个通用排查动作。第一确认配置文件路径正确宿主机~/.openclaw/openclaw.json映射到容器内/root/.openclaw/openclaw.json。第二确认容器重启过配置改动不会热加载。第三确认端口没有被占用docker compose ps看端口映射状态。第四确认防火墙放行了 18789 端口尤其是局域网访问场景。如果用了 CC Switch、Cline MCP 或者 Codex 的 auth.json配置里必须写全三件套Base URL、Key、Model ID。缺任何一个都会导致调用失败。Base URL 用 https://taotoken.net/api Key 用控制台拿到的值Model ID 用模型列表里的标识。三样东西的格式和位置都要对不能只填其中两个。排查的时候建议按顺序来先看容器日志再看配置文件最后看网络连通性。日志里通常有最直接的错误信息配置文件问题用 JSON 校验工具查网络问题用curl在容器内测试。6. 语义一致 CTA把 OpenClaw 接入流程走完整OpenClaw 在 Docker 里跑通之后模型接入这一层建议用兼容 OpenAI 格式的接口配置最简单出错也容易排查。如果你还没有可用的模型节点可以走 TaoToken 这条路径Base URL 用 https://taotoken.net/api Key 在控制台创建Model ID 按需选择。配置片段直接套用第 3 节的 JSON把taotoken换成你的节点名称就行。接入过程中如果遇到 401 或者模型不存在的报错优先检查 Key 和 Model ID 是否匹配。需要看具体接口文档的话接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL 和参数说明。想先验证模型对话效果可以在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 里直接试。如果打算长期跑编码类 Agent 任务Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。飞书配对那边记住不要反复发消息用pairing list feishu拿最新配对码再用pairing approve feishu审批。Web UI 访问问题先改allowedOrigins再重启容器最后用局域网 IP 和本地 IP 各试一次。这三步走完Docker 部署 OpenClaw 的完整流程就闭环了。