🔧 Hermes Agent 配置阿里云百炼 (Bailian) 完整教程

📋 目录

1. 背景与问题
2. 前置条件
3. 解决方案
4. 详细配置步骤
5. 测试验证
6. 常见问题
7. 配置模板

1️⃣ 背景与问题

Hermes Agent 是 Nous Research 开发的开源 AI 助手框架， 支持持久化记忆、自主技能创建和多平台集成。官方文档中提到的 LLM 提供商包括 OpenRouter、Anthropic、Gemini 等， 但没有直接提到阿里云百炼 (Bailian)。

经过排查发现：

• Hermes v0.8.0 的 CLI 不支持 openai provider（只有 openrouter）
• 环境变量 OPENAI_BASE_URL 不会被读取
• 但支持 OPENROUTER_BASE_URL！

2️⃣ 前置条件

2.1 阿里云百炼账号

1. 访问 阿里云百炼控制台
2. 登录/注册阿里云账号
3. 完成实名认证（需要）
4. 开通百炼服务

2.2 获取 API Key

1. 进入 API 管理页面
2. 点击「创建 API Key」
3. 复制并安全保存（只显示一次！）

2.3 环境要求

• Docker 和 Docker Compose
• Linux/macOS/WSL2
• 网络连接（能访问阿里云 API）

3️⃣ 解决方案

关键发现：Hermes 使用 OPENROUTER_BASE_URL 环境变量来支持自定义 OpenAI 兼容端点。

# ❌ 错误（不会被读取）
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://coding.dashscope.aliyuncs.com/v1

# ✅ 正确（Hermes 会读取）
OPENROUTER_API_KEY=sk-xxx
OPENROUTER_BASE_URL=https://coding.dashscope.aliyuncs.com/v1

4️⃣ 详细配置步骤

4.1 创建目录结构

mkdir -p ~/hermes-agent/data
mkdir -p ~/hermes-agent/home/.hermes
mkdir -p ~/hermes-agent/memory

4.2 创建环境变量文件

cat > ~/hermes-agent/data/.env << 'EOF'
# 阿里云百炼 API 配置
# 注意：必须使用 OPENROUTER_ 前缀！
OPENROUTER_API_KEY=sk-your-api-key-here
OPENROUTER_BASE_URL=https://coding.dashscope.aliyuncs.com/v1

# 可选：同时设置 DASHSCOPE 变量（某些情况需要）
DASHSCOPE_API_KEY=sk-your-api-key-here
DASHSCOPE_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
EOF

4.3 复制到家目录

cp ~/hermes-agent/data/.env ~/hermes-agent/home/.hermes/.env

4.4 创建配置文件

cat > ~/hermes-agent/data/config.yaml << 'EOF'
# Hermes Agent 配置文件
# 阿里云百炼 (Bailian) 配置

llm:
  provider: openrouter  # 必须写 openrouter
  model: qwen3.5-plus   # 模型名称（后续用命令设置）
  base_url: https://coding.dashscope.aliyuncs.com/v1

agent:
  name: Hermes
  persona: Helpful AI assistant

memory:
  enabled: true

channels:
  cli:
    enabled: true

gateway:
  enabled: false

compression:
  enabled: false
EOF

4.5 启动 Docker 容器

docker run -d --name hermes-agent \
  --restart unless-stopped \
  --env OPENROUTER_API_KEY=sk-your-api-key-here \
  --env OPENROUTER_BASE_URL=https://coding.dashscope.aliyuncs.com/v1 \
  -v ~/hermes-agent/data:/opt/data \
  -v ~/hermes-agent/home/.hermes:/root/.hermes \
  -v ~/hermes-agent/memory:/root/.local/share/hermes/memory \
  -it nousresearch/hermes-agent:latest

4.6 设置模型

# 等待容器启动
sleep 5

# 设置模型（必须！）
docker exec hermes-agent hermes config set model qwen3.5-plus

# 验证配置
docker exec hermes-agent hermes status

5️⃣ 测试验证

5.1 交互式对话

docker exec -it hermes-agent hermes chat

进入交互模式后，输入测试问题：

你好，你是谁？

5.2 单次查询

docker exec hermes-agent hermes chat -q '你好，简单回答你是谁'

5.3 预期输出

Query: 你好，简单回答你是谁
Initializing agent...

╭─ ⚕ Hermes ───────────────────────────────────────────────────────────╮
我是 Hermes Agent，一个运行在终端中的 CLI AI 助手。我可以帮你执行各种任务，
比如：

- 文件操作（读写、搜索、编辑）
- 网页浏览和交互
- 代码执行和调试
- 系统命令运行
- 任务自动化和调度
- 以及更多...

有什么需要帮忙的吗？
╰──────────────────────────────────────────────────────────────────────╯

6️⃣ 常见问题

Q1: API call failed [HTTP 401]

原因：环境变量未正确设置

解决：

# 检查环境变量是否生效
docker exec hermes-agent env | grep OPENROUTER

# 应该看到：
# OPENROUTER_API_KEY=sk-xxx
# OPENROUTER_BASE_URL=https://coding.dashscope.aliyuncs.com/v1

Q2: model `` is not supported

原因：模型名称未设置

解决：

docker exec hermes-agent hermes config set model qwen3.5-plus

Q3: 仍然访问 openrouter.ai

原因：使用了 OPENAI_BASE_URL 而不是 OPENROUTER_BASE_URL

解决：重启容器并确保使用正确的环境变量名

Q4: Bailian API 返回 400 错误

可能原因：

• API Key 无效或过期
• 模型名称不正确（尝试 qwen3.5-plus 或 qwen-plus）
• 账户余额不足

7️⃣ 配置模板

完整 Docker Compose 配置

version: '3.8'

services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    environment:
      - OPENROUTER_API_KEY=sk-your-api-key-here
      - OPENROUTER_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
    volumes:
      - ~/hermes-agent/data:/opt/data
      - ~/hermes-agent/home/.hermes:/root/.hermes
      - ~/hermes-agent/memory:/root/.local/share/hermes/memory
    stdin_open: true
    tty: true

环境变量参考

可用模型列表

阿里云百炼支持的模型（部分）：

• qwen3.5-plus - 通义千问 3.5 Plus（推荐）
• qwen-plus - 通义千问 Plus
• qwen-turbo - 通义千问 Turbo（快速）
• qwen-max - 通义千问 Max（最强）

🎉 总结

通过本文，你应该已经成功将阿里云百炼配置到 Hermes Agent。关键点是使用 OPENROUTER_BASE_URL 而不是 OPENAI_BASE_URL。

Hermes Agent 的强大之处在于它的自我改进能力和持久化记忆。配合百炼的 qwen3.5-plus 模型，你可以在本地运行一个强大的 AI 助手。