> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/de/modul-9-uberwachung-and-fehlerbehebung/06-common-issues.md).

# Häufige Probleme & Lösungen

Fehlersuchmuster für die am häufigsten auftretenden VergeOS-Probleme — VM-Netzwerk, Gast-Speicherberichterstattung, SEL-Rauschen, NAS-Freigaben, Installationsprobleme und Speicherdegradation.

## Fehlerbehebungs-Kurzübersicht

Diese Seite fasst die häufigsten Probleme zusammen, auf die VergeOS-Administratoren stoßen, geordnet nach Subsystem. Jeder Abschnitt enthält Symptome, Ursachen und schrittweise Vorgehensweisen zur Behebung.

```mermaid
graph TD
    A["Symptom identifizieren"] --> B{"Welches Subsystem?"}
    B -->|VM| C["Netzwerk / Speicher"]
    B -->|Storage| D["vSAN / NAS"]
    B -->|Hardware| E["SEL / IPMI"]
    B -->|Install| F["Boot / Beitritt"]

    C --> G["Schritte zur Fehlerbehebung"]
    D --> G
    E --> G
    F --> G
    G --> H{"Behoben?"}
    H -->|Yes| I["Dokumentieren & Schließen"]
    H -->|No| J["An Support eskalieren"]

    style A fill:#4a90d9,color:#fff
    style B fill:#2c3e50,color:#fff
    style G fill:#27ae60,color:#fff
    style J fill:#e74c3c,color:#fff
```

***

## VM-Netzwerkkonnektivität

Netzwerkkonnektivitätsprobleme sind das häufigste Support-Thema. Bevor Sie tiefer einsteigen, prüfen Sie, ob **andere VMs** in derselben Umgebung auf das Internet zugreifen können. Wenn keine kann, liegt das Problem wahrscheinlich vor VergeOS (Switch, Firewall, ISP). Wenn andere VMs problemlos funktionieren, handelt es sich fast immer um eine Fehlkonfiguration der betroffenen VM.

### Fehlende NIC-Konfiguration

**Symptom:** Die VM startet, aber im Gastbetriebssystem sind keine Netzwerkschnittstellen sichtbar.

**Lösung:**

1. Öffnen Sie das VM-Dashboard und prüfen Sie den **NICs** -Abschnitt
2. Wenn keine NIC aufgeführt ist, klicken Sie auf **NIC hinzufügen**
3. Wählen Sie das richtige Netzwerk und setzen Sie den Schnittstellentyp auf **VirtIO** (empfohlen) oder **E1000** für Legacy-Kompatibilität
4. Die NIC erscheint im Gast sofort, wenn Hot-Plug aktiviert ist (Standard) — auf einigen Betriebssystemen ist möglicherweise ein erneutes Scannen des Gast-OS erforderlich. Führen Sie nur dann einen Power-Cycle durch, wenn Hot-Plug deaktiviert ist.

### Falsche Netzwerkzuordnung

**Symptom:** Die VM hat eine NIC, kann aber weder andere VMs noch das Internet erreichen.

**Lösung:**

1. Navigieren Sie zum VM-Dashboard → **NICs**
2. Stellen Sie sicher, dass der NIC-Status **Up**
3. ist **Netzwerk** Spalte das richtige Netzwerk anzeigt — vergleichen Sie mit einer funktionierenden VM in derselben Umgebung
4. Wenn falsch, bearbeiten Sie die NIC und weisen Sie sie dem richtigen Netzwerk zu
5. Führen Sie einen Power-Cycle der VM durch

### Fehlende VirtIO-Treiber

**Symptom:** Die Windows-VM zeigt im Geräte-Manager keinen Netzwerkadapter an, obwohl in VergeOS eine NIC konfiguriert ist.

**Lösung:**

1. Stellen Sie sicher, dass im **NICs** Abschnitt der VM in VergeOS eine NIC vorhanden ist
2. Verbinden Sie sich mit der VM über die **Remote-Konsole**
3. Installieren Sie die VirtIO-Treiber von der ISO des Gast-Agenten — siehe die VergeOS-Dokumentation zum [VM Guest Agent](https://docs.verge.io/run-the-platform/de/virtuelle-maschinen/vm-guest-agent.md) für Download- und Installationsschritte
4. Nach der Treiberinstallation erkennt Windows den Netzwerkadapter automatisch

### Falsche Gast-IP-Konfiguration

**Symptom:** Die NIC ist vorhanden und die Treiber sind installiert, aber die VM kann das Netzwerk dennoch nicht erreichen.

**Lösung:**

1. Prüfen Sie im Gastbetriebssystem, ob der Netzwerkadapter erkannt und aktiviert ist
2. Für DHCP: Stellen Sie sicher, dass im Netzwerk ein DHCP-Dienst läuft (prüfen Sie **Netzwerke → \[Netzwerk] → DHCP**)
3. Für statische IP: Bestätigen Sie, dass IP-Adresse, Subnetzmaske, Gateway und DNS-Einstellungen dem Netzwerkdesign entsprechen
4. Verwenden Sie das **Netzwerkdiagnose-Tool** (Ping, ARP-Scan) aus dem VergeOS-Netzwerkkontext, um die Layer-2-Konnektivität zu prüfen

***

## Speicherberichterstattung des Gasts

Administratoren, die von VMware oder Nutanix migrieren, bemerken oft, dass VergeOS eine höhere Speicherauslastung meldet, als sie erwarten. Das ist beabsichtigt — kein Problem.

### Zugewiesener vs. aktiver Speicher

**Symptom:** VergeOS zeigt eine VM mit 8 GB RAM, aber der Task-Manager des Gasts zeigt nur 2 GB in Benutzung.

**Erklärung:** VergeOS zeigt den **zugewiesenen** Speicher an — den physischen RAM, der auf dem Host für diese VM reserviert ist. Wenn Sie einer VM 8 GB zuweisen, reserviert der Hypervisor sofort 8 GB physischen Speicher, unabhängig davon, wie viel der Gast aktiv verbraucht. Das ist die tatsächliche Ressourcenbindung auf dem Host.

### Kein Memory Ballooning

Im Gegensatz zu Plattformen, die auf Memory Ballooning angewiesen sind, um ungenutzten Gast-Speicher zurückzugewinnen, **verwendet VergeOS absichtlich kein Ballooning**. Diese Designentscheidung bietet:

* **Vorhersagbare Leistung** — kein Balloon-Treiber-Overhead und keine überraschende Speicherdrucksituation
* **Einfachere Kapazitätsplanung** — zugewiesen = zugesagt; kein Rätselraten bei Überbelegungsquoten
* **Höhere Zuverlässigkeit** — kein Risiko von durch Ballooning verursachten OOM-Zuständen innerhalb von Gastsystemen
* **Genaue Größenplanung für Migrationen** — was Sie zuweisen, benötigen Sie auf dem Zielhost

### Best Practices für die Kapazitätsplanung

| Metrik                               | Wo prüfen                                        | Was es bedeutet                                     |
| ------------------------------------ | ------------------------------------------------ | --------------------------------------------------- |
| **VM zugewiesener RAM**              | VM-Dashboard                                     | Physischer RAM, der für diese VM reserviert ist     |
| **Aktiver RAM des Gasts**            | Im Gastbetriebssystem (Task-Manager / `free -h`) | Was der Gast tatsächlich verwendet                  |
| **Verfügbarer RAM des Knotens**      | Knoten-Dashboard → Speicher                      | Wie viel Host-RAM noch nicht zugewiesen ist         |
| **Maximale Ziel-RAM-% des Clusters** | System → Einstellungen → Erweitert               | Schwellenwert für Entscheidungen zur VM-Platzierung |

{% hint style="success" %}
**VMs richtig dimensionieren**

Da VergeOS den vollen Betrag zuweist, ist die richtige Dimensionierung des VM-Speichers wichtiger als auf Plattformen mit Ballooning. Beginnen Sie mit konservativen Zuweisungen und erhöhen Sie nur dann, wenn die Überwachung des Gasts eine dauerhaft hohe Auslastung zeigt.
{% endhint %}

***

## SEL-Rauschen (falsch positive IPMI-Logs)

Einige Serverhardware erzeugt wiederholte, harmlose IPMI-Logeinträge, die das System Event Log (SEL) füllen und unnötige Warnungen auslösen. Der häufigste Verursacher ist die **"Get SEL Info command failed"** -Meldung.

### Den SEL verstehen

Das System Event Log wird in der Hardware (auf dem BMC/IPMI-Controller) mit begrenzter Kapazität gespeichert. Sobald es voll ist, **können keine neuen Ereignisse aufgezeichnet werden** bis das Protokoll geleert wird. Das Knoten-Dashboard zeigt die SEL-Kapazität als Prozentbalken an.

### SEL-Rauschen über die API filtern

Um falsch positive Meldungen zu unterdrücken, ohne echte Hardwarewarnungen zu verlieren:

1. Navigieren Sie zu **System → API-Dokumentation**
2. Suchen Sie die **settings** Tabelle und klappen Sie sie auf
3. Klicken Sie auf die **POST** -Option und geben Sie diesen Body ein:

```json
{
  "key": "syslog_regex_list",
  "value": "2E2A4765742053454C20496E666F20636F6D6D616E64206661696C65642E",
  "default_value": "",
  "description": "Hex-kodierte Zeilen von regulären Ausdrücken, die aus syslog herausgefiltert werden"
}
```

4. Klicken Sie auf **Ausführen**

Der Wert ist ein hex-kodierter Regex: `.*Get SEL Info command failed.` — Sie können zusätzliche Muster mit einem Hex-Kodierungswerkzeug kodieren und mehrere Muster mit `|`.

**Beispiel — zwei Muster filtern:**

Der Regex `(Get SEL Info command failed|Unable to send command: Device or resource busy)` kodiert zu:

```
284765742053454C20496E666F20636F6D6D616E64206661696C65647C556E61626C6520746F2073656E6420636F6D6D616E643A20446576696365206F72207265736F75726365206275737929
```

### Neustart des IPMI-Dienstes

Starten Sie nach Anwendung des Filters die Protokollaufzeichnung auf jedem betroffenen Knoten neu:

**Option A — über die Benutzeroberfläche:**

1. Navigieren Sie zu **Infrastruktur → Knoten → \[Knoten]**
2. Bearbeiten Sie den Knoten, **deaktivieren Sie** "Capture System Logs", senden
3. 15 Sekunden warten
4. Bearbeiten Sie den Knoten erneut, **erneut aktivieren** "Capture System Logs"

**Option B — per SSH:**

```bash
sudo systemctl restart openipmi
```

### Einen vollen SEL leeren

Wenn der SEL bereits voll ist:

1. Navigieren Sie zu **Infrastruktur → Knoten → \[Knoten]**
2. Klicken Sie auf **SEL leeren** im linken Menü
3. Bestätigen Sie mit **Ja**

***

## Probleme mit NAS-Freigaben

### Windows: Kann keine Verbindung zu CIFS-Freigaben herstellen

**Symptom:** Windows-10/11-Clients können nicht auf CIFS-Freigaben zugreifen und erhalten selbst mit korrekten Anmeldedaten die Fehler "Zugriff verweigert" oder "kann keine Verbindung herstellen".

**Ursache:** Moderne Windows-Standardkonfigurationen deaktivieren unsichere Gastanmeldungen für SMB-Verbindungen.

**Lösung — unsichere Gastanmeldungen aktivieren:**

1. Drücken Sie `Win + R`, geben Sie ein `gpedit.msc`, drücken Sie Enter
2. Navigieren Sie zu: **Computerkonfiguration → Administrative Vorlagen → Netzwerk → Lanman Workstation**
3. Suchen Sie **Unsichere Gastanmeldungen aktivieren** → Rechtsklick → **Bearbeiten**
4. Wählen Sie **Aktiviert** → Klicken Sie auf **OK**
5. **Starten Sie** das Windows-Gerät neu

{% hint style="warning" %}
**Windows Home Edition**

`gpedit.msc` ist unter Windows Home nicht verfügbar. Verwenden Sie stattdessen den Registrierungs-Editor: Navigieren Sie zu `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters` und setzen Sie `AllowInsecureGuestAuth` (DWORD) auf `1`.
{% endhint %}

### macOS: Verbindungsfehler oder schlechte Leistung

**Symptom:** Der macOS-Finder kann keine Verbindung zu CIFS-Freigaben herstellen, Verbindungen brechen intermittierend ab oder die Leistung ist unbrauchbar.

**Lösung — SMB3 erzwingen über `nsmb.conf`:**

1. Öffnen Sie das Terminal und erstellen oder bearbeiten Sie die SMB-Konfiguration:

```bash
sudo nano /etc/nsmb.conf
```

2. Fügen Sie Folgendes hinzu:

```ini
[default]
smb_neg=smb3_only
signing_required=no
```

3. **Leeren Sie den macOS-SMB-Cache:**

```bash
sudo rm -rf /var/db/samba/*
sudo rm -rf /var/db/smb/*
```

4. **Starten Sie Ihren Mac neu** um die Änderungen zu übernehmen

**Erweiterte Konfigurationsoptionen für macOS-Clients:** Für bessere macOS-Kompatibilität fügen Sie die macOS-orientierten Direktiven hinzu (einschließlich `vfs objects = fruit streams_xattr` und die zugehörigen `fruit:*` Optionen) unter **Erweiterte Konfigurationsoptionen** in den NAS-CIFS-Einstellungen (**NAS → CIFS**). Dadurch werden native Apple-SMB-Erweiterungen aktiviert.

### Zugriff verweigert-Fehler

**Symptom:** Benutzer erhalten beim Durchsuchen oder Öffnen von Dateien auf einer Freigabe „Zugriff verweigert“, obwohl sie den Freigabenamen sehen können.

**Checkliste zur Lösung:**

1. **Liste gültiger Benutzer:** Navigieren Sie zu **NAS → Freigaben → \[Freigabe]** und bestätigen Sie, dass der Benutzer oder die Gruppe in der Liste der gültigen Benutzer enthalten ist
2. **Browseable-Einstellung:** Stellen Sie sicher, dass die Freigabe auf **browseable** gesetzt ist, wenn Benutzer sie auffinden sollen
3. **Force User / Force Group:** Falls konfiguriert, stellen Sie sicher, dass der erzwungene Benutzer/die erzwungene Gruppe über Lese-/Schreibrechte auf dem zugrunde liegenden Volume verfügt
4. **NAS-Dienst neu starten:** Nach Berechtigungsänderungen den NAS-Dienst neu starten, um sie anzuwenden

### Langsame CIFS-Leistung

**Symptom:** Dateiübertragungen über CIFS sind deutlich langsamer als erwartet.

**Lösung:**

1. **SMB-Protokollversion:** Unter **NAS → Volumes → \[Volume] → Erweiterte Konfiguration**prüfen Sie die minimale SMB-Protokollversion. Wenn sie zu niedrig eingestellt ist (SMB1), wird eine Legacy-Aushandlung erzwungen
2. **Netzwerkpfad:** Verwenden Sie Netzwerkdiagnose (Ping, Traceroute), um die Latenz zwischen dem Client-Subnetz und dem NAS-Netzwerk zu prüfen
3. **Verbindungsbelastung:** Verwenden Sie NAS Diagnostics → **Samba-Status** um aktive Verbindungen zu prüfen und überlastete Freigaben zu identifizieren
4. **NAS-Ressourcen:** Überprüfen Sie CPU- und Speicherzuweisung für den NAS-Dienst — unterdimensionierte NAS-VMs werden zum Engpass für den Durchsatz

***

## Installations-Fehlerbehebung

### Startprobleme

**Symptom:** Der Knoten startet nicht vom VergeOS-USB-Installer.

**Lösung:**

* Überprüfen Sie, ob die BIOS-/UEFI-Boot-Einstellungen zum Typ des Installationsmediums passen (UEFI empfohlen)
* Testen Sie das USB-Medium auf einem bekannt funktionierenden System, um ein defektes Laufwerk auszuschließen
* Bestätigen Sie die Hardwarekompatibilität — prüfen Sie, ob die CPU 64-Bit mit Hardwarevirtualisierung (VT-x/AMD-V) unterstützt
* Deaktivieren Sie Secure Boot im BIOS, wenn der Installer nicht geladen werden kann

### Abweichungen bei der Netzwerkkonfiguration

**Symptom:** Die Installation ist abgeschlossen, aber der Knoten kann nicht mit anderen Knoten oder dem Netzwerk kommunizieren.

**Lösung:**

* Während der Installation **sofort anhalten** wenn eine erkannte IP oder Schnittstelle nicht zu Ihrem Netzwerkdesign passt
* Überprüfen Sie, ob die VLAN-Konfigurationen den Switch-Port-Einstellungen entsprechen
* Prüfen Sie die physischen Kabelverbindungen — der Installer erkennt Schnittstellen automatisch; falsch verkabelte Anschlüsse führen zu falschen Schnittstellenzuweisungen
* Bestätigen Sie, dass die IP-Adressierung nicht mit vorhandenen Geräten im Netzwerk kollidiert

### JBOD-Modus des Storage-Controllers

**Symptom:** Der VergeOS-Installer erkennt nicht alle erwarteten Laufwerke.

**Lösung:**

* VergeOS erfordert, dass Laufwerke als einzelne Datenträger präsentiert werden (JBOD-/Passthrough-Modus), **nicht** als RAID-Arrays
* Öffnen Sie das BIOS des Storage-Controllers (z. B. PERC, MegaRAID) und konfigurieren Sie jedes Laufwerk als JBOD-Volume oder einzelnes RAID-0
* Einige Controller benötigen Firmware-Updates zur Unterstützung des JBOD-Modus — konsultieren Sie die Hardware-Dokumentation des Herstellers

### Fehler beim Beitritt des sekundären Knotens

**Symptom:** Der sekundäre Controller oder Compute-Knoten kann dem vorhandenen Cluster nicht beitreten.

**Lösung:**

1. Stellen Sie sicher, dass Sie **"No"** ausgewählt haben, als Sie gefragt wurden, ob dies eine Neuinstallation ist (für sekundäre Knoten)
2. Bestätigen Sie, dass Sie die **Admin-Anmeldedaten des primären Controllers** korrekt eingegeben haben
3. Stellen Sie sicher, dass sich beide Knoten im selben Netzwerk befinden und sich gegenseitig erreichen können (prüfen Sie die VLAN-Zuweisungen der Switch-Ports)
4. Passen Sie die Verschlüsselungseinstellungen exakt an die des primären Controllers an
5. Passen Sie die Laufwerks-Tier-Zuweisungen exakt an die des primären Controllers an
6. Wenn der sekundäre Knoten startet, aber in der primären UI nicht sichtbar ist, prüfen Sie die Netzwerkkonfiguration des Core-Fabric und verifizieren Sie die Switch-Konnektivität zwischen den Knoten

***

## Speicherprobleme

### vSAN degradiert

**Symptom:** Das Dashboard zeigt eine vSAN-Tier-Ebene mit dem Status „degradiert“ oder „nicht redundant“ an.

**Erklärung:** Ein degradierter Zustand bedeutet, dass ein oder mehrere Laufwerke in einer Tier-Ebene ausgefallen oder nicht verfügbar sind, der vSAN jedoch weiterhin betriebsbereit ist. Die Daten bleiben zugänglich, weil VergeOS die Redundanz über die Knoten hinweg aufrechterhält.

**Lösung:**

1. Navigieren Sie zu **System → vSAN → Laufwerke** um das/die ausgefallene(n) Laufwerk(e) zu identifizieren
2. Überprüfen Sie die SMART-Daten des Laufwerks über **Knoten-Diagnose → S.M.A.R.T.-Diagnosetest**
3. Wenn ein physischer Austausch erforderlich ist, verwenden Sie **Knoten-Diagnose → LED-Steuerung** um den Laufwerksschacht zur Identifizierung zu beleuchten
4. Wenden Sie sich an den Verge-Support für Hinweise zum Laufwerksaustausch — der vSAN stellt die Redundanz automatisch wieder her, sobald ein Ersatzlaufwerk hinzugefügt wurde

### Wiederherstellungszeiten für Laufwerke

**Erwartungen verstehen:** Die Wiederherstellungszeiten hängen von der Datenmenge auf der Tier-Ebene und der I/O-Kapazität der verbleibenden Laufwerke ab. Während einer Wiederherstellung:

* Das System bleibt voll funktionsfähig
* Die Schreibleistung kann leicht reduziert sein
* Überwachen Sie den Fortschritt über die Fortschrittsanzeige der Tier-Ebene im vSAN-Dashboard (100 % = abgeschlossen)

{% hint style="success" %}
**Auswirkungen der Wiederherstellung minimieren**

Vermeiden Sie es, während einer Wiederherstellung migrationsintensive Workloads oder große Datenimporte zu planen. Der vSAN priorisiert Wiederherstellungsoperationen, aber zusätzliche I/O verlängert das Wiederherstellungsfenster.
{% endhint %}

### Warnungen zu Kapazitätsschwellen

**Symptom:** Dashboard-Warnungen weisen darauf hin, dass die Speicherkapazität sich den Grenzen nähert.

**Lösung:**

1. Überprüfen Sie die Auslastung der Tier-Ebene in **System → vSAN** — jede Tier-Ebene zeigt genutzte gegenüber gesamter Kapazität
2. Überprüfen Sie die SMART-Daten des Laufwerks über **Infrastruktur → Knoten → \[Knoten] → Diagnose → S.M.A.R.T.-Diagnosetest** um Verschleißwerte und Laufwerkszustandsindikatoren zu prüfen
3. Zur sofortigen Entlastung identifizieren und entfernen Sie unnötige Snapshots oder ungenutzte VM-Laufwerke
4. Für eine langfristige Lösung fügen Sie Laufwerke oder Knoten hinzu, um die Tier-Ebene zu erweitern — siehe die vSAN-Skalierungsverfahren

Die folgenden Schwellenwerte sind **Schulungshinweise** für die Planung, keine dokumentierten Grenzwerte. Die dokumentierten Werte sind die **80 % Standard für hohe Nutzung des Abonnements** (wird von den vorbefüllten vSAN-/Storage-Tier-Warnungen bei hoher Nutzung verwendet) und die **90% `sync_max_usage`** Schwellenwert, bei dem vSAN Schreibvorgänge drosselt und die Ebene markiert `kein Speicherplatz`.

| Auslastungsgrad | Maßnahme erforderlich                                                       |
| --------------- | --------------------------------------------------------------------------- |
| **< 70%**       | Normaler Betrieb — keine Maßnahmen erforderlich                             |
| **70–85 %**     | Kapazitätserweiterung planen; Aufbewahrungsrichtlinien für Snapshots prüfen |
| **85–90 %**     | Nutzung aktiv reduzieren oder Kapazität erweitern                           |
| **> 90%**       | Kritisch — Erweiterung priorisieren; Risiko von Schreibfehlern              |

***

## Entscheidungsbaum zur Fehlerbehebung

Wenn ein Problem auftritt, das in keine der oben genannten Kategorien passt, folgen Sie diesem allgemeinen Ablauf:

### 1. Problem eingrenzen

Betroffen ist eine VM, ein Netzwerk, ein Knoten oder das gesamte System? Die Eingrenzung bestimmt, mit welchem Diagnosetool begonnen werden sollte.

### 2. Komponentenbezogene Diagnosen verwenden

Beginnen Sie mit dem komponentenspezifischen Diagnosetool (Netzwerk-, Knoten-, NAS- oder vSAN-Diagnose) — sie werden automatisch im richtigen Kontext ausgeführt.

### 3. Systemprotokolle prüfen

Überprüfen Sie die Dashboard-Protokolle und Systemwarnungen auf zusammenhängende Ereignisse. Achten Sie auf Muster — wurden mehrere Warnungen gleichzeitig ausgelöst?

### 4. Mit Daten eskalieren

Wenn das Problem nicht behoben ist, erstellen Sie ein **Systemdiagnose** Paket (System → Systemdiagnose) und reichen Sie es zusammen mit Ihrer Supportanfrage ein.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/de/modul-9-uberwachung-and-fehlerbehebung/06-common-issues.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
