常见问题

通用

桥接代理和直通代理有什么区别？

桥接代理 使用适配器在不同 API 格式之间转换。例如，它可以接受 OpenAI 格式的请求并转换为 Anthropic 格式后转发。适用于客户端和供应商使用不同 API 格式的场景。

直通代理 原样转发请求，不做任何格式转换，仅注入已存储的 API Key。适用于客户端和供应商使用相同 API 格式的场景。

默认代理地址是什么？

默认代理服务器运行在 http://127.0.0.1:9527。你可以在 设置 中修改主机和端口。

Amux Desktop 需要联网吗？

需要联网才能将请求转发到 LLM 供应商 API。但应用本身完全在本地运行 — 不会向 Amux 服务器发送任何数据（除非你启用了隧道或分析统计）。

我的数据存储在哪里？

所有数据存储在本地：

供应商

支持哪些 LLM 供应商？

Amux Desktop 内置了 OpenAI、Anthropic、DeepSeek、Moonshot、通义千问、智谱、Google Gemini 和 MiniMax 的预设。你也可以使用 openai 适配器类型配合自定义 Base URL 添加任何 OpenAI 兼容的供应商。

我的 API Key 安全吗？

安全。API Key 经加密后存储在本地 SQLite 数据库中，除发送到对应供应商 API 外，不会离开你的机器。

如何添加预设中没有的自定义供应商？

进入 供应商 → Add Provider，选择最接近的适配器类型（大多数 OpenAI 兼容 API 使用 openai 适配器），输入 Base URL 和 API Key，然后手动添加模型或从供应商 API 获取。

代理

可以同时使用多个代理吗？

可以。你可以创建任意数量的桥接代理，启用任意数量的直通代理。每个代理有自己唯一的路径，可以独立访问。

模型映射是怎么工作的？

模型映射将客户端请求中的模型名翻译为目标供应商的另一个模型。例如，客户端请求 gpt-4o 可以路由到 Anthropic 的 claude-sonnet-4-20250514。你还可以设置默认映射作为兜底，当没有特定模型匹配时使用。

为什么我的代理返回错误？

常见原因：

1. API Key 无效 — 检查供应商的 API Key 是否正确
2. 适配器错误 — 确保入站适配器与客户端发送的格式匹配
3. 模型未找到 — 确认目标模型名在供应商侧有效
4. 超时 — 如果供应商响应慢，在设置中增加超时时间
5. 服务未运行 — 在仪表盘确认代理服务器已启动

Code Switch

Code Switch 是做什么的？

Code Switch 修改 CLI 工具的配置（如 Claude Code 的 ~/.claude/settings.json），将请求路由到 Amux Desktop 的本地代理。这样你就可以让 Claude Code 使用任意 LLM 模型，而不仅限于 Anthropic 的模型。

Code Switch 会破坏我的 Claude Code 配置吗？

不会。Code Switch 在修改前会备份原始配置。禁用 Code Switch 后，原始配置会自动恢复。

可以在 Codex CLI 上使用 Code Switch 吗？

Codex 支持在计划中但尚未实现。目前仅支持 Claude Code。

隧道

隧道安全吗？

隧道流量通过 Cloudflare 网络加密传输。但任何拥有公网 URL 的人都可以访问你的代理。使用隧道时，请务必在设置中启用 Unified API Key 鉴权。

为什么隧道无法启动？

常见原因：

1. 网络问题 — 确保有网络连接且防火墙未阻止到 Cloudflare 的出站连接
2. cloudflared 下载失败 — 该二进制文件在首次使用时自动下载，检查网络连接
3. 端口冲突 — 确保代理服务器正在运行后再启动隧道

令牌与安全

什么是 Unified API Key？

启用后，代理服务器要求客户端在 Authorization: Bearer <key> 头中包含有效的 API 令牌。未启用时，代理接受所有请求而不需要鉴权。

sk-amux.xxx 和普通密钥有什么区别？

• sk-amux.xxx：平台令牌，在本地校验。实际使用供应商存储的 API Key 发送上游请求。
• 其他格式：直接透传给上游供应商，绕过存储的密钥。

我应该启用鉴权吗？

以下情况建议启用：

• 使用 隧道 将代理暴露到公网时
• 多个用户或应用访问代理时
• 需要在日志中追踪每个令牌的使用情况时

仅本地使用时，可以不启用。

性能

供应商响应慢怎么办？

默认请求超时为 60 秒，你可以在 设置 中调整。流式请求的连接会保持打开直到响应完成。

Amux Desktop 会增加明显的延迟吗？

Amux Desktop 的请求路由和格式转换仅增加极少的开销（通常 < 5ms）。响应时间的绝大部分来自上游 LLM 供应商。

Amux Desktop 占用多少磁盘空间？

应用本身很轻量。存储使用取决于：

• 日志：可配置保留期（默认 7 天，最多 10000 条）
• 数据库：随供应商、代理和令牌增长（通常 < 10MB）
• 请求/响应体：如果在日志设置中启用，可能会显著增长

故障排除

代理服务器无法启动

1. 检查端口（默认 9527）是否被其他应用占用
2. 尝试在设置中更换端口
3. 重启 Amux Desktop

流式响应不工作

1. 确保客户端在请求体中发送了 "stream": true
2. 检查目标供应商是否支持所选模型的流式传输
3. 如果从浏览器调用，检查 CORS 设置

配置导入失败

1. 确保文件是 Amux Desktop 导出的有效 JSON 文件
2. 检查文件是否来自兼容版本
3. 尝试重启应用后重新导入

下一步