需检查配置文件、环境变量、接口调用及模型注册四方面：一、在~/.openclaw/openclaw.json中正确配置DASHSCOPE_API_KEY和dashscope提供者；二、systemd服务需在unit文件中导出API Key；三、可直连DashScope兼容接口调试；四、确保agents.defaults.model.primary为完整路径如“dashscope/qwen3-max”且openclaw status显示active。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已安装 OpenClawAI 并希望调用通义千问 Qwen-Max 模型，但模型未响应或报错“model not found”“API key invalid”等，则可能是由于配置文件缺失、API Key 未正确注入或模型标识不匹配所致。以下是解决此问题的步骤：
一、配置 openclaw.json 中的 DashScope 提供商
该方法通过直接修改 OpenClaw 的核心配置文件，显式声明 DashScope 为模型提供商，并绑定 Qwen-Max 系列模型，确保 Gateway 能识别并路由请求。
1、确认配置文件路径为 ~/.openclaw/openclaw.json，若不存在则手动创建该目录及文件。
2、在文件顶层添加或合并 "env" 字段，填入从阿里云百炼控制台获取的 API Key：
"env": {"DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
3、在 "models.providers" 下新增 "dashscope" 板块，设置 baseUrl 为兼容模式地址，并声明至少一个 Qwen-Max 模型 ID（如 qwen-max、qwen3-max 或 qwen-vl-max）。
4、确保模型 ID 与阿里云百炼当前开通权限一致，例如若仅开通了 qwen3-max，则不可填写 qwen-vl-max，否则触发 404 错误。
二、通过环境变量全局注入 API Key（适用于 systemd 启动场景）
当 OpenClaw Gateway 以用户级 systemd 服务方式运行时，它默认不读取 openclaw.json 中的 env 字段，必须在服务单元文件中显式导出环境变量，否则所有模型请求均会因认证失败而中断。
1、执行命令 systemctl --user edit openclaw-gateway.service 进入编辑模式。
2、在 [Service] 段落内添加以下两行：
Environment="DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Environment="NODE_ENV=production"
3、保存并退出后，执行 systemctl --user daemon-reload 重载配置。
4、重启服务：systemctl --user restart openclaw-gateway.service。
为 OpenClaw 创建可直接分流的 GitHub issue 草稿，用于报告代理缓慢、损坏、无响应、工具匮乏、性能下降或“不够智能”等问题。使用 ...
三、使用 OpenAI 兼容接口方式直连调用（无需 OpenClaw 框架）
该方法绕过 OpenClaw 的模型调度层，直接通过标准 OpenAI SDK 或 HTTP 请求对接 DashScope 的兼容接口，适用于快速验证 API 可用性或临时调试，不依赖 openclaw.json 配置。
1、安装 Python SDK：pip install openai（注意：此处使用官方 openai 库，非阿里云专属 SDK）。
2、编写调用脚本，将 base_url 替换为 DashScope 兼容地址：
https://dashscope.aliyuncs.com/compatible-mode/v1。
3、设置 model 参数为 qwen3-max 或 qwen-vl-max（需与百炼控制台已开通模型严格一致）。
4、发起请求时，确保请求头中包含 Authorization: Bearer sk-xxx，且 payload 中 messages 字段格式符合 OpenAI 标准。
四、校验模型注册状态与默认代理设置
OpenClaw 在启动时会扫描 providers 下所有模型并注册至内部 registry，若模型未出现在 agents.defaults.model.primary 中，或 primary 值拼写错误（如多空格、大小写不符），则默认不会启用该模型。
1、检查 "agents.defaults.model.primary" 的值是否为完整模型路径，例如 "dashscope/qwen3-max"，而非仅 "qwen3-max"。
2、确认 "agents.models" 下存在对应键名，如 "dashscope/qwen3-max":{}，空对象即可，缺失将导致初始化失败。
3、运行 openclaw status 命令，查看输出中 models 列表是否包含目标模型及其状态是否为 active。
4、若状态为 inactive，执行 openclaw restart 强制重载全部配置。
