From 5d4edaa95f587a3c071bd76494e254222b858cda Mon Sep 17 00:00:00 2001 From: Sev7eNup <79143581+Sev7eNup@users.noreply.github.com> Date: Wed, 12 Aug 2026 16:30:15 +0200 Subject: [PATCH] docs: a proxy is not the answer to an unreachable endpoint Both AI-features documents put the outbound-proxy section ahead of the stage-by-stage diagnosis, so a reader arriving with "the endpoint in our corporate network is unreachable" meets the proxy first and configures one. That is not a hypothetical: it happened. An endpoint sitting in another network segment without a firewall rule was read as a proxy problem and cost several rounds before the missing rule was found. A proxy answers "outbound traffic MAY only leave this network through the proxy"; it does nothing for a route that is blocked. Both sections now say so up front and point at the stage diagnosis, which answers the question in seconds - the cheaper first step. --- docs/ai-features.md | 10 ++++++++++ src/nodepilot-docs-ui/content/ai-features.md | 7 +++++++ 2 files changed, 17 insertions(+) diff --git a/docs/ai-features.md b/docs/ai-features.md index 7a61be9..ccd0f3e 100644 --- a/docs/ai-features.md +++ b/docs/ai-features.md @@ -108,6 +108,16 @@ Neu-Eintippen. **Outbound-Proxy (`Llm:Proxy:*`):** +> **Erst die Stufe feststellen, dann konfigurieren.** Ein Proxy ist die Antwort auf „ausgehender +> Verkehr **darf** dieses Netz nur über den Proxy verlassen" — **nicht** auf „der Endpunkt ist +> nicht erreichbar". Liegt der Endpunkt in einem anderen Netzsegment und fehlt die +> Firewall-Freischaltung, hilft kein Proxy; hier einen zu setzen verschiebt nur, wohin die +> Verbindung *nicht* aufgebaut wird. Welche Stufe scheitert, sagt +> [„Endpunkt nicht erreichbar"](#endpunkt-nicht-erreichbar--welche-stufe-gescheitert-ist) weiter +> unten in Sekunden — das ist der billigere erste Schritt. (Real passiert: ein +> `LLM endpoint TCP:`-Fehlschlag wurde als Proxy-Problem gelesen und kostete mehrere Runden, bis +> die fehlende Firewall-Regel gefunden war.) + Gilt für **alle** ausgehenden LLM-Aufrufe — Script-/Workflow-Generierung, beide Chats, die `llmQuery`-Activity und den „Testen"-Button in den Settings. Ein Block pro Installation, nicht pro Profil: der Fall „Cloud-Profil über den Proxy, lokales Ollama direkt" wird über `BypassList` diff --git a/src/nodepilot-docs-ui/content/ai-features.md b/src/nodepilot-docs-ui/content/ai-features.md index 6fff188..61d85f9 100644 --- a/src/nodepilot-docs-ui/content/ai-features.md +++ b/src/nodepilot-docs-ui/content/ai-features.md @@ -183,6 +183,13 @@ Einstellungen. Es ist bewusst ein Block für die gesamte Installation und nicht der gemischte Fall — Cloud-Modell über den Proxy, lokales Modell direkt — wird über die Ausnahmeliste abgebildet. +Ein Proxy ist dabei die Antwort auf „ausgehender Verkehr **darf** dieses Netz nur über den Proxy +verlassen" — nicht auf „der Endpunkt ist nicht erreichbar". Liegt der Endpunkt in einem anderen +Netzsegment und fehlt die Freischaltung in der Firewall, ändert ein Proxy daran nichts. Prüfen Sie +deshalb zuerst, welche Stufe scheitert: der Abschnitt +[Wenn der Endpunkt nicht erreichbar ist](#wenn-der-endpunkt-nicht-erreichbar-ist) beantwortet das +in Sekunden. + | Einstellung | Bedeutung | |---|---| | `Mode` | `Off` verbindet direkt (Voreinstellung), `System` übernimmt den Proxy des Dienstkontos samt dessen Ausnahmeregeln, `Custom` verwendet die Adresse unten |