Swanmail

使用 LLM API ​

Swanmail 可以直接调用云端 LLM API 作为 AI 助手。目前支持两类提供商：

  • 兼容 OpenAI 的 chat completions API —— OpenAI、Groq、本地 Ollama 等。
  • Anthropic Messages API —— Claude 系列模型。

这样你无需编写 CLI 包装，即可使用托管服务或本地模型服务器。

何时使用 LLM API ​

在以下情况选择 LLM API：

  • 你已经有 OpenAI、Groq 或 Anthropic 的 API key。
  • 你正在运行类似 Ollama 的本地模型服务器。
  • 你想先体验 AI 功能，暂时不想安装本地智能体 CLI。

如果追求完全本地/离线，Ollama 是最简单的选择，因为邮件内容不会离开你的机器。

支持的任务 ​

LLM API 配置支持所有现有智能体任务：

  • classify —— 给邮件分类和打标签。
  • spam_check —— 估算垃圾邮件概率。
  • summarize —— 总结会话。
  • translate —— 翻译邮件文本。
  • custom_filter —— 对一组邮件运行用户自定义提示。
  • test —— 发送任意提示并查看 JSON 输出。

配置 ​

  1. 打开 设置 → LLM API。

  2. 点击 添加 API 配置，选择 OpenAI 或 Anthropic。

  3. 填写三个必填项（当前 UI 和运行时要求 API key 非空，本地端点也一样）：

    字段示例
    API URLhttps://api.openai.com/v1 或 https://api.anthropic.com/v1
    API Keysk-...
    模型gpt-4o、claude-sonnet-4-20250514 等

  4. 保存，并在 设置 → AI 助手 中为一个或多个账号启用。

示例配置 ​

OpenAI ​

  • API URL: https://api.openai.com/v1
  • API Key: 你的 OpenAI API key
  • 模型: gpt-4o-mini 或 gpt-4o

Anthropic ​

  • API URL: https://api.anthropic.com/v1
  • API Key: 你的 Anthropic API key
  • 模型: claude-sonnet-4-20250514 或其他 Claude 模型

Groq ​

  • API URL: https://api.groq.com/openai/v1
  • API Key: 你的 Groq API key
  • 模型: llama3-8b-8192 或其他 Groq 模型

Ollama（本地） ​

确保 Ollama 正在运行，并已拉取模型，例如：

bash
ollama pull llama3.2
ollama serve

然后在 Swanmail 中配置：

  • API URL: http://localhost:11434/v1
  • API Key：填写非空占位值（如果本地服务不校验认证，可以使用任意非空值）
  • 模型: llama3.2
  • 允许私有/本地端点: 开启此开关，否则 localhost 会被 SSRF 过滤拦截。

请求格式 ​

兼容 OpenAI ​

Swanmail 发送的请求体：

json
{
  "model": "your-model",
  "messages": [{ "role": "user", "content": "<rendered prompt>" }],
  "temperature": 0.3
}

端点必须返回标准 OpenAI 响应格式：

json
{
  "choices": [{ "message": { "content": "..." } }]
}

Anthropic ​

Swanmail 发送的请求体：

json
{
  "model": "your-model",
  "messages": [{ "role": "user", "content": "<rendered prompt>" }],
  "max_tokens": 1024
}

端点必须返回：

json
{
  "content": [{ "type": "text", "text": "..." }]
}

返回内容应包含可解析的 JSON。Swanmail 会自动提取 JSON 对象并应用到邮件（分类、标签、垃圾评分等）。

安全说明 ​

  • API key 用保存在 macOS 钥匙串、由 Windows DPAPI 保护或保存在 Linux Secret Service 中的密钥加密。
  • 原始 key 不会发送到应用界面。
  • 界面只能看到 hasApiKey 布尔值，用于提示是否已保存 key。
  • 每次请求前都会校验 LLM API URL：默认拒绝非 HTTP(S) 协议、嵌入凭据以及私有/回环地址。
  • 如需使用 Ollama 等本地服务器，请在配置中开启允许私有/本地端点。该选项按 LLM API 配置单独 opt-in。