Środowiska uruchomieniowe agentów

Agent runtime to komponent, który jest właścicielem jednej przygotowanej pętli modelu: odbiera prompt, steruje wyjściem modelu, obsługuje natywne wywołania narzędzi i zwraca ukończoną turę do OpenClaw.

Runtimy łatwo pomylić z dostawcami, ponieważ oba pojęcia pojawiają się w pobliżu konfiguracji modelu. To różne warstwy:

W kodzie zobaczysz też słowo harness. Harness to implementacja, która zapewnia agent runtime. Na przykład dołączony harness Codex implementuje runtime codex. Konfiguracja publiczna używa agentRuntime.id we wpisach dostawcy lub modelu; klucze runtime całego agenta są przestarzałe i ignorowane. openclaw doctor --fix usuwa stare przypięcia runtime całego agenta i przepisuje przestarzałe odwołania runtime do modeli na kanoniczne odwołania dostawca/model oraz, tam gdzie trzeba, politykę runtime w zakresie modelu.

Istnieją dwie rodziny runtime:

• Osadzone harnessy działają wewnątrz przygotowanej pętli agenta OpenClaw. Dziś jest to wbudowany runtime pi oraz zarejestrowane harnessy Plugin, takie jak codex.
• Backendy CLI uruchamiają lokalny proces CLI, zachowując kanoniczne odwołanie do modelu. Na przykład anthropic/claude-opus-4-7 z przypisanym do modelu agentRuntime.id: "claude-cli" oznacza „wybierz model Anthropic, wykonaj przez Claude CLI”. claude-cli nie jest identyfikatorem osadzonego harnessa i nie może być przekazywany do wyboru AgentHarness.

Powierzchnie Codex

Najwięcej nieporozumień wynika z kilku różnych powierzchni używających nazwy Codex:

Te powierzchnie są celowo niezależne. Włączenie Plugin codex udostępnia natywne funkcje serwera aplikacji; openclaw doctor --fix odpowiada za naprawę przestarzałej trasy openai-codex/* i czyszczenie nieaktualnych przypięć sesji. Wybranie openai/* jako modelu agenta oznacza teraz „uruchom to przez Codex”, chyba że używana jest nieagentowa powierzchnia OpenAI API.

Typowa konfiguracja subskrypcji ChatGPT/Codex używa OAuth Codex do uwierzytelniania, ale zachowuje odwołanie do modelu jako openai/* i wybiera runtime codex:

{  agents: {    defaults: {      model: "openai/gpt-5.5",    },  },}

Oznacza to, że OpenClaw wybiera odwołanie do modelu OpenAI, a następnie prosi runtime serwera aplikacji Codex o uruchomienie osadzonej tury agenta. Nie oznacza to „użyj rozliczeń API” ani nie oznacza, że kanał, katalog dostawcy modelu lub magazyn sesji OpenClaw staje się Codex.

Gdy dołączony Plugin codex jest włączony, sterowanie Codex w języku naturalnym powinno używać natywnej powierzchni poleceń /codex (/codex bind, /codex threads, /codex resume, /codex steer, /codex stop) zamiast ACP. Używaj ACP dla Codex tylko wtedy, gdy użytkownik wyraźnie prosi o ACP/acpx lub testuje ścieżkę adaptera ACP. Claude Code, Gemini CLI, OpenCode, Cursor i podobne zewnętrzne harnessy nadal używają ACP.

To drzewo decyzji dla agenta:

1. Jeśli użytkownik prosi o wiązanie/sterowanie/wątek/wznowienie/sterowanie/zatrzymanie Codex, użyj natywnej powierzchni poleceń /codex, gdy dołączony Plugin codex jest włączony.
2. Jeśli użytkownik prosi o Codex jako osadzony runtime albo chce zwykłego doświadczenia agenta Codex opartego na subskrypcji, użyj openai/<model>.
3. Jeśli użytkownik wyraźnie wybiera PI dla modelu OpenAI, zachowaj odwołanie do modelu jako openai/<model> i ustaw politykę runtime dostawcy/modelu na agentRuntime.id: "pi". Wybrany profil uwierzytelniania openai-codex jest wewnętrznie kierowany przez przestarzały transport uwierzytelniania Codex w PI.
4. Jeśli przestarzała konfiguracja nadal zawiera odwołania do modeli openai-codex/*, napraw ją do openai/<model> za pomocą openclaw doctor --fix; doctor zachowuje trasę uwierzytelniania Codex, dodając przypisane do dostawcy/modelu agentRuntime.id: "codex" tam, gdzie sugerowało to stare odwołanie do modelu.
5. Jeśli użytkownik wyraźnie mówi ACP, acpx lub adapter ACP Codex, użyj ACP z runtime: "acp" i agentId: "codex".
6. Jeśli żądanie dotyczy Claude Code, Gemini CLI, OpenCode, Cursor, Droid lub innego zewnętrznego harnessa, użyj ACP/acpx, a nie natywnego runtime podagenta.

Podział prefiksów rodziny OpenAI opisują OpenAI i Dostawcy modeli. Kontrakt wsparcia runtime Codex opisuje Runtime harnessa Codex.

Własność runtime

Różne runtimy są właścicielami różnych części pętli.

Ten podział własności jest główną regułą projektową:

• Jeśli OpenClaw jest właścicielem powierzchni, OpenClaw może zapewnić normalne zachowanie hooków Plugin.
• Jeśli natywny runtime jest właścicielem powierzchni, OpenClaw potrzebuje zdarzeń runtime lub natywnych hooków.
• Jeśli natywny runtime jest właścicielem kanonicznego stanu wątku, OpenClaw powinien tworzyć kopię lustrzaną i projektować kontekst, a nie przepisywać nieobsługiwane internale.

Wybór runtime

OpenClaw wybiera osadzony runtime po rozstrzygnięciu dostawcy i modelu:

1. Wygrywa polityka runtime przypisana do modelu. Może znajdować się w skonfigurowanym wpisie modelu dostawcy albo w agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime.
2. Następna jest polityka runtime przypisana do dostawcy w models.providers.<provider>.agentRuntime.
3. W trybie auto zarejestrowane runtimy Plugin mogą zgłaszać obsługiwane pary dostawca/model.
4. Jeśli w trybie auto żaden runtime nie zgłosi tury, OpenClaw używa PI jako runtime kompatybilności. Użyj jawnego identyfikatora runtime, gdy uruchomienie musi być ścisłe.

Przypięcia runtime dla całej sesji i całego agenta są ignorowane. Obejmuje to OPENCLAW_AGENT_RUNTIME, stan sesji agentHarnessId/agentRuntimeOverride, agents.defaults.agentRuntime oraz agents.list[].agentRuntime. Uruchom openclaw doctor --fix, aby usunąć nieaktualną konfigurację runtime całego agenta i przekonwertować przestarzałe odwołania runtime do modeli tam, gdzie OpenClaw może zachować intencję.

Jawne runtimy Plugin dostawcy/modelu zawodzą w sposób zamknięty. Na przykład agentRuntime.id: "codex" przy dostawcy lub modelu oznacza Codex albo jasny błąd wyboru/runtime; nigdy nie jest po cichu kierowane z powrotem do PI.

Aliasy backendów CLI różnią się od identyfikatorów osadzonych harnessów. Preferowana forma Claude CLI to:

{  agents: {    defaults: {      model: "anthropic/claude-opus-4-7",      models: {        "anthropic/claude-opus-4-7": {          agentRuntime: { id: "claude-cli" },        },      },    },  },}

Przestarzałe odwołania, takie jak claude-cli/claude-opus-4-7, pozostają obsługiwane dla kompatybilności, ale nowa konfiguracja powinna zachowywać kanoniczną postać dostawca/model i umieszczać backend wykonawczy w polityce runtime dostawcy/modelu.

Tryb auto jest celowo konserwatywny dla większości dostawców. Modele agentów OpenAI są wyjątkiem: brak ustawionego runtime i auto rozstrzygają się do harnessa Codex. Jawna konfiguracja runtime PI pozostaje opcjonalną trasą kompatybilności dla tur agentów openai/*; po sparowaniu z wybranym profilem uwierzytelniania openai-codex OpenClaw kieruje PI wewnętrznie przez przestarzały transport uwierzytelniania Codex, zachowując publiczne odwołanie do modelu jako openai/*. Nieaktualne przypięcia sesji OpenAI PI są ignorowane przez wybór runtime i można je wyczyścić za pomocą openclaw doctor --fix.

Jeśli openclaw doctor ostrzega, że Plugin codex jest włączony, a w konfiguracji nadal pozostaje openai-codex/*, traktuj to jako przestarzały stan trasy. Uruchom openclaw doctor --fix, aby przepisać go na openai/* z runtime Codex.

Kontrakt kompatybilności

Gdy runtime nie jest PI, powinien dokumentować, które powierzchnie OpenClaw obsługuje. Użyj tej struktury dla dokumentacji runtime:

Kontrakt obsługi środowiska uruchomieniowego Codex jest udokumentowany w Środowisko uruchomieniowe harness Codex.

Etykiety stanu

Dane wyjściowe stanu mogą pokazywać zarówno etykiety Execution, jak i Runtime. Traktuj je jako diagnostykę, a nie nazwy dostawców.

• Referencja modelu, taka jak openai/gpt-5.5, wskazuje wybranego dostawcę/model.
• Identyfikator środowiska uruchomieniowego, taki jak codex, wskazuje, która pętla wykonuje turę.
• Etykieta kanału, taka jak Telegram lub Discord, wskazuje, gdzie odbywa się rozmowa.

Jeśli uruchomienie nadal pokazuje nieoczekiwane środowisko uruchomieniowe, najpierw sprawdź zasady środowiska uruchomieniowego wybranego dostawcy/modelu. Starsze przypięcia środowiska uruchomieniowego sesji nie decydują już o routingu.

Powiązane

• Harness Codex
• Środowisko uruchomieniowe harness Codex
• OpenAI
• Plugins harness agentów
• Pętla agenta
• Modele
• Status