Grok Plugin Codex

grok-plugin-codex stellt eine lokal installierte Grok-CLI über einen gebündelten Node/TypeScript-MCP-Server für Codex bereit. Codex bleibt für Umfang, Arbeitsbereichszustand, Verifikation, Git und endgültige Beurteilung verantwortlich; Grok ist eine begrenzte zweite Oberfläche.

Version 0.3.0 ist die aktuelle Veröffentlichung. Sie normalisiert das Grok-Stoppgrund-Vokabular (end_turn und EndTurn sind eine Tatsache), klassifiziert Timeouts und Kontingenterschöpfung korrekt, setzt Dispatch-Tools standardmäßig auf Hintergrund mit zeitlichen Budgets pro Art, gibt bei jedem nicht vollständigen Ergebnis einen Wiederherstellungsgriff zurück, weigert sich, ein ohne einen einzigen Tool-Aufruf erzieltes Urteil als abgeschlossene Überprüfung zu melden, und fügt grok_finalize hinzu – die ein-Turn-, tool-freie Möglichkeit, eine bereits existierende Antwort wiederherzustellen. Siehe CHANGELOG.md für die vollständigen Vertragsänderungen. Version 0.2 führte die private zentrale Worker-Architektur und typisierte MCP-Envelopes ein.

Repository: https://github.com/handong66/grok-plugin-codex Ausführliche Beschreibung: https://han-dong.link/en/work/grok-plugin-codex

Requirements

• Node.js >=22

• npm

• macOS oder Linux

• Unterstützung des lokalen Plugin-Marktplatzes von Codex

• Grok CLI installiert und authentifiziert

Überprüfen Sie die drei Laufzeitebenen separat:

grok --version   # CLI can be discovered
grok --help      # installed flags/capabilities
grok models      # authentication and model listing

Ein aufgeführtes Modell hat nicht unbedingt einen echten Aufruf abgeschlossen. grok_check bewahrt diese Unterscheidung.

Related MCP server: chatgpt-codex-local-mcp

Installation

npm install
npm run check
codex plugin marketplace add .
codex plugin add grok-plugin-codex --marketplace grok-plugin-codex

Starten Sie nach der Installation oder dem Upgrade eine neue Codex-Aufgabe. Bestehende Aufgaben behalten den MCP-Server und den Skill-Snapshot, mit dem sie gestartet wurden. Wenn eine neue Codex Desktop-Aufgabe den aktualisierten Skill, aber nicht die aktualisierten MCP-Tools sieht, starten Sie Codex Desktop neu und erstellen Sie eine weitere Aufgabe; der Desktop-Prozess kann seine MCP-Registrierung über eine Neuinstallation hinweg behalten.

Das installierte Paket enthält beides:

plugins/grok-plugin-codex/dist/server.js
plugins/grok-plugin-codex/dist/job-worker.js

Fähigkeitsoberfläche

• grok_check, grok_models: CLI/Fähigkeit, Authentifizierung, Berechtigung und Modelldiagnose. authenticated und entitled sind true, false oder "unknown" — niemals null.

• grok_run, grok_continue: explizite Prompt-Ausführung und Fortsetzung bekannter Sitzungen.

• grok_finalize: ein Turn, keine Tools, vollständige Antwort — die Wiederherstellung für eine zeitlich begrenzte, turn-begrenzte, abgebrochene oder durch Berechtigungen blockierte Ausführung.

• grok_rescue, grok_review, grok_adversarial_review: erzwungene schreibgeschützte, keine Unter-Agenten zweite Durchläufe. Jeder benötigt ein target (oder problem), für das auch der Name des Geschwister-Plugins prompt akzeptiert wird. grok_adversarial_review akzeptiert ein optionales threatModel; Ergebnisse außerhalb davon sind beratend und blockieren möglicherweise nicht.

• grok_sessions, grok_export: Sitzungsinspektion im expliziten Arbeitsbereich und Markdown-Export.

• grok_status, grok_result, grok_cancel: privater zentraler Hintergrund-Job-Lebenszyklus nur per jobId. grok_status gibt günstigen Fortschritt zurück (textChars, eventCounts, lastEventAt, toolCallCount, deniedToolCalls) und akzeptiert ein optionales waitMs (≤ 30 s) serverseitiges Warten; grok_result blättert finalText mit finalTextOffset / finalTextMaxChars um.

Das aktuelle MCP listTools-Schema ist maßgeblich für genaue Argumente. Der Repository-Smoke-Test sperrt die veröffentlichte Oberfläche und lehnt Abweichungen ab.

Ergebnisvertrag

Erfolgreiche Operationen geben zurück:

{ "ok": true, "data": {}, "error": null, "warnings": [] }

Geschäftsfehler setzen MCP isError: true und geben zurück:

{
  "ok": false,
  "data": null,
  "error": { "code": "typed_code", "message": "actionable message", "retryable": false },
  "warnings": []
}

Eingabeschemaverletzungen sind SDK-generierte Tool-Fehler (isError: true) ohne den Plugin-Geschäftsumschlag; Clients müssen das aufgelöste Tool-Ergebnis inspizieren, anstatt sich nur auf die Promise-Ablehnung zu verlassen. Jedes Tool veröffentlicht ein Ausgabeschema, und plugin-behandelter JSON-Text spiegelt structuredContent wider.

Arbeitsbereichs- und Prompt-Grenzen

Arbeitsbereichsoperationen erfordern cwd. Der Server kanonisiert Symlinks und verlangt, dass das aufgelöste Verzeichnis innerhalb einer aktiven MCP-Arbeitsbereichswurzel bleibt. Private Codex-Pfade wie ~/.codex werden blockiert, es sei denn, der Benutzer autorisiert dieses Risiko explizit.

Prompts werden kurzzeitig in privaten 0600-Dateien zwischengespeichert, damit ein getrennter Worker das Beenden des MCP-Servers überleben kann. Der Worker liest und löscht die Zwischenspeicherdatei, bevor Grok läuft, und liefert dann den Prompt über eine 0600-FIFO in einem zufälligen 0700-Verzeichnis. Grok erhält nur diesen privaten Pfadnamen über natives --prompt-file; der Launcher entfernt die Verknüpfung, sobald Grok sie öffnet, bevor Prompt-Bytes geschrieben werden. Prompt-Text wird nicht in die Argumentliste des Kindprozesses oder den Job-Datensatz aufgenommen. GROK_BIN ist die einzige unterstützte benutzerdefinierte ausführbare Konfiguration und muss aus der vertrauenswürdigen MCP-Umgebung stammen.

Hintergrund-Jobs

Hintergrund-Jobs laufen in einem getrennten Worker und überleben MCP-Server-Neustarts. Der Zustand befindet sich unter:

1. $GROK_PLUGIN_STATE_DIR, wenn explizit konfiguriert;

2. $XDG_STATE_HOME/grok-plugin-codex;

3. ~/.local/state/grok-plugin-codex.

Ein explizites Zustandsverzeichnis muss disjunkt zu jeder aktiven Arbeitsbereichswurzel sein: weder innerhalb einer Wurzel noch ein Vorfahre einer solchen. Es muss leer sein, den Eigentumsmarker des Plugins tragen oder dem strengen privaten Vor-Marker-Job-Layout entsprechen; das Plugin wird kein vorhandenes gemeinsames Verzeichnis beanspruchen oder chmod darauf ausführen. Diese Prüfungen schlagen geschlossen fehl, bevor repository-lokaler Zustand erstellt oder geändert wird.

Verzeichnisse verwenden 0700; Datensätze, Logs, Prompt-Zwischenspeicherdateien, Abbruchmarker, Heartbeats und Besitzer-Token-prozessübergreifende Sperren verwenden 0600. Datensatzschreibvorgänge sind atomar und der Endstatus ist monoton. Die Stornierung wird durch einen Marker linearisiert, der vom besitzenden Worker verbraucht wird. Jede Prozessgruppe wird von einem privaten Launcher angeführt, dessen Befehlsidentität die Job-ID und ein zufälliges Job-Token enthält; die Bereinigung veralteter Worker beendet eine persistierte Gruppe nur, wenn alle drei übereinstimmen, und der Launcher entfernt verbleibende Nachkommen vor dem Beenden.

Dispatch-Tools (grok_run, grok_review, grok_adversarial_review, grok_rescue) standardmäßig auf background: true; grok_continue standardmäßig auf Vordergrund. Speichern Sie data.job.id, rufen Sie dann Job-Tools mit jobId auf. Ein Vordergrundaufruf (background: false) blockiert für höchstens timeoutMs plus eine 10 s Gnadenfrist und gibt dann foreground_wait_timeout mit dieser Job-ID zurück. Ein ausgelassenes timeoutMs wird standardmäßig pro Art gesetzt — run/continue 180000, review/rescue 240000, adversarial_review 300000 — und ein expliziter Wert wird in keiner Richtung begrenzt; beide effektiven Werte werden als effectiveTimeoutMs / effectiveMaxTurns zurückgegeben. Der empfohlene Rhythmus für einen Hintergrund-Job ist ein grok_status mit waitMs, dann ein grok_result, anstatt einer Polling-Schleife. Nur diese Kombination ist endgültig:

data.resultComplete === true

Intern erfordert Vollständigkeit auch nicht-leeren endgültigen Text und ein normales Endereignis, und — für grok_review und grok_adversarial_review — mindestens einen Tool-Aufruf, da ein Urteil eines Prüfers, der nichts geöffnet hat, eine Meinung ist (no_evidence_review). Die schreibgeschützten Arten laufen im Planmodus, wo die Shell-Ausführung automatisch verweigert wird: fügen Sie den Diff oder die Befehlsausgabe, die die Überprüfung benötigt, inline in das Ziel ein, und ein Lauf, der abgebrochen wurde, weil ein Shell-Befehl Genehmigung benötigte, wird als permission_denied_headless gemeldet, nicht als zu breites Ziel. Stoppgründe werden groß-/kleinschreibungs- und trennzeichenunabhängig normalisiert (end_turn und EndTurn sind dieselbe Tatsache), der Rohwert bleibt in outputSummary.stopReason erhalten, und Aufrufer dürfen ihn nicht selbst per String-Vergleich prüfen. Ein abgebrochenes Ende wird als cancelled_output zurückgegeben. Ein nicht erkannter Stoppgrund nach echtem Text wird mit stopReasonRecognised: false plus einer Warnung akzeptiert, anstatt verworfen zu werden.

Jedes nicht vollständige Ergebnis trägt einen Wiederherstellungsgriff — error.details.recovery bei einem fehlgeschlagenen Vordergrundaufruf, data.recovery bei grok_result — geformt als { jobId, grokSessionId, partialTextChars, suggested: { tool: "grok_finalize", args }, fallback: { tool: "grok_continue", args } }. Der Griff ist wie angegeben ausführbar: suggested ist die Ein-Aufruf-Wiederherstellung, und fallback ist dasselbe ausgeschrieben für einen Aufrufer, der nur grok_continue spricht (maxTurns: 1 plus den grok_finalize-Prompt). Keiner verlangt eine verkürzte Antwort. Das Mittel für max_turns_reached und für einen abgebrochenen oder zeitlich begrenzten Lauf ist grok_finalize mit dieser Job-ID, oder derselbe Aufruf von Hand: setzen Sie dieselbe Sitzung mit maxTurns: 1 fort und einen Prompt, der Grok anweist, die Verwendung von Tools einzustellen und die endgültige Antwort jetzt auszugeben. Verengen Sie das Ziel nicht, erhöhen Sie maxTurns nicht und führen Sie die Aufgabe nicht erneut aus — die teilweise Antwort wird nie zerstört, error.details.finalTextRef ist die Job-ID, und grok_result gibt den vollständig erfassten Text zurück, unabhängig davon, was resultComplete sagt.

resultComplete berücksichtigt die Kürzung selbst: outputTruncated sagt nur, dass das gemeinsame Erfassungsfenster überlaufen ist, was normalerweise Tool-Aufruf-Echo ist, während textTruncated sagt, dass Antworttext verworfen wurde, und ist das Flag, das die Vollständigkeit ablehnt. Überdimensionierte Tool-Nutzlasten werden zum Erfassungszeitpunkt ausgelassen und available_commands-Nutzlasten werden verworfen; setzen Sie GROK_PLUGIN_RAW_CAPTURE=1, um den Anbieterstrom wörtlich für die Plugin-Entwicklung zu behalten.

Verwenden Sie data.finalText. Teilzustände sind nur Diagnosen, und die rohen Pro-Token-Log-Enden werden nur zurückgegeben, wenn grok_result mit includeRawTail: true aufgerufen wird. Der Worker behält die Antwort in einem append-only <id>.final.txt-Ledger und die Stromfakten in <id>.summary.json, sodass grok_result aus diesem Ledger antwortet, anstatt den Rohstrom neu zu parsen, und grok_status liest den Fortschritt aus derselben Datei. Terminal-Job-Artefakte werden sieben Tage lang aufbewahrt und opportunistisch bereinigt.

Upgrade von 0.1

• Schließen Sie 0.1-Hintergrund-Jobs vor dem Upgrade ab oder brechen Sie sie ab.

• 0.2 scannt oder vertraut alten <workspace>/.grok-plugin-codex/jobs-Datensätzen nicht.

• Alte Arbeitsbereichsverzeichnisse werden nicht automatisch entfernt, da sie zum Arbeitsbereich des Benutzers gehören.

• Pro-Aufruf ausführbare Auswahl, vom Aufrufer ausgewählte Exportdateien, implizite Überprüfungsziele und Job-Steuerungs-cwd wurden entfernt.

Datenschutzgrenze

Das Plugin kopiert keine versteckten Codex-Kontext, System-/Entwicklernachrichten, Überlegungen, beliebige Tool-Ausgaben, Geheimnisse oder Anmeldeinformationen in Prompts. Es kann keinen sensiblen Text schwärzen, den ein Aufrufer explizit bereitstellt. Siehe docs/privacy.md.

Entwicklung

npm install
npm run check
git diff --check

Optionale authentifizierte Aufrufung:

npm run smoke:live-grok

Laufzeitschemata und Tests sind maßgeblich. Gebündelte README/Skill-Dateien sind der installierte Benutzervertrag; test/contract-drift.test.ts und der MCP-Smoke verhindern, dass entfernte Argumente oder nicht übereinstimmende Versionen wieder auftauchen.

Siehe docs/development.md und docs/verification.md.

Projektrichtlinien

• Datenschutzrichtlinie

• Nutzungsbedingungen

• Sicherheitsrichtlinie

• Mitwirken