So verbinden Sie NexoPOS mit Codex (ChatGPT) über Oxen

Oxen verbindet einen NexoPOS-Store über das Model Context Protocol (MCP) mit Codex. Nachdem die Verbindung konfiguriert ist, kann Codex die von dem Oxen-Token erlaubten NexoPOS-Tools verwenden – zum Beispiel, um Produkte zu finden, Artikel mit niedrigem Bestand zu prüfen, Verkäufe zusammenzufassen, Bestellungen nachzuschlagen und, wenn dies gestattet ist, Datensätze zu erstellen.

Dieser Leitfaden behandelt die lokale ChatGPT-Desktop-App (Codex), die Codex-CLI und die Codex-IDE-Erweiterung. Diese Clients nutzen die gleiche MCP-Konfiguration auf demselben Codex-Host. ChatGPT im Web liest die lokale Codex-Konfiguration eines Computers nicht aus; Web-Nutzer benötigen ein installiertes Plugin, das die Remote-MCP-Verbindung bereitstellt.

Welche Verbindung besteht?

Der Datenpfad lautet:

Ihre Anfrage in Codex → Oxen MCP-Server → Ihr autorisierter NexoPOS-Shop

Oxen stellt die Tools und den vertrauenswürdigen Store-Kontext bereit. Codex entscheidet, welches Tool aus Ihrer Anfrage aufgerufen wird, Oxen prüft die Berechtigungen des Tokens, und NexoPOS gibt das zulässige Ergebnis zurück. Das Token bestimmt, welcher Store und welche Funktionen verfügbar sind. Daher sollte niemals manuell eine Store-Kennung in einen Prompt oder einen Tool-Aufruf aufgenommen werden.

Der in dieser Anleitung verwendete Oxen-Endpunkt ist:

https://nexocloud.dev/mcp/oxen

Oxen verwendet Streamable-HTTP und eine Bearer-Token-Authentifizierung. Während der Überprüfung für diese Anleitung hat der Endpunkt einen MCP-Handshake als Oxen 2.0.0 mit der Protokollversion 2025-06-18 abgeschlossen.

Anforderungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Eine funktionsfähige NexoPOS-Installation, die mit Nexo Cloud/Oxen verbunden ist.
• Ein Oxen-Zugriffstoken mit den erforderlichen Berechtigungen für die vorgesehenen Aufgaben.
• Die ChatGPT-Desktop-App mit Codex, Codex CLI oder der Codex-IDE-Erweiterung.
• Ein vertrauenswürdiges lokales Projekt, wenn die Konfiguration nur auf ein Projekt angewendet werden soll.

Die folgenden Beispiele gehen davon aus, dass das Projekt eine private token.env-Datei mit dieser Struktur enthält:

TOKEN="replace-with-your-oxen-token"
URL="https://example.com/mcp/oxen"

Füge das echte Token nicht in Dokumentationen, Prompts, Screenshots, Commits oder in die config.toml ein.

Schütze zuerst das Token

Fügen Sie token.env zur .gitignore-Datei des Projekts hinzu, bevor Sie Projektdateien committen:

token.env

Wenn das Token bereits festgeschrieben oder geteilt wurde, reicht es nicht aus, die Datei aus dem neuesten Commit zu entfernen, da sie möglicherweise weiterhin in der Git-Historie verbleibt. Widerrufe das offengelegte Token in NexoPOS/Nexo Cloud, stelle ein Ersatztoken aus und aktualisiere anschließend token.env.

Verwenden Sie die engstmöglichen Token-Berechtigungen, die die Arbeit des Benutzers abdecken. Ein Reporting-Workflow benötigt normalerweise nur Lesezugriff auf Tools; er sollte nicht automatisch Berechtigungen zur Erstellung von Kunden-, Lieferanten- oder Produktdaten erhalten.

Option 1: Mit einer Umgebungsvariable verbinden

Dies ist die einfachste Einrichtung für Codex CLI oder für eine IDE, die aus derselben Terminalsitzung gestartet wird.

1. Token-Umgebungsdatei (token.env) in PowerShell laden

Öffnen Sie PowerShell im Projektverzeichnis und führen Sie Folgendes aus:

$oxenSettings = Get-Content -LiteralPath .\token.env | ConvertFrom-StringData
$env:OXEN_TOKEN = $oxenSettings.TOKEN.Trim('"')

Dies setzt OXEN_TOKEN nur für den aktuellen PowerShell-Prozess und für Programme, die daraus gestartet werden. Wenn das Terminal geschlossen wird, wird es gelöscht.

2. Fügen Sie die MCP-Konfiguration hinzu

Erstelle oder aktualisiere „.codex/config.toml“ im Projekt:

[mcp_servers.oxen]
url = "https://example.com/mcp/oxen"
bearer_token_env_var = "OXEN_TOKEN"
enabled = true
required = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

Die MCP-Konfiguration mit Projektumfang wird nur für vertrauenswürdige Projekte geladen. Damit der Server in jedem lokalen Projekt verfügbar ist, setze die gleiche Tabelle stattdessen in der Benutzereinstellung unter ~/.codex/config.toml ein.

default_tools_approval_mode = "writes" lässt schreibgeschützte Tools normal laufen, während vor Tools, die nicht als schreibgeschützt markiert sind, eine Genehmigung eingeholt wird. Behalte diese Einstellung bei, sofern die Richtlinie deiner Organisation nicht verlangt, dass jeder Aufruf genehmigt werden muss.

3. Starte Codex aus demselben Terminal heraus

Starten Sie den Client aus der PowerShell-Sitzung, die OXEN_TOKEN enthält. Für Codex CLI:

Kodex

Wenn ein IDE über eine andere Verknüpfung oder aus einem bereits laufenden Prozess heraus gestartet wird, kann sie die temporäre Umgebungsvariable möglicherweise nicht übernehmen. Starte sie aus dem vorbereiteten Terminal neu oder verwende Option 2.

Option 2: Lassen Sie Codex token.env über einen Header-Helper lesen

Diese Option ist praktisch für die ChatGPT-Desktop-App, da sie nicht davon abhängt, dass die App eine temporäre Terminal-Variable erbt. Codex unterstützt einen lokalen Befehl „http_headers_helper“ für Streamable-HTTP-Server. Der Befehl muss ein JSON-Objekt ausgeben, das die Anforderungsheader enthält.

1. Erstelle ein lokales Header-Helper-Skript

Erstelle „tools/Get-OxenHeaders.ps1“ mit folgendem Inhalt:

$ErrorActionPreference = 'Stop'

$projectRoot = Split-Path -Parent $PSScriptRoot
$tokenFile = Join-Path $projectRoot 'token.env'

if (-not (Test-Path -LiteralPath $tokenFile)) {
    throw "Oxen token file not found: $tokenFile"
}

$settings = Get-Content -LiteralPath $tokenFile | ConvertFrom-StringData
$token = $settings.TOKEN.Trim('"')

if ([string]::IsNullOrWhiteSpace($token)) {
    throw 'TOKEN is missing from token.env'
}

@{ Authorization = "Bearer $token" } | ConvertTo-Json -Compress

Das Skript gibt nur das Header-JSON aus, das Codex benötigt. Fügen Sie keine Diagnoseausgaben hinzu, da zusätzlicher Text die Helper-Antwort ungültig machen würde.

2. Konfigurieren Sie den Oxen-Server

Fügen Sie dies zu „.codex/config.toml“ hinzu und ersetzen Sie den Pfad durch den absoluten Pfad zum Hilfsskript:

[mcp_servers.oxen]
url = "https://example.com/mcp/oxen"
http_headers_helper = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File 'C:\\path\\to\\project\\tools\\Get-OxenHeaders.ps1'"
enabled = true
required = true
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

Verwenden Sie nur eine Autorisierungsmethode. Entfernen Sie „bearer_token_env_var“, wenn Sie „http_headers_helper“ verwenden; eine explizite Quelle für den Bearer-Token hat Vorrang vor einem von „http_headers_helper“ bereitgestellten Authorization-Header.

3. Vertrauen und Neustart

Öffnen Sie das Projekt in der ChatGPT-Desktop-App und vertrauen Sie ihm, wenn Sie dazu aufgefordert werden. Starten Sie anschließend Codex neu, damit die MCP-Konfiguration neu geladen wird. In der Desktop-App entspricht der entsprechende Menüpfad „Einstellungen → MCP-Server“. Der offizielle Einrichtungsablauf besteht darin, einen Server hinzuzufügen, „Streamable HTTP“ auszuwählen, dessen URL anzugeben, zu speichern und neu zu starten.

Überprüfen Sie die Verbindung

Geben Sie in der ChatGPT-Desktop-App oder in der Codex-Terminaloberfläche Folgendes ein:

/mcp

Bestätigen Sie, dass Oxen aktiviert und verbunden ist. In einem Terminal außerhalb der Codex-TUI können Sie außerdem Folgendes ausführen:

codex mcp list

Platzhalter für Bild: Ein Screenshot des /mcp-Panels, der Oxen als aktiviert und verbunden zeigt. Schneiden Sie nicht zusammenhängende Server und Kontoinformationen aus.

Dann beginnen Sie mit einer harmlosen, schreibgeschützten Anfrage:

Verwenden Sie Oxen, um mir fünf Produkte anzuzeigen. Geben Sie nur den Namen jedes Produkts, die SKU und den aktuellen Bestand zurück.

Weitere nützliche Verifizierungsaufforderungen sind:

Use Oxen to list the products that are at or below their low-stock threshold.

Use Oxen to summarize paid, unpaid, partially paid, tax, and income totals for this month. Do not create or modify anything.

Use Oxen to search for order NS-1001, then show its line items. Do not make changes.

Codex sollte einen Aufruf des Oxen-Tools anzeigen und die zurückgegebenen Store-Daten speichern. Wenn es ohne Aufruf von Oxen aus allgemeinem Wissen antwortet, sage ausdrücklich „Use the Oxen MCP server“ und prüfe /mcp erneut.

Verfügbare Ochsen-Funktionen

Die genaue Liste hängt von den Berechtigungen des Tokens ab. Der verifizierte Server hat diese Tools offengelegt:

Produkte und Bestände

• search_products: Produkte nach Name, SKU oder Barcode finden.
• get_product: Ruft ein Produkt anhand seiner numerischen Kennung ab.
• get_low_stock_products: Finde alarmaktivierte Bestände, die bei oder unter ihrem Schwellenwert liegen, einschließlich Informationen zum Mangel.
• search_product_sales: Gib die begrenzte aggregierte Produktsumme zurück, nach Wert sortiert.
• create_product: Erstellen Sie ein einziges einfaches materielles oder immaterielles Produkt unter Verwendung vorhandener Kategorien- und Mengeneinheitenkennungen.
• import_products: Importiert atomar zwischen 1 und 50 einfache Produkte, mit Kategorien- und Mengeneinheitenauflösung.

Kunden und Lieferanten

• Kunden suchen: nach Name, E-Mail oder Telefonnummer suchen.
• get_customer: Ruft einen Kunden sowie Kontensummen ab.
• create_customer: Erstellen Sie einen Kunden und optionale Rechnungs- oder Lieferadressen.
• create_provider: Erstelle einen Lieferanten/Dienstleister aus den erlaubten Kontaktfeldern.

Bestellungen, Finanzen und Berichterstattung

• search_orders: Suche nach Bestellcode, Zeitraum oder Zahlungsstatus.
• get_order: Ruft eine Bestellung und ihre Positionen ab.
• search_wallet_history: abgerenzte Kontoauszugspositionen des Kunden abrufen.
• get_dashboard_summary: Gibt bezahlte, unbezahlte, teilweise bezahlte, Steuer- und Einkommenssummen für einen Datumsbereich zurück.
• generate_report: Erstellen Sie einen gebrandeten PDF-/HTML-Vorschaubericht oder einen CSV-Export aus ausgewählten Berichtabschnitten.

Oxen hat außerdem sichere Referenzressourcen für die aktuelle Store-Konfiguration, Zahlungsarten, Produktkategorien und Steuergruppen offengelegt. Codex kann diese Ressourcen verwenden, um gültige Kennungen auszuwählen und Ergebnisse für den verbundenen Store zu formatieren.

Platzhalterbild: Eine Codex-Konversation, die eine schreibgeschützte Anfrage bei niedrigem Bestand, den Oxen-Toolaufruf und eine kurze, geschwärzte Ergebnis-Tabelle zeigt.

Leseaktionen vs. Schreibaktionen

Suchen, Nachschlagen, Zusammenfassungen und das Lesen von Referenzressourcen ändern NexoPOS nicht. Erstellungs- und Import-Tools tun dies.

Bevor Sie einen Write-Call genehmigen, prüfen Sie jedes Feld, das von Codex angezeigt wird. Insbesondere:

• Überprüfen Sie Namen, Preise, Barcodes, SKUs, Kategorien-IDs, Mengeneinheiten und Steuereinstellungen.
• Verwenden Sie für jeden beabsichtigten Schreibvorgang einen eindeutigen idempotency_key. Wenn eine Anfrage erneut versucht werden muss, verwenden Sie denselben Schlüssel, damit ein Netzwerk-Retry keine Duplikate erzeugt.
• Bestätigen Sie die Kontaktdaten des Kunden und des Anbieters, bevor Sie sie übermitteln.
• Teste die Schreibrechte mit einem klar benannten temporären Datensatz nur dann, wenn es die Richtlinie deines Shops zulässt, und entferne ihn anschließend bei Bedarf aus NexoPOS.
• Denken Sie daran, dass „import_products“ atomar ist: Der gesamte Batch wird zurückgerollt, wenn bei einer Zeile ein Fehler auftritt.

Ein sicherer Zwei-Schritt-Prompt ist:

Prepare the Oxen arguments for a new product named “House Blend 250 g” at 12.50. First read the available product categories and units. Show me the proposed values, but do not call create_product until I approve them.

Platzhalter für Bild: Ein Screenshot von Codex, der eine vorgeschlagene Aktion „create_product“ anzeigt und auf eine Genehmigung wartet, wobei store-spezifische Kennungen unkenntlich gemacht wurden.

Praktische Anfragen nach der Einrichtung

Sobald die Nur-Lese-Prüfungen funktionieren, kann Codex mehrstufige Fragen wie diese bearbeiten:

Use Oxen to find low-stock products, rank them by shortage, and explain which five need attention first. Do not modify inventory.

Use Oxen to compare this month's dashboard totals with last month's. Show the absolute and percentage changes and flag any unpaid balance.

Use Oxen to find the top 10 products by sales value, then generate a branded PDF report with KPI cards and a bar chart. Show me the planned report sections before creating the file.

Read this CSV, validate each product against the available NexoPOS categories and units, report all problems, and wait for my approval before calling import_products.

Fehlerbehebung

Ochsen erscheinen nicht in /mcp

• Bestätigen Sie, dass die Konfigurationsdatei für ein projektbezogenes Setup exakt „.codex/config.toml“ heißt oder für ein benutzerbezogenes Setup „config.toml“ unter „~/.codex“.
• Stellen Sie sicher, dass das Projekt vertrauenswürdig ist.
• Starten Sie die ChatGPT-Desktop-App oder die IDE-Erweiterung neu, nachdem Sie die MCP-Einstellungen geändert haben.
• Führe „codex mcp list“ und „codex mcp --help“ in einem Terminal aus.
• Validieren Sie die TOML-Syntax, insbesondere Windows-Backslashes und Anführungszeichen in „http_headers_helper“.

Der Server gibt „401 Unauthorized“ zurück.

• Prüfe, dass TOKEN in token.env vorhanden ist und keine versehentlichen Leerzeichen enthält.
• Wenn Sie bearer_token_env_var verwenden, bestätigen Sie, dass OXEN_TOKEN in der Umgebung definiert ist, die Codex gestartet hat.
• Wenn Sie den Helper verwenden, führen Sie ihn direkt aus und bestätigen Sie, dass er ein einziges kompaktes JSON-Objekt erzeugt. Geben Sie die Ausgabe nicht aus oder teilen Sie sie nicht, da sie das Bearer-Token enthält.
• Geben Sie das Token erneut aus, falls es widerrufen, abgelaufen oder offengelegt wurde.

Der Server gibt „403 Forbidden“ zurück.

Das Token wird erkannt, verfügt jedoch nicht über die Berechtigung für die angeforderte Funktion oder die Store-Richtlinie blockiert es. Fordern Sie den NexoPOS-Administrator auf, nur den erforderlichen Scope zu gewähren. Umgehen Sie die Berechtigungsgrenze nicht, indem Sie Store-IDs oder Anmeldeinformationen in den Prompt einfügen.

Lese-Tools funktionieren, aber Erstellungs-Tools fehlen.

Dies ist normalerweise ein Berechtigungsproblem, kein Verbindungsfehler. Oxen stellt tools bereit, die nach Berechtigungen eingeschränkt sind. Daher kann ein Token mit Nur-Lesezugriff absichtlich create_product, create_customer, create_provider oder import_products weglassen.

Die Desktop-App verbindet sich, aber ChatGPT im Web nicht.

Das ist zu erwarten. Lokale Codex-Clients teilen die MCP-Konfiguration des Hosts, aber ChatGPT Web liest keine lokalen .codex/config.toml-Dateien. ChatGPT Web benötigt ein installiertes Plugin, das entweder das Remote-MCP-Server-Setup bündelt oder eine Verbindung dazu herstellt, und kann außerdem von Administratoren des Arbeitsbereichs gesteuert werden.

Die Verbindung läuft ab.

• Bestätigen Sie, dass https://nexocloud.dev/mcp/oxen von dem Computer aus erreichbar ist.
• Überprüfen Sie Proxy-, Firewall- und DNS-Regeln.
• Erhöhen Sie startup_timeout_sec, wenn die Verbindung langsam ist.
• Behalten Sie tool_timeout_sec hoch genug bei, damit die Berichtserstellung möglich ist, die möglicherweise länger dauert als eine einfache Suche.

Sicherheits-Checkliste

• Halten Sie token.env aus Git und Backups fern, die zum Teilen vorgesehen sind.
• Füge niemals ein Token in einen Codex-Prompt ein.
• Setze das Token niemals direkt in der config.toml ein.
• Verwenden Sie HTTPS und den exakten Oxen-Endpunkt.
• Gewähren Sie die engstmöglichen Berechtigungen für das Tool.
• Aktiviere Schreibwerkzeug-Freigaben.
• Überprüfen Sie die vorgeschlagenen Schreiben, bevor Sie sie genehmigen.
• Widerrufen und ersetzen Sie alle Tokens, die möglicherweise offengelegt wurden.
• Verwenden Sie separate Tokens für Produktions- und Testspeicher.
• Entfernen oder deaktivieren Sie den MCP-Eintrag, wenn der Zugriff nicht mehr benötigt wird.

Oxen trennen

Um den Server zu deaktivieren, ohne seine Einstellungen zu löschen:

[mcp_servers.oxen]
enabled = false

Entfernen Sie alternativ den Abschnitt „[mcp_servers.oxen]“ und starten Sie Codex neu. Löschen Sie die aktuelle Shell-Variable mit:

Remove-Item Env:OXEN_TOKEN

Wenn der Computer oder das Repository den Eigentümer wechselt, widerrufen Sie außerdem das Token.