1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
9.6 KiB
Authentifizierung und Sicherheit
Zugriff auf CodeNomad kann über OpenCode Arbeit auf dem Backend-Host ausführen. Behandeln Sie Serverpasswörter, Browsersitzungen und gekoppelte Geräte als mächtige Zugangsdaten. CodeNomad ist keine mandantenfähige Ausführungs-Sandbox.
Serverauthentifizierung wählen
| Methode | Lebensdauer und Geltungsbereich |
|---|---|
--password oder CODENOMAD_SERVER_PASSWORD |
Laufzeitüberschreibung für diesen Backend-Prozess. Bei jedem Start erneut nötig; nicht gespeichert. Übersteuert die verwaltete Passwortdatei. |
| In Einstellungen gesetztes Passwort | Speichert einen gesalzenen scrypt-Hash in auth.json neben der aktiven Konfigurations-YAML. Bei späteren Starts ohne Laufzeitüberschreibung verwendet. |
--generate-token |
Aktiviert lokale einmalige Ersteinrichtung; ausgegebenes Token gilt 60 Sekunden. Kein wiederverwendbares API-Token und kein Fernsteuerungslink. |
| Fernsteuerungskopplung | Separate Geräte-Cookie-Authentifizierung, vom Host verwaltet; siehe Fernsteuerung. |
Standardbenutzername ist codenomad. Eine gespeicherte Auth-Datei behält ihren Benutzernamen; nur --username zu ändern benennt diese gespeicherte Identität nicht um. Ohne konfiguriertes Passwort, Ersteinrichtungsmodus oder ausdrücklich übersprungene Authentifizierung verweigert der Server den Start.
Bevorzugen Sie geschützte Umgebungs-/Dienstgeheimnisse gegenüber Passwörtern in Befehlsargumenten oder Shell-Verlauf. Wer Ihre Prozessumgebung oder das Konfigurationsverzeichnis einsehen kann, kann die Bereitstellung möglicherweise dennoch kompromittieren.
Dauerhaftes Passwort erstmalig einrichten
- Starten Sie lokal ohne Laufzeit-Passwortüberschreibung. Verwenden Sie zur Loopback-Ersteinrichtung ohne vorherige Zertifikatseinrichtung
codenomad --host 127.0.0.1 --https=false --http=true --generate-token --launch. - Öffnen Sie auf dem Backend-Rechner
/auth/tokenan der ausgegebenen Local Connection URL und übermitteln Sie den nachCODENOMAD_BOOTSTRAP_TOKEN:ausgegebenen Wert. Teilen Sie diese Ausgabe nicht. - Öffnen Sie Einstellungen → Remote-Zugriff → Direktzugriff (lokales Netzwerk, erweitert) → Server-Passwort.
- Wählen Sie Passwort festlegen, füllen Sie Neues Passwort und Passwort bestätigen mit mindestens acht Zeichen aus und wählen Sie Passwort speichern.
- Lassen Sie beim nächsten Start
--generate-tokenweg und verwenden Sie für Direktverbindungen das gespeicherte Passwort. Konfigurieren Sie vor Fernzugriff vertrauenswürdiges HTTPS; der Loopback-HTTP-Einrichtungsbefehl ist kein Befehl für entfernte Bereitstellung.
Ersteinrichtung wird nur vom eigenen Loopback-Listener des Hosts angenommen, nicht von LAN-Clients oder Fernsteuerungseingängen. Behalten Sie dafür die standardmäßige Loopback-Bindung. Ein abgelaufenes/verbrauchtes Token erfordert einen neuen Ersteinrichtungsstart. Existiert bereits ein dauerhaftes Passwort, erlaubt die Ersteinrichtungssitzung stattdessen Passwort ändern.
auth.json wird von der App verwaltet; bearbeiten Sie keinen Hash von Hand und veröffentlichen Sie die Datei nicht. Stammt das Passwort aus CLI/Umgebung, verweigern Einstellungen dessen Ersatz: Starten Sie ohne diese Überschreibung neu, um ein vorhandenes verwaltetes Passwort zu nutzen, oder setzen Sie eines über lokale Ersteinrichtung. Eine unlesbare/unbeschreibbare Auth-Datei benötigt eine OS-Rechte-/Pfadkorrektur, keine deaktivierte Authentifizierung.
Browsersitzungen und Widerruf
Direkte Anmeldung erzeugt eine undurchsichtige Backend-Sitzung im Arbeitsspeicher und ein codenomad_session-Cookie (oder den konfigurierten Cookie-Namen). Cookies sind HttpOnly, SameSite=Lax, auf / begrenzt und bei Ausgabe über HTTPS als Secure markiert. Es sind Browsersitzungs-Cookies; ein Backend-Neustart macht die Sitzungen im Speicher ungültig. Authentifizieren Sie sich bei Aufforderung an Ort und Stelle neu, statt fehlgeschlagene Änderungen erneut zu senden.
Ein Passwortwechsel ändert spätere Zugangsdatenprüfungen; er macht bereits ausgegebene Direkt-Sitzungen oder Fernsteuerungsgeräte nicht ungültig. Bei Kompromittierungsverdacht:
- Begrenzen Sie die Netzwerkfreigabe und setzen Sie auf dem Host ein neues Passwort oder ändern Sie Ihr Laufzeitgeheimnis und starten neu.
- Starten Sie das Backend neu, um vorhandene Direkt-Sitzungen ungültig zu machen.
- Verwenden Sie unter Fernsteuerung → Gekoppelte Geräte separat Widerrufen für unbekannte Geräte. Stoppen Sie Fernsteuerung, wenn Sie deren gesamten Zugriffsweg sofort abschneiden müssen.
- Prüfen Sie betroffene Dateien, Anbieterkonten und native OpenCode-Aktivität. Zugriff zu beenden macht bereits angenommene Arbeit nicht rückgängig.
Die separate 30-Tage-Inaktivitätsgrenze und Fünf-Minuten-Kopplungslinks erläutert Fernsteuerung. Passwortwechsel ist kein Gerätewiderruf, Tunnelstopp keine Gerätelöschung.
Transport und Listenerfreigabe schützen
Verwenden Sie vertrauenswürdiges HTTPS für direkten Fernzugriff. Reines HTTP offenbart Passwörter, Sitzungscookies und Arbeitsinhalte jedem, der diesen Netzwerkabschnitt beobachten kann. Endet TLS an einem Reverse-Proxy, halten Sie den Backend-Abschnitt auf Loopback oder einem anderen geschützten Netzwerk; Proxy-TLS verschlüsselt keine offenliegende Upstream-HTTP-Verbindung.
--dangerously-skip-auth / CODENOMAD_SKIP_AUTH deaktiviert CodeNomads Direkt-Listener-Anmeldung und behandelt Anfragen als authentifiziert. Dies macht eine Serverfreigabe nicht sicher. Ein ohne durchsetzende Schutzgrenze erreichbarer Listener gewährt jedem Erreichenden Zugriff; ein VPN allein unterscheidet keine vertrauenswürdigen von nicht vertrauenswürdigen VPN-Nutzern. Lassen Sie Authentifizierung aktiviert, sofern Sie nicht jeden Zugriffsweg unabhängig entworfen und geprüft haben. Fernsteuerung benötigt auch mit diesem Flag ein gekoppeltes Gerät.
Prüfen Sie Bindungsmatrix und TLS-Verfahren, besonders den eigenständigen Nur-HTTP-Modus: Er beachtet --host und kann Klartext über Loopback hinaus freigeben. Beheben Sie Zertifikatsfehler niemals durch deaktivierte Prüfung.
CODENOMAD_SKIP_AUTH=false lässt die Authentifizierung aktiviert, sofern --dangerously-skip-auth nicht angegeben wird. 1, true, yes oder on aktivieren die Authentifizierungsumgehung; Groß-/Kleinschreibung und umgebende Leerzeichen werden ignoriert. 0, false, no, off, leere oder nur aus Leerzeichen bestehende Werte sowie eine nicht gesetzte Variable lassen sie aus. Jeder andere Wert verhindert den Serverstart, auch mit dem CLI-Flag. Das Flag hat Vorrang vor einem gültigen Aus-Wert; siehe CLI-Referenz.
Host-Grenze verstehen
--workspace-root begrenzt die zu öffnenden Arbeitsbereiche, --unrestricted-root lockert die Ordnersuche. Keines ist OS-Gefängnis, Container, Dateisystem-Sandbox oder Einschränkung autorisierter nativer Werkzeuge. Agenten, Shell-Befehle, Plugins und MCP-Werkzeuge handeln mit den Rechten des Ausführungshosts und ihren konfigurierten Zugangsdaten.
SideCars sind vertrauenswürdige Ergänzungen. CodeNomad hält seine Anmelde- und Geräte-Cookies vom SideCar-Dienst zurück, aber die SideCar-Seite lädt im selben Origin wie CodeNomad, und ihre Skripte können mit Ihrer angemeldeten Sitzung handeln. Registrieren Sie nur Dienste, denen Sie ebenso vertrauen wie CodeNomad selbst.
Verwenden Sie für echte Isolation OS-Konten, Container/VMs und vorgelagerte Berechtigungskonfiguration. Gewähren Sie einem Gerät nicht nur deshalb Zugriff, weil es Ihrer Erwartung nach nur einen Tab sehen wird. Serverkonfiguration und gemeinsamer OpenCode-Dienst können andere Unterhaltungen/Projekte betreffen; deren separate Grenzen erläutern OpenCode-Einrichtung, Berechtigungen und Erweiterungen.
Zugangsdaten und Diagnosen privat halten
OpenCode verwaltet Anbieterverbindungen und seinen globalen Unterhaltungsspeicher. CodeNomad liest Verbindungsmetadaten und ausgewählte Zugangsdaten serverseitig für unterstützte Nutzungsintegrationen; Browser-APIs liefern keine geheimen Anbieterwerte zurück. Die Erneuerung extern verwalteter OAuth-Anmeldungen liegt bei deren Eigentümer; CodeNomad tauscht deren Refresh-Tokens nicht aus. Siehe Anbieter.
| Material | Umgang |
|---|---|
| Passwörter, Ersteinrichtungstokens, Kopplungslinks, Cookies | Niemals in Issues, Screenshots, Shell-Mitschnitte oder geteilte Logs einfügen. |
auth.json, private TLS-Schlüssel, Tunnelidentität, Konfigurationsgeheimnisse |
Mit OS-Rechten und verschlüsselten Sicherungen schützen; keine vollständigen Verzeichnisse für Support hochladen. |
| Unterhaltungstext, Anhänge, Arbeitsbereichspfade und Remote-Adressen | Vor Teilen prüfen/schwärzen; sie können Personen, Projekte oder Infrastruktur identifizieren. |
| Anbieterschlüssel und Sprachzugangsdaten | Nur in den vorgesehenen Einstellungen/beim Zugangsdatenverwalter eingeben; prüfen, welcher Anbieter Daten erhält. Siehe Sprache. |
| Debug-/Trace-Logs und Netzwerkmitschnitte | Nur Nötiges sammeln, lokal prüfen und vor Meldung schwärzen. Nicht voraussetzen, dass jede nachgelagerte Werkzeugausgabe frei von Geheimnissen ist. |
Einstellungen → Info → Fehler melden bereitet begrenzte Diagnosen vor, ohne Listener, Adressen, Pfade, Zugangsdaten oder Unterhaltungsinhalte vorauszufüllen. Prüfen Sie vor dem Absenden alles selbst Ergänzte. Siehe Support.