1. openclaw 接千问 qwen3-max 到底卡在哪openclaw 是一个把本地工具链和多家大模型串起来的网关型工具你可以把它理解成一个「模型路由器」浏览器里聊天、命令行里跑 Agent、编辑器里做补全请求都先到 openclaw再由它转发给真正的模型服务。它本身不产出模型能力只负责鉴权、路由、会话管理和并发调度。适合谁适合那些不想在每个客户端里重复填 Key、又想把国产大模型接进日常开发流的人。千问大模型里的 qwen3-max 是通义千问系列的旗舰档长文本理解、代码生成、结构化输出都比较稳很多团队拿它当主力对话模型。问题在于openclaw 默认的 provider 列表里并没有「千问」这一项你在配置界面里翻半天也找不到 qwen3-max 的影子。于是最常见的做法是走 Custom Provider手动填 API Base URL、鉴权字段和模型 ID。但这一步的坑比想象中多。有人把 Base URL 填成了控制台首页地址请求直接 404有人模型 ID 写成了大写Qwen3-Max网关侧匹配不到还有人配置写完了却忘了重启容器浏览器里一直转圈。这篇就聚焦一件事在 openclaw 里把 qwen3-max 配通给出可复制的 config.toml 配置骨架再用一次最小请求验证它真的活了。如果你手上还没有统一的 Key 通道TaoToken 可以作为一处统一 Key/API 通道来用官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 后面配置里会提到它对应的接入方式。需要先说明一点openclaw 不同版本的配置文件路径不完全一样。较新版本把配置落在~/.openclaw/openclaw.json而部分发行版或你自己改过的部署会读config.toml。本文的骨架以 TOML 形式给出字段名和 JSON 版一一对应你按自己实际读的那个文件来落就行。判断方法很简单进容器后ls ~/.openclaw/看哪个文件存在、哪个被configure命令写过就以那个为准。2. 前置准备Key、通道与 openclaw 环境在动配置文件之前有三样东西要先备齐缺一个后面都会报错。第一是模型服务侧的 API Key。如果你直接用百炼平台就去控制台创建 API Key注意归属的业务空间要和授权了 qwen3-max 的那个空间一致否则请求会返回权限不足。创建完把sk-开头的字符串存好它只完整显示一次。如果你希望多个模型共用一个 Key、少管几套鉴权也可以走 TaoToken 的统一通道在它的控制台里生成 Key再在 openclaw 里把 Base URL 指向它的 API 地址https://taotoken.net/api。两种方式在 openclaw 里的配置结构是一样的区别只在baseUrl和apiKey两个字段。第二是确认 openclaw 已经跑起来。Docker 部署的话容器名通常是openclaw-gateway配套还有一个openclaw-nginx做前端反代。用docker ps看一眼两个容器是不是都在 Up 状态。没起来就先按官方部署文档把镜像拉起来别在配置阶段排查启动问题会互相干扰。第三是确认你能进到容器里改配置。命令是docker exec -it openclaw-gateway sh进去之后当前用户一般是node家目录是/home/node。配置文件就在/home/node/.openclaw/下面。改之前先备份一份cp openclaw.json openclaw.json.bak这一步别省配置写错导致网关起不来的时候回滚全靠它。注意API Key 属于敏感凭据不要提交到 Git也不要在截图里露出完整字符串。配置文件权限建议保持600。3. config.toml 配置骨架模型标识、通道与鉴权下面这份骨架是核心你可以直接抄把占位符替换成自己的值。字段分三块models定义 provider 和模型清单agents指定默认用哪个模型gateway管网关自身的监听和鉴权。# ~/.openclaw/config.toml # 若你的版本读 openclaw.json把下面结构等价转成 JSON 即可 [models] mode merge [models.providers.custom-qwen-max] # 通道地址直连百炼用 dashscope 的 compatible-mode # 走统一通道则填 https://taotoken.net/api baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1 apiKey sk-替换成你自己的Key api openai-completions [[models.providers.custom-qwen-max.models]] id qwen3-max-2026-01-23 # 必须全小写与授权模型一致 name qwen3-max (Custom Provider) reasoning false input [text] contextWindow 16000 maxTokens 4096 [models.providers.custom-qwen-max.models.cost] input 0 output 0 cacheRead 0 cacheWrite 0 [agents.defaults] [agents.defaults.model] primary custom-qwen-max/qwen3-max-2026-01-23 [agents.defaults.models] custom-qwen-max/qwen3-max-2026-01-23 {} [agents.defaults.compaction] mode safeguard [agents.defaults] maxConcurrent 4 [agents.defaults.subagents] maxConcurrent 8 [gateway] mode local bind lan [gateway.auth] mode token token 替换成你自己的网关token [gateway.controlUi] allowedOrigins [http://192.168.1.50:18789] allowInsecureAuth true dangerouslyDisableDeviceAuth true [gateway.trustedProxies] proxies [192.168.0.0/16, 172.16.0.0/12, 10.0.0.0/8]几个字段值得单独说清楚。api openai-completions表示走 OpenAI 兼容协议请求路径是/chat/completions这是目前接入国产模型最省事的方式绝大多数服务都支持。id必须和你在模型服务侧授权/开通的那个模型标识完全一致大小写敏感写成Qwen3-Max大概率匹配失败。primary是「provider 名/模型 id」的拼接中间那个斜杠不能少写错了网关会找不到模型。contextWindow和maxTokens按你实际开通的规格填。qwen3-max 的上下文窗口远大于 16000但 openclaw 侧填小一点更安全避免一次塞太多内容把额度打满。cost字段填 0 只是让 openclaw 不做费用估算不影响实际计费真实账单以模型服务侧为准。如果你用的是统一通道把baseUrl换成https://taotoken.net/apiapiKey换成在 TaoToken 控制台生成的 Key其余结构不动。这样以后想换模型只改id和primary两处就行不用重新配鉴权。4. 验证连通性一次最小请求跑通配置写完先别急着开浏览器。最稳的验证顺序是重启容器 → 命令行发一次最小请求 → 再开 UI。先重启两个容器让新配置生效docker restart openclaw-gateway docker restart openclaw-nginx等十几秒用docker logs --tail 50 openclaw-gateway看启动日志确认没有config parse error或provider not found之类的报错。如果日志里出现 provider 名和模型 id说明配置已经被正确加载。接着在宿主机上直接对模型服务发一次最小请求绕过 openclaw先确认 Key 和通道本身是通的curl -s https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer sk-替换成你自己的Key \ -H Content-Type: application/json \ -d { model: qwen3-max-2026-01-23, messages: [{role: user, content: 只回复两个字通了}], max_tokens: 16 }返回体里如果能看到choices[0].message.content是「通了」说明 Key、通道、模型 id 三者都对。这一步失败的话问题在模型服务侧跟 openclaw 无关先解决鉴权或授权问题。模型侧通了之后再验证 openclaw 这一层。进容器用 openclaw 自带的命令发一次请求docker exec -it openclaw-gateway sh openclaw chat --model custom-qwen-max/qwen3-max-2026-01-23 --prompt 只回复两个字通了如果这条命令能拿到回复说明 openclaw 的 provider 路由、鉴权注入、模型映射全部正常。这时候再打开浏览器访问http://你的IP:18789填入gateway.auth.token里那个 token登录后在对话框里发一句话应该就能正常对话了。实测下来最容易出问题的不是配置本身而是「改了配置没重启」和「模型 id 大小写不一致」这两件事。前者表现为 UI 里模型列表还是旧的后者表现为请求返回模型不存在。两个都排查一遍基本就通了。5. 本篇常见错排查报错一model not found或unknown model。九成是id和primary对不上。检查models.providers.provider.models[].id和agents.defaults.model.primary里斜杠后面的部分是否逐字符一致包括大小写和日期后缀。qwen3-max 的完整标识常带日期比如qwen3-max-2026-01-23少写日期段也会匹配失败。报错二401 Unauthorized。Key 错了、过期了或者 Key 归属的业务空间没有授权这个模型。去模型服务控制台确认 Key 状态和模型授权范围。走统一通道的话确认 Key 是在对应项目下生成的且额度没被用完即停策略拦下。报错三404 Not Found。Base URL 填错。直连百炼必须是https://dashscope.aliyuncs.com/compatible-mode/v1末尾不要多加/chat/completionsopenclaw 会自己拼路径。走统一通道则是https://taotoken.net/api同样不要带多余后缀。报错四配置改了但 UI 里没变化。没重启容器或者改错了文件。openclaw 可能同时存在openclaw.json和config.toml实际读的是哪一个要以启动日志为准。改完记得docker restart openclaw-gateway只重启 nginx 不够。报错五浏览器登录后一直转圈。多半是gateway.auth.token和页面里填的不一致或者allowedOrigins没包含你实际访问的地址。把访问用的 IP 和端口加进allowedOrigins重启网关再试。报错六请求超时。检查容器能不能出网docker exec -it openclaw-gateway sh进去后curl -I https://dashscope.aliyuncs.com看是否通。容器网络隔离、DNS 配置错误都会导致超时这类问题跟模型配置无关。6. 后续怎么用把 qwen3-max 接进日常流配通只是第一步。接下来你可以把 openclaw 的网关地址填进编辑器插件、命令行 Agent 或自建脚本让它们统一走custom-qwen-max/qwen3-max-2026-01-23这个模型。想换模型时只改primary一行重启网关即可客户端侧完全不用动这正是用网关层做模型路由的价值。如果你打算长期跑编码类任务或 Agent 工作流建议把 Key 通道和模型清单分开管理Key 走统一通道模型清单在 openclaw 里维护。这样新增模型时只加一段[[models.providers...models]]不用碰鉴权。需要生成或管理 Key 的话可以到 https://taotoken.net/api-keys 处理接入细节和字段说明看 https://taotoken.net/doc 想先在网页里直接试 qwen3-max 的效果用 https://taotoken.net/model-chat 最快如果是长期编码和 Agent 场景https://taotoken.net/coding-plan 更合适。配置过程中卡在鉴权或接入字段上优先翻接入文档比反复改配置省时间。