OpenClaw 接入阿里云百炼（DashScope）完整踩坑指南OpenClaw 接入阿里云百炼（DashScope）

OpenClaw 接入阿里云百炼（DashScope）完整踩坑指南

环境：Ubuntu 22.04 / WSL2 | OpenClaw 2026.3.24 | 阿里云百炼平台

结论先说：不要用 OpenClaw 内置的 modelstudio provider，改用自定义 dashscope provider，API Key 直接写在 openclaw.json 的 models.providers 里。

一、背景

OpenClaw 是一个开源的 AI 代理框架，支持多种大模型。官方内置了 modelstudio provider 用于接入阿里云模型，但实际配置过程中遇到了很多坑。

本文记录了从零开始配置 OpenClaw + 阿里云百炼 API Key 的完整过程，以及遇到的各类报错和最终解决方案。

二、安装 OpenClaw

# 全局安装（需要 Node.js 18+）
npm install -g @anthropic-ai/openclaw

# 或者使用官方安装脚本
curl -fsSL https://get.openclaw.ai | bash

安装完成后，运行引导流程：

openclaw onboard

引导过程中会提示选择认证方式。如果你有阿里云百炼的 API Key，可以选择 modelstudio-api-key-cn（中国区）。

三、获取阿里云百炼 API Key

访问阿里云百炼控制台
登录后进入 API-KEY 管理
点击 创建 API Key
复制生成的 Key（格式：sk-xxxxxxxxxxxxxxxxxxxxxxxx）

⚠️ 注意：百炼 API Key 和阿里云 Model Studio 的 API Key 是不同的服务！OpenClaw 内置的 modelstudio provider 指向的是 coding.dashscope.aliyuncs.com，而百炼兼容模式使用的是 dashscope.aliyuncs.com/compatible-mode/v1。这就是后续报错的根本原因。

四、用 curl 验证 API Key 是否有效

在配置 OpenClaw 之前，先用 curl 测试你的 API Key：

curl -X POST "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions" \
  -H "Authorization: Bearer sk-你的API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-turbo","messages":[{"role":"user","content":"你好"}]}'

如果返回正常的 JSON 响应（包含 AI 回复内容），说明 Key 没问题。

五、配置过程（踩坑实录）

坑 1：`modelstudio` provider 找不到 API Key

按照 OpenClaw 引导流程选择 modelstudio-api-key-cn 后，TUI 启动报错：

Agent failed before reply: No API key found for provider "modelstudio".
Auth store: /home/用户名/.openclaw/agents/main/agent/auth-profiles.json

尝试过的方案（全部失败）：

方案	说明	结果
`auth-profiles.json` 写 API Key	在 agent 目录下的认证文件里写	❌ 不认
环境变量 `MODELSTUDIO_API_KEY`	`export MODELSTUDIO_API_KEY=sk-...`	❌ 不认
`~/.openclaw/.env` 文件	写入 `.env` 文件	❌ 不认
`openclaw.json` 的 `env` 字段	`env.MODELSTUDIO_API_KEY`	❌ 不认
`openclaw config set auth.profiles.xxx`	CLI 设置认证	❌ apiKey 字段不被接受
重新走 `openclaw onboard`	再次引导配置	❌ 依然不行

坑 2：修改 baseUrl 后出现 HTTP 401

发现 modelstudio 的默认 baseUrl 是 coding.dashscope.aliyuncs.com/v1（阿里云 Model Studio 专用），手动改成百炼兼容模式的 dashscope.aliyuncs.com/compatible-mode/v1 后：

HTTP 401: Invalid access token or token expired

说明请求确实到达了百炼服务器，但 modelstudio provider 的认证逻辑和百炼平台不兼容。

坑 3：`openai-compatible` provider 报 Unknown model

尝试用 openai-compatible provider：

Agent failed before reply: Unknown model: openai-compatible/qwen-turbo.

OpenClaw 不允许直接使用内置的 openai-compatible provider。

六、最终解决方案 ✅

核心思路：创建一个自定义 provider，名字不跟内置的冲突，直接在 models.providers 里配置 baseUrl + apiKey。

步骤 1：编辑 `~/.openclaw/openclaw.json`

在 models.providers 下添加自定义 provider dashscope：

{
  "models": {
    "mode": "merge",
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-你的API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen-turbo",
            "name": "qwen-turbo",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 100000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "dashscope/qwen-turbo"
      },
      "models": {
        "dashscope/qwen-turbo": {
          "alias": "Qwen"
        }
      }
    }
  }
}

步骤 2：清理旧 Session

rm -rf ~/.openclaw/agents/main/sessions/

这一步很重要！旧的 Session 会缓存之前的模型配置。

步骤 3：重启并启动 TUI

pkill -f openclaw
openclaw tui

步骤 4：验证

启动 TUI 后，底部状态栏应显示：

agent main | session main (openclaw-tui) | dashscope/qwen-turbo | tokens ?/100k

输入消息，如果能正常收到 AI 回复，说明配置成功！🎉

七、如果你想用其他模型

百炼平台支持多种模型，只需要在 models 数组里添加即可：

{
  "id": "qwen-plus",
  "name": "qwen-plus",
  "reasoning": false,
  "input": ["text", "image"],
  "contextWindow": 131072,
  "maxTokens": 8192
}

然后切换默认模型：

"model": { "primary": "dashscope/qwen-plus" }

常用模型推荐：

模型 ID	说明	上下文窗口	适合场景
`qwen-turbo`	快速响应	100K	日常对话、简单任务
`qwen-plus`	均衡性能	131K	通用场景
`qwen-max`	最强性能	32K	复杂推理、长文本
`qwen-coder-plus`	代码专用	1M	编程辅助

八、关键经验总结

为什么 `modelstudio` provider 不好使？

服务端点不同：modelstudio 指向 coding.dashscope.aliyuncs.com（阿里云 Model Studio），而百炼平台用的是 dashscope.aliyuncs.com/compatible-mode/v1
认证机制不同：modelstudio 可能有自己的认证流程，不兼容百炼的 API Key
API Key 存储位置：modelstudio 的认证配置方式特殊，auth-profiles.json、环境变量、openclaw.json 的 env 字段都试过，都不行

自定义 Provider 为什么能成功？

完全控制 baseUrl：直接指向百炼兼容模式
API Key 直接写在 provider 里：不需要依赖 auth-profiles.json 或环境变量
避免了内置 provider 的各种限制：用自定义名称不会和 OpenClaw 内置逻辑冲突

一句话总结

不要用 OpenClaw 内置的 modelstudio provider 接入阿里云百炼，改用自定义 provider + OpenAI 兼容模式，API Key 直接写在 openclaw.json 的 models.providers 里。

九、常见问题 FAQ

Q: 启动 TUI 后底部状态栏还显示旧模型？

清理 Session 缓存：

rm -rf ~/.openclaw/agents/main/sessions/

Q: 报 `No API key found for provider "xxx"`？

确保 apiKey 字段写在 openclaw.json 的 models.providers.xxx 对象里，而不是 auth-profiles.json 或其他地方。

Q: 报 `Unknown model: xxx`？

确保：

Provider 名称在 models.providers 中存在
模型 ID 在该 provider 的 models 数组中存在
格式为 provider/model-id

Q: 如何切换模型？

在 TUI 中按 Ctrl+M 或使用命令：

openclaw models set dashscope/qwen-plus

十、参考链接

本文基于 OpenClaw 2026.3.24 版本编写，后续版本可能有变化。

OpenClaw 接入阿里云百炼（DashScope）完整踩坑指南