Przejdź do głównej treści

​
Backendy CLI (zapasowe środowisko uruchomieniowe)

OpenClaw może uruchamiać lokalne CLI AI jako zapasowe rozwiązanie tylko tekstowe, gdy dostawcy API są niedostępni, objęci limitami szybkości lub tymczasowo działają nieprawidłowo. To podejście jest celowo zachowawcze:
  • Narzędzia OpenClaw nie są wstrzykiwane bezpośrednio, ale backendy z bundleMcp: true mogą otrzymywać narzędzia gateway przez mostek loopback MCP.
  • Strumieniowanie JSONL dla CLI, które je obsługują.
  • Sesje są obsługiwane (dzięki czemu kolejne tury pozostają spójne).
  • Obrazy mogą być przekazywane dalej, jeśli CLI akceptuje ścieżki do obrazów.
To rozwiązanie zostało zaprojektowane jako siatka bezpieczeństwa, a nie główna ścieżka. Używaj go, gdy chcesz mieć odpowiedzi tekstowe typu „zawsze działa” bez polegania na zewnętrznych API. Jeśli chcesz w pełni wyposażone środowisko z kontrolą sesji ACP, zadaniami w tle, powiązaniem wątku/rozmowy i trwałymi zewnętrznymi sesjami kodowania, użyj Agentów ACP. Backendy CLI nie są ACP.

​
Szybki start dla początkujących

Możesz używać Codex CLI bez żadnej konfiguracji (dołączona wtyczka OpenAI rejestruje domyślny backend): 
openclaw agent --message "hi" --model codex-cli/gpt-5.4
Jeśli twój gateway działa pod launchd/systemd i PATH jest minimalne, dodaj tylko ścieżkę polecenia: 
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}
To wszystko. Nie są potrzebne klucze ani dodatkowa konfiguracja uwierzytelniania poza samym CLI. Jeśli używasz dołączonego backendu CLI jako głównego dostawcy wiadomości na hoście gateway, OpenClaw teraz automatycznie ładuje właścicielską dołączoną wtyczkę, gdy twoja konfiguracja jawnie odwołuje się do tego backendu w referencji modelu lub w agents.defaults.cliBackends.

​
Używanie jako rozwiązania zapasowego

Dodaj backend CLI do listy rozwiązań zapasowych, aby był uruchamiany tylko wtedy, gdy modele główne zawiodą: 
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.4"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.4": {},
      },
    },
  },
}
Uwagi:
  • Jeśli używasz agents.defaults.models (lista dozwolonych), musisz uwzględnić tam również modele backendu CLI.
  • Jeśli główny dostawca zawiedzie (uwierzytelnianie, limity szybkości, limity czasu), OpenClaw spróbuje następnie użyć backendu CLI.

​
Przegląd konfiguracji

Wszystkie backendy CLI znajdują się pod: 
agents.defaults.cliBackends
Każdy wpis jest kluczowany przez identyfikator dostawcy (np. codex-cli, my-cli). Identyfikator dostawcy staje się lewą stroną referencji modelu: 
<provider>/<model>

​
Przykładowa konfiguracja

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          // CLI w stylu Codex mogą zamiast tego wskazywać plik promptu:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​
Jak to działa

  1. Wybiera backend na podstawie prefiksu dostawcy (codex-cli/...).
  2. Buduje prompt systemowy przy użyciu tego samego promptu OpenClaw i kontekstu obszaru roboczego.
  3. Uruchamia CLI z identyfikatorem sesji (jeśli obsługiwany), aby historia pozostała spójna.
  4. Parsuje dane wyjściowe (JSON lub zwykły tekst) i zwraca końcowy tekst.
  5. Utrwala identyfikatory sesji dla każdego backendu, aby kolejne tury ponownie używały tej samej sesji CLI.
Dołączony backend Anthropic claude-cli jest ponownie obsługiwany. Pracownicy Anthropic powiedzieli nam, że użycie Claude CLI w stylu OpenClaw jest znowu dozwolone, więc OpenClaw traktuje użycie claude -p jako zatwierdzone dla tej integracji, chyba że Anthropic opublikuje nową politykę.
Dołączony backend OpenAI codex-cli przekazuje prompt systemowy OpenClaw przez nadpisanie konfiguracji model_instructions_file Codex (-c model_instructions_file="..."). Codex nie udostępnia flagi w stylu Claude --append-system-prompt, więc OpenClaw zapisuje złożony prompt do pliku tymczasowego dla każdej nowej sesji Codex CLI. Dołączony backend Anthropic claude-cli otrzymuje migawkę Skills OpenClaw na dwa sposoby: kompaktowy katalog Skills OpenClaw w dołączonym prompcie systemowym oraz tymczasową wtyczkę Claude Code przekazaną przez --plugin-dir. Wtyczka zawiera tylko kwalifikujące się Skills dla danego agenta/sesji, dzięki czemu natywny resolver Skills Claude Code widzi ten sam przefiltrowany zestaw, który OpenClaw w przeciwnym razie reklamowałby w prompcie. Nadpisania zmiennych środowiskowych/API key dla Skills są nadal stosowane przez OpenClaw do środowiska procesu potomnego dla tego uruchomienia.

​
Sesje

  • Jeśli CLI obsługuje sesje, ustaw sessionArg (np. --session-id) lub sessionArgs (placeholder {sessionId}), gdy identyfikator musi zostać wstawiony do wielu flag.
  • Jeśli CLI używa podpolecenia wznawiania z innymi flagami, ustaw resumeArgs (zastępuje args przy wznawianiu) i opcjonalnie resumeOutput (dla wznowień niebędących JSON).
  • sessionMode:
    • always: zawsze wysyłaj identyfikator sesji (nowy UUID, jeśli żaden nie jest zapisany).
    • existing: wysyłaj identyfikator sesji tylko wtedy, gdy był wcześniej zapisany.
    • none: nigdy nie wysyłaj identyfikatora sesji.
Uwagi dotyczące serializacji:
  • serialize: true utrzymuje kolejność uruchomień na tej samej ścieżce.
  • Większość CLI serializuje na jednej ścieżce dostawcy.
  • OpenClaw porzuca ponowne użycie zapisanej sesji CLI, gdy stan uwierzytelniania backendu się zmienia, w tym przy ponownym logowaniu, rotacji tokena lub zmianie poświadczenia profilu uwierzytelniania.

​
Obrazy (przekazywanie dalej)

Jeśli twoje CLI akceptuje ścieżki do obrazów, ustaw imageArg: 
imageArg: "--image",
imageMode: "repeat"
OpenClaw zapisze obrazy base64 do plików tymczasowych. Jeśli imageArg jest ustawione, te ścieżki są przekazywane jako argumenty CLI. Jeśli imageArg nie jest ustawione, OpenClaw dołącza ścieżki plików do promptu (wstrzyknięcie ścieżki), co wystarcza dla CLI, które automatycznie ładują pliki lokalne ze zwykłych ścieżek.

​
Wejścia / wyjścia

  • output: "json" (domyślnie) próbuje sparsować JSON i wyodrębnić tekst + identyfikator sesji.
  • Dla wyjścia JSON Gemini CLI OpenClaw odczytuje tekst odpowiedzi z response, a użycie z stats, gdy usage nie istnieje lub jest puste.
  • output: "jsonl" parsuje strumienie JSONL (na przykład Codex CLI --json) i wyodrębnia końcową wiadomość agenta oraz identyfikatory sesji, jeśli są obecne.
  • output: "text" traktuje stdout jako końcową odpowiedź.
Tryby wejścia:
  • input: "arg" (domyślnie) przekazuje prompt jako ostatni argument CLI.
  • input: "stdin" wysyła prompt przez stdin.
  • Jeśli prompt jest bardzo długi i ustawiono maxPromptArgChars, używane jest stdin.

​
Wartości domyślne (własność wtyczki)

Dołączona wtyczka OpenAI rejestruje również wartość domyślną dla codex-cli:
  • command: "codex"
  • args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • output: "jsonl"
  • resumeOutput: "text"
  • modelArg: "--model"
  • imageArg: "--image"
  • sessionMode: "existing"
Dołączona wtyczka Google rejestruje również wartość domyślną dla google-gemini-cli:
  • command: "gemini"
  • args: ["--output-format", "json", "--prompt", "{prompt}"]
  • resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
  • imageArg: "@"
  • imagePathScope: "workspace"
  • modelArg: "--model"
  • sessionMode: "existing"
  • sessionIdFields: ["session_id", "sessionId"]
Wymaganie wstępne: lokalny Gemini CLI musi być zainstalowany i dostępny jako gemini w PATH (brew install gemini-cli lub npm install -g @google/gemini-cli). Uwagi dotyczące JSON Gemini CLI:
  • Tekst odpowiedzi jest odczytywany z pola JSON response.
  • Użycie przechodzi awaryjnie na stats, gdy usage nie istnieje lub jest puste.
  • stats.cached jest normalizowane do OpenClaw cacheRead.
  • Jeśli brakuje stats.input, OpenClaw wyprowadza tokeny wejściowe z stats.input_tokens - stats.cached.
Nadpisuj tylko wtedy, gdy jest to potrzebne (często: bezwzględna ścieżka command).

​
Domyślne ustawienia będące własnością wtyczki

Domyślne ustawienia backendu CLI są teraz częścią powierzchni wtyczki:
  • Wtyczki rejestrują je przez api.registerCliBackend(...).
  • Backend id staje się prefiksem dostawcy w referencjach modeli.
  • Konfiguracja użytkownika w agents.defaults.cliBackends.<id> nadal nadpisuje domyślne ustawienie wtyczki.
  • Czyszczenie konfiguracji specyficznej dla backendu pozostaje własnością wtyczki dzięki opcjonalnemu hookowi normalizeConfig.
Wtyczki, które potrzebują niewielkich shimów zgodności promptów/wiadomości, mogą deklarować dwukierunkowe transformacje tekstu bez zastępowania dostawcy ani backendu CLI: 
api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});
input przepisuje prompt systemowy i prompt użytkownika przekazywane do CLI. output przepisuje strumieniowane delty asystenta i sparsowany tekst końcowy, zanim OpenClaw obsłuży własne znaczniki sterujące i dostarczenie do kanału. Dla CLI, które emitują JSONL zgodny z Claude Code stream-json, ustaw jsonlDialect: "claude-stream-json" w konfiguracji tego backendu.

​
Nakładki MCP pakietu

Backendy CLI nie otrzymują bezpośrednio wywołań narzędzi OpenClaw, ale backend może włączyć generowaną nakładkę konfiguracji MCP za pomocą bundleMcp: true. Obecne zachowanie dołączonych backendów:
  • claude-cli: generowany ścisły plik konfiguracji MCP
  • codex-cli: wbudowane nadpisania konfiguracji dla mcp_servers
  • google-gemini-cli: generowany plik ustawień systemowych Gemini
Gdy bundle MCP jest włączone, OpenClaw:
  • uruchamia loopback HTTP MCP server, który udostępnia narzędzia gateway procesowi CLI
  • uwierzytelnia mostek przy użyciu tokena na sesję (OPENCLAW_MCP_TOKEN)
  • ogranicza dostęp do narzędzi do bieżącej sesji, konta i kontekstu kanału
  • ładuje włączone serwery bundle-MCP dla bieżącego obszaru roboczego
  • scala je z dowolnym istniejącym kształtem konfiguracji/ustawień backendu MCP
  • przepisuje konfigurację uruchomienia przy użyciu trybu integracji będącego własnością backendu z rozszerzenia będącego jego właścicielem
Jeśli żadne serwery MCP nie są włączone, OpenClaw nadal wstrzykuje ścisłą konfigurację, gdy backend włącza bundle MCP, aby uruchomienia w tle pozostawały odizolowane.

​
Ograniczenia

  • Brak bezpośrednich wywołań narzędzi OpenClaw. OpenClaw nie wstrzykuje wywołań narzędzi do protokołu backendu CLI. Backendy widzą narzędzia gateway tylko wtedy, gdy włączą bundleMcp: true.
  • Strumieniowanie jest zależne od backendu. Niektóre backendy strumieniują JSONL; inne buforują do zakończenia działania.
  • Ustrukturyzowane wyjścia zależą od formatu JSON danego CLI.
  • Sesje Codex CLI są wznawiane przez wyjście tekstowe (bez JSONL), co jest mniej ustrukturyzowane niż początkowe uruchomienie --json. Sesje OpenClaw nadal działają normalnie.

​
Rozwiązywanie problemów

  • Nie znaleziono CLI: ustaw command na pełną ścieżkę.
  • Nieprawidłowa nazwa modelu: użyj modelAliases, aby odwzorować provider/model → model CLI.
  • Brak ciągłości sesji: upewnij się, że ustawiono sessionArg, a sessionMode nie ma wartości none (Codex CLI obecnie nie może wznawiać z wyjściem JSON).
  • Obrazy są ignorowane: ustaw imageArg (i sprawdź, czy CLI obsługuje ścieżki plików).