AstrBot API 接入完全指南

2026年3月14日

本教程详细介绍在 AstrBot 中配置各种大语言模型 API 的多种方法，帮助你快速搭建自己的 AI 聊天机器人。

简介

AstrBot 是一个开源的 AI Agent 聊天机器人平台，支持多种即时通讯软件的接入，包括 QQ、Telegram、飞书、钉钉、Discord 等。它支持大语言模型对话、多模态、Agent、MCP、技能、知识库、人格设置等功能。

AstrBot 适配了三种原生 API 格式：OpenAI API 格式、Google Gemini API 格式和 Anthropic API 格式。通过这些接口，你可以接入几乎所有主流的 AI 模型服务提供商。

准备工作

在开始之前，你需要：

  • 安装 AstrBot：uv tool install astrbot
  • 初始化项目：astrbot init
  • 拥有相应的 API 访问权限
  • 配置文件位于 data/cmd_config.json

方法一：使用 Defapi（推荐）

如果你想节省成本，推荐使用 Defapi！

Defapi 是一个 AI 模型聚合平台，所有模型价格只有官方的半价。Defapi 支持 OpenAI 兼容的 v1/chat/completions 接口，配置简单方便。

优势

  • 价格半价：Claude Sonnet 仅需 $1.5/M 输入，$7.5/M 输出
  • 兼容性强：完美兼容 OpenAI 接口格式
  • 稳定可靠：国内访问速度快
  • 支持模型丰富：涵盖 Claude、GPT、Gemini 等多种模型

支持的主要模型

  • Claude Opus / Sonnet / Haiku
  • GPT-4o / GPT-4o-mini
  • Gemini 1.5 Flash

配置步骤

  1. 访问 Defapi 注册账号，获取 API Key

  2. 修改配置文件 data/cmd_config.json：

{
    "provider": [
        {
            "id": "defapi-claude",
            "type": "openai_chat_completion",
            "model": "claude-sonnet-4-20250514",
            "key": ["你的Defapi-API-Key"],
            "api_base": "https://api.defapi.org/v1",
            "enable": true
        }
    ],
    "provider_settings": {
        "default_provider_id": "defapi-claude"
    }
}

或者通过 WebUI 配置：

  1. 访问 AstrBot 控制台 (默认 http://localhost:6185)

  2. 进入「服务提供商」页面

  3. 点击「+ 新增服务提供商」

  4. 选择「OpenAI」类型

  5. 填写 API Key：你的Defapi-API-Key

  6. 填写 API Base URL：https://api.defapi.org/v1

  7. 填写模型名称：claude-sonnet-4-20250514

  8. 保存配置

  9. 验证配置：

启动 AstrBot 并发送消息测试：

astrbot

在支持的聊天平台发送消息，Bot 会自动使用 Defapi 的模型进行回复。

方法二：使用 OpenAI 官方 API

这是最直接的接入方式，适合有 OpenAI API Key 的用户。

获取 API Key

  1. 访问 OpenAI Platform
  2. 进入 API Keys 页面创建新密钥

配置文件

{
    "provider": [
        {
            "id": "openai-official",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["sk-xxx"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

方法三：使用 OpenRouter

OpenRouter 提供统一的 API 接口，可访问多种模型，包括 Claude、GPT、Gemini 等。

获取 API Key

  1. 访问 OpenRouter
  2. 注册并创建 API Key

配置文件

{
    "provider": [
        {
            "id": "openrouter",
            "type": "openai_chat_completion",
            "model": "openai/gpt-4o-mini",
            "key": ["sk-or-v1-xxx"],
            "api_base": "https://openrouter.ai/api/v1",
            "enable": true
        }
    ]
}

可用模型示例

  • openai/gpt-4o
  • anthropic/claude-sonnet-4-5
  • google/gemini-1.5-flash

方法四：使用 Anthropic Claude 官方 API

如果你想直接使用 Claude 模型，可以使用 Anthropic 官方 API。

获取 API Key

  1. 访问 Anthropic Console
  2. 创建 API Key

配置文件

{
    "provider": [
        {
            "id": "anthropic-claude",
            "type": "anthropic_chat_completion",
            "model": "claude-sonnet-4-20250514",
            "key": ["sk-ant-api03-xxx"],
            "enable": true
        }
    ]
}

方法五：使用 Google Gemini 官方 API

获取 API Key

  1. 访问 Google AI Studio
  2. 创建 API Key

配置文件

{
    "provider": [
        {
            "id": "gemini-official",
            "type": "googlegenai_chat_completion",
            "model": "gemini-1.5-flash",
            "key": ["AIzaSy-xxx"],
            "enable": true
        }
    ]
}

方法六：使用国内模型服务商

AstrBot 也支持多种国内模型服务商，价格更优惠，访问更稳定。

SiliconFlow

{
    "provider": [
        {
            "id": "siliconflow",
            "type": "openai_chat_completion",
            "model": "Qwen/Qwen2-7B-Instruct",
            "key": ["sk-xxx"],
            "api_base": "https://api.siliconflow.cn/v1",
            "enable": true
        }
    ]
}

DeepSeek

{
    "provider": [
        {
            "id": "deepseek",
            "type": "openai_chat_completion",
            "model": "deepseek-chat",
            "key": ["sk-xxx"],
            "api_base": "https://api.deepseek.com/v1",
            "enable": true
        }
    ]
}

方法七：使用环境变量

为了安全性，推荐使用环境变量加载 API Key。

配置方式

{
    "provider": [
        {
            "id": "openai-env",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["$OPENAI_API_KEY"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

然后在系统环境变量中设置：

export OPENAI_API_KEY="sk-xxx"

验证是否正常工作

配置完成后，验证步骤如下：

  1. 重启 AstrBot 服务
astrbot

  1. 在已配置的消息平台发送消息测试

  2. 检查控制台日志，确保 API 调用成功

如果配置正确，你应该能收到 AI 的回复。

内部机制：Provider 系统

AstrBot 的 Provider 系统设计非常灵活，理解其工作原理有助于更好地使用。

Provider 注册机制

AstrBot 使用装饰器模式注册 Provider：

@register_provider_adapter(
    "openai_chat_completion",
    "OpenAI API Chat Completion 提供商适配器",
)
class ProviderOpenAIOfficial(Provider):
    pass

所有 Provider 实现位于 astrbot/core/provider/sources/ 目录。

请求流程

  1. 用户发送消息
  2. AstrBot 接收消息并构建上下文
  3. 根据配置选择 Provider
  4. Provider 将请求转换为对应 API 格式
  5. 发送请求到模型服务商的 API
  6. 解析响应并返回结果

多 Key 负载均衡

AstrBot 支持配置多个 API Key，实现负载均衡：

{
    "provider": [
        {
            "id": "openai-multi-key",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["key1", "key2", "key3"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

当某个 Key 触发速率限制时，会自动切换到其他 Key。

错误处理

AstrBot 内置完善的错误处理机制：

  • 401/403 错误：认证问题
  • 429 错误：速率限制，自动切换 Key
  • 超时错误：可配置代理或更换服务商

常见用例

1. 智能客服

将 AstrBot 接入企业微信或钉钉，作为智能客服回答客户问题。

2. 群聊助手

在 QQ 群或 Discord 中使用，作为群聊助手，提供信息查询、翻译等功能。

3. 角色扮演

配置人格和系统提示词，让 AI 扮演特定角色（如虚拟偶像、游戏 NPC）。

4. 个人助理

接入 Telegram 或微信，作为个人的 AI 助手，帮助处理日常事务。

5. 内容创作

利用 AI 的文本生成能力，帮助撰写文章、生成创意内容。

相关文档

Updated 2026年3月14日