MoltBot 配置 API 代理: 3 步接入 Claude Opus 等多模型完整教程

想让 MoltBot 接入 Claude Opus 4.5 或其他大模型,却不知道如何配置 API 代理? 本文将手把手教你完成 MoltBot 多 Provider 配置,让你的 AI 助手同时接入多个模型服务,实现智能切换和容灾备份。

核心价值: 读完本文,你将掌握 MoltBot 的 models.providers 配置方法,学会设置主模型、备用模型和模型别名,打造稳定可靠的 AI 助手。

MoltBot API 代理配置: 核心概念解析

MoltBot 支持通过 OpenAI Compatible API 接入几乎所有主流大模型服务。理解以下核心概念,是配置成功的关键。

MoltBot 配置文件体系

MoltBot Provider 配置核心字段

每个 Provider 配置包含以下关键字段:

API 协议类型说明

MoltBot 支持两种主流的 OpenAI 兼容协议:

🎯 配置建议: 大多数 API 代理服务 (如 API易 apiyi.com) 使用 openai-completions 协议。如果你使用的是本地部署的 LM Studio 或 Ollama,则需要使用 openai-responses。

MoltBot 多 Provider 配置: 完整示例

下面是一个实际可用的多 Provider 配置示例,同时接入 API易 和 Qwen Portal 两个服务:

完整配置文件示例

{
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "${QWEN_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "coder-model", "name": "Qwen Coder", "contextWindow": 128000 },
          { "id": "vision-model", "name": "Qwen Vision", "contextWindow": 128000 }
        ]
      },
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5", "contextWindow": 200000 },
          { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4", "contextWindow": 200000 },
          { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000 }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101",
        "fallbacks": ["qwen-portal/vision-model"]
      },
      "models": {
        "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
        "apiyi/claude-sonnet-4-20250514": { "alias": "sonnet" },
        "qwen-portal/coder-model": { "alias": "qwen" }
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

配置结构详解

1. models.providers 部分

这是定义 API 代理服务的核心部分:

"providers": {
  "apiyi": {
    "baseUrl": "https://api.apiyi.com/v1",
    "apiKey": "${APIYI_API_KEY}",
    "api": "openai-completions",
    "models": [...]
  }
}

• Provider ID (apiyi): 自定义的服务标识,后续引用时使用
• baseUrl: API 端点,必须以 /v1 结尾
• apiKey: 支持直接填写或使用 ${ENV_VAR} 环境变量
• models: 该 Provider 支持的模型列表

2. agents.defaults.model 部分

定义默认使用的模型和容灾策略:

"model": {
  "primary": "apiyi/claude-opus-4-5-20251101",
  "fallbacks": ["qwen-portal/vision-model"]
}

• primary: 主模型,格式为 provider-id/model-id
• fallbacks: 备用模型数组,主模型失败时自动切换

3. agents.defaults.models 部分

定义模型别名,方便快速切换:

"models": {
  "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
  "qwen-portal/coder-model": { "alias": "qwen" }
}

配置别名后,可以在对话中使用 /model opus 快速切换模型。

MoltBot API 代理配置: 分步教程

第一步: 获取 API Key

在配置之前,你需要准备好 API Key:

🚀 快速开始: 推荐使用 API易 apiyi.com 作为主要 Provider,一个 API Key 即可调用 Claude、GPT、Gemini 等主流模型,无需分别注册多个平台。

第二步: 设置环境变量

为了安全起见,建议使用环境变量存储 API Key:

# Linux/macOS - 添加到 ~/.bashrc 或 ~/.zshrc
export APIYI_API_KEY="sk-your-apiyi-key"
export QWEN_API_KEY="your-qwen-key"
export TELEGRAM_BOT_TOKEN="your-telegram-token"

# 使配置生效
source ~/.bashrc

# Windows PowerShell
$env:APIYI_API_KEY = "sk-your-apiyi-key"
$env:QWEN_API_KEY = "your-qwen-key"
$env:TELEGRAM_BOT_TOKEN = "your-telegram-token"

第三步: 编辑配置文件

打开或创建 MoltBot 配置文件:

# 打开配置文件
nano ~/.moltbot/moltbot.json

# 或使用 VS Code
code ~/.moltbot/moltbot.json

将以下配置粘贴到文件中:

{
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 200000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101"
      }
    }
  }
}

第四步: 验证配置

重启 MoltBot 并验证配置是否生效:

# 重启 MoltBot
moltbot restart

# 检查当前模型配置
moltbot models list

# 测试模型调用
moltbot chat "你好,请告诉我你是什么模型"

{
  "models": {
    "mode": "merge",
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "Claude Opus 4.5",
            "contextWindow": 200000,
            "maxTokens": 32000
          },
          {
            "id": "claude-sonnet-4-20250514",
            "name": "Claude Sonnet 4",
            "contextWindow": 200000,
            "maxTokens": 64000
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "contextWindow": 128000,
            "maxTokens": 16384
          },
          {
            "id": "gemini-2.5-pro",
            "name": "Gemini 2.5 Pro",
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      },
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "${QWEN_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "contextWindow": 128000
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "contextWindow": 128000
          }
        ]
      },
      "local-ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "llama3.3:70b",
            "name": "Llama 3.3 70B",
            "contextWindow": 128000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "apiyi/claude-opus-4-5-20251101",
        "fallbacks": [
          "apiyi/claude-sonnet-4-20250514",
          "qwen-portal/vision-model",
          "local-ollama/llama3.3:70b"
        ]
      },
      "models": {
        "apiyi/claude-opus-4-5-20251101": {
          "alias": "opus",
          "params": { "temperature": 0.7 }
        },
        "apiyi/claude-sonnet-4-20250514": {
          "alias": "sonnet",
          "params": { "temperature": 0.5 }
        },
        "apiyi/gpt-4o": {
          "alias": "gpt"
        },
        "qwen-portal/coder-model": {
          "alias": "qwen"
        },
        "local-ollama/llama3.3:70b": {
          "alias": "llama"
        }
      },
      "imageModel": "apiyi/gpt-4o"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    },
    "discord": {
      "enabled": false,
      "token": "${DISCORD_BOT_TOKEN}"
    }
  }
}

💡 配置技巧: 使用 "mode": "merge" 可以保留 MoltBot 内置的模型配置,同时添加你的自定义 Provider。这样即使自定义服务不可用,也能回退到默认配置。

MoltBot 模型配置: 高级参数详解

模型条目完整字段

模型参数配置 (params)

在 agents.defaults.models 中可以为每个模型设置默认参数:

"models": {
  "apiyi/claude-opus-4-5-20251101": {
    "alias": "opus",
    "params": {
      "temperature": 0.7,
      "maxTokens": 16000
    }
  }
}

⚠️ 注意: temperature 是高级参数,除非你了解模型的默认设置并确实需要调整,否则建议不要设置。

MoltBot Fallback 容灾配置

Fallback 机制是 MoltBot 的重要特性,确保 AI 助手始终可用。

Fallback 工作原理

用户请求
    ↓
主模型 (primary)
    ↓ (失败)
备用模型 1 (fallbacks[0])
    ↓ (失败)
备用模型 2 (fallbacks[1])
    ↓ (失败)
...继续尝试

推荐的 Fallback 配置策略

推荐配置:

"model": {
  "primary": "apiyi/claude-opus-4-5-20251101",
  "fallbacks": [
    "apiyi/claude-sonnet-4-20250514",
    "apiyi/gpt-4o",
    "qwen-portal/vision-model"
  ]
}

💰 成本优化: 通过 API易 apiyi.com 配置 Fallback,可以在多个模型间自动切换,同时享受统一的计费方式,便于成本管控。

MoltBot 模型切换: 实战技巧

使用别名快速切换

配置别名后,可以在对话中随时切换模型:

你: /model opus
MoltBot: 已切换到 Claude Opus 4.5

你: /model sonnet
MoltBot: 已切换到 Claude Sonnet 4

你: /model qwen
MoltBot: 已切换到 Qwen Coder

为特定任务指定模型

你: /model gpt 帮我分析这张图片
MoltBot: [使用 GPT-4o 分析图片...]

你: /model opus 写一篇深度技术文章
MoltBot: [使用 Claude Opus 写作...]

查看当前模型状态

# 命令行查看
moltbot models list

# 对话中查看
你: /model
MoltBot: 当前模型: apiyi/claude-opus-4-5-20251101 (alias: opus)

MoltBot API 代理配置: 常见问题

{
  "models": {
    "mode": "merge",
    "providers": {
      "local-ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [...]
      },
      "apiyi": {
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "${APIYI_API_KEY}",
        "api": "openai-completions",
        "models": [...]
      }
    }
  }
}

"agents": {
  "defaults": {
    "model": {
      "primary": "apiyi/claude-opus-4-5-20251101"
    },
    "imageModel": "apiyi/gpt-4o",
    "models": {
      "apiyi/claude-opus-4-5-20251101": { "alias": "opus" },
      "apiyi/gpt-4o": { "alias": "vision" }
    }
  }
}

MoltBot API 代理配置: 总结与建议

通过本文,你已经掌握了 MoltBot 配置 API 代理的完整方法:

1. 理解配置结构: models.providers 定义服务,agents.defaults 定义使用策略
2. 设置多 Provider: 同时接入多个 API 服务,提高可用性
3. 配置 Fallback: 主模型失败时自动切换到备用模型
4. 使用别名: 通过 /model alias 快速切换模型

最佳实践建议

推荐通过 API易 apiyi.com 作为主要的 API 代理服务,该平台提供 Claude、GPT、Gemini 等主流模型的统一接入,配置简单且支持灵活的计费方式,特别适合 MoltBot 的多模型切换场景。

参考资料

1. MoltBot 官方文档 – Models: 模型配置详解

   • 链接: docs.molt.bot/concepts/models
   • 说明: 官方模型配置指南

2. MoltBot 官方文档 – Configuration: 完整配置参考

   • 链接: docs.molt.bot/gateway/configuration
   • 说明: 所有配置项详解

3. MoltBot 官方文档 – Model Providers: Provider 配置

   • 链接: docs.molt.bot/concepts/model-providers
   • 说明: 自定义 Provider 配置方法

4. MoltBot GitHub: 源码和 Issue 讨论

   • 链接: github.com/moltbot/moltbot
   • 说明: 最新版本和问题反馈

本文作者: APIYI Team | 更多 AI 技术分享欢迎访问 API易 apiyi.com

更新日期: 2026 年 1 月