Gravity Claw Railway-Betriebslog

Umfang: Einen Gravity-Claw-AI-Agent auf Railway betreiben, ohne zwei Telegram-Bot-Instanzen gleichzeitig gegen denselben Token laufen zu lassen.

Projektdaten

Diese Werte einmal ausfuellen und dann im gesamten Ablauf verwenden.

Voraussetzungen

Railway CLI

Railway CLI installieren und pruefen:

npm install -g @railway/cli
railway --version

Login

Bei Railway authentifizieren:

railway login --browserless

Projekt verknuepfen

Im Gravity-Claw-Ordner ausfuehren:

railway link

Danach das richtige Railway-Projekt und den passenden Service auswaehlen.

Umgebungsvariablen setzen

Jeden benoetigten Wert aus .env nach Railway uebertragen:

railway variables set TELEGRAM_BOT_TOKEN="your-token"
railway variables set OPENROUTER_API_KEY="your-key"
# Fuer jede benoetigte Variable wiederholen.

Entwicklungszyklus

1. Railway pausieren -> 2. Lokal testen -> 3. Deployen -> 4. Verifizieren

Phase 1: Railway pausieren

Vor lokalen Tests immer zuerst den Railway-Service pausieren.

Zwei Bot-Instanzen, die denselben Telegram-Token pollen, konkurrieren um dieselben Nachrichten. Einige Updates landen bei Railway, andere auf dem Laptop, und keine Umgebung laeuft verlaesslich.

railway down

Phase 2: Lokal testen

Den lokalen Dev-Server mit Hot Reload starten:

npm run dev

Das startet tsx watch src/index.ts und fuehrt bei Codeaenderungen automatische Restarts aus. Der Bot wird waehrenddessen direkt ueber Telegram getestet.

Nach Abschluss der Tests den lokalen Server mit Ctrl+C stoppen.

Phase 3: Auf Railway deployen

Vor dem Deploy einen Type-Check ausfuehren:

npx tsc --noEmit

Falls neue Umgebungsvariablen hinzugekommen sind, vor dem Deployment setzen:

railway variables set NEW_VAR_NAME="value"

Deploy ausfuehren:

railway up --detach

Railway startet einen Docker-Build. Erwartbar sind etwa 60 bis 90 Sekunden Build-Zeit. Der Bot kann kurz offline sein und verbindet sich danach automatisch wieder.

Phase 4: Verifizieren

Nachdem der Build Zeit zum Abschluss hatte, Logs pruefen:

railway logs --lines 40

Erwartete Signale:

• Soul loaded (soul.md)
• Connected as @your_bot_name
• Heartbeat scheduled
• Keine Crash-Traces
• Keine unbehandelten Fehler

Schnellreferenz

Betriebsnotizen

SQLite wird bei jedem Deploy zurueckgesetzt

Das Railway-Dateisystem ist ephemer. Die lokale SQLite-Datenbank, typischerweise gravity-claw.db, startet bei jedem Deploy frisch. Kurzfristige Konversationserinnerung geht dadurch verloren.

Pinecone Semantic Memory liegt in der Cloud und bleibt ueber Deployments hinweg erhalten.

Dateien, die per Dockerfile deployed werden

Diese Dateien und Ordner gehoeren erwartbar zum Deployment-Artefakt:

• src/
• tsconfig.json
• soul.md
• mcp.json
• package.json
• package-lock.json

Dateien, die per .dockerignore ausgeschlossen werden

Diese Dateien sollten nicht deployed werden:

• .env
• node_modules/
• gravity-claw.db

Troubleshooting

Agenten-Workflow

Fuer Antigravity- oder Gemini-artige AI-Coding-Agents werden die Deployment-Workflow-Dateien im .agent/-Ordner des Projekts abgelegt. Der Agent kann dann den Zyklus aus Pausieren, Testen, Deployen und Verifizieren ohne manuelle Railway-Befehle durchfuehren.

Praktisch sollte der Operator “deploy” sagen koennen, und der Agent fuehrt den vollstaendigen Railway-Ablauf aus.