CoPaw API 接入教程：GPT & Gemini & Claude 快速入门

本指南介绍如何将各种 LLM（大型语言模型）提供商接入 CoPaw。CoPaw 是一个支持多种聊天渠道、定时任务和自定义技能的 Personal AI Assistant（个人 AI 助手）。

简介

CoPaw 是构建在 AgentScope 之上的开源 AI 助手框架，支持钉钉、飞书、QQ、Discord、iMessage 等多个平台。无论你是为企业构建个人 AI 助手，还是开发多渠道客服机器人，CoPaw 都能灵活连接你偏好的 LLM 提供商。

CoPaw 的核心优势之一是通过 OpenAI 兼容的 API 接口支持多种模型提供商。本指南将引导你完成接入流程，并重点介绍具有成本效益的解决方案。

概述

CoPaw 使用 AgentScope 的 OpenAIChatModel 与不同的 LLM 提供商进行通信。所有远程提供商都使用 OpenAI 兼容的 /v1/chat/completions 端点，使得在不同提供商之间切换或添加新提供商变得非常简单。

配置文件存储在 CoPaw 工作目录下的 providers.json 文件中。

方法一：Defapi（推荐 - 半价优惠）

Defapi 提供大约官方价格一半的主要 LLM 提供商 API 访问。它完全兼容 OpenAI 协议，是接入 CoPaw 的绝佳选择。

为什么选择 Defapi？

成本效益：比官方 API 便宜约 50%
协议兼容：完全兼容 OpenAI 的 /v1/chat/completions
多种模型：可访问 GPT-4o、Claude Sonnet、Gemini Flash 等
简单配置：无需复杂设置

配置

编辑 CoPaw 配置文件，将 Defapi 添加为自定义提供商：

{
  "custom_providers": {
    "defapi": {
      "id": "defapi",
      "name": "Defapi",
      "default_base_url": "https://api.defapi.cn/v1",
      "api_key_prefix": "",
      "base_url": "https://api.defapi.cn/v1",
      "api_key": "your-defapi-api-key",
      "models": [
        {"id": "gpt-4o-mini", "name": "GPT-4o Mini"},
        {"id": "gpt-4o", "name": "GPT-4o"},
        {"id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4"},
        {"id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash"}
      ],
      "chat_model": "OpenAIChatModel"
    }
  },
  "active_llm": {
    "provider_id": "defapi",
    "model": "gpt-4o-mini"
  }
}

Defapi 可用模型

模型	适用场景
gpt-4o-mini	快速、成本效益高的响应
gpt-4o	复杂推理、编码
claude-sonnet-4-20250514	均衡的性能
gemini-2.0-flash	多模态、快速响应

方法二：内置提供商

CoPaw 预置了多个内置提供商，只需配置 API Key 即可启用。

OpenAI

{
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "active_llm": {
    "provider_id": "openai",
    "model": "gpt-4o-mini"
  }
}

ModelScope（魔搭）

{
  "providers": {
    "modelscope": {
      "base_url": "https://api-inference.modelscope.cn/v1",
      "api_key": "ms-your-key"
    }
  }
}

DashScope（阿里云）

{
  "providers": {
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-your-key"
    }
  }
}

方法三：OpenRouter

OpenRouter 通过统一 API 聚合多个 LLM 提供商：

{
  "providers": {
    "openrouter": {
      "base_url": "https://openrouter.ai/api/v1",
      "api_key": "sk-or-your-key"
    }
  },
  "active_llm": {
    "provider_id": "openrouter",
    "model": "openrouter/google/gemini-2.0-flash"
  }
}

方法四：本地模型

适用于需要离线操作或数据隐私的场景：

Ollama

{
  "providers": {
    "ollama": {
      "base_url": "http://localhost:11434/v1",
      "api_key": ""
    }
  },
  "active_llm": {
    "provider_id": "ollama",
    "model": "llama3"
  }
}

llama.cpp

pip install 'copaw[llamacpp]'
copaw models download Qwen/Qwen3-4B-GGUF

验证配置

配置完成后，验证你的设置：

启动 CoPaw：copaw app
打开 Console：http://127.0.0.1:8088/
进入 Settings → Models
测试提供商连接

或使用 CLI：

copaw models

内部机制

CoPaw 如何连接 LLM 提供商

CoPaw 的提供商系统通过多个层级工作：

配置层（providers/store.py）：读取和写入 providers.json，管理 API Key 和端点 URL。
注册层（providers/registry.py）：维护内置和自定义提供商及其模型定义的列表。
模型工厂（agents/model_factory.py）：根据提供商配置创建相应的 ChatModel 实例。
Agent 运行时（agents/react_agent.py）：通过 ReAct（推理 + 行动）循环使用模型生成响应。

OpenAI 兼容接口意味着当你发送消息时，CoPaw 会构造一个 POST 请求到 {base_url}/chat/completions，并携带你的消息和参数。响应被解析后用于生成助手的回复。

Token 管理

CoPaw 实现智能 Token 管理：

上下文窗口因提供商而异（例如 GPT-4o：128K，Claude：200K）
内存压缩有助于管理长对话
你可以配置 max_tokens 来控制响应长度

常见用例

1. 客服自动化

在钉钉或 Discord 上部署 CoPaw，使用 AI 驱动的响应处理客户咨询。连接 GPT-4o 处理复杂问题，或使用较小的模型处理常见问题解答。

2. 内容生成管道

安排 CoPaw 生成每日新闻通讯或社交媒体内容。使用心跳功能在特定时间触发自动内容创建。

3. 会议总结

与日历 API 集成，自动总结会议笔记和待办事项。Claude 模型擅长理解细微的讨论。

4. 知识库问答

使用 CoPaw 的记忆搜索功能构建检索增强生成（RAG）系统。上传文档并让用户通过任何支持的渠道进行查询。

5. 多语言翻译服务

利用 Gemini 的多语言能力实现多渠道实时翻译。为不同用户组配置不同的语言对。

故障排除

常见问题

401 未授权

验证 API Key 是否正确
检查密钥是否已过期或被撤销

连接超时

检查网络连接
验证防火墙设置允许出站 HTTPS

模型未找到

确认模型 ID 正确
检查该模型在你的地区是否可用

Ollama 连接失败

确保 ollama serve 正在运行
验证 Base URL 是 http://localhost:11434/v1

快速开始命令

# 安装 CoPaw
pip install copaw

# 使用默认配置初始化
copaw init --defaults

# 启动应用
copaw app

# 配置你喜欢的 LLM 提供商
# 编辑 ~/.copaw/.secret/providers.json

总结

CoPaw 通过其 OpenAI 兼容接口提供灵活的 LLM 集成。对于具有成本效益的 AI 助手部署，Defapi 以半价访问主要模型提供最佳性价比。内置提供商覆盖大多数用例，而自定义提供商支持与任何 OpenAI 兼容 API 的集成。

从 Defapi 开始，获得最佳的成本和性能平衡，然后根据你的具体需求探索其他提供商。