1. OpenClaw 公网访问为什么卡在设备身份校验OpenClaw 的 Control UI 默认走的是「本机可信」模型浏览器和服务跑在同一台机器上网关认为设备身份天然可信所以本地http://127.0.0.1:18789打开一切正常。可一旦你把端口映射到公网用http://你的IP:18789或http://你的域名:18789去访问页面要么白屏、要么控制台报错、要么直接弹出control ui requires device identity登录框都出不来。这个报错的核心含义是网关在握手阶段要求浏览器提供一个「设备身份凭证」而公网访问场景下这个凭证拿不到或者校验不通过。它和 Token 认证是两套东西——Token 管的是「你有没有权限登录」设备身份管的是「你这个设备是不是被信任的」。很多人配好了 Token 却依然进不去就是卡在后者。触发条件其实就那么几类。第一类是绑定地址问题gateway.bind还停留在localhost公网请求根本到不了网关或者到了但被判定为非本地来源。第二类是来源校验allowedOrigins没把你的域名或 IP 加进去浏览器发起的跨域请求被拦。第三类就是设备身份校验本身Control UI 在非安全上下文HTTP 而非 HTTPS下无法完成设备指纹的建立于是直接拒绝。我试过在纯 HTTP 公网环境下折腾半天最后发现不是 Token 写错了而是设备身份这一关卡死了。理解这条链路之后解决思路就清晰了要么补齐 HTTPS 让设备身份能正常建立要么在受控前提下显式关闭设备身份校验。前者是生产推荐后者是快速验证和临时使用的捷径。下面先把 TaoToken 这个前置环节说清楚因为无论你走哪条路模型调用这一层都得先通。2. TaoToken 前置准备把模型调用链路先打通在动 OpenClaw 网关配置之前建议先把模型调用这一层独立验证通过。原因很简单如果模型侧本身就不通你会在网关报错和模型报错之间反复横跳排查成本翻倍。TaoToken 在这里扮演的是统一模型接入层的角色它提供兼容 OpenAI 风格的接口OpenClaw 的chatCompletions端点可以直接对接。你需要准备三样东西Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 到控制台创建路径是 API Keys 页面创建后复制保存它只显示一次。Model ID 按你实际要用的模型填比如常见的对话模型标识。创建 Key 的入口在这里https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。登录后点新建给它起个能认出来的名字比如openclaw-gateway方便以后按用途吊销。生成后立刻复制页面刷新就看不到了。拿到三件套之后先别急着往 OpenClaw 里塞用一条 curl 命令独立验证模型侧是否通curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的APIKey \ -d { model: 你的ModelID, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回的 JSON 里choices[0].message.content是「通了」说明 Base URL、Key、Model ID 三件套没问题可以进入网关配置环节。如果这里就报 401那先解决 Key 的问题别往下走。这一步的意义在于把变量隔离——模型侧确认无误后后面所有报错都只可能出在 OpenClaw 网关本身。顺便说一句如果你打算长期跑编码类或 Agent 类任务可以了解下 Coding Plan它在高频调用场景下比按量计费更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。不过这只是可选优化不影响本篇的报错修复。3. 可复制配置openclaw.json 关键片段与命令行改法OpenClaw 的配置有两个改法命令行openclaw config set和直接编辑~/.openclaw/openclaw.json。命令行适合快速改单项配置文件适合一次性看全貌。我建议先用命令行把关键项改掉再打开配置文件核对避免手抖写错 JSON 结构。先看命令行方式三条命令依次执行# 1. 允许非安全认证解决 HTTP 场景下的跨域与握手问题 openclaw config set gateway.controlUi.allowInsecureAuth true # 2. 关键步骤关闭设备身份校验让 HTTP 公网访问可以通过 openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true # 3. 重启网关服务使配置生效 openclaw gateway restart执行完第三条后网关会重新加载配置。注意dangerouslyDisableDeviceAuth这个名字里的dangerously不是吓唬人它确实会削弱一层防护所以只建议在受控网络或临时验证时用生产环境请走后面的 HTTPS 方案。如果你更习惯直接编辑配置文件打开~/.openclaw/openclaw.json找到gateway节点对照下面这段结构核对。路径和字段名要和原文一致别自己造字段{ gateway: { port: 18789, bind: lan, controlUi: { allowInsecureAuth: true, dangerouslyDisableDeviceAuth: true, allowedOrigins: [ http://你的域名或IP:18789 ] }, auth: { mode: token, token: 你的复杂Token }, http: { endpoints: { chatCompletions: { enabled: true } } } } }几个字段要重点确认。bind设成lan或0.0.0.0只写localhost的话公网请求进不来。allowedOrigins里必须包含你实际访问用的完整来源带协议带端口比如http://1.2.3.4:18789或http://your.domain:18789少一个字符都可能被拦。auth.mode保持tokentoken填你自己生成的复杂字符串别用弱口令。改完配置文件同样要openclaw gateway restart。这里有个容易忽略的点命令行改和手动改如果冲突以最后一次写入为准所以别两边同时改同一个字段。改完建议cat ~/.openclaw/openclaw.json看一眼最终落盘的内容确认 JSON 没有语法错误——多一个逗号都会导致网关启动失败。4. 验证请求从 curl 到浏览器逐步确认成功配置改完不代表就通了得一步步验证。验证顺序建议从内到外先本机 curl再本机浏览器最后公网浏览器。这样任何一步失败你都能立刻知道问题出在哪一层。第一步本机验证网关是否正常监听curl -i http://127.0.0.1:18789/如果返回 200 或 302说明网关进程活着。如果连接被拒检查openclaw gateway restart是否真的成功用ps aux | grep openclaw看进程在不在。第二步本机带 Token 验证 chatCompletions 端点curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的APIKey \ -d { model: 你的ModelID, messages: [{role: user, content: ping}] }这一步其实在第二节已经做过这里再跑一次是为了确认网关重启没有影响模型侧配置。返回正常内容就说明http.endpoints.chatCompletions.enabled生效了。第三步公网浏览器访问http://你的IP:18789或http://你的域名:18789。如果之前报control ui requires device identity现在应该能看到登录界面。输入你的 Token 登录进入 Control UI。如果还是白屏打开浏览器开发者工具的 Console 和 Network 面板看具体是哪个请求失败、返回什么状态码。第四步登录后在 UI 里发一条测试消息确认模型调用链路端到端打通。这一步成功说明网关、认证、模型三层全部就绪。整个验证过程的关键是「分层隔离」——每一层单独确认不要跳步。很多人一上来就直接公网访问失败了不知道是网关没起、Token 错了还是设备校验拦了只能瞎猜。5. 常见报错排查401、local proxy failed 与 OAuth 类问题即使按上面配完实际环境里还是会撞到各种报错。这里按真实遇到的频率排一下对照着查。401 Unauthorized最常见。先确认请求头里Authorization: Bearer 你的APIKey格式对不对Bearer 后面有一个空格。再确认 Key 有没有过期或被吊销去控制台 API Keys 页面核对。如果 curl 本机通、公网不通那多半是网关的auth.token和你在 UI 里输入的 Token 不一致重新核对openclaw.json里的auth.token字段。local proxy failed这个通常出现在网关尝试转发请求到模型端点时。检查chatCompletions的 Base URL 是否指向https://taotoken.net/api注意结尾不要多加斜杠或路径。另外确认服务器出网正常curl -I https://taotoken.net/api能通。如果服务器在受限网络里出网被拦也会报这个。reading choices 相关报错一般是模型返回结构不符合预期或者 Model ID 填错了导致返回了错误对象。回到第二节的 curl 命令用同样的 Model ID 独立测一次确认返回里有choices数组。如果 curl 正常但网关报这个错检查 OpenClaw 的模型配置字段有没有拼写错误。OAuth 类报错如果你用的是需要 OAuth 流程的接入方式注意 OpenClaw 的auth.mode要设成对应模式Token 模式不涉及 OAuth。出现 OAuth 报错通常是模式选错了或者回调地址没配对。这种场景下建议先切回token模式验证基础链路再单独调 OAuth。设备身份报错反复出现确认dangerouslyDisableDeviceAuth真的写进去了用openclaw config get gateway.controlUi.dangerouslyDisableDeviceAuth查一下当前值。如果返回false说明没生效可能是配置文件被覆盖或者重启没成功。另外allowInsecureAuth也要同时为true两个是配套的。排查时有个通用技巧把网关日志打开openclaw gateway logs或看对应日志文件报错发生的时间点附近通常有更详细的堆栈。浏览器侧则看 Network 面板里失败请求的 Response Body往往比页面上的提示信息更有用。6. 生产环境怎么收尾HTTPS 与访问控制快速验证用dangerouslyDisableDeviceAuth没问题但生产环境不能这么裸奔。设备身份校验被关掉之后任何拿到 Token 的人都能从任意设备登录风险是实打实的。正确的收尾方式是补上 HTTPS让设备身份校验能正常工作然后把那个危险开关关回去。推荐用 Nginx 反向代理加 Lets Encrypt 免费证书。Nginx 监听 443把请求转发到本机127.0.0.1:18789OpenClaw 的bind可以改回localhost不直接暴露端口。证书用 certbot 申请自动续期。这样浏览器访问的是https://你的域名安全上下文成立设备身份校验能正常建立dangerouslyDisableDeviceAuth就可以设回falseopenclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth false openclaw gateway restart同时把allowedOrigins改成你的 HTTPS 域名比如https://your.domain。再配一层 IP 白名单只允许可信来源访问进一步收窄暴露面。Token 依然要保留它是登录凭证和设备身份是两道独立的门。如果你在配置过程中需要查更细的字段说明接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数列表。想先在网页里验证模型对话是否正常可以用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 快速试一条。长期跑编码和 Agent 任务的话Coding Plan 的入口前面给过了按需取用。最后提醒一句dangerouslyDisableDeviceAuth这个开关的设计意图就是「临时、受控、尽快恢复」。把它当成调试工具而不是长期方案。公网访问的安全底线是 HTTPS 加访问控制设备身份校验能开就开着别为了省事把它永久关掉。