[Bug / Feature Request] agent 的 API 地址处理与文档不一致，并建议完善 Headers、代理、重试及执行可观测性

背景

在使用 FIRERPA 内置 agent 命令对接模型 API、执行 Android 自动化任务时，遇到一些接口兼容性、网络连接和执行效率方面的问题，希望反馈并提出改进建议。

相关文档：https://device-farm.com/docs/zh/model-extension

下面包含已复现的问题、使用中观察到的现象，以及功能建议。对于代理、重试和等待机制，目前无法从现有输出确认内部实现，因此也希望维护者协助说明；如果已有对应配置入口，希望能补充到文档中。

1. --api 的实际地址处理行为与文档描述不一致

复现方式

按照文档对完整接口地址的描述，将 --api 设置为：

https://open.bigmodel.cn/api/paas/v4/chat/completions

命令形式如下，密钥和模型名称已替换为占位值：

agent \
  --api "https://open.bigmodel.cn/api/paas/v4/chat/completions" \
  --key "YOUR_API_KEY" \
  --model "YOUR_MODEL_NAME" \
  --prompt "打开系统设置"

实际报错：

openai.NotFoundError: Error code: 404 - {'timestamp': '2026-09-18T01:03:50.423+00:00', 'status': 404, 'error': 'Not Found', 'path': '/v4/chat/completions/chat/completions'}

实际行为

从错误中的路径可以看到，/chat/completions 被重复追加了：

/v4/chat/completions/chat/completions

这说明当前行为更接近将 --api 作为 base_url 使用，而不是直接使用传入的完整接口地址，与文档描述不一致。

期望行为

希望统一参数语义、实际实现、命令帮助和文档示例：

• 如果 --api 表示完整接口地址，应直接使用，不再追加 /chat/completions。
• 如果实际要求传入 Base URL，希望修正文档，并考虑使用更明确的 --base-url 命名。

也建议针对这类明显的路径重复拼接问题，提供更直接的错误提示。

2. 希望支持自定义模型请求 HTTP Headers

目前在文档中找到了 --api、--key、--model 等配置，但未找到追加自定义 HTTP Headers 的入口。

部分模型 API 或自建网关，除了常规 API Key 外，还需要额外的网关认证、租户或项目标识，例如：

X-Gateway-Token: xxx
X-API-Key: xxx
X-Tenant-ID: xxx
X-Project-ID: xxx

希望增加可重复传入的 --header / -H 参数，例如：

# 以下为建议语法，并非现有功能。
agent \
  ... \
  --header "X-Gateway-Token: YOUR_GATEWAY_TOKEN" \
  --header "X-Tenant-ID: YOUR_TENANT_ID"

这里指的是 agent → 模型 API 的请求头，而不是 MCP 客户端 → FIRERPA MCP 服务 的请求头。

希望自定义 Headers 能应用于任务中的所有模型请求，包括工具调用后的后续请求。同时，建议明确与默认请求头（例如 Authorization）冲突时的处理规则，并支持通过配置文件或环境变量加载敏感值，避免只能直接写入命令行。

3. 希望增加显式代理配置

使用现象

在 Android 的 Wi-Fi 设置中配置好代理后，浏览器等应用可以访问 Google 等外部站点，但 agent 对接需要通过该网络访问的模型 API 时，仍然出现超时，无法正常使用。

目前无法确认：

• agent 是否会读取 Android Wi-Fi 的代理设置。
• 是否需要单独配置代理，或是否已有受支持的代理环境变量。

浏览器能够访问，并不能直接说明 agent 使用了相同的网络路径，因此希望提供明确的配置方式和排查信息。

建议

增加显式代理参数，例如：

# 以下为建议语法，并非现有功能。
agent \
  ... \
  --proxy "http://PROXY_HOST:PORT"

建议说明支持的代理协议、代理认证方式，以及命令行参数与环境变量的优先级；同时提供连接超时、响应读取超时等配置。

代理最好能够仅作用于模型 API 请求，避免影响本地设备或 MCP 连接。详细日志中也希望能看到当前是否启用了代理，但不要打印代理密码等敏感信息。

4. 部分模型返回 HTTP 429，希望完善重试配置与提示

使用部分模型时会遇到 HTTP 429。

目前未找到重试次数、等待间隔或退避策略的配置入口，也无法从输出判断是否已经发生过重试。因此，这里并不是确认内部完全没有重试，而是希望重试行为能够被配置和观察。

建议支持：

• 可配置最大重试次数、最大累计等待时间，以及带随机抖动的指数退避策略。
• 对可重试的限流响应，在服务端提供有效 Retry-After 时优先参考；对于明确的额度不足等不可恢复情况，及时提示，避免无效重试。
• 打印重试原因、当前次数、下一次等待时间，以及最终失败原因。

重试范围也希望明确限定，避免因重试模型请求或恢复任务而无意重复执行已经完成的设备操作。

5. 执行过程中间隔较长，希望明确等待机制并支持调整

实际日志

一次设置相关任务的输出如下：

Fri Sep 18 09:08:09 2026 assistant: 点击设置图标，打开设置应用，以进入网络设置页面
Fri Sep 18 09:08:53 2026 assistant: 等待设置页面完全加载
Fri Sep 18 09:10:44 2026 assistant: 点击主页返回系统桌面，重新打开系统设置应用
Fri Sep 18 09:12:22 2026 assistant: 点击底部设置按钮，进入系统设置主页
Fri Sep 18 09:13:18 2026 assistant: 向下滚动查看更多设置选项，寻找网络设置

相邻输出的时间间隔约为 44～111 秒，第一条到最后一条共 5 分 9 秒。

需要说明的是，这些只是输出之间的时间差，不能直接等同于工具执行耗时或框架等待时间。但从使用体验来看，这类简单操作的整体推进速度偏慢，而且仅凭现有输出无法判断时间主要花在哪里：

是模型响应慢、网络连接或重试耗时、工具执行慢、页面未就绪，还是 Agent 内部存在固定等待？

日志中还出现了返回桌面、重新打开设置等行为，也难以判断是模型决策问题、页面状态识别问题，还是执行结果反馈不足。

建议

希望说明是否存在固定 sleep、操作节流、页面加载等待或轮询间隔，并提供可调整的配置。

也希望考虑支持可选的“模型驱动等待”模式：由提示词及显式等待工具决定是否等待、等待多久，而不是依赖不可见、不可调整的固定长等待。必要的页面就绪检查、超时上限和保护间隔可以保留，但希望能够配置并在日志中解释原因。

核心诉求不是简单取消所有等待，而是让等待行为合理、可控、可解释，并能够区分“模型耗时”和“设备操作耗时”。

6. 希望支持流式输出和详细诊断日志

流式输出

目前运行时看到的内容主要是 assistant 文本，长时间没有新输出时，很难判断任务是在正常处理、等待模型、重试，还是已经卡住。

对于支持流式响应的模型接口，希望提供可选的流式打印，例如建议增加 --stream，及时展示收到的文本增量，而不是长时间没有任何反馈。

流式显示本身不一定能缩短任务总耗时，但有助于改善交互体验，并观察模型响应进度。工具调用仍应在参数接收完整并校验后执行。

详细日志

希望提供 --verbose / --debug 等模式，至少能够观察：

也希望可以选择记录更完整的模型请求、响应、工具调用和工具结果，以便复现和分析问题。API Key、Authorization、自定义认证 Headers、代理凭证等敏感信息应脱敏。

目前最大的问题是：无法从输出判断究竟是模型延迟、模型决策、网络问题，还是 Agent 自身的执行与等待策略影响了速度。

如果能提供这些诊断信息，用户就能更有针对性地选择模型、调整提示词、排查网络或优化任务，而不是只能凭体感判断“不够流畅”。

总结

希望优先确认并修复 --api 地址语义与文档不一致的问题，并逐步完善自定义 Headers、代理、重试、等待控制和执行可观测性。

这些能力对于接入不同模型网关、在代理网络下运行，以及长期执行自动化任务都很有帮助。若其中部分能力已经支持，也希望补充相应的命令示例和配置说明。

感谢维护这个项目！