第9章 - 自定义模型与阿里云百炼

嗨，朋友！这一章是重头戏——我来教你如何在 OpenClaw 中配置自定义 AI 模型，特别是使用**阿里云百炼（DashScope）**的国产大模型。对于国内用户来说，这可能是最实用的一章了！

🤔 为什么要自定义模型？

OpenClaw 默认使用 Anthropic Claude 或 OpenAI GPT，但这些模型对国内用户有几个痛点：

痛点	说明
网络问题	需要翻墙访问 API，不稳定
价格较高	Claude/GPT 的 API 费用不便宜
合规要求	某些场景需要使用国内模型

好消息是，OpenClaw 支持任何兼容 OpenAI API 格式的模型提供商！阿里云百炼的 DashScope 就完美兼容。

🌟 阿里云百炼（DashScope）简介

阿里云百炼是阿里云的 AI 模型服务平台，提供多种大模型：

模型	说明	上下文长度	推荐场景
qwen3-max	Qwen3 旗舰版	256K	复杂推理、长文本
qwen-plus	Qwen 增强版	128K	日常对话、代码生成
qwen-turbo	Qwen 快速版	128K	简单任务、低延迟
deepseek-v3.2	DeepSeek V3.2	64K	代码、数学推理

🔑 第一步：获取 DashScope API Key

1. 注册阿里云账号

如果你还没有阿里云账号，先去注册一个：阿里云官网

2. 开通百炼服务

访问阿里云百炼控制台，开通 DashScope 服务。

3. 创建 API Key

在控制台中找到 API Key 管理，创建一个新的 Key：

格式示例：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

重要

妥善保管你的 API Key，不要泄露给任何人，不要上传到 GitHub 等公开仓库！

4. 确认 API Base URL

DashScope 提供两种 API 格式，OpenClaw 必须使用 OpenAI 兼容格式：

类型	Base URL	是否可用
OpenAI 兼容	`https://dashscope.aliyuncs.com/compatible-mode/v1`	✅ 必须用这个
DashScope 原生	`https://dashscope.aliyuncs.com/api/v1`	❌ 不兼容

注意

这里很容易踩坑！一定要用 OpenAI 兼容模式的 URL，不要用 DashScope 原生 API 的 URL。

⚙️ 第二步：理解配置结构

在动手之前，先理解 OpenClaw 自定义模型配置的三大核心部分：

openclaw.json
├── models.providers      ← 第1步：定义模型提供商（API地址、Key、模型列表）
├── agents.defaults.models ← 第2步：注册模型到 Agent（让 Agent 知道有这个模型）
└── agents.defaults.model  ← 第3步：设置默认模型（告诉 Agent 优先用哪个）

这三个部分缺一不可，少配任何一个模型都不会生效。

🛠️ 第三步：编辑配置文件

配置文件位置：

~/.openclaw/openclaw.json

提示

建议使用 cat << 'EOF' 方式写入配置，不要用 nano 粘贴多行 JSON——nano 粘贴大段内容容易格式乱掉。

方案一：只用 DashScope（最简单）

如果你只想用阿里云百炼的模型，配置最简单：

cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "~/.openclaw/workspace",
      "models": {
        "dashscope/qwen3-max-2026-01-23": {}
      },
      "model": {
        "primary": "dashscope/qwen3-max-2026-01-23"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "你的gateway-token"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "models": {
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-你的DashScope密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-max-2026-01-23",
            "name": "Qwen3 Max",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
EOF

方案二：DashScope + Qwen Portal 免费模型（推荐）

Qwen Portal 提供免费的 Coder 和 Vision 模型，搭配 DashScope 付费模型使用更划算：

cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "~/.openclaw/workspace",
      "models": {
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "qwen-portal/vision-model": {},
        "dashscope/qwen3-max-2026-01-23": {}
      },
      "model": {
        "primary": "dashscope/qwen3-max-2026-01-23"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "你的gateway-token"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "plugins": {
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      }
    }
  },
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "qwen-oauth",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "reasoning": false,
            "input": ["text"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      },
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-你的DashScope密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-max-2026-01-23",
            "name": "Qwen3 Max",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "auth": {
    "profiles": {
      "qwen-portal:default": {
        "provider": "qwen-portal",
        "mode": "oauth"
      }
    }
  }
}
EOF

方案三：多个 DashScope 模型

你也可以在 DashScope 下注册多个模型，按需切换：

cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "agents": {
    "defaults": {
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "~/.openclaw/workspace",
      "models": {
        "dashscope/qwen3-max-2026-01-23": {},
        "dashscope/qwen-plus": {},
        "dashscope/qwen-turbo": {},
        "dashscope/deepseek-v3.2": {}
      },
      "model": {
        "primary": "dashscope/qwen3-max-2026-01-23"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "你的gateway-token"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "models": {
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-你的DashScope密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-max-2026-01-23",
            "name": "Qwen3 Max",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 256000,
            "maxTokens": 8192
          },
          {
            "id": "qwen-plus",
            "name": "Qwen Plus",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "qwen-turbo",
            "name": "Qwen Turbo",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "deepseek-v3.2",
            "name": "DeepSeek V3.2",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 65536,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
EOF

🔍 第四步：配置项详解

models.providers —— 定义提供商

{
  "models": {
    "providers": {
      "dashscope": {                                          // ← 提供商名称（自定义）
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",  // ← API 地址
        "apiKey": "sk-xxx",                                   // ← API Key
        "api": "openai-completions",                          // ← API 协议（固定值）
        "models": [                                           // ← 模型列表
          {
            "id": "qwen3-max-2026-01-23",                    // ← 模型 ID（用于引用）
            "name": "Qwen3 Max",                              // ← 显示名称
            "reasoning": false,                               // ← 是否推理模型
            "input": ["text"],                                // ← 输入类型
            "contextWindow": 256000,                          // ← 上下文窗口大小
            "maxTokens": 8192                                 // ← 最大输出 Token
          }
        ]
      }
    }
  }
}

agents.defaults.models —— 注册模型

{
  "agents": {
    "defaults": {
      "models": {
        "dashscope/qwen3-max-2026-01-23": {}      // ← 格式：提供商名/模型ID
      }
    }
  }
}

关键

格式是 提供商名称/模型ID，中间用斜杠分隔。例如 dashscope/qwen3-max-2026-01-23。这里的 dashscope 必须和 models.providers 中定义的名称一致。

agents.defaults.model —— 设置默认模型

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "dashscope/qwen3-max-2026-01-23"   // ← 默认使用的模型
      }
    }
  }
}

✅ 第五步：验证和启动

1. 验证 JSON 格式

cat ~/.openclaw/openclaw.json | python3 -m json.tool

如果输出格式化的 JSON 表示格式正确，如果报错则需要检查 JSON 语法。

2. 清除旧会话（切换模型后建议执行）

rm -rf ~/.openclaw/workspace/sessions/*

3. 启动 TUI

openclaw tui

4. 检查状态栏

启动后，底部状态栏应显示你配置的模型：

agent main | session main | dashscope/qwen3-max-2026-01-23 | tokens xxx/256k

注意

如果状态栏显示的是 anthropic/qwen3-max-2026-01-23 而不是 dashscope/qwen3-max-2026-01-23，说明 agents.defaults.models 中的注册配置有误，dashscope 这个前缀必须和 models.providers 中的 key 完全一致。

5. 开启新对话测试

# 开启全新对话
openclaw tui --session new

在 TUI 中输入任意问题，测试模型是否正常响应。

🔄 使用 Qwen Portal 免费模型

除了 DashScope 付费模型，Qwen Portal 还提供完全免费的模型：

配置 Qwen Portal OAuth

使用 Qwen Portal 需要进行 OAuth 认证：

# 初始化时会自动引导 OAuth
openclaw init

认证步骤：

终端会显示一个授权 URL
在浏览器中打开：https://chat.qwen.ai/authorize?user_code=XXX&client=qwen-code
登录并授权
终端显示 Qwen OAuth complete 即成功

Qwen Portal 配置

{
  "plugins": {
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      }
    }
  },
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "qwen-oauth",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "reasoning": false,
            "input": ["text"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "auth": {
    "profiles": {
      "qwen-portal:default": {
        "provider": "qwen-portal",
        "mode": "oauth"
      }
    }
  }
}

注册 Qwen Portal 模型

{
  "agents": {
    "defaults": {
      "models": {
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "qwen-portal/vision-model": {}
      }
    }
  }
}

"alias": "qwen" 表示你可以在对话中用 @qwen 来快速切换到这个模型。

🌐 通过 Web UI 远程调试

如果 OpenClaw 运行在远程服务器上，你可以通过 SSH 隧道在本地浏览器中调试：

1. 建立 SSH 隧道

在本地电脑上运行：

ssh -L 18789:127.0.0.1:18789 你的用户名@你的服务器IP

2. 获取 Dashboard 链接

在远程服务器上运行：

openclaw dashboard --no-open

系统会输出带 token 的链接：

Dashboard URL: http://127.0.0.1:18789/?token=你的token值

3. 本地浏览器访问

将链接粘贴到本地浏览器，就可以通过图形界面操作了：

http://localhost:18789/?token=你的token值

提示

如果 token 显示 undefined，运行 openclaw configure --section gateway 重新配置 Gateway Token。

⚠️ 常见问题

Q1: 模型无响应（超时）

原因：配置不一致

排查步骤：

确认 agents.defaults.model.primary 的值与 models.providers 中定义的 提供商名/模型ID 完全一致
确认 baseUrl 使用的是 OpenAI 兼容模式 URL
确认 API Key 正确且有余额

# 测试 API 连通性
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3-max-2026-01-23","messages":[{"role":"user","content":"你好"}]}'

Q2: 状态栏显示错误的 provider 前缀

原因：agents.defaults.models 中的 key 和 models.providers 中的 key 不一致

解决：确保两处使用完全相同的提供商名称，例如都是 dashscope

Q3: JSON 配置格式错误

症状：Gateway 启动失败或行为异常

预防：

# 写入前先验证
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# 如果报错，常见原因：
# - 多余的逗号（最后一项后面不要加逗号）
# - 缺少引号
# - 括号不匹配

建议：不要用 nano 编辑器粘贴大段 JSON，用 cat << 'EOF' 方式整体写入更可靠。

Q4: 国内服务器安装 OpenClaw 慢

# 使用淘宝 npm 镜像
npm i -g clawdbot --registry=https://registry.npmmirror.com

# 如果遇到 GitHub SSH 权限问题
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

📊 DashScope 可用模型参考

模型 ID	名称	上下文	推荐用途
`qwen3-max-2026-01-23`	Qwen3 Max	256K	复杂推理、长文本处理
`qwen-plus`	Qwen Plus	128K	日常对话、通用任务
`qwen-turbo`	Qwen Turbo	128K	简单任务、低延迟
`deepseek-v3.2`	DeepSeek V3.2	64K	代码生成、数学推理

省钱建议

日常简单对话用 qwen-turbo（最便宜）
通用任务用 qwen-plus（性价比高）
复杂任务用 qwen3-max（效果最好）
代码相关用 Qwen Portal 的 coder-model（免费）

💡 长安的配置建议

作为过来人，我给你几点实用建议：

先用免费模型试手 - Qwen Portal 的 coder-model 和 vision-model 完全免费，先熟悉 OpenClaw 再花钱
备份配置文件 - 每次修改 openclaw.json 前先备份：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
切换模型后清会话 - rm -rf ~/.openclaw/workspace/sessions/* 避免旧会话干扰
用 cat 写配置 - 不要用 nano 粘贴 JSON，用 cat << 'EOF' 方式更可靠
测试 API 连通性 - 修改配置后先用 curl 测试 API 是否能正常调用

💪 练习题

OpenClaw 自定义模型需要配置哪三个部分？各自的作用是什么？
DashScope 的 OpenAI 兼容 API URL 是什么？为什么不能用原生 API URL？
尝试在配置中同时添加 qwen3-max 和 qwen-turbo，并将 qwen3-max 设为默认模型。

答案提示

三个部分：models.providers（定义提供商和模型）、agents.defaults.models（注册模型到 Agent）、agents.defaults.model（设置默认模型）。缺一不可。
URL 是 https://dashscope.aliyuncs.com/compatible-mode/v1。因为 OpenClaw 使用 OpenAI 兼容协议调用模型，原生 DashScope API 格式不兼容。
参考方案三的配置示例，在 models 数组中添加两个模型，在 agents.defaults.models 中注册两个，在 model.primary 中设为 dashscope/qwen3-max-2026-01-23。

相关链接：

下一步: 回到最佳实践学习更高级的用法。