CodeNomad/docs/help/de/opencode.md
Pascal André c8fb4f13c3
Some checks are pending
Publish help / build (push) Waiting to run
Publish help / deploy (push) Blocked by required conditions
feat(opencode): replace service supervision with Start OpenCode at login (#1288)
## Summary

Replaces the **Keep OpenCode running** OS supervision with a simple,
voluntary **Start OpenCode at login** setting (Settings → OpenCode). It
is off by default, has no link to Missions, and its only state is one OS
artifact per user account that starts `opencode serve --service` at
sign-in. CodeNomad no longer supervises, health-checks or restarts
OpenCode itself.

## Behavior per OS

| OS | Artifact | Crash handling |
| --- | --- | --- |
| Windows | One scheduled task (`CodeNomad-OpenCode-Login`) with a
single logon trigger for the current SID, `InteractiveToken` +
`LeastPrivilege` (no password, no elevation). Its action is a stable
copy of a GUI-subsystem launcher
(`%LOCALAPPDATA%\CodeNomadOpenCodeLogin`) that starts OpenCode with
`CreateNoWindow` and exits, so no console window appears. | Not
restarted. |
| Windows → WSL | Same task, launching `wsl.exe --distribution <d>
--exec <binary> serve --service` when the selected executable is a WSL
path (a distribution root alone is refused). A CodeNomad server running
*inside* WSL reports the setting as unavailable. | Not restarted. |
| macOS | `~/Library/LaunchAgents/org.codenomad.opencode-login.plist`
with `RunAtLoad`, `KeepAlive { Crashed = true }` and the server's `PATH`
in `EnvironmentVariables`. Written/deleted without `launchctl`, so it
applies at next login. | Relaunched by launchd after a crash; an
explicit `opencode service stop` stays stopped. |
| Linux | `~/.config/systemd/user/codenomad-opencode-login.service`,
`WantedBy=default.target`, `Restart=on-abnormal` +
`RestartPreventExitStatus=SIGKILL`, `Environment="PATH=…"` (server's
PATH only), enabled/disabled without `--now`, no linger. Hosts without
`/usr/bin/systemctl` report unavailable. | Relaunched after a crash
signal (SIGSEGV, SIGABRT…); never after an exit code (`opencode service
stop` exits 130) or SIGKILL. |

- Turning the setting off removes only that task / LaunchAgent / unit; a
running OpenCode keeps running.
- The artifact keeps the selected executable path (package-manager links
survive versioned upgrades) and follows explicit executable changes and
verified installs (`refresh()` also rewrites the PATH). Command wrappers
(`.cmd`, `.ps1`) are refused with a fixed `unsupported-binary` error.
- Windows reads a task as absent only on Task Scheduler's
`ObjectNotFound`; any other lookup failure is an error.
- UI: one switch with a one-sentence info tip, and one fixed localized
error when a change is refused or the state cannot be read (10 locales).
Stable row anchor: `#opencode-login-start`; help section id:
`#login-start`.
- API: `GET|POST /api/opencode/login-start` (`{ state: "on" | "off" |
"unavailable" }` / `{ enabled }`); POST requires a live human session. A
GET also applies the migration below.

## Migration from the former supervision

At server startup and before every read or change:
- If a former service key was ON, the new login artifact is installed
**first**. If that fails, the former installation is left untouched and
reported as `on` (it still starts OpenCode); an explicit OFF then
retires it without installing anything, and fails while it cannot be
released.
- Each former guard is released by rewriting its manifest to OFF; only
its exact resources are removed. Windows:
`CodeNomad-OpenCode-<key>-Main/-Recovery` matched by their exact
description marker, disabled, Main awaited (never ended), then
unregistered. macOS: `bootout` (relies on `AbandonProcessGroup`) and
plist removal once unloaded. Linux: `stop` only when `systemctl show`
reports that exact file loaded with `KillMode=process` and no drop-in,
then disable/unlink.
- Linger is disabled only when CodeNomad owned it (unchanged marker
fingerprint) **and** a user session is open; personal or altered linger
is never touched.
- The running OpenCode is never stopped during migration.

## Removed

The PowerShell guard, probe, Recovery task and per-minute backstop;
runtime provisioning and target pinning; manifests, receipts, stores and
locks; linger registry and ownership; the WSL bridge; health circuit and
the Failed/Retry UI; the unused connection-pinning resolver parameter
and `maximumBytes` storage parameters; their native qualification
scripts, UI card, hook and i18n. The macOS process-identity helper used
by Missions is kept (renamed `process-identity-macos`, `identity` only).

## Validation

- Server and UI typecheck; `git diff --check`.
- Unit tests: artifact generation (task XML, plist incl. PATH and
XML-invalid characters, unit incl. restart policy and PATH), idempotent
install/remove per OS, `ObjectNotFound`-only absence, migration from
each former installation including linger ownership, route auth/error
codes, launch resolution (WSL root refusal, PATH filtering) — 25 tests
in the two login-start files; targeted server suites 1003 tests (998
pass, 5 pre-existing skips).
- Browser: `tests/browser/opencode-login-start.test.ts` (states,
one-sentence tip, read error kept after a refused change, all 10
locales) plus related settings/setup fixtures — 104/104.
- Help: `scripts/test-help.mjs` 31/31.

### Real runs (each removed everything it created; the shared service
registration's SHA256 and LastWriteTimeUtc were unchanged)

- **Windows** (`scripts/test-opencode-login-start-windows-native.mjs`):
uniquely named task + isolated OpenCode service (own HOME/XDG roots and
port). Started on demand: `opencode.exe serve --service` on the isolated
port, no visible window (only a hidden `conhost.exe` child), launcher
exited, task back to Ready with result 0. Disabling removed the task
while the service kept running.
- **Windows → WSL** (`scripts/test-opencode-login-start-wsl-native.mjs`,
Ubuntu, OpenCode 2.2.5 in a run-owned directory, isolated XDG roots via
`WSLENV`): the task started a hidden `wsl.exe` chain, and `serve
--service` ran in the distribution with the isolated environment,
listening on the isolated port and reachable from Windows (HTTP 401
without credentials). No owned or new visible window, task Ready/0.
Disabling removed the task and the service kept running. Cleanup stopped
it, removed the downloaded CLI and roots, and returned the distribution
to Stopped.
- **Linux** (`scripts/test-opencode-login-start-linux-native.mjs`,
Ubuntu 24.04 VM, no linger, unique unit name, isolated XDG roots and
port):
- a real logout/login (user manager restarted) started the unit with the
server's PATH;
- `opencode service stop` exited 130 and was **not** restarted (the
former `Restart=on-failure` restarted it, measured);
- a port held by another listener caused no restart loop (OpenCode 2.2.5
waits without exiting);
  - SIGSEGV was relaunched, SIGKILL was not;
  - disabling removed the unit while OpenCode kept running;
- linger stayed `no`, and the user unit directory was unchanged after
cleanup.
- macOS: artifact and adapter tests only (no real login run).
2026-11-04 03:54:39 +01:00

12 KiB

OpenCode einrichten

CodeNomad verbindet sich mit einem gemeinsamen OpenCode-Dienst auf dem Ausführungshost. CLI-Auswahl, Aktualisierung ihrer Dateien, Dienstneustart und Konfigurationsneuladen sind unterschiedliche Vorgänge; keiner ersetzt die anderen.

CLI auswählen oder installieren

  1. Öffnen Sie Einstellungen → OpenCode und wählen Sie auf der Karte OpenCode-Binärdatei unterhalb von OpenCode-Version die Programmdatei.
  2. Lassen Sie den automatischen Eintrag ausgewählt, um den PATH des Servers zu bevorzugen, sofern er kein älteres OpenCode enthält, und danach dessen OpenCode-2-Installation im Benutzer-npm; oder verwenden Sie Nach Binärdatei suchen... beziehungsweise geben Sie einen Pfad ein und wählen Hinzufügen.
  3. Verwenden Sie Status und Updates prüfen. Fehlt OpenCode, wählen Sie OpenCode installieren und starten; prüfen Sie vorher Host und Installationsumfang.
  4. Falls die Einrichtung Verbinden und fortfahren anbietet, verwenden Sie dies nach Behebung des gemeldeten Problems.

Die Installation verwendet gebündeltes Node/npm für eine normale Benutzerinstallation, die mit anderen Clients geteilt wird. Für den Benutzer installieren und PATH konfigurieren ändert die Terminaleinrichtung dieses Benutzers; öffnen Sie danach ein neues Terminal. Ein Browser verbindet sich mit dem CodeNomad-Server: Dateiauswahl und Programmdateiauswahl betreffen diesen Server, nicht das Browsergerät.

Steht ein älteres OpenCode im PATH an erster Stelle, hängt die angebotene Aktion davon ab, wie es installiert wurde. Bei einem mit npm installierten OpenCode 1.x fragt OpenCode {version} durch OpenCode 2 ersetzen nach Bestätigung, entfernt dieses npm-Paket und installiert OpenCode 2 im selben npm-Ordner; der OpenCode-Datenordner bleibt erhalten, und OpenCode 2 importiert 1.x-Unterhaltungen selbst. Ein älteres oder unbrauchbares, auf anderem Weg installiertes OpenCode (winget, Homebrew, manuell) wird nie verändert: OpenCode 2 für CodeNomad installieren installiert OpenCode 2 daneben im Benutzer-npm-Ordner, und CodeNomad verwendet dann diese Kopie. Liegt dieser ältere Befehl selbst im Benutzer-npm-Ordner (zum Beispiel ein Link in ~/.local/bin) oder ist dieser Ordner nicht beschreibbar, nennt die Einrichtung den Grund, statt die Aktion anzubieten: Verschieben Sie den Befehl oder benennen Sie ihn um, oder korrigieren Sie die Ordnerrechte, und wählen Sie dann Status und Updates prüfen. Der Befehl opencode eines Terminals kann weiterhin die ältere Version starten. Eine ausdrücklich ausgewählte benutzerdefinierte Programmdatei wird nie ersetzt.

Installierte Programmdatei und laufender Dienst können unterschiedliche Versionen haben. Vergleichen Sie auf der Karte OpenCode-Version Installierte Version mit Laufender Dienst, statt anzunehmen, eine andere Programmdatei habe den laufenden Daemon ersetzt; Versionsdetails nennt Mindest- und empfohlene Version. Ist die Installation beschäftigt oder die Programmdatei gesperrt, warten Sie auf die Freigabe durch Installationsprogramm/Prozess und prüfen Sie vor dem Wiederholen den Status; starten Sie keine konkurrierenden Installationen.

Erforderliche, empfohlene und ungeprüfte Versionen

Einstufung Aktuelle Anforderung Bedeutung
Minimum OpenCode 2.2.3 Das Bildgenerierungswerkzeug, das die Einstellungen unter Bilder und die Design-Erweiterung nutzen, sowie die korrekte Reihenfolge von JavaScript-Jobs in Code Mode und das native Wiedergabe- und Komprimierungsformat; mit früheren Versionen gespeicherte Unterhaltungen bleiben nach dem Update lesbar.
Empfohlen OpenCode 2.2.5 Qualifiziertes Ziel, getrennt vom technischen Minimum.
Ungeprüft Neuere oder angepasste, nicht vollständig validierte Version Nicht allein wegen fehlender Tests abgelehnt; geprüft werden die tatsächlichen API-Verträge des verbundenen Dienstes.

Der verbundene Dienst muss die erforderlichen Verträge für Sitzungen, Berechtigungen, Forms, Posteingang und Sitzungsumgebung bereitstellen. Native Missionszeitplanung prüft auch die Zeitplan-APIs, das Plugin-/Anbieterpaket und die wirksame Einstellung experimental.schedules. Die Verfügbarkeit richtet sich nach diesen genutzten Fähigkeiten, auch bei kompatiblen künftigen Versionen. Meldet die Einrichtung einen nicht unterstützten laufenden Dienst, wählen/installieren Sie eine unterstützte CLI und führen Sie bei Bereitschaft den expliziten Neustart des gemeinsamen Dienstes aus.

Host, WSL und gemeinsamer Dienst

Unter Windows läuft eine ausgewählte WSL-Programmdatei in der gewählten Distribution. Installieren/aktualisieren Sie sie dort und verwenden Sie dort gültige Pfade. WSL-Verbindungen hängen von der Windows-Localhost-Weiterleitung ab. Windows-CLI und WSL-CLI sind keine austauschbaren Ausführungsumgebungen.

OpenCode verwaltet seine globale Dienstregistrierung, Sitzungen, Nachrichten und Datenbank. CodeNomad erstellt keine private OpenCode-Datenbank pro Fenster oder Projekt. Das Schließen eines Projekt-Tabs schließt das Projekt in CodeNomad; Sitzungen laufen in OpenCode weiter und erscheinen wieder, wenn Sie das Projekt erneut öffnen. CodeNomad entlädt niemals native Locations. Das Schließen eines ganzen Fensters, Beenden oder Neuladen bewahrt Projektverbindungen für die Wiederherstellung; weder diese Aktionen noch das Herunterfahren des Backends beenden den gemeinsamen Daemon. Siehe Projekte.

OpenCode bei der Anmeldung starten

Unter Einstellungen → OpenCode lässt OpenCode bei der Anmeldung starten das Betriebssystem den OpenCode-Dienst bei Ihrer Anmeldung im Hintergrund starten, auch wenn CodeNomad geschlossen ist. Die Einstellung bleibt aus, bis Sie sie einschalten, wirkt ab Ihrer nächsten Anmeldung und gilt für Ihr Konto auf dem Computer, auf dem der CodeNomad-Server läuft. Sie startet die auf der Karte OpenCode-Binärdatei gewählte Programmdatei; die Auswahl einer anderen nativen Programmdatei aktualisiert sie, sonst startet sie weiter die bisherige.

System Was OpenCode startet Nach einem Absturz
Windows Eine verborgene geplante Aufgabe für Ihr Konto, ohne Kennwort oder Administratorrechte. Eine WSL-Programmdatei startet in ihrer Distribution. Kein Neustart.
macOS Ein LaunchAgent. Neustart durch macOS.
Linux Ein systemd-Benutzerdienst, der bei der Anmeldung startet, ohne Lingering zu aktivieren. Neustart durch systemd.

Ausschalten entfernt nur diese Aufgabe, diesen LaunchAgent oder Dienst; ein laufendes OpenCode läuft weiter. Lässt sich die Einstellung nicht ändern, erscheint darunter ein Fehler: Wählen Sie das native OpenCode-Programm statt eines Skript-Wrappers oder prüfen Sie die Aufgabenplanung bzw. die Benutzerdienste des Systems und versuchen Sie es erneut. Auf diesem System nicht verfügbar erscheint, wenn der CodeNomad-Server in WSL oder auf einem anderen System ohne Anmeldestart läuft.

Aktualisieren, neu starten oder neu laden

  1. Wählen Sie unter Einstellungen → OpenCode die Aktion Status und Updates prüfen.
  2. Um installierte CLI-Dateien zu ersetzen, wählen Sie gegebenenfalls Auf OpenCode {version} aktualisieren. Warten Sie den Abschluss ab.
  3. Prüfen Sie den Status des laufenden Dienstes. Verwenden Sie Gemeinsamen Dienst neu starten nur, wenn Sie die ausgewählte Installation für jeden verbundenen Client aktivieren möchten.
  4. Für einen Prozessneustart ohne Installation klappen Sie Fehlerbehebung auf, wählen OpenCode-Dienst neu starten und bestätigen.
Aktion Umfang und Wirkung Sichere Wiederherstellung
CLI aktualisieren Ändert die unterstützte installierte Programmdatei; startet den laufenden Daemon nicht implizit neu. Prüfen Sie nach Fehlern installierte und laufende Version; wiederholen Sie erst nach Fehlerbehebung ausdrücklich.
Dienst neu starten Ersetzt den gemeinsamen Prozess und unterbricht aktive Arbeit in allen verbundenen OpenCode-Clients; Sitzungsverlauf bleibt erhalten. Gesunde laufende native Missionszeitpläne werden automatisch wiederhergestellt; prüfen Sie offene Durchläufe und jede Pause/jeden Fehler/jede Ungewissheit. Bestehende tägliche Einträge erfordern Fortsetzen. Prüfen Sie einmalige Unterhaltungen und deren Wiederherstellungssteuerung separat; siehe Missionen.
OpenCode-Konfiguration neu laden Behält den Prozess, erstellt aber jede geladene Location für alle Clients neu. Bricht offene Berechtigungen/Forms ab und schließt Terminals/Hintergrundbefehle; aktive Arbeit kann unterbrochen werden. Prüfen Sie Ressourcen und offene Arbeit erneut. Wiederholen Sie keinen Prompt und keine Änderung nur wegen einer verlorenen Antwort.

Verwenden Sie OpenCode-Konfiguration neu laden (unter Fehlerbehebung, wenn der laufende Dienst es unterstützt) ausdrücklich, wenn gespeicherte Konfiguration oder installierte Plugins weiter fehlen und die Unterbrechung akzeptabel ist. Dies ist keine harmlose Anzeigeaktualisierung. CodeNomad verwendet keine ältere ausgewählte CLI, um einen neueren laufenden Daemon herunterzustufen.

Sitzungsumgebung

  1. Öffnen Sie Einstellungen → Erweitert und klappen Sie Umgebungsvariablen auf.
  2. Ergänzen, ändern oder entfernen Sie die Überschreibungen des Profils; jede Änderung wird sofort gespeichert.
  3. Senden Sie den nächsten Prompt, benutzerdefinierten Befehl oder Sitzungs-Shell-Aufruf über CodeNomad, um die aktuelle Umgebung auf diese Unterhaltung anzuwenden.

Dies ist eine Konfigurationsprofileinstellung, die serverseitig vor jedem Senden angewandt wird. Bloßes Öffnen/Lesen einer Unterhaltung oder Speichern von Einstellungen verändert keine native Sitzung. Das Entfernen einer Überschreibung stellt den geerbten Wert des Ausführungshosts wieder her oder entfernt ihn, wenn er dort fehlt. Fehler beim Anwenden blockieren das Senden, statt veraltete Werte zu verwenden.

Die Umgebung steuert spätere lokale Shell-Starts in dieser nativen Sitzung. Bereits laufende Prozesse behalten ihre Umgebung. Sie konfiguriert Anbieter, MCP-/LSP-Server, unabhängige Terminals oder reine Location-Hintergrund-Shells nicht neu. Prompts in Warteschlangen erfassen nicht jeweils eine eigene Umgebung; ein anderer OpenCode-Client kann dieselbe Sitzungsumgebung ersetzen. Nehmen Sie nicht an, dass vollständig innerhalb von OpenCode erstellte Kind-Sitzungen eine CodeNomad-Aktualisierung zum Sendezeitpunkt erhalten.

Zulässige Variablen werden auch beim Start eines gestoppten Dienstes übergeben; die Verbindung zu einem vorhandenen Daemon ändert dessen Prozessumgebung nicht. Unter WSL werden Werte mit der Linux-Ausführungsumgebung kombiniert, nicht mit Windows-PATH/HOME. Änderungen an Überschreibungen verlagern weder OpenCodes Datenbank noch Dienstregistrierung.

Native Konfigurationsdateien bearbeiten

  1. Öffnen Sie Einstellungen → Konfigurationsdateien und wählen Sie Datei.
  2. Prüfen Sie den angezeigten Pfad, bearbeiten Sie und wählen Sie Speichern.
  3. Verwenden Sie Neu laden, um die Datei erneut zu lesen; dies ist nicht OpenCode-Konfiguration neu laden.

Dieser Editor bietet nur die aufgelisteten globalen Dateien opencode.json und opencode.jsonc unter .config/opencode des CodeNomad-Serverbenutzers. Er ist weder ein beliebiger Dateieditor noch eine Projektkonfigurationsauswahl und garantiert nicht, dass ein WSL-Daemon oder ein Daemon mit angepassten Suchpfaden diese Datei liest. Prüfen Sie das Ziel anhand des angezeigten Pfads; für andere Wurzeln nutzen Sie die eigenen Werkzeuge des Daemons.

Speichern schreibt die Datei als Text; es validiert weder die gesamte native Konfiguration noch startet/lädt es OpenCode neu. Stimmen Sie Änderungen mit anderen Clients ab: Diese Oberfläche bietet keine Zusammenführung externer Änderungen. Sichern Sie vor umfangreichem Ersetzen eine Kopie. Dateiwechsel oder Neuladen eines geänderten Entwurfs fragt nach dessen Verwerfen.

Konfigurationsbezogene Abläufe finden Sie unter Integrationen, Anbieter, Missionen und OpenCode-Dokumentation.