OpenCode dokumentiert Bash als Werkzeug der Projektausführungsumgebung. Das ist der entscheidende Prüfpunkt: Eine SSH-Verbindung zu einem Remote Mac schaltet den Agenten nicht automatisch auf diesen Rechner um. Lassen Sie den OpenCode-Arbeitsbereich und die Befehle auf dem Mac laufen oder rufen Sie die Befehle ausdrücklich per SSH dort auf. Prüfen Sie dann getrennt Dateiänderung, xcodebuild und gespeichertes Testergebnis. OpenCode beschreibt den Ausführungskontext der Werkzeuge.

Sofortmaßnahme: Ermitteln Sie zuerst den Rechner, auf dem OpenCode ausgeführt wird. Erst danach prüfen Sie Projektpfad und Xcode-Umgebung auf dem tatsächlichen Build-Knoten.
Diese Woche: Führen Sie einen kontrollierten Test mit einem bekannten Commit durch und sichern Sie Exit-Status, Ergebnisbündel und die verwendeten Pfade.

Für wen dieser Leitfaden gedacht ist:
Sie entwickeln auf Windows oder Linux, müssen aber iOS- oder macOS-Projekte mit Xcode bauen.
Sie betreiben macOS CI und müssen Agent-Arbeitsbereich und Build-Knoten voneinander abgrenzen.
Sie verantworten die Einbindung von OpenCode in eine Apple-Toolchain und brauchen nachvollziehbare Rechte- und Abnahmekriterien.

Zuletzt geprüft am 24.10.2026. Die Versions- und Funktionshinweise beziehen sich auf die offiziellen OpenCode-Werkzeugdokumente und Änderungsprotokolle sowie die unten verlinkten Apple-Dokumente.

01

OpenCode 2.0 und Remote Mac: Zuerst den Ausführungsort feststellen

Der Fehler „Befehl erfolgreich, aber auf dem falschen Rechner“ entsteht häufig durch eine falsche Annahme über die Verbindung. Sie können von Ihrem Linux- oder Windows-Rechner aus per SSH einen Mac erreichen und trotzdem OpenCode lokal verwenden. In diesem Fall bleiben das geöffnete Projekt und die Bash-Aufrufe in der Umgebung des lokalen Agenten, sofern Sie die Ausführung nicht ausdrücklich auf den Mac verlagern.

Unterscheiden Sie diese drei Orte:

  • Hauptrechner: Dort läuft Ihr Editor oder Ihre lokale Shell. Ein verfügbarer SSH-Zugang sagt zunächst nur etwas über die Verbindung aus.
  • OpenCode-Projektausführungsumgebung: Dort werden die projektbezogenen Werkzeuge und Bash-Befehle ausgeführt. Prüfen Sie, in welchem Arbeitsbereich OpenCode gestartet wurde.
  • Remote Mac: Dort müssen die Projektdateien und die passende Xcode-Toolchain erreichbar sein, wenn der Build tatsächlich auf macOS stattfinden soll.

Verlassen Sie sich nicht auf die Ausgabe eines Befehls, der nur „erfolgreich“ meldet. Lassen Sie die Ausführung Umgebungshinweise liefern: aktueller Verzeichnispfad, Hostname und ein eindeutiges Merkmal des geöffneten Repositorys. Prüfen Sie dieselben Hinweise in einer interaktiven SSH-Sitzung. Stimmen sie nicht überein, haben Sie unterschiedliche Ausführungskontexte vor sich.

Achtung: SSH ist ein Transportweg, keine automatische Umleitung des Agenten. Ein erreichbarer Mac beweist weder, dass OpenCode dort läuft, noch, dass sein Bash-Werkzeug die Remote-Shell verwendet.

Auch die Version sollten Sie bei einer Fehlersuche nicht aus einer alten Anleitung übernehmen. Das offizielle OpenCode-Änderungsprotokoll führt die laufenden Veröffentlichungen und Änderungen auf. Prüfen Sie dort vor einer Versionsdiagnose, welche Ausgabe Sie tatsächlich einsetzen. Leiten Sie aus einem Einzelfall oder einer früheren Versionsnummer keine allgemeine Aussage über das aktuelle Werkzeugverhalten ab.

02

Falsche Projektkopie und Arbeitsverzeichnis auseinanderhalten

Ein Agent kann am richtigen Rechner arbeiten und dennoch die falsche Projektkopie bearbeiten. Das passiert, wenn das Repository lokal geöffnet ist, während Sie auf dem Remote Mac eine zweite Kopie bauen. Auch zwei Verzeichnisse mit gleichem Namen sind kein Beleg dafür, dass es sich um dieselbe Arbeitskopie handelt.

Erfassen Sie deshalb für beide Seiten die vollständigen Pfade und den Git-Commit. Verwenden Sie dafür ein neutrales Schema, zum Beispiel <lokaler-pfad> und <remote-projektpfad>. Vergleichen Sie anschließend eine konkrete Datei, die OpenCode geändert haben soll. Die Änderung muss in der Kopie sichtbar sein, die xcodebuild tatsächlich verwendet.

Ist der Commit verschieden, stoppen Sie den Build. Übertragen Sie die beabsichtigten Änderungen auf die vorgesehene Kopie oder starten Sie OpenCode mit dem richtigen Arbeitsbereich. Bauen Sie nicht versuchsweise beide Verzeichnisse und wählen Sie anschließend das erfolgreichere Ergebnis: Damit bleibt unklar, welches Artefakt zur Änderung gehört.

Prüfen Sie außerdem, ob die Projektdateien im Remote-Arbeitsbereich schreibbar sind. Ein Agent kann Quelltext lesen, aber beim Schreiben an einer Dateiberechtigung scheitern. Das ist ein anderes Problem als ein erfolgreicher Schreibvorgang im lokalen Klon. Für eine belastbare Prüfung gehören daher zusammen:

  • der Arbeitsverzeichnispfad der OpenCode-Ausführung;
  • der Repository-Pfad auf dem Remote Mac;
  • derselbe erwartete Commit;
  • eine nachvollziehbare Dateiänderung in der gebauten Kopie.
03

Xcode-Befehle, Zugriff und Tests getrennt prüfen

Wenn OpenCode auf dem Remote Mac arbeitet, xcodebuild aber fehlt oder die falsche Installation verwendet wird, prüfen Sie die Umgebung genau dort, wo der Build-Prozess läuft. Eine lokale Ausgabe von xcode-select oder eine funktionierende Entwicklungsumgebung auf Ihrem Windows- oder Linux-Rechner ist kein Beleg für den Zustand des Remote-Kontos.

Apple dokumentiert xcodebuild als Teil der Xcode-Kommandozeilenwerkzeuge und beschreibt die Installation dieser Werkzeuge in der Anleitung zu den Xcode Command Line Tools. Die Referenz der Xcode-Kommandozeilenwerkzeuge hilft dabei, verfügbare Befehle und ihre vorgesehenen Aufgaben zu prüfen.

Führen Sie die Diagnose als jenes Konto aus, das OpenCode beziehungsweise den CI-Auftrag ausführt. Ermitteln Sie den aufgelösten Pfad von xcodebuild, die aktive Entwicklerverzeichnis-Einstellung und die von dieser Sitzung gemeldete Xcode-Version. Wenn die Befehle in einer interaktiven SSH-Sitzung funktionieren, aber im Agenten nicht, vergleichen Sie Shell, Umgebungsvariablen und Startkonfiguration. Ein Unterschied dort kann erklären, warum eine interaktive Anmeldung und ein nicht interaktiver Build verschiedene Werkzeuge sehen.

Ein vorhandener Compiler löst außerdem nicht automatisch alle Projektfehler. Trennen Sie diese Bereiche:

  • Repository-Zugriff: Kann das Ausführungskonto das Projekt und benötigte Unterverzeichnisse lesen?
  • Private Abhängigkeiten: Sind die nötigen Zugangsdaten für genau diesen Prozess verfügbar, ohne sie in Quelltext oder Protokolle zu schreiben?
  • Signierung: Kann der Build auf die benötigten Signiermaterialien zugreifen, und ist dieser Zugriff für die konkrete Aufgabe vorgesehen?
  • Dateibearbeitung: Darf OpenCode nur die erforderlichen Projektdateien ändern, oder ist die Ursache ein fehlendes Schreibrecht?
  • Build-Ziel: Stimmen Scheme, Konfiguration und Destination mit dem Auftrag überein?

Beginnen Sie mit dem ersten konkreten Fehler im Protokoll. Gewähren Sie nicht pauschal zusätzliche Rechte für das gesamte Konto oder Repository, nur weil ein privater Abhängigkeitsschritt scheitert. OpenCode stellt eine konfigurierbare Berechtigungssteuerung für Werkzeuge bereit. Nutzen Sie sie, um notwendige Freigaben gezielt zu erteilen und Änderungen nachvollziehbar zu halten.

04

Entscheidungsübersicht für die Fehlersuche

Nutzen Sie diese Übersicht, bevor Sie die Ausführungsarchitektur verändern. Der entscheidende Unterschied ist, ob OpenCode selbst auf dem Remote Mac arbeitet oder Befehle ausdrücklich an ihn weitergibt.

Option Wo liegen Arbeitsbereich und Befehlsausführung? Geeignet, wenn … Hauptrisiko
Lokales OpenCode ohne Remote-Aufruf Projekt und Bash-Ausführung auf dem Hauptrechner Sie nur lokale Aufgaben erledigen oder Änderungen vorbereiten SSH-Verfügbarkeit wird fälschlich als Remote-Xcode-Ausführung verstanden
OpenCode mit Projektarbeitsbereich auf dem Remote Mac Arbeitsbereich und Xcode-Befehle auf dem Mac Agent, Dateien und Apple-Toolchain gemeinsam auf dem Build-Knoten arbeiten sollen Benutzerkonto, Arbeitsbereich und Rechte müssen auf dem Mac stimmen
Lokales OpenCode mit ausdrücklich per SSH gestarteten Befehlen Agent lokal, ausgewählte Befehle und Builds auf dem Mac Sie die Zuständigkeiten bewusst trennen und Remote-Aufrufe protokollieren Pfade, Shell-Umgebung und Ergebnisübertragung müssen explizit behandelt werden

Wählen Sie den Remote-Arbeitsbereich, wenn OpenCode Dateien direkt in der zu bauenden Kopie ändern soll. Wählen Sie explizite SSH-Ausführung, wenn die Steuerung lokal bleiben soll, aber der Build auf dem Mac stattfinden muss. Bleiben Sie lokal, wenn das Projekt keine Apple-Toolchain benötigt. Ein Mischbetrieb kann sinnvoll sein, braucht jedoch eine klare Übergabe der Dateien und Ergebnisse.

05

Simulatorziel und Testergebnis nicht mit einem erfolgreichen Build verwechseln

Ein erfolgreicher Build belegt nicht, dass ein Simulator-Test gestartet wurde. Prüfen Sie zunächst, ob der Auftrag tatsächlich Tests enthält und ob Scheme und Destination zum Projekt passen. Wenn ein erwartetes Simulatorziel nicht verfügbar ist, kann die Ursache im installierten Laufzeitumfang oder in der gewählten Destination liegen. Das ist zunächst ein Zielkonfigurationsproblem, nicht automatisch ein Ausfall von OpenCode.

Apple beschreibt, wie Apps auf simulierten oder physischen Geräten ausgeführt werden, in der Dokumentation zu Simulatoren und Geräten. Vergleichen Sie die dort beschriebenen Voraussetzungen mit dem tatsächlichen Remote Mac. Verlassen Sie sich nicht auf eine Geräteauswahl, die Sie auf Ihrem eigenen Rechner gesehen haben.

Für die Prüfung sind drei Fragen getrennt zu beantworten:

  • Wurde der erwartete Build-Auftrag ausgeführt?
  • Wurden Tests für das vorgesehene Scheme und die passende Destination gestartet?
  • Wurde das Ergebnis so gespeichert, dass Sie es später öffnen und dem Commit zuordnen können?

Apple erläutert das Ausführen und Interpretieren von Tests in der Dokumentation zu Testergebnissen. Verwenden Sie diese Grundlage, um einen Testlauf vom bloßen Kompilieren zu unterscheiden.

Damit eine erfolgreiche Ausführung später überprüfbar bleibt, erfassen Sie den Exit-Status des konkreten Prozesses und den Speicherort des Ergebnisbündels. Wenn ein CI-System Protokolle und Artefakte sammelt, prüfen Sie zusätzlich den Schritt, der das Bündel übernimmt. Ein Pfad in einer Konsolenausgabe bedeutet noch nicht, dass das Ergebnis dauerhaft an einem für Ihr Team erreichbaren Ort liegt.

Erfahrungshinweis: Behandeln Sie „Build erfolgreich“, „Tests gestartet“ und „Testergebnis gesichert“ als getrennte Abnahmepunkte. Wenn einer fehlt, ist die Aufgabe noch nicht vollständig nachgewiesen.

06

FAQ: OpenCode mit Xcode auf einem Remote Mac

Wo wird ein Bash-Befehl ausgeführt, den OpenCode startet?

Der Bash-Aufruf läuft in der Projektausführungsumgebung von OpenCode. Prüfen Sie den Rechner, auf dem der Agent arbeitet, und das dortige aktuelle Verzeichnis. Eine erfolgreiche SSH-Anmeldung von Ihrem Hauptrechner zeigt nur, dass der Remote Mac erreichbar ist. Sie beweist nicht, dass Agent-Befehle an die Remote-Shell weitergeleitet werden.

Wie verwendet OpenCode das Xcode-Projektverzeichnis auf dem Mac?

Öffnen Sie den Arbeitsbereich auf dem Remote Mac, wenn OpenCode dort Dateien bearbeiten und anschließend bauen soll. Alternativ lassen Sie ausgewählte Befehle ausdrücklich per SSH ausführen. In beiden Varianten vergleichen Sie den Repository-Pfad und Commit mit der tatsächlich gebauten Kopie. Prüfen Sie eine konkrete Dateiänderung, bevor Sie den Build als Nachweis für den bearbeiteten Stand werten.

Was ist zu prüfen, wenn SSH funktioniert, aber xcodebuild fehlt?

Führen Sie die Diagnose mit dem Konto aus, das den Agenten oder CI-Auftrag ausführt. Prüfen Sie den aufgelösten xcodebuild-Pfad und das aktive Entwicklerverzeichnis auf dem Remote Mac. Funktioniert der Befehl nur in einer interaktiven SSH-Sitzung, vergleichen Sie deren Shell- und Umgebungswerte mit der Agent-Ausführung. Die lokale Xcode-Installation ist hierfür kein Beleg.

Wie lässt sich ein gespeichertes Testergebnis nachweisen?

Prüfen Sie, ob der Testprozess den erwarteten Exit-Status geliefert hat, und kontrollieren Sie den angegebenen Pfad des Ergebnisbündels. Öffnen Sie dieses auf dem Mac oder verifizieren Sie, dass Ihr CI-Ablauf es als Artefakt übernommen hat. Ordnen Sie das Ergebnis dem getesteten Commit zu. Ein erfolgreicher Build ohne Testlauf oder gesichertes Ergebnis genügt nicht als Testnachweis.

07

Reproduzierbarer Prüfablauf für den Remote-Build

Gehen Sie in dieser Reihenfolge vor. Halten Sie die verwendeten Werte fest, ohne Zugangsdaten in ein dauerhaftes Protokoll zu übernehmen.

Erstens: Ausführungsort feststellen. Lassen Sie OpenCode eine harmlose Umgebungsinformation ausgeben: Hostname und aktuelles Verzeichnis. Ermitteln Sie dieselben Angaben in der SSH-Sitzung. Weichen die Werte ab, korrigieren Sie zuerst den Ausführungsweg.

Zweitens: Arbeitsbereich und Repository zuordnen. Erfassen Sie den vollständigen Projektpfad, den Git-Commit und den Zustand der Arbeitskopie. Machen Sie das für den OpenCode-Arbeitsbereich und den Remote-Build-Pfad. Stimmen die Werte nicht überein, wählen Sie eine maßgebliche Kopie und übertragen Sie nur die vorgesehenen Änderungen.

Drittens: Änderung in der Build-Kopie nachweisen. Lassen Sie eine kontrollierte, harmlose Änderung an einer geeigneten Datei vornehmen. Prüfen Sie, ob sie im Verzeichnis sichtbar ist, das der Build verwendet. So erkennen Sie eine versehentliche Änderung im lokalen Klon, bevor ein Xcode-Ergebnis falsch zugeordnet wird.

Viertens: Toolchain unter dem richtigen Konto prüfen. Ermitteln Sie auf dem Remote Mac den xcodebuild-Pfad und das aktive Entwicklerverzeichnis. Vergleichen Sie die Ergebnisse mit der vorgesehenen Xcode-Installation. Fehlt das Kommando oder zeigt es auf eine unerwartete Umgebung, beheben Sie diese Abweichung, bevor Sie Abhängigkeiten oder Tests untersuchen.

Fünftens: Zugriff nach Fehlerquelle eingrenzen. Lesen Sie den ersten aussagekräftigen Fehler im Protokoll und ordnen Sie ihn Repository-Zugriff, Abhängigkeiten, Signierung oder Dateibearbeitung zu. Erteilen Sie nur die nötige Berechtigung. Vermeiden Sie es, mit weitreichenden Freigaben mehrere mögliche Ursachen gleichzeitig zu überdecken.

Sechstens: Build-Ziel und Testauftrag prüfen. Kontrollieren Sie Scheme und Destination und bestätigen Sie, dass das gewählte Simulator- oder Geräteziel auf dem Remote Mac verfügbar ist. Prüfen Sie, ob der Auftrag tatsächlich Tests ausführt; ein Build-Aufruf kann erfolgreich sein, ohne dass die gewünschte Testausführung stattgefunden hat.

Siebtens: Ergebnis und Commit gemeinsam sichern. Erfassen Sie den Prozessstatus, den Pfad des Ergebnisbündels und den getesteten Commit. Prüfen Sie, ob der CI-Ablauf das Bündel übernimmt. Wiederholen Sie den Lauf mit demselben Commit, wenn das Ergebnis nicht eindeutig dem getesteten Stand zugeordnet werden kann.

Nach diesem Ablauf treffen Sie die nächste Entscheidung anhand von Belegen: Pfadfehler korrigieren, Toolchain oder Rechte gezielt anpassen, denselben Auftrag reproduzieren oder die Ausführung bewusst auf einen Remote-Mac-Arbeitsbereich verlagern. Wenn die vorhandenen Protokolle weder Rechner noch Projektkopie oder Testergebnis belegen, ändern Sie nicht mehrere Systeme zugleich. Ergänzen Sie zuerst diese Nachweise.

08

Wenn der Hauptrechner keine Apple-Toolchain bereitstellt

Windows oder Linux kann weiterhin Ihr sinnvoller Hauptarbeitsplatz sein. Die Grenze zeigt sich dort, wo der Auftrag eine lokale Xcode-Toolchain, passende Simulatorziele oder einen macOS-Build erfordert. Eine selbst organisierte Weiterleitung über SSH kann funktionieren, verlangt aber zusätzliche Pflege: Remote-Pfade müssen stimmen, Konten und private Zugangsdaten brauchen begrenzte Rechte, und Ergebnisse müssen zurück an den ausführenden CI-Ablauf gelangen. Auch ein eigener Mac-Knoten bringt Wartungsaufwand für Betriebssystem, Xcode und Zugriffsschutz mit sich.

Wenn Sie vor allem die Ausführung auf macOS verlässlich verfügbar machen müssen, können Sie sich zunächst über Remote-Mac-Zugänge und die verfügbaren Angebote von VpsMesh informieren. Prüfen Sie anschließend anhand Ihrer tatsächlichen Build-Aufträge, ob ein Mietmodell, ein eigener Mac oder eine andere CI-Architektur zu Laufzeit, Datenschutzanforderungen und Wartungskapazität passt. Angaben zu Mietoptionen für den Mac mini sollten Sie dabei mit Ihrem konkreten Bedarf abgleichen, statt aus diesem Fehlerleitfaden eine pauschale Kosten- oder Leistungsaussage abzuleiten.

Muss Ihr Team häufig kurzfristig auf eine macOS-Umgebung zugreifen und soll ein eigener Knoten vermieden werden, kann das Mieten eines Remote Mac die praktische Alternative sein. Bleibt die Last dauerhaft hoch oder benötigen Ihre Abläufe physische Schnittstellen und eine vollständig kontrollierte Hardwareumgebung, ist ein eigener Mac unter Umständen passender. Entscheidend ist, dass OpenCode, Projektkopie, xcodebuild und gesicherte Testergebnisse in derselben nachvollziehbaren Ausführungskette zusammenpassen.