DroidProxy：macOS菜单栏AI代理，统一管理Claude/Codex/Gemini并增强推理

1. 项目概述：DroidProxy，一个为AI编程工具而生的macOS菜单栏代理

如果你和我一样，日常重度依赖像Factory.ai这样的AI编程工具，并且同时使用Claude、OpenAI Codex和Google Gemini等多个模型来辅助代码生成和审查，那么你肯定遇到过同一个痛点：如何在不同的AI服务之间无缝切换，并精细控制它们的“思考”深度？每次在Claude的Web界面、OpenAI的API控制台和Gemini的Studio之间跳转，不仅效率低下，更重要的是，你无法将这些强大的模型统一集成到你的本地开发工作流中。DroidProxy正是为了解决这个核心问题而诞生的。

简单来说，DroidProxy是一个原生macOS菜单栏应用。它的核心功能是在本地（localhost:8317）创建一个统一的代理服务器，将你对Claude、Codex和Gemini的API请求进行中转、认证和增强。它最吸引我的地方在于，它不仅仅是一个简单的“转发器”，而是一个“思考增强器”。它能自动为Claude Opus/Sonnet、GPT-5.x Codex系列以及Gemini模型注入特定的“思考”参数，让你在Factory.ai等工具中直接调用这些模型时，就能享受到更深度、更可控的推理能力，而无需手动修改每一个API请求。

这个项目基于CLIProxyAPIPlus构建，但将其包装成了一个拥有精美UI、一键认证和实时状态监控的桌面应用。对于使用Apple Silicon Mac（M1/M2/M3/M4）的开发者而言，它几乎是开箱即用的生产力倍增器。接下来，我将深入拆解它的设计思路、核心功能、配置细节，并分享我在实际使用中积累的避坑经验和高级技巧。

2. 核心功能深度解析：不止于代理

DroidProxy的功能列表看起来可能有些技术化，但每一项都直指AI辅助编程中的实际需求。我们来逐一拆解，看看它们到底解决了什么问题。

2.1 一键OAuth认证与凭证管理

这是所有功能的基础，也是体验提升最明显的一点。通常，要使用Claude、Gemini的API，你需要手动获取API密钥，并在你的工具配置中填入。DroidProxy将这个过程简化到了极致。

• 工作原理：应用内嵌了安全的OAuth 2.0流程。当你点击菜单栏图标，选择登录Claude或Gemini时，它会打开系统浏览器引导你完成官方授权。授权成功后，访问令牌（Token）会被安全地存储在macOS的钥匙串（Keychain）中，并写入本地的认证文件。DroidProxy会持续监控这个文件的状态。
• 解决了什么：
  1. 安全性：Token不散落在各处配置文件中，而是由系统钥匙串统一管理。
  2. 便捷性：无需记忆和复制粘贴冗长的API Key。
  3. 自动刷新：对于支持刷新令牌的OAuth流程，DroidProxy能在令牌过期前自动更新，实现“一次登录，长期有效”，避免了工作中突然因认证失效而中断。
• 实操注意：首次登录时，请确保网络通畅，并留意浏览器可能会提示“localhost”的重定向，这是正常现象。登录成功后，菜单栏图标旁会显示一个小绿点或服务名称，表示认证有效。

2.2 自适应思考代理：解锁Claude的深层推理

这是DroidProxy的“灵魂”功能。Anthropic为Claude模型设计了“思考”（thinking）特性，允许模型在输出最终答案前，在内部进行更长时间的推理。DroidProxy能自动为发送到http://localhost:8317的Claude请求注入这个参数。

• 技术细节：对于Claude Opus 4.7和Sonnet 4.6的请求，代理会注入thinking: {"type":"adaptive"}参数。更重要的是，它允许你通过设置界面，为不同模型单独配置output_config.effort（努力程度）。
  • Opus 4.7：可配置low,medium,high,xhigh,max。max会驱使模型进行最深入、最耗时的推理，适合解决极其复杂的问题。
  • Sonnet 4.6：可配置low,medium,high,max。
• 解决了什么：在Factory.ai等工具中，你通常只能调用基础模型。通过DroidProxy，你相当于获得了Anthropic API Playground中对“思考”滑块的控制能力，可以直接在编码工具中要求Claude进行更深度的算法设计、复杂逻辑梳理或安全漏洞分析。
• 个人经验：对于日常代码补全和解释，medium或high足矣，响应速度和质量平衡得很好。当我在重构一个大型模块或设计一个复杂系统架构时，才会切换到xhigh或max。你会明显感觉到模型返回的代码更健壮，考虑的边界条件更全面，但等待时间也会相应增加。

2.3 Codex推理控制与Gemini思考级别

DroidProxy对OpenAI的GPT-5.3 Codex、5.4、5.5以及Google的Gemini模型也提供了类似的支持。

• OpenAI Codex系列：请求通过OpenAI兼容的端点http://localhost:8317/v1发送时，代理会注入reasoning: {"effort":"..."}参数。同样支持low,medium,high,xhigh等级别。这对于需要Codex进行复杂代码生成或逻辑推理的任务至关重要。
• Gemini模型：实现方式更巧妙。它通过重写模型名称后缀来注入思考级别。
  • 对于gemini-3.1-pro-preview，你可以使用gemini-3.1-pro-preview-low,-medium,-high。
  • 对于gemini-3-flash-preview，则支持-minimal,-low,-medium,-high。
  • 当你使用gemini-3.1-pro-preview-high作为模型名调用代理时，DroidProxy会将其转换为标准的模型名，并附加上对应的思考级别参数再转发给真实的Gemini API。
• 解决了什么：统一了不同AI供应商的“深度推理”控制方式。你无需记住OpenAI用reasoning，Gemini用thinking_spec，只需在DroidProxy的设置界面滑动滑块，或在调用时使用约定的模型名称即可。

2.4 “最大预算模式”：Sonnet的全力一击

这是一个非常有趣且实用的“杀手锏”功能。点击设置中的“Max Budget Mode”按钮，它会为所有Sonnet 4.6的请求强制启用最大限度的思考。

• 它做了什么：它会为请求注入budget_tokens: 63999,max_tokens: 64000, 以及effort: max。这实际上是模拟了Claude API中“扩展思考”的经典配置，允许模型使用海量的中间令牌进行推理。
• 设计意图：作者幽默地称之为“核按钮”，并备注“Sonnet全力思考，配额问题你自己负责”。这清晰表明了其用途——当你需要Sonnet拿出最佳表现解决一个难题，且不计较令牌消耗和延迟时，就打开它。对于Opus 4.7，此模式不影响，仍使用你自定义的滑块设置。
• 使用场景：我通常会在进行最终代码审查、安全性深度审计或求解一个困扰已久的复杂算法问题时开启此模式。效果提升是显著的，Sonnet会产出接近Opus深度的分析，但成本远低于直接调用Opus。

2.5 无缝集成与自动更新

• Factory.ai集成：这是DroidProxy的主要应用场景。你只需要在Factory的Droid配置中，将Claude的端点改为http://localhost:8317，将OpenAI/Codex的端点改为http://localhost:8317/v1，Gemini的端点也指向http://localhost:8317/v1，即可完成配置。之后所有通过Factory发起的请求都会经由DroidProxy增强。
• Sparkle自动更新：应用内置了Sparkle框架，每天检查更新并在后台静默安装。这保证了你能持续获得功能改进和Bug修复，无需手动去GitHub下载新版本。

3. 从安装到配置：手把手搭建你的AI代理枢纽

了解了核心功能后，我们来看看如何将它实际用起来。整个过程非常直观。

3.1 下载与安装

由于项目编译需要特定的macOS开发环境，对于绝大多数用户，强烈建议直接下载官方发布的预编译版本。

1. 访问发布页面：打开浏览器，前往DroidProxy的GitHub Releases页面。
2. 选择正确版本：根据你的Mac芯片类型下载：
   • Apple Silicon (M1/M2/M3/M4)：下载DroidProxy-arm64.dmg文件。
   • 注意：项目明确要求macOS 13.0 (Ventura) 及以上，且仅支持Apple Silicon芯片。Intel Mac用户无法运行。
3. 安装应用：打开下载的.dmg文件，将DroidProxy.app拖拽到“应用程序”文件夹中。
4. 首次运行：从“应用程序”文件夹或Launchpad中启动DroidProxy。由于应用已通过苹果公证（Notarized），系统可能会提示“来自未识别的开发者”，此时需要进入“系统设置”->“隐私与安全性”，在底部允许运行。之后，你会在屏幕顶部的菜单栏看到一个火箭形状的图标。

3.2 服务认证与连接

安装完成后，菜单栏图标是灰色的（未激活）。你需要登录至少一项服务才能启动代理服务器。

1. 点击菜单栏图标：点击火箭图标，下拉菜单会显示可登录的服务（Claude, Codex, Gemini）以及一个“Settings”选项。
2. 登录服务：
   • 点击“Login to Claude...”或“Login to Gemini...”。这会触发OAuth流程，打开你的默认浏览器。
   • 在浏览器中按照提示完成授权（登录你的Anthropic或Google账户，并同意DroidProxy访问）。
   • 授权成功后，浏览器页面会提示“认证成功，可以关闭此窗口”。回到DroidProxy，你会发现对应服务旁边出现了用户名或邮箱，并且菜单栏图标可能变为彩色或带有活动标识。
3. 验证代理运行：登录成功后，DroidProxy会自动在后台启动代理服务器。你可以打开终端，使用curl命令快速测试：

   # 测试Claude代理端点是否存活 curl -I http://localhost:8317 # 应该返回 HTTP/1.1 404 Not Found （这是正常的，因为根路径没有定义处理程序，但说明服务器在运行） # 或者测试OpenAI兼容端点 curl http://localhost:8317/v1/models -H "Authorization: Bearer dummy-key" # 由于我们还没配置Factory，这里可能返回认证错误，但也说明/v1端点已就绪

3.3 配置Factory.ai使用代理

这是让DroidProxy发挥价值的关键一步。你需要修改Factory的配置，使其将请求发送到本地代理。

重要提示：Factory的配置可能因版本更新而略有不同，但核心思路是修改Droid定义中的API基础URL。

1. 定位Factory配置：Factory的配置文件通常位于~/.factory/droids/目录下，每个Droid对应一个.md文件。
2. 编辑Droid配置：以你想要使用增强版Claude的Droid为例，用文本编辑器打开其配置文件。
3. 修改API端点：找到配置中关于模型API的部分（通常是api_base_url或base_url字段）。
   • 对于Claude模型：将端点改为http://localhost:8317。
   • 对于OpenAI/Codex模型：将端点改为http://localhost:8317/v1。
   • 对于Gemini模型：同样将端点改为http://localhost:8317/v1，并且模型名称按前述规则添加后缀（如gemini-3.1-pro-preview-high）。
4. 示例片段：一个修改后的Claude Droid配置可能看起来像这样：

   # 在Droid的配置文件中 model: claude-3-5-sonnet-20241022 api_base_url: http://localhost:8317 # ... 其他配置保持不变

5. 重启Factory：保存配置文件后，通常需要重启Factory应用或重新加载Droid配置，使更改生效。

3.4 配置思考强度

现在，你可以通过DroidProxy的图形界面精细控制每个模型的“思考力度”了。

1. 点击菜单栏图标，选择“Settings”。
2. 在弹出的设置窗口中，你会看到为每个支持的模型系列（Claude Opus, Claude Sonnet, GPT-5.3 Codex, GPT-5.4, GPT-5.5, Gemini 3.1 Pro, Gemini 3 Flash）提供的滑块。
3. 拖动滑块到你想要的努力级别（如medium,high）。
4. 设置是实时生效的。之后所有通过该代理发送的对应模型请求，都会自动附加上你配置的思考参数。

4. 高级用法与“挑战者”Droid实战

项目自带了一个极具价值的“彩蛋”——三款“挑战者”Droid。它们不是用来写代码的，而是用来审代码的，专治各种“我觉得这样写没问题”的自满情绪。

4.1 “挑战者”Droid是什么？

这是三个预设的Factory Droid，分别基于Claude Opus 4.7、GPT-5.5和Gemini 3.1 Pro。它们的核心指令是扮演“魔鬼代言人”或“严格的代码审查员”。当你对一段代码、一个架构决策感到满意时，可以召唤它们来发起挑战。

• 核心职责：
  • 挑战你的决策：为什么用A方案不用B？这里是否存在过度设计？
  • 揭示潜在权衡：你提升性能的同时，牺牲了可读性还是可维护性？
  • 压力测试边界情况：如果输入是null、空数组、极大值会怎样？
  • 提出具体替代方案：不只是批评，还会给出改进建议或另一种实现思路。
• 只读模式：它们被设计为不直接修改你的文件，而是提供结构化的文本反馈，包括挑战点、边缘案例和对你代码中优秀部分的肯定。这保证了审查过程的安全性和可讨论性。

4.2 安装“挑战者”Droid

安装过程其实就是将项目预置的配置文件复制到你的个人Factory配置目录。

# 确保你位于DroidProxy的项目目录下，或者知道下载的源码中 `.factory` 文件夹的位置。 # 创建必要的目录（如果不存在） mkdir -p ~/.factory/droids ~/.factory/commands # 复制Droid定义文件 cp /path/to/droidproxy/.factory/droids/challenger-opus.md ~/.factory/droids/ cp /path/to/droidproxy/.factory/droids/challenger-gpt.md ~/.factory/droids/ cp /path/to/droidproxy/.factory/droids/challenger-gemini.md ~/.factory/droids/ # 复制对应的斜杠命令定义文件 cp /path/to/droidproxy/.factory/commands/challenge-opus.md ~/.factory/commands/ cp /path/to/droidproxy/.factory/commands/challenge-gpt.md ~/.factory/commands/ cp /path/to/droidproxy/.factory/commands/challenge-gemini.md ~/.factory/commands/

复制完成后，重启Factory.app，新的Droid和命令就应该可用了。

4.3 在实战中使用代码挑战者

假设我正在Factory中编写一个Python函数，用于解析用户输入的日期字符串。我写了一个初步版本，感觉还不错。

1. 召唤挑战者：在Factory的聊天输入框里，输入斜杠命令/challenge-opus。
2. 提供上下文：命令执行后，通常会提示你提供代码或上下文。我会将我写的函数代码粘贴进去，并简要说明其目的：“这是一个日期解析函数，旨在处理多种常见格式。”
3. 接收结构化批判：Opus挑战者Droid会开始工作。它返回的不会是一段笼统的“看起来不错”的评论，而可能是一个结构化的输出：
   • 挑战1：“你使用了strptime并捕获了ValueError，但你的格式列表[‘%Y-%m-%d’， ‘%m/%d/%Y’]是否考虑了国际日期格式（DD/MM/YYYY）？这可能导致歧义。”
   • 挑战2：“函数在解析失败时返回None。调用者是否总是检查了返回值？是否考虑抛出一个更具体的自定义异常，包含原始输入字符串，以便于调试？”
   • 边缘案例：“如果输入字符串包含多余的空格、时区信息（如‘2023-01-01T00:00:00Z’）或是一个时间戳，当前逻辑会失败。”
   • 肯定之处：“使用预定义的格式列表进行循环尝试是处理多格式解析的经典模式，清晰且易于扩展。”
   • 替代方案：“可以考虑使用dateutil.parser第三方库，它更健壮，但会增加依赖。或者，可以增加一个strict=False参数，在宽松模式下尝试解析。”
4. 交叉验证：我不止步于一个模型的意见。我可以继续输入/challenge-gpt和/challenge-gemini，让GPT-5.5和Gemini 3.1 Pro从它们的角度再审查一遍。GPT可能会更关注算法效率，而Gemini可能会对错误信息的设计提出不同见解。
5. 迭代改进：综合三位“挑战者”的意见，我重构了我的函数：增加了日期格式顺序的逻辑（优先匹配年月日明确的格式），将返回None改为抛出一个信息丰富的DateParseError，并在文档中明确了函数的能力边界。

这种多模型、批判性的审查流程，极大地提升了代码质量，并帮助我提前发现了许多单靠自己或单一模型容易忽略的盲点。

5. 常见问题排查与实战心得

即使工具设计得再完善，在实际部署和使用中总会遇到一些“坑”。以下是我在长时间使用DroidProxy过程中总结的一些典型问题和解决方案。

5.1 代理服务器启动失败或无法连接

这是最常见的问题，通常表现为Factory提示“无法连接到模型”或“API错误”，或者DroidProxy菜单栏图标显示未连接状态。

5.2 思考参数未生效

你配置了high努力程度，但感觉模型的响应速度和内容深度没有变化。

• 检查请求流：首先确认请求确实经过了DroidProxy。可以在DroidProxy的Settings窗口中开启更详细的日志（如果支持），或者使用像mitmproxy这样的中间人工具拦截发往localhost:8317的请求，查看请求体是否包含了thinking或reasoning字段。
• 确认模型匹配：确保你在DroidProxy中配置的模型滑块，与Factory实际调用的模型完全对应。例如，为Opus 4.7配置的滑块，不会影响Sonnet 4.6的请求。
• API兼容性：思考参数是模型特定的功能。请确认你使用的模型版本确实支持该功能。例如，早期的Claude 3.0版本可能不支持adaptivethinking。

5.3 性能与延迟感知

开启高努力程度（如max,xhigh）后，模型响应时间显著变长。

• 这是预期行为：更深入的思考意味着模型在“内部”进行了更多的计算步骤，消耗了更多的推理时间和令牌。这相当于你用等待时间换取更高质量的输出。
• 策略选择：
  • 日常开发：使用medium或high，在质量和速度间取得良好平衡。
  • 深度设计/审查：在需要最高质量输出时（如撰写设计文档、关键代码审查），切换到xhigh或max，并耐心等待。
  • 善用“最大预算模式”：对于Sonnet，当你需要一次性的深度分析但不想每次都手动设置时，直接打开这个开关。
• 配额监控：深度思考会消耗更多令牌，请密切关注你的API用量，特别是Anthropic和OpenAI的配额限制。

5.4 关于自建与源码编译

大多数用户无需编译源码。但如果你有定制化需求或想了解内部机制，可以尝试。

1. 环境准备：确保你的Mac已安装最新版本的Xcode命令行工具和Swift包管理器。
2. 获取源码：git clone https://github.com/anand-92/droidproxy.git
3. 调试构建：在项目根目录运行make build，这会在.build目录生成可执行文件。
4. 发布构建与签名：运行./create-app-bundle.sh。这个脚本会处理代码签名和打包成.app。注意：你需要有自己的苹果开发者证书才能进行有效的签名，否则应用可能无法在非开发机器上运行或触发系统安全警告。
5. 依赖项目：理解DroidProxy重度依赖CLIProxyAPIPlus这个二进制文件（位于Resources/目录）。它是实际处理网络代理和协议转换的核心引擎。DroidProxy的Swift代码主要负责UI、配置管理和进程控制。

6. 项目架构浅析与扩展思路

虽然作为用户我们主要与UI交互，但了解其背后的设计能帮助我们更好地 troubleshoot 和想象其可能性。

6.1 核心组件协作

从Project Structure可以看出，这是一个典型的Swift macOS菜单栏应用架构：

• AppDelegate：应用生命周期和菜单栏图标管理的核心。
• ServerManager：最关键的组件之一。负责启动、停止和监控底层的cli-proxy-api-plus二进制进程。这个进程才是真正监听localhost:8317端口的HTTP/S代理服务器。
• ThinkingProxy：业务逻辑核心。它作为HTTP请求的中间件，拦截从Factory发来的请求，根据配置的规则（模型名、思考强度设置）对请求体进行修改（注入JSON参数），然后再转发给真实的AI服务API。
• AuthStatus：负责监控auth.json凭证文件的变化，并更新UI状态。它使用FileMonitor之类的技术来监听文件改动。
• TunnelManager：可能负责处理更复杂的网络隧道场景（虽然当前版本可能未启用），为未来功能留出接口。
• SettingsView：使用SwiftUI构建的用户配置界面。你的滑块操作会在这里被捕获，并持久化到UserDefaults或配置文件中，同时通知ThinkingProxy更新其注入规则。

6.2 扩展可能性

DroidProxy的架构为扩展提供了清晰的路径：

1. 支持更多模型：如果你想为新的AI模型（如DeepSeek、国内大模型）添加思考控制，主要工作集中在ThinkingProxy.swift中，增加新的模型识别规则和参数注入逻辑，并在SettingsView中添加对应的UI控件。
2. 自定义代理规则：目前的规则主要是注入思考参数。理论上，你可以修改代理逻辑，实现请求/响应的任意修改，比如统一修改系统提示词（system prompt）、添加自定义请求头、或者对响应内容进行后处理（如格式化代码）。
3. 集成更多开发工具：除了Factory.ai，理论上任何可以通过HTTP API配置AI后端的IDE插件或工具（如Cursor、Windsurf、甚至是自定义脚本）都可以受益于DroidProxy的统一代理和增强功能。关键在于让这些工具将API端点指向localhost:8317。

6.3 安全与隐私考量

这是一个本地代理，所有数据流经你的机器，这是一个重要的优势。

• 凭证安全：OAuth令牌存储在苹果钥匙串中，这是macOS上最安全的凭证存储方式之一，比放在明文配置文件里安全得多。
• 数据本地性：你的代码、提示词等所有数据在发送到云端AI服务前，只经过你自己的电脑和DroidProxy进程。DroidProxy本身不开源服务器端，因此不存在额外的第三方数据中转风险。
• 信任基础：你最终需要信任CLIProxyAPIPlus这个二进制文件以及DroidProxy应用本身。使用从官方Releases下载的、经过苹果公证的版本，可以最大程度降低风险。

经过几个月的深度使用，DroidProxy已经从我的一个“尝鲜工具”变成了AI编程工作流中不可或缺的基础设施。它巧妙地解决了多模型管理、认证繁琐和深度推理控制这三个核心痛点。尤其是“挑战者”Droid的引入，将AI从单纯的代码生成助手，提升为了一个严肃的代码审查伙伴。这种将多个顶级模型通过一个轻量、美观的本地应用统一调度和增强的思路，代表了AI工具开发的一个实用方向——不追求大而全的平台，而是聚焦于解决一个垂直领域的深度工作流问题。如果你是一名Apple Silicon Mac用户，并且同时使用多个AI编码服务，我强烈建议你花半小时部署和尝试一下DroidProxy，它很可能会重塑你与AI协作编程的方式。