Backendy CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Narzędzia OpenClaw nie są wstrzykiwane bezpośrednio, ale backendy z bundleMcp: true mogą otrzymywać narzędzia Gateway przez most MCP local loopback.
• Strumieniowanie JSONL dla CLI, które je obsługują.
• Sesje są obsługiwane (więc kolejne tury pozostają spójne).
• Obrazy mogą być przekazywane dalej, jeśli CLI akceptuje ścieżki obrazów.

​

Szybki start dla początkujących

openclaw agent --message "hi" --model codex-cli/gpt-5.5

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}

​

Używanie jako fallback

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.5"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.5": {},
      },
    },
  },
}

• Jeśli używasz agents.defaults.models (listy dozwolonych), musisz uwzględnić tam również modele backendu CLI.
• Jeśli główny dostawca zawiedzie (uwierzytelnianie, limity szybkości, timeouty), OpenClaw spróbuje następnie backendu CLI.

​

Omówienie konfiguracji

agents.defaults.cliBackends

<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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          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 jest obsługiwany), aby historia pozostała spójna. Dołączony backend claude-cli utrzymuje proces Claude stdio przy życiu dla każdej sesji OpenClaw i wysyła kolejne tury przez stream-json stdin.
4. Parsuje wyjście (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.

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

Sesje

• Jeśli CLI obsługuje sesje, ustaw sessionArg (np. --session-id) lub sessionArgs (placeholder {sessionId}), gdy ID musi zostać wstawiony do wielu flag.
• Jeśli CLI używa podpolecenia resume z innymi flagami, ustaw resumeArgs (zastępuje args podczas wznawiania) i opcjonalnie resumeOutput (dla wznowień innych niż JSON).
• sessionMode:
  • always: zawsze wysyłaj identyfikator sesji (nowy UUID, jeśli żaden nie jest zapisany).
  • existing: wysyłaj identyfikator sesji tylko wtedy, gdy wcześniej jakiś zapisano.
  • none: nigdy nie wysyłaj identyfikatora sesji.
• claude-cli domyślnie używa liveSession: "claude-stdio", output: "jsonl", oraz input: "stdin", aby kolejne tury ponownie używały aktywnego procesu Claude. Ciepłe stdio jest teraz domyślne, także dla niestandardowych konfiguracji, które pomijają pola transportu. Jeśli Gateway zostanie zrestartowany lub bezczynny proces zakończy działanie, OpenClaw wznawia z zapisanego identyfikatora sesji Claude. Zapisane identyfikatory sesji są weryfikowane względem istniejącego czytelnego transkryptu projektu przed wznowieniem, więc fantomowe powiązania są czyszczone z reason=transcript-missing zamiast po cichu zaczynać świeżą sesję Claude CLI pod --resume.
• Sesje live Claude zachowują ograniczone strażniki wyjścia JSONL. Domyślne ustawienia pozwalają na maksymalnie 8 MiB i 20 000 surowych linii JSONL na turę. Tury Claude intensywnie używające narzędzi mogą podnieść te limity dla backendu przez agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars oraz maxTurnLines; OpenClaw ogranicza te ustawienia do 64 MiB i 100 000 linii.
• Zapisane sesje CLI są ciągłością należącą do dostawcy. Niejawny dzienny reset sesji ich nie przerywa; /reset i jawne polityki session.reset nadal to robią.
• Świeże sesje CLI zwykle reseedują tylko z podsumowania Compaction OpenClaw oraz ogona po Compaction. Aby odzyskać krótkie sesje unieważnione przed Compaction, backend może włączyć opcję reseedFromRawTranscriptWhenUncompacted: true. OpenClaw nadal utrzymuje reseed surowego transkryptu w ograniczonym zakresie i ogranicza go do bezpiecznych unieważnień, takich jak brakujące transkrypty CLI, zmiany promptu systemowego/MCP lub ponowienie po wygaśnięciu sesji; zmiany profilu auth lub epoki poświadczeń nigdy nie reseedują surowej historii transkryptu.

• serialize: true utrzymuje uruchomienia w tej samej ścieżce w kolejności.
• Większość CLI serializuje w jednej ścieżce dostawcy.
• OpenClaw porzuca ponowne użycie zapisanej sesji CLI, gdy zmienia się wybrana tożsamość auth, w tym zmieniony identyfikator profilu auth, statyczny API key, statyczny token lub tożsamość konta OAuth, gdy CLI ją ujawnia. Rotacja tokenów dostępu i odświeżania OAuth nie przerywa zapisanej sesji CLI. Jeśli CLI nie ujawnia stabilnego identyfikatora konta OAuth, OpenClaw pozwala temu CLI egzekwować uprawnienia wznowienia.

​

Prelude fallback z sesji claude-cli

• Prelude preferuje najnowsze podsumowanie /compact lub marker compact_boundary, a następnie dołącza najnowsze tury po granicy do limitu znaków. Tury sprzed granicy są odrzucane, ponieważ podsumowanie już je reprezentuje.
• Bloki narzędzi są łączone w kompaktowe wskazówki (tool call: name) oraz (tool result: …), aby zachować uczciwy budżet promptu. Podsumowanie jest oznaczane (truncated), jeśli przekroczy limit.
• Fallbacki tego samego dostawcy z claude-cli do claude-cli polegają na własnym --resume Claude i pomijają prelude.
• Ziarno ponownie używa istniejącej walidacji ścieżki pliku sesji Claude, więc nie można odczytywać dowolnych ścieżek.

​

Obrazy (przekazywanie dalej)

imageArg: "--image",
imageMode: "repeat"

​

Wejścia / wyjścia

• output: "json" (domyślnie) próbuje sparsować JSON i wyodrębnić tekst oraz identyfikator sesji.
• Dla wyjścia JSON Gemini CLI OpenClaw odczytuje tekst odpowiedzi z response oraz użycie ze stats, gdy usage brakuje lub jest puste.
• output: "jsonl" parsuje strumienie JSONL (na przykład Codex CLI --json) i wyodrębnia końcową wiadomość agenta oraz identyfikatory sesji, gdy są obecne.
• output: "text" traktuje stdout jako końcową odpowiedź.

• 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.

​

Domyślne wartości (należące do pluginu)

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

• 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"]

• Tekst odpowiedzi jest odczytywany z pola JSON response.
• Użycie wraca do stats, gdy usage jest nieobecne lub puste.
• stats.cached jest normalizowane do cacheRead OpenClaw.
• Jeśli brakuje stats.input, OpenClaw wyprowadza tokeny wejściowe z stats.input_tokens - stats.cached.

​

Wartości domyślne należące do Pluginu

• Pluginy rejestrują je za pomocą api.registerCliBackend(...).
• id backendu staje się prefiksem dostawcy w odwołaniach do modeli.
• Konfiguracja użytkownika w agents.defaults.cliBackends.<id> nadal nadpisuje wartość domyślną Pluginu.
• Czyszczenie konfiguracji specyficznej dla backendu pozostaje własnością Pluginu przez opcjonalny hook normalizeConfig.

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" },
  ],
});

​

Nakładki MCP pakietu

• claude-cli: generowany ścisły plik konfiguracji MCP
• codex-cli: wbudowane nadpisania konfiguracji dla mcp_servers; generowany serwer loopback OpenClaw jest oznaczony trybem zatwierdzania narzędzi per serwer w Codex, aby wywołania MCP nie mogły zatrzymać się na lokalnych monitach zatwierdzania
• google-gemini-cli: generowany plik ustawień systemowych Gemini

• uruchamia serwer HTTP MCP loopback, który udostępnia narzędzia Gateway procesowi CLI
• uwierzytelnia most tokenem per sesja (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 istniejącym kształtem konfiguracji/ustawień MCP backendu
• przepisuje konfigurację uruchomienia przy użyciu trybu integracji należącego do backendu z właścicielskiego rozszerzenia

​

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 specyficzne dla backendu. Niektóre backendy strumieniują JSONL; inne buforują do zakończenia.
• Dane wyjściowe strukturalne zależą od formatu JSON CLI.
• Sesje Codex CLI wznawiają działanie przez wyjście tekstowe (bez JSONL), które jest mniej strukturalne 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 zmapować provider/model → model CLI.
• Brak ciągłości sesji: upewnij się, że sessionArg jest ustawione, a sessionMode nie ma wartości none (Codex CLI obecnie nie może wznawiać z wyjściem JSON).
• Obrazy ignorowane: ustaw imageArg (i sprawdź, czy CLI obsługuje ścieżki plików).

​

Powiązane

• Runbook Gateway
• Modele lokalne