本文档介绍如何将 Hermes Agent 配置使用阿里云 DashScope（通义千问）作为推理后端，包括 Credential Pool（凭证池）多 Key 轮询配置。
目录
- 环境要求
- 配置步骤
- [Credential Pool 多 Key 配置](#Credential Pool 多 Key 配置)
- [Coding Plan 配置](#Coding Plan 配置)
- [国内版 vs 国际版](#国内版 vs 国际版)
- 常用模型列表
- 使用方法
- 故障排查
环境要求
- Hermes Agent 已安装（位于
~/.hermes/hermes-agent/） - Python 3.11+
- 阿里云 DashScope API Key（可在 阿里云 DashScope 控制台 获取）
配置步骤
Step 1: 配置环境变量
编辑 ~/.hermes/.env 文件（如果不存在，从 .env.example 复制）：
bash
# 阿里 DashScope API Key（国内版）
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# Coding Plan API Key（可选，用于 coder 模型）
ALIBABA_CODING_PLAN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ALIBABA_CODING_PLAN_BASE_URL=https://coding.dashscope.aliyuncs.com/v1注意 :
.env文件权限应设为600（仅 owner 可读）：
bashchmod 600 ~/.hermes/.env
Step 2: 配置 config.yaml
编辑 ~/.hermes/config.yaml：
yaml
model: qwen-plus # 默认模型
providers:
alibaba:
api_key_env: DASHSCOPE_API_KEY
base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
credential_pool_strategies:
alibaba: round_robin # 多 Key 轮询策略Step 3: 验证配置
bash
hermes config check输出应显示：
✓ DASHSCOPE_API_KEY
✓ DASHSCOPE_BASE_URLCredential Pool 多 Key 配置
Hermes 支持 Credential Pool（凭证池），可以为同一个 Provider 配置多个 API Key，实现：
- 轮询使用（round_robin）- 依次使用各个 Key
- 故障转移（failover）- 主 Key 失败时切换到备用 Key
- 负载均衡 - 分散请求避免单 Key 限流
添加多个 Key
bash
# 添加第一个 Key
hermes auth add alibaba --type api-key --api-key "sk-xxxx1" --label "dashscope-key-1"
# 添加第二个 Key
hermes auth add alibaba --type api-key --api-key "sk-xxxx2" --label "dashscope-key-2"
# 添加更多 Key...
hermes auth add alibaba --type api-key --api-key "sk-xxxx3" --label "dashscope-key-3"查看已添加的 Credentials
bash
hermes auth list输出：
alibaba (3 credentials):
#1 dashscope-key-1 api_key manual ←
#2 dashscope-key-2 api_key manual
#3 dashscope-key-3 api_key manual配置轮询策略
在 ~/.hermes/config.yaml 中设置：
yaml
credential_pool_strategies:
alibaba: round_robin # 或 failoverCoding Plan 配置
阿里云 Coding Plan 提供专门的代码生成模型（如 qwen3-coder-plus），适合编程场景。
配置方法
bash
# 添加 Coding Plan Key
hermes auth add alibaba-coding-plan --type api-key --api-key "sk-xxxx" --label "coding-plan-key"使用 Coding 模型
bash
hermes chat -q "写一个 Python 快速排序函数" -m qwen3-coder-plus国内版 vs 国际版
| 版本 | API Endpoint | 适用场景 |
|---|---|---|
| 国内版 | dashscope.aliyuncs.com |
国内用户，无需代理 |
| 国际版 | dashscope-intl.aliyuncs.com |
海外用户，需要国际版 Key |
注意 : 国内版和国际版的 API Key 不互通，请根据你的 Key 类型选择正确的 endpoint。
国内版配置
bash
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
ALIBABA_CODING_PLAN_BASE_URL=https://coding.dashscope.aliyuncs.com/v1国际版配置
bash
DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
ALIBABA_CODING_PLAN_BASE_URL=https://coding-intl.dashscope.aliyuncs.com/v1常用模型列表
通用对话模型
| 模型 ID | 说明 |
|---|---|
qwen-turbo |
快速响应，成本低 |
qwen-plus |
平衡性能与成本（推荐） |
qwen-max |
最强通用模型 |
qwen3-max |
Qwen3 系列最强 |
qwen3.5-plus |
Qwen3.5 平衡版 |
qwen3.7-max |
Qwen3.7 最新旗舰 |
代码生成模型
| 模型 ID | 说明 |
|---|---|
qwen-coder-plus |
代码生成优化 |
qwen-coder-turbo |
快速代码生成 |
qwen3-coder-plus |
Qwen3 代码版 |
qwen3-coder-next |
Qwen3 代码版 Next |
推理模型
| 模型 ID | 说明 |
|---|---|
qwq-plus |
推理增强版 |
deepseek-r1 |
DeepSeek 推理模型 |
deepseek-v3 |
DeepSeek V3 |
其他模型
DashScope 还提供：
- 视觉模型 :
qwen-vl-max,qwen-vl-plus - 数学模型 :
qwen-math-plus,qwen-math-turbo - 语音模型 :
qwen-tts-*,qwen3-tts-* - 第三方模型 :
glm-5,kimi-k2.5,MiniMax-M2.5
使用方法
交互式聊天
bash
hermes chat单次查询
bash
hermes chat -q "解释什么是递归" -m qwen-plus指定模型
bash
hermes chat -m qwen3-coder-plus -q "写一个 React 组件"切换默认模型（交互式）
bash
hermes model静默模式（适合脚本调用）
bash
hermes chat -q "你的问题" -Q故障排查
问题: "No inference provider configured"
原因 : .env 文件未正确配置或位置不对
解决方案:
bash
# 确保 .env 在正确位置
cp ~/.hermes/hermes-agent/.env ~/.hermes/.env
chmod 600 ~/.hermes/.env
# 验证配置
hermes config check问题: API Key 认证失败 (401)
原因: Key 类型与 endpoint 不匹配（国内版 Key 用了国际版 endpoint）
解决方案 :
检查你的 Key 是国内版还是国际版，设置正确的 DASHSCOPE_BASE_URL。
问题: 模型不可用
原因: 模型名称错误或该模型需要特定 Key
解决方案:
bash
# 查看可用模型
curl -H "Authorization: Bearer sk-xxxx" \
https://dashscope.aliyuncs.com/compatible-mode/v1/models查看 Credential Pool 状态
bash
hermes auth status alibaba配置文件示例
~/.hermes/.env
bash
# 阿里 DashScope（国内版）
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# Coding Plan
ALIBABA_CODING_PLAN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ALIBABA_CODING_PLAN_BASE_URL=https://coding.dashscope.aliyuncs.com/v1~/.hermes/config.yaml（关键配置）
yaml
model: qwen-plus
providers:
alibaba:
api_key_env: DASHSCOPE_API_KEY
base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
credential_pool_strategies:
alibaba: round_robin
terminal:
backend: local
cwd: .
timeout: 180相关链接
📝 提示: Credential Pool 功能让你的 API Key 使用更加灵活，当某个 Key 达到限额时会自动切换，提高服务的可用性。