Feishu REST API failures via macOS system proxy — intermittent ProxyError / SSLEOFError

Summary

When macOS has a system HTTP/HTTPS proxy configured (e.g. ClashX / mihomo on 127.0.0.1:1082), Feishu REST API calls (message send, message edit, reactions) intermittently fail with ProxyError or SSLEOFError. The Lark SDK's lark.Client uses requests under the hood, which respects the macOS system proxy by default. When the local proxy drops the CONNECT tunnel mid-handshake, REST calls fail even though the WebSocket connection (which doesn't go through HTTP proxy) is healthy.

Environment

• Hermes Agent: latest main (commit 0384398c6)
• macOS: 26.5 (Apple Silicon)
• System proxy: 127.0.0.1:1082 (ClashX / mihomo)
• Feishu mode: WebSocket

Steps to Reproduce

1. Configure macOS system proxy to 127.0.0.1:1082 for both HTTP and HTTPS
2. Run Hermes Gateway with Feishu connected via WebSocket
3. Wait for the local proxy to have a transient hiccup (restart, connection timeout, etc.)
4. Hermes attempts to send or edit a message via Feishu REST API

Actual Behavior

REST API calls fail with one of two error patterns:

Pattern A — Proxy refuses connection:

[Feishu] Failed to send message to oc_xxx:
ProxyError('Cannot connect to proxy.', OSError('Tunnel connection failed: 503 Service Unavailable'))

Pattern B — Proxy drops CONNECT tunnel mid-TLS:

[Feishu] Failed to edit message om_xxx:
SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1016)')

Observed frequency: Clusters of 2-4 errors within a ~15 minute window, then clears for hours. Consistent with a local proxy that has intermittent stability issues — not a Feishu server-side problem.

Expected Behavior

Feishu REST API calls should be resilient to transient local proxy failures, or Hermes should provide a way to bypass the system proxy for specific platforms without affecting other applications that need the proxy.

Root Cause

lark.Client uses requests.Session internally. On macOS, requests discovers and uses the system proxy by default. There is no configuration option in lark.Client.builder() to disable proxy usage (trust_env=False).

The WS connection (wss://msg-frontier.feishu.cn) is unaffected because WebSocket connections don't go through HTTP proxies.

Workaround Applied (Local)

Set client._session.trust_env = False on the Lark client's internal session in gateway/platforms/feishu.py:_build_lark_client():

def _build_lark_client(self, domain: Any) -> Any:
    client = (
        lark.Client.builder()
        .app_id(self._app_id)
        .app_secret(self._app_secret)
        .domain(domain)
        .log_level(lark.LogLevel.WARNING)
        .build()
    )
    if hasattr(client, "_session"):
        client._session.trust_env = False
    return client

This is a hack — it relies on the internal _session attribute of lark.Client, which is not part of the public API.

Suggested Proper Fix

1. Option A (Hermes-side): Add a config option platforms.feishu.bypass_system_proxy: true that sets trust_env=False on the Lark client session
2. Option B (Lark SDK upstream): Add .trust_env(bool) to lark.Client.builder() API
3. Option C (Docs): Document in Feishu setup guide that users with system proxies should set no_proxy=open.feishu.cn in their Hermes environment

Related

• #31367 — Feishu WS disconnect causes full gateway restart (related but separate root cause — WS vs REST API)
• #31386 — Adapter-level WS reconnect fix (merged)
• #32574 — Gateway platform liveness watchdog (could help detect zombie REST connections too)

Log Excerpts

2026-05-29 18:07:17 [Lark] ProxyError: Cannot connect to proxy, Tunnel connection failed: 503 Service Unavailable
2026-05-29 20:28:37 [Feishu] Failed to edit message: SSLEOFError(8, UNEXPECTED_EOF_WHILE_READING)
2026-05-29 20:33:19 [Feishu] Failed to edit message: SSLEOFError(8, UNEXPECTED_EOF_WHILE_READING)
2026-05-29 22:45:58 [Feishu] Failed to send message: SSLEOFError(8, UNEXPECTED_EOF_WHILE_READING)