必须绕开模型标识符错配、环境变量覆盖冲突、百炼平台服务区域不一致三类高频报错，否则服务启动后持续返回401或503错误且无法触发Skill执行。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在OpenClaw v2026.3.24中稳定对接阿里云通义千问标准API，必须绕开模型标识符错配、环境变量覆盖冲突、百炼平台服务区域不一致这三类高频报错，否则服务启动后会持续返回401或503错误且无法触发任何Skill执行。
确认OpenClaw版本与千问API兼容性
执行 openclaw --version 命令，输出必须为 v2026.3.24 或更高（如 v2026.4.5）。若显示 clawdbot 或 moltbot 开头的版本号，需先运行 npm install -g openclaw@latest 升级，旧版存在千问v3系列模型的context length硬编码缺陷，会导致长文本解析直接截断。
检查Node.js版本：运行 node -v，结果必须为 【v22.16.0 或 v24.0.0+】。低于v22.16.0将无法加载千问Qwen3-Max-Thinking模型的流式响应模块，表现为AI回复卡在“思考中”状态超过90秒后自动中断。
获取并验证阿里云百炼API Key
登录阿里云百炼控制台 → 进入「API密钥管理」→ 点击「创建AccessKey」→ 复制新生成的 AccessKey ID 与 AccessKey Secret。
⚠️ 注意：必须勾选「开通百炼服务」并完成实名认证，否则即使密钥正确也会在OpenClaw启动时抛出 Error: Unauthorized access to Bailian endpoint 错误。
在终端执行以下命令验证密钥有效性：
curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation" \
-H "Authorization: Bearer <你的AccessKey ID>" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3-max-2026-01-23", "input": {"messages": [{"role": "user", "content": "测试"}]}, "parameters": {"temperature": 0.1}}'
若返回含 output.text 的JSON，则密钥可用；若返回 {"code":"InvalidParameter","message":"Invalid model name"}，说明当前地域未开通该模型——立即切换百炼控制台右上角地域为「中国香港」或「新加坡」。
配置OpenClaw使用千问标准接口
方法一：环境变量直写（推荐用于轻量服务器/无影云电脑）
编辑 ~/.bashrc 或 ~/.zshrc，追加以下三行：
export OPENCLAW_MODEL_PROVIDER="dashscope"
export DASHSCOPE_API_KEY="your_accesskey_id_here"
export OPENCLAW_MODEL_NAME="qwen3-max-2026-01-23"
保存后执行 source ~/.zshrc（MacOS/Linux）或重启PowerShell（Windows）。
OpenClaw专家 — 用于任何OpenClaw问题或需求，包括配置错误、网关崩溃、网关未启动、斜杠指令、频道路由等。
方法二：配置文件覆盖（推荐用于本地多模型切换场景）
进入OpenClaw项目根目录，打开 config/default.yaml，定位到 llm: 区块，修改为：
llm:
provider: dashscope
api_key: your_accesskey_id_here
model: qwen3-max-2026-01-23
base_url: https://dashscope.aliyuncs.com/api/v1
⚠️ 关键点：【base_url末尾不能带斜杠】，否则OpenClaw会拼接出 https://dashscope.aliyuncs.com/api/v1//services/... 导致404。
方法三：启动参数注入（临时调试用）
在OpenClaw项目目录下执行：
openclaw start --llm-provider dashscope --llm-api-key your_accesskey_id_here --llm-model qwen3-max-2026-01-23
该方式优先级最高，会覆盖环境变量与配置文件设置，适合快速验证单次连接。
启动服务并验证千问调用是否生效
第一步：确保防火墙已放行端口18789
在阿里云轻量服务器控制台 → 实例安全组 → 添加入方向规则 → 协议类型TCP → 端口范围18789 → 授权对象0.0.0.0/0。
第二步：启动OpenClaw服务
执行 openclaw start，观察终端输出，直到出现 Gateway listening on http://0.0.0.0:18789 且无红色ERROR字样。
第三步：发送测试请求
新开终端窗口，执行：
curl -X POST "http://localhost:18789/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "请用中文回答：当前时间是几月几日？"}]}'
第四步：检查响应内容
若返回JSON中包含 "content":"当前时间是2026年6月14日"，说明千问API已成功穿透OpenClaw网关；若返回 {"error":"Model not found"}，请立即检查 OPENCLAW_MODEL_NAME 是否拼写为 qwen3-max-2026-01-23（注意中间是短横线，不是下划线）。
