From b5d8a3e30a76ca9a8141c140d50fe07960af236a Mon Sep 17 00:00:00 2001
From: dianed-square <73617011+dianed-square@users.noreply.github.com>
Date: Wed, 18 Feb 2026 11:31:10 -0800
Subject: [PATCH] docs: system proxy settings (#7311)

---
 .../docs/guides/environment-variables.md      |  2 ++
 .../docs/troubleshooting/known-issues.md      | 32 +++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 99db4c4226..35e8c7da07 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -456,6 +456,8 @@ export HTTPS_PROXY="http://username:password@proxy.company.com:8080"
 export NO_PROXY="localhost,127.0.0.1,.internal"
 ```
 
+Alternatively, proxy settings can be configured through your operating system's network settings. If you encounter connection issues, see [Corporate Proxy or Firewall Issues](/docs/troubleshooting/known-issues#corporate-proxy-or-firewall-issues) for troubleshooting steps.
+
 ## Observability
 
 Beyond goose's built-in [logging system](/docs/guides/logs), you can export telemetry to external observability platforms for advanced monitoring, performance analysis, and production insights.
diff --git a/documentation/docs/troubleshooting/known-issues.md b/documentation/docs/troubleshooting/known-issues.md
index 921ccd0639..344afd557f 100644
--- a/documentation/docs/troubleshooting/known-issues.md
+++ b/documentation/docs/troubleshooting/known-issues.md
@@ -446,6 +446,38 @@ If you still encounter a `failed to connect` error, you can try using WSL's [Mir
 
 ---
 
+### Corporate Proxy or Firewall Issues
+
+If you're behind a corporate proxy or firewall and goose cannot connect to your LLM provider, you may see errors like:
+
+```
+error sending request for url (https://api.openai.com/...)
+failed to connect to api.openai.com
+```
+
+goose supports HTTP/HTTPS proxy configuration through standard environment variables and system proxy settings. Environment variables take precedence when both are configured.
+
+**Solution:**
+
+1. **Configure [proxy environment variables](/docs/guides/environment-variables#network-configuration):**
+   ```bash
+   export HTTPS_PROXY="http://proxy.company.com:8080"
+   export NO_PROXY="localhost,127.0.0.1,.internal"
+   ```
+
+2. **Or use system proxy settings:**
+   - **macOS**: System Settings → Network → [select connection] → Details → Proxies
+   - **Windows**: Settings → Network & Internet → Proxy
+
+3. **Restart goose** after configuring proxy settings
+
+If you continue to experience connection issues, verify:
+- Your proxy URL and port are correct
+- You have authentication credentials if required (format: `http://username:password@proxy:port`)
+- Your proxy allows HTTPS connections to your LLM provider's domain
+
+---
+
 ### Airgapped/Offline Environment Issues
 
 If you're working in an airgapped, offline, or corporate-restricted environment, you may encounter issues where MCP server extensions fail to activate or download their runtime dependencies.