OpenClaw 在 macOS 下网络代理问题修复指南 fetch failed

OpenClaw 在 macOS 下网络代理问题修复指南

问题背景

在 macOS 上运行 OpenClaw Gateway 时，可能出现 fetch failed 或请求超时的错误。这个问题通常不是 Codex 认证失效，而是 Gateway 进程没有正确使用本地代理环境变量。原因在于 LaunchAgent 启动的服务不会继承终端中的 export 变量。

解决方案步骤

1. 停止当前 Gateway 服务

launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist
openclaw gateway status  # 确认 not loaded

2. 编辑 plist 文件并添加代理环境变量

路径：~/Library/LaunchAgents/ai.openclaw.gateway.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>ai.openclaw.gateway</string>

    <key>Comment</key>
    <string>OpenClaw Gateway (v2026.2.25)</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>ProgramArguments</key>
    <array>
      <string>/opt/homebrew/Cellar/node/23.9.0/bin/node</string>
      <string>/opt/homebrew/lib/node_modules/openclaw/dist/index.js</string>
      <string>gateway</string>
      <string>--port</string>
      <string>18789</string>
    </array>

    <key>StandardOutPath</key>
    <string>/Users/aibot/.openclaw/logs/gateway.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/aibot/.openclaw/logs/gateway.err.log</string>

    <key>EnvironmentVariables</key>
    <dict>
      <key>HOME</key>
      <string>/Users/aibot</string>
      <key>TMPDIR</key>
      <string>/var/folders/qz/3yw812rj4wnb4dvf4wqh45200000gp/T/</string>
      <key>PATH</key>
      <string>/Users/aibot/.local/bin:/Users/aibot/.npm-global/bin:/Users/aibot/bin:/Users/aibot/.volta/bin:/Users/aibot/.asdf/shims:/Users/aibot/.bun/bin:/Users/aibot/Library/Application Support/fnm/aliases/default/bin:/Users/aibot/.fnm/aliases/default/bin:/Users/aibot/Library/pnpm:/Users/aibot/.local/share/pnpm:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>

      <key>OPENCLAW_GATEWAY_PORT</key>
      <string>18789</string>
      <key>OPENCLAW_GATEWAY_TOKEN</key>
      <string>9c9b815e4926b8aab19cbb3e1a7b7a9b23732c6f6e6518ed</string>
      <key>OPENCLAW_LAUNCHD_LABEL</key>
      <string>ai.openclaw.gateway</string>
      <key>OPENCLAW_SYSTEMD_UNIT</key>
      <string>openclaw-gateway.service</string>
      <key>OPENCLAW_SERVICE_MARKER</key>
      <string>openclaw</string>
      <key>OPENCLAW_SERVICE_KIND</key>
      <string>gateway</string>
      <key>OPENCLAW_SERVICE_VERSION</key>
      <string>2026.2.25</string>

      <!-- 代理设置 -->
      <key>HTTP_PROXY</key>
      <string>http://127.0.0.1:7890</string>
      <key>HTTPS_PROXY</key>
      <string>http://127.0.0.1:7890</string>
      <key>ALL_PROXY</key>
      <string>socks5://127.0.0.1:7890</string>
    </dict>
  </dict>
</plist>

3. 重新加载并启动 Gateway

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

4. 验证状态

openclaw gateway status
openclaw logs --follow

• 确认 Runtime: running 和 RPC probe: ok。
• 查看日志中不再出现 fetch failed 或请求超时。

5. 临时测试方式（可选）

在终端直接运行 Gateway，让它继承当前 shell 的代理环境：

openclaw gateway

如果这样可以正常连接 Codex，则说明代理配置正确。

---

📌 注意事项：

• 永久生效需要 plist 中的代理环境变量。
• 不要手动乱改 LaunchAgent 的 ProgramArguments 或 plist 根结构，否则会导致 bootstrap 失败。
• 如果仍然超时，需要排查 ***/VPN/DNS/IPv6 路由问题。