AIProxyServer - 指南

快速开始

1. 启动应用

打开 AIProxyServer。首次启动时 proxy 会自动开始运行,在本地机器的端口 8421 上监听。主窗口包含三个区域:

• Proxy Server — 当前状态、基础 URL,以及启动或停止监听器的按钮
• Bearer Token — 可选的认证开关以及令牌显示
• Providers — 所有支持的云端 AI 提供商,每行都带有 Set API Key 按钮

2. 添加第一个 API 密钥

1. 从 Providers 列表中任选一个提供商(例如 OpenAI (ChatGPT))
2. 点击 Get API key 在浏览器中打开提供商的控制台,然后创建或复制一个密钥
3. 点击同一行的 Set API Key,在对话框中粘贴值
4. 点击 Save。状态标签会变成绿色的 Configured

3. 连接客户端应用

将任何 OpenAI 兼容客户端指向 proxy。基础 URL 为 http://localhost:8421/<provider>/v1。其中 provider 段决定请求被发送到哪个云端。

# 示例:指向 proxy 的 OpenAI Python SDK
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

客户端永远不会看到真实密钥。AIProxyServer 在转发请求时附加上游凭据。

界面概览

Proxy Server 面板

Bearer Token 面板

• Require Bearer Token authentication — 开关认证的复选框。为了方便本地使用,默认关闭。
• Token field — 以只读方式显示当前令牌。以圆点形式展示,可用 Copy 获取。
• Regenerate — 生成一个新的随机令牌。现有的客户端必须更新为新值。

Providers 面板

每个支持的云端提供商占据一行。每行显示:

• 显示名称(例如 Claude (Anthropic))
• 配置状态 — API 密钥已保存时显示绿色 Configured,否则显示灰色 Not configured
• 客户端使用的 URL 路径,例如 /anthropic/v1/chat/completions
• Set API Key — 打开输入凭据的对话框
• Get API key — 在浏览器中打开提供商的控制台

支持的提供商

内置 11 种云端 AI 服务。大多数原生使用 OpenAI Chat Completions 格式,因此直接中继。3 种(Anthropic、Gemini、ERNIE)使用各自的协议,AIProxyServer 会即时翻译请求和响应,因此客户端始终看到的都是 OpenAI 格式。

提供商特定备注

• Azure OpenAI — 将完整的部署端点粘贴到 Endpoint Base URL 字段中,例如 https://my-resource.openai.azure.com/openai/deployments/gpt-4o。proxy 会自动追加 /chat/completions?api-version=2024-02-01。
• ERNIE — Baidu Qianfan 使用 OAuth,因此同时需要 API Key 和 Secret Key。AIProxyServer 会在后台请求并缓存访问令牌。
• Gemini — 通过 URL 查询参数进行认证,proxy 会自动添加。免费层级的每分钟配额仍然适用。

API 参考

端点

流式传输

当客户端发送 "stream": true 时,proxy 以 OpenAI 格式的 Server-Sent Events 响应:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Anthropic 和 Gemini 的原生流也会被转换为该格式,因此所有客户端都可以使用单一解析器。

认证标头

启用 Require Bearer Token authentication 时,每个请求都需要带上主窗口中显示的令牌:

Authorization: Bearer <token-shown-in-app>

设置

从底部工具栏的齿轮图标打开 Settings 窗口。

客户端示例

cURL

# OpenAI(直通)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# 通过相同的 OpenAI 格式调用 Claude
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # Bearer Token 关闭时被忽略
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// 使用任何 OpenAI 兼容的 Dart 客户端
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // Bearer Token 关闭时不使用
);

提示

• 本地开发时保持 Bearer Token 关闭,启用 LAN 访问的瞬间立即开启。
• 在客户端代码中为每个提供商使用不同的 Base URL,这样只需更改一个常量即可切换提供商。
• proxy 会自动启动,但发生端口冲突时可从主窗口暂时停止。
• 如果提供商的免费层级对您进行速率限制,上游错误消息将原样转发。不会对客户端隐藏任何重试逻辑。
• /v1/providers 端点对于在运行时发现哪些提供商已配置非常有用。

疑难解答

proxy 无法启动

• 可能有其他进程已在使用端口 8421。请在 Settings 中更改端口并重启 proxy。
• 请在系统日志中查看启动时显示的错误消息。

请求返回 401 Unauthorized

• Bearer Token 要求已开启,但客户端未发送匹配的 Authorization: Bearer ... 标头。
• 提供商自身的 API 密钥可能无效 — 上游错误会原样转发,请检查消息正文。

请求返回 "API key is not configured"

• 打开 Providers 列表,点击对应提供商的 Set API Key。
• 对于 ERNIE,必须同时填写 API Key 和 Secret Key。对于 Azure OpenAI,还需填写 Endpoint Base URL。

移动设备无法访问 proxy

• 在 Settings 中开启 Allow LAN Access。
• 使用 Base URL 字段中显示的 LAN IP,而不是 localhost。
• 确认两台设备处于同一 Wi-Fi 网络,并且防火墙允许对 proxy 端口的入站连接。

流式响应一次性全部到达

• 请确认客户端在 JSON 正文中发送了 "stream": true。
• 某些 HTTP 库默认会对 SSE 进行缓冲 — 请在客户端禁用响应缓冲。

隐私

• API 密钥使用 Fernet 加密存储在 ~/Library/Application Support/AIProxyServer/credentials.enc 中。master.key 中的加密密钥具有 0600 权限。
• 启用时,Bearer Token 也仅存储在加密保险库中,不会写入常规设置文件。
• proxy 仅向您明确配置的提供商转发请求。不会发起任何其他出站调用。
• 没有遥测、没有分析、没有崩溃报告。
• 默认网络绑定仅为 127.0.0.1。LAN 暴露须主动开启。
• 不存储对话内容。AIProxyServer 转发字节后立即遗忘。