中文
中文English日本語

OpenClaw 接入豆包大模型 & Telegram Bot 配置说明

作者： /

一、环境与前提

  • OpenClaw 运行方式：Docker（gateway 容器）
  • 大模型平台：火山方舟（Ark / 豆包）
  • 接入方式：OpenAI Chat Completions 兼容接口
  • 通信渠道：Telegram Bot（私聊）

二、问题背景与根因总结

1️⃣ 初始问题现象

  • Telegram Bot 可以收消息，但返回错误：404 The model or endpoint ... does not exist or you do not have access to it
  • 直接使用 doubao-lite-4k-240328 等 model id 调用失败

2️⃣ 根本原因（两个关键点）

（1）豆包 模型 ID ≠ 可调用推理入口

  • /models 返回的 doubao-lite-4k-240328 等 模型 ID
  • 实际推理必须使用 Endpoint ID（ep-xxxx）
  • 未创建 / 未使用 endpoint → 一律 404

（2）OpenClaw API 类型配置错误

  • 早期使用了："api": "openai-completions"
  • 但豆包是 聊天模型，必须走：POST /chat/completions

三、正确验证路径（关键）

1️⃣ 使用 Endpoint ID 直接 curl 验证（成功）

curl -sS https://ark.cn-beijing.volces.com/api/v3/chat/completions \
  -H "Authorization: Bearer <ARK_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"ep-20251031171004-t2qcf",
    "messages":[{"role":"user","content":"ping"}]
  }'

返回正常内容 ⇒ endpoint + region + key 均正确

四、OpenClaw 配置修改（核心）

文件路径（宿主机）：

~/.openclaw/openclaw.json

一共需要改 3 个地方，必须保持一致

① models.providers.doubao.models[].id

从模型 ID → Endpoint ID

"models": [
  {
    "id": "ep-20251031171004-t2qcf",
    "name": "Doubao",
    "reasoning": false,
    "input": ["text"],
    "contextWindow": 128000,
    "maxTokens": 8192
  }
]

并确认：

"api": "openai-completions"

② agents.defaults.model.primary

"primary": "doubao/ep-20251031171004-t2qcf"

③ agents.defaults.models 的 key

"models": {
  "doubao/ep-20251031171004-t2qcf": {
    "alias": "Doubao"
  }
}

✅ 修改后完整逻辑

  • OpenClaw 内部统一引用：doubao/ep-20251031171004-t2qcf
  • 实际请求路径：/chat/completions
  • Ark 后端：endpoint → 底层模型（如 doubao-seed-1-6-lite-251015）

五、Telegram Bot 配置说明（确认有效）

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "<YOUR_BOT_TOKEN>",
    "dmPolicy": "pairing",
    "allowFrom": [8434826952],
    "groupPolicy": "disabled",
    "streamMode": "partial"
  }
}

关键字段说明

  • enabled: true：必须显式开启
  • dmPolicy: pairing：私聊需配对（安全）
  • allowFrom：允许的用户 ID（白名单）
  • groupPolicy: disabled：禁用群，避免误触发
  • streamMode: partial：流式输出（推荐）

六、容器与生效方式

1️⃣ 校验 JSON

jq . ~/.openclaw/openclaw.json

2️⃣ 重启 gateway

docker restart openclaw-openclaw-gateway-1

3️⃣ Telegram 私聊 Bot 测试

  • 能正常回复 ⇒ 全链路生效

七、重要经验总结（避坑）

  1. 豆包必须用 endpoint（ep-xxxx），不能直接用 model id
  2. OpenClaw 必须用 openai-chat-completions
  3. /models 能看到 ≠ 可推理
  4. Region 必须一致（endpoint 在北京，就用 ark.cn-beijing）
  5. agents.defaults.model.primary 和 models.providers 必须一致，否则隐性 404

八、当前状态

  • ✅ 大模型推理正常
  • ✅ Telegram Bot 对话正常
  • ✅ OpenClaw 配置稳定可复用
滚动至顶部