AIProxyServer - 指南

快速上手

1. 启动应用

打开 AIProxyServer。首次启动时代理会自动运行，并监听本机的端口 8421 。主窗口分为三个区域：

• 代理服务器 — 当前状态、基础 URL，以及启动或停止监听器的按钮
• Bearer Token — 可选的认证开关与令牌显示
• 服务商 — 所有受支持的云端 AI 服务商，每行都带有一个 设置 API 密钥 按钮

2. 添加第一个 API 密钥

1. 从服务商列表中任选一个（例如 OpenAI (ChatGPT))
2. 点击 获取 API 密钥 在浏览器中打开该服务商的控制台，然后创建或复制一个密钥
3. 点击 设置 API 密钥 ，在同一行中将该值粘贴到对话框内
4. 点击 保存。状态标签会变为 已配置 并显示为绿色

3. 连接客户端应用

将任何 OpenAI 兼容客户端指向该代理。基础 URL 为 http://localhost:8421/<provider>/v1。URL 中的服务商片段决定请求转发到哪个云服务。

# 示例：将 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 会在转发请求时附加上游凭据。

界面概览

代理服务器面板

Bearer Token 面板

• 要求 Bearer Token 认证 — 用于开启或关闭认证的复选框。默认关闭，便于本地无障碍使用。
• 令牌字段 — 只读显示当前令牌，以圆点形式呈现；使用 复制 即可获取。
• 重新生成 — 生成一个新的随机令牌。现有客户端必须更新为新值。

服务商面板

每个受支持的云服务商占一行。每行显示：

• 显示名称（例如 Claude (Anthropic))
• 配置状态 — 已保存 API 密钥时显示绿色 已配置 ，否则显示灰色 未配置 。
• 客户端使用的 URL 路径，例如 /anthropic/v1/chat/completions
• 设置 API 密钥 — 打开输入凭据的对话框
• 获取 API 密钥 — 在浏览器中打开该服务商的控制台

支持的服务商

内置十一种云端 AI 服务。多数原生使用 OpenAI Chat Completions 格式，可直接透传代理。其中三种（Anthropic、Gemini、ERNIE）使用各自的协议；AIProxyServer 会实时转换请求与响应，因此您的客户端始终只接触 OpenAI 格式。

各服务商注意事项

• Azure OpenAI — 请将完整的部署端点粘贴到 端点基础 URL 字段中，例如 https://my-resource.openai.azure.com/openai/deployments/gpt-4o。代理会自动追加 API 路径：/chat/completions?api-version=2024-02-01 。
• ERNIE — 百度千帆使用 OAuth，因此 API Key 和 Secret Key 两者都必须填写。AIProxyServer 会在后台请求并缓存访问令牌。
• Gemini — 认证通过 URL 查询参数完成，代理会为您自动添加。免费套餐的每分钟配额限制仍然适用。

API 参考

端点

流式传输

当客户端发送 "stream": true时，代理会以 OpenAI 格式返回 Server-Sent Events：

SSE 角色数据：data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

SSE 内容数据：data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

SSE 结束标记：data: [DONE]

Anthropic 与 Gemini 的原生数据流会被转换为该格式，让所有客户端都能使用同一个解析器。

认证请求头

当 要求 Bearer Token 认证 开启时，请在每个请求中发送主窗口中显示的令牌：

授权请求头：Authorization: Bearer <token-shown-in-app>

设置

点击底部工具栏的齿轮图标即可打开设置窗口。

客户端示例

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 保持关闭；一旦启用局域网访问，请立即开启它。
• 在客户端代码中为每个服务商使用不同的基础 URL，这样只需修改一个常量即可切换服务商。
• 代理会自动启动，但如果发生端口冲突，您可以在主窗口中临时停止它。
• 如果某个服务商的免费套餐对您限流，上游错误消息会原样转发。不会向客户端隐藏任何重试逻辑。
• 使用 /v1/providers 端点可以在运行时查看哪些服务商已完成配置。

疑难解答

代理无法启动

• 可能已有其他进程占用了 8421 端口。请在设置中修改端口并重启代理。
• 请查看系统日志中启动时显示的错误消息。

请求返回 401 Unauthorized

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

请求返回「API key is not configured」

• 打开服务商列表，并为相应服务商点击 设置 API 密钥 。
• 对于 ERNIE，API Key 和 Secret Key 都必须填写。对于 Azure OpenAI，还需要填写端点基础 URL。

移动设备无法访问代理

• 请开启 允许局域网访问 （位于设置中）。
• 请使用基础 URL 字段中显示的局域网 IP，而不是 localhost.
• 请确认两台设备处于同一 Wi-Fi 网络，并且防火墙允许代理端口的入站连接。

流式响应一次性全部到达

• 请确认您的客户端在 JSON 正文中发送了 "stream": true 在 JSON 正文中。
• 部分 HTTP 库默认会缓冲 SSE — 请在客户端关闭响应缓冲。

隐私

• API 密钥使用 Fernet 加密后存储于 凭据文件路径：~/Library/Application Support/AIProxyServer/credentials.enc。加密密钥保存在 master.key 中，权限为 0600。
• 启用后的 Bearer Token 同样仅保存在加密保险库中，绝不会写入普通设置文件。
• 代理只会将请求转发到您明确配置过的服务商，不会发起任何其他外部调用。
• 无遥测、无分析、无崩溃上报。
• 默认网络绑定仅为 127.0.0.1 。局域网暴露需要您主动开启。
• 不保存对话内容。AIProxyServer 只转发字节，转发后立即遗忘。