Перейти до основного вмісту
Вбудований Plugin codex дає OpenClaw змогу виконувати вбудовані ходи агентів OpenAI через app-server Codex замість вбудованого harness OpenClaw. Використовуйте harness Codex, коли хочете, щоб Codex керував низькорівневим сеансом агента: нативним відновленням треду, нативним продовженням інструментів, нативним Compaction і виконанням app-server. OpenClaw і далі керує каналами чату, файлами сеансів, вибором моделі, динамічними інструментами OpenClaw, підтвердженнями, доставкою медіа та видимим дзеркалом транскрипту. Звичайне налаштування використовує канонічні посилання на моделі OpenAI, як-от openai/gpt-5.5. Не налаштовуйте застарілі посилання Codex GPT. Розміщуйте порядок автентифікації агента OpenAI у auth.order.openai; старі ідентифікатори профілів автентифікації Codex і старі записи порядку автентифікації Codex є застарілим станом, який виправляє openclaw doctor --fix. Коли жодна пісочниця OpenClaw не активна, OpenClaw запускає треди app-server Codex з увімкненим нативним режимом коду Codex, залишаючи code-mode-only вимкненим за замовчуванням. Це зберігає доступність нативного робочого простору й можливостей коду Codex, тоді як динамічні інструменти OpenClaw продовжують працювати через міст app-server item/tool/call. Активна ізоляція OpenClaw у пісочниці та обмежені політики інструментів повністю вимикають нативний режим коду, якщо ви не ввімкнете експериментальний шлях exec-server для пісочниці. Ця нативна для Codex функція окрема від режиму коду OpenClaw, який є опційним середовищем виконання QuickJS-WASI для загальних запусків OpenClaw з іншою формою введення exec. Для ширшого поділу між моделлю, провайдером і середовищем виконання почніть з середовищ виконання агентів. Коротко: openai/gpt-5.5 є посиланням на модель, codex є середовищем виконання, а Telegram, Discord, Slack або інший канал залишається поверхнею комунікації.

Вимоги

  • OpenClaw з доступним вбудованим Plugin codex.
  • Якщо ваша конфігурація використовує plugins.allow, додайте codex.
  • app-server Codex 0.125.0 або новіший. Вбудований Plugin за замовчуванням керує сумісним бінарним файлом app-server Codex, тому локальні команди codex у PATH не впливають на звичайний запуск harness.
  • Автентифікація Codex доступна через openclaw models auth login --provider openai, обліковий запис app-server у Codex home агента або явний профіль автентифікації Codex з API-ключем.
Щодо пріоритету автентифікації, ізоляції середовища, власних команд app-server, виявлення моделей і всіх полів конфігурації див. довідник harness Codex.

Швидкий старт

Більшість користувачів, які хочуть Codex в OpenClaw, потребують саме цього шляху: увійти з підпискою ChatGPT/Codex, увімкнути вбудований Plugin codex і використовувати канонічне посилання на модель openai/gpt-*. Увійдіть через Codex OAuth:
openclaw models auth login --provider openai
Увімкніть вбудований Plugin codex і виберіть модель агента OpenAI:
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}
Якщо ваша конфігурація використовує plugins.allow, додайте туди також codex:
{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
Перезапустіть Gateway після зміни конфігурації Plugin. Якщо наявний чат уже має сеанс, використайте /new або /reset перед тестуванням змін середовища виконання, щоб наступний хід визначив harness із поточної конфігурації.

Спільне використання тредів із Codex Desktop і CLI

Типове appServer.homeScope: "agent" ізолює кожного агента OpenClaw від нативного стану Codex оператора. Щоб власник міг попросити OpenClaw перевіряти й керувати тими самими нативними тредами, які показують Codex Desktop і Codex CLI, увімкніть використання користувацького Codex home:
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            homeScope: "user",
          },
        },
      },
    },
  },
}
Режим user-home доступний лише з локальним stdio-транспортом. Він використовує $CODEX_HOME, якщо змінну встановлено, і ~/.codex в іншому разі, включно з нативними автентифікацією Codex, конфігурацією, Plugin і сховищем тредів у цьому home. OpenClaw не впроваджує профіль автентифікації OpenClaw у цей app-server. Ходи власника отримують інструмент codex_threads. Він може перелічувати, шукати, читати, форкати, перейменовувати, архівувати й відновлювати нативні треди. Попросіть агента форкнути тред, коли хочете продовжити його в OpenClaw; форк приєднується до поточного сеансу OpenClaw і залишається видимим для інших нативних клієнтів Codex. Архівування потребує явного підтвердження, що тред закрито деінде. Не відновлюйте й не записуйте той самий тред одночасно з OpenClaw та іншого клієнта Codex. Codex координує активних авторів усередині одного процесу app-server, а не між незалежними процесами Desktop, CLI та OpenClaw. Форк створює окреме продовження і є безпечним шляхом співіснування.

Конфігурація

Конфігурація зі швидкого старту є мінімально життєздатною конфігурацією harness Codex. Задавайте параметри harness Codex у конфігурації OpenClaw, а CLI використовуйте лише для автентифікації Codex:
ПотребаЗадайтеДе
Увімкнути harnessplugins.entries.codex.enabled: trueКонфігурація OpenClaw
Зберегти дозволене встановлення PluginДодайте codex у plugins.allowКонфігурація OpenClaw
Спрямовувати ходи агентів OpenAI через Codexagents.defaults.model або agents.list[].model як openai/gpt-*Конфігурація агента OpenClaw
Увійти через ChatGPT/Codex OAuthopenclaw models auth login --provider openaiПрофіль автентифікації CLI
Додати резерв API-ключа для запусків CodexПрофіль API-ключа openai:*, указаний після автентифікації підписки в auth.order.openaiПрофіль автентифікації CLI + конфігурація OpenClaw
Закриватися з помилкою, коли Codex недоступнийagentRuntime.id: "codex" провайдера або моделіКонфігурація моделі/провайдера OpenClaw
Використовувати прямий трафік OpenAI APIagentRuntime.id: "openclaw" провайдера або моделі зі звичайною автентифікацією OpenAIКонфігурація моделі/провайдера OpenClaw
Налаштувати поведінку app-serverplugins.entries.codex.config.appServer.*Конфігурація Plugin Codex
Увімкнути нативні застосунки Plugin Codexplugins.entries.codex.config.codexPlugins.*Конфігурація Plugin Codex
Увімкнути Codex Computer Useplugins.entries.codex.config.computerUse.*Конфігурація Plugin Codex
Використовуйте посилання на моделі openai/gpt-* для ходів агентів OpenAI, що працюють через Codex. Надавайте перевагу auth.order.openai для порядку «спочатку підписка, потім резервний API-ключ». Наявні старі ідентифікатори профілів автентифікації Codex і старий порядок автентифікації Codex є застарілим станом лише для doctor; не записуйте нові застарілі посилання Codex GPT. Не задавайте compaction.model або compaction.provider для агентів, що працюють через Codex. Codex виконує Compaction через свій нативний стан треду app-server, тому OpenClaw ігнорує ці локальні перевизначення сумаризатора під час виконання, а openclaw doctor --fix видаляє їх, коли агент використовує Codex. Lossless і далі підтримується як рушій контексту для складання, приймання та супроводу навколо ходів Codex. Налаштовуйте його через plugins.slots.contextEngine: "lossless-claw" і plugins.entries.lossless-claw.config.summaryModel, а не через agents.defaults.compaction.provider. openclaw doctor --fix мігрує стару форму compaction.provider: "lossless-claw" у слот рушія контексту Lossless, коли Codex є активним середовищем виконання, але нативний Codex і далі володіє Compaction. Нативний harness app-server Codex підтримує рушії контексту, яким потрібне передpromptне складання. Загальні CLI-бекенди, включно з codex-cli, не надають такої можливості хоста. Для агентів, що працюють через Codex, /compact запускає нативний Compaction app-server Codex для прив’язаного треду. OpenClaw не чекає завершення, не накладає тайм-аут OpenClaw, не перезапускає спільний app-server і не перемикається на рушій контексту або публічний сумаризатор OpenAI як запасний варіант. Якщо нативна прив’язка треду Codex відсутня або застаріла, команда завершується закритою помилкою, щоб оператор бачив реальну межу середовища виконання, а не тихе перемикання бекендів Compaction.
{
  auth: {
    order: {
      openai: ["openai:user@example.com", "openai:api-key-backup"],
    },
  },
}
У цій формі обидва профілі й далі працюють через Codex для ходів агентів openai/gpt-*. API-ключ є лише резервом автентифікації, а не запитом на перемикання на OpenClaw або звичайний OpenAI Responses. Решта цієї сторінки охоплює типові варіанти, між якими користувачі мають вибирати: форму розгортання, маршрутизацію із закритою помилкою, політику guardian-підтверджень, нативні Plugin Codex і Computer Use. Повні списки параметрів, значення за замовчуванням, enum-значення, виявлення, ізоляцію середовища, тайм-аути й поля транспорту app-server див. у довіднику harness Codex.

Перевірка середовища виконання Codex

Використайте /status у чаті, де очікуєте Codex. Хід агента OpenAI, що працює через Codex, показує:
Runtime: OpenAI Codex
Потім перевірте стан app-server Codex:
/codex status
/codex models
/codex status повідомляє про підключення app-server, обліковий запис, ліміти швидкості, сервери MCP і Skills. /codex models перелічує live-каталог app-server Codex для harness і облікового запису. Якщо /status неочікуваний, див. Усунення неполадок.

Маршрутизація та вибір моделі

Тримайте посилання провайдерів і політику середовища виконання окремо:
  • Використовуйте openai/gpt-* для ходів агентів OpenAI через Codex.
  • Не використовуйте застарілі посилання Codex GPT у конфігурації. Запустіть openclaw doctor --fix, щоб виправити застарілі посилання та несвіжі прив’язки маршрутів сеансів.
  • agentRuntime.id: "codex" необов’язковий для звичайного автоматичного режиму OpenAI, але корисний, коли розгортання має завершуватися закритою помилкою, якщо Codex недоступний.
  • agentRuntime.id: "openclaw" явно переводить провайдера або модель у вбудоване середовище виконання OpenClaw, коли це зроблено навмисно.
  • /codex ... керує нативними розмовами app-server Codex із чату.
  • ACP/acpx є окремим шляхом зовнішнього harness. Використовуйте його лише тоді, коли користувач просить ACP/acpx або адаптер зовнішнього harness.
Типова маршрутизація команд:
Намір користувачаВикористовуйте
Прикріпити поточний чат/codex bind [--cwd <path>]
Відновити наявну гілку Codex/codex resume <thread-id>
Перелічити або відфільтрувати гілки Codex/codex threads [filter]
Перелічити нативні Plugin Codex/codex plugins list
Увімкнути або вимкнути налаштований нативний Plugin Codex/codex plugins enable <name>, /codex plugins disable <name>
Прикріпити наявний сеанс Codex CLI на спареному вузлі/codex sessions --host <node> [filter], потім /codex resume <session-id> --host <node> --bind here
Надіслати лише відгук Codex/codex diagnostics [note]
Запустити завдання ACP/acpxКоманди сеансу ACP/acpx, не /codex
Сценарій використанняНалаштуйтеПеревіртеПримітки
Підписка ChatGPT/Codex із нативним середовищем виконання Codexopenai/gpt-* плюс увімкнений Plugin codex/status показує Runtime: OpenAI CodexРекомендований шлях
Завершуватися помилкою, якщо Codex недоступнийПостачальник або модель agentRuntime.id: "codex"Хід завершується помилкою замість вбудованого резервного варіантаВикористовуйте для розгортань лише з Codex
Спрямовувати трафік прямого ключа OpenAI API через OpenClawПостачальник або модель agentRuntime.id: "openclaw" і звичайна автентифікація OpenAI/status показує середовище виконання OpenClawВикористовуйте лише коли OpenClaw є навмисним вибором
Застаріла конфігураціязастарілі посилання Codex GPTopenclaw doctor --fix переписує їїНе пишіть нову конфігурацію таким способом
Адаптер ACP/acpx CodexACP sessions_spawn({ runtime: "acp" })Стан завдання/сеансу ACPОкремо від нативного обв’язування Codex
agents.defaults.imageModel дотримується того самого поділу за префіксом. Використовуйте openai/gpt-* для звичайного маршруту OpenAI і codex/gpt-* лише тоді, коли розуміння зображень має виконуватися через обмежений хід сервера застосунку Codex. Не використовуйте застарілі посилання Codex GPT; doctor переписує цей застарілий префікс на openai/gpt-*.

Шаблони розгортання

Базове розгортання Codex

Використовуйте конфігурацію швидкого старту, коли всі ходи агента OpenAI мають типово використовувати Codex.
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}

Розгортання зі змішаними постачальниками

Ця форма залишає Claude типовим агентом і додає іменований агент Codex:
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-6",
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
      },
    ],
  },
}
З цією конфігурацією агент main використовує свій звичайний шлях постачальника, а агент codex використовує сервер застосунку Codex.

Розгортання Codex із завершенням помилкою

Для ходів агента OpenAI openai/gpt-* вже розв’язується в Codex, коли доступний вбудований Plugin. Додайте явну політику середовища виконання, коли потрібне письмове правило завершення помилкою:
{
  models: {
    providers: {
      openai: {
        agentRuntime: {
          id: "codex",
        },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
Коли Codex примусово задано, OpenClaw завершується рано з помилкою, якщо Plugin Codex вимкнено, сервер застосунку надто старий або сервер застосунку не може запуститися.

Політика сервера застосунку

Типово Plugin запускає керований OpenClaw бінарний файл Codex локально з транспортом stdio. Встановлюйте appServer.command лише тоді, коли навмисно хочете запускати інший виконуваний файл. Використовуйте транспорт WebSocket лише тоді, коли сервер застосунку вже працює в іншому місці:
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
          },
        },
      },
    },
  },
}
Локальні сеанси сервера застосунку stdio типово мають довірену позицію локального оператора: approvalPolicy: "never", approvalsReviewer: "user" і sandbox: "danger-full-access". Якщо локальні вимоги Codex не дозволяють цю неявну позицію YOLO, OpenClaw натомість вибирає дозволені дозволи guardian. Коли для сеансу активна пісочниця OpenClaw, OpenClaw вимикає нативний Code Mode Codex, сервери MCP користувача та виконання Plugin із підтримкою застосунку для цього ходу замість покладання на пісочницю на боці хоста Codex. Доступ до оболонки надається через динамічні інструменти на основі пісочниці OpenClaw, як-от sandbox_exec і sandbox_process, коли доступні звичайні інструменти exec/process. Використовуйте нормалізований режим exec OpenClaw, коли хочете нативний автоогляд Codex перед виходами з пісочниці або додатковими дозволами:
{
  tools: {
    exec: {
      mode: "auto",
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
Для сеансів сервера застосунку Codex OpenClaw відображає tools.exec.mode: "auto" на схвалення, переглянуті Codex Guardian, зазвичай approvalPolicy: "on-request", approvalsReviewer: "auto_review" і sandbox: "workspace-write", коли локальні вимоги дозволяють ці значення. У tools.exec.mode: "auto" OpenClaw не зберігає застарілі небезпечні перевизначення Codex approvalPolicy: "never" або sandbox: "danger-full-access"; використовуйте tools.exec.mode: "full" для навмисної позиції Codex без схвалень. Застарілий пресет plugins.entries.codex.config.appServer.mode: "guardian" досі працює, але tools.exec.mode: "auto" є нормалізованою поверхнею OpenClaw. Для порівняння на рівні режимів із схваленнями host exec і дозволами ACPX див. Режими дозволів. Для кожного поля сервера застосунку, порядку автентифікації, ізоляції середовища, виявлення та поведінки тайм-аутів див. Довідник обв’язування Codex.

Команди та діагностика

Вбудований Plugin реєструє /codex як slash-команду в будь-якому каналі, що підтримує текстові команди OpenClaw. Нативне виконання та керування потребують власника або клієнта Gateway operator.admin. Це включає прив’язування або відновлення гілок, надсилання або зупинення ходів, зміну моделі, fast-mode або стану дозволів, ущільнення або перегляд, а також від’єднання прив’язки. Інші авторизовані відправники зберігають команди лише для читання: стан, довідку, обліковий запис, модель, гілку, сервер MCP, skill і перевірку прив’язки. Поширені форми:
  • /codex status перевіряє підключення до сервера застосунку, моделі, обліковий запис, ліміти частоти, сервери MCP і skills.
  • /codex models перелічує живі моделі сервера застосунку Codex.
  • /codex threads [filter] перелічує нещодавні гілки сервера застосунку Codex.
  • /codex resume <thread-id> прикріплює поточний сеанс OpenClaw до наявної гілки Codex.
  • /codex compact просить сервер застосунку Codex ущільнити прикріплену гілку.
  • /codex review запускає нативний перегляд Codex для прикріпленої гілки.
  • /codex diagnostics [note] запитує перед надсиланням відгуку Codex для прикріпленої гілки.
  • /codex account показує стан облікового запису та лімітів частоти.
  • /codex mcp перелічує стан серверів MCP сервера застосунку Codex.
  • /codex skills перелічує skills сервера застосунку Codex.
Для більшості звітів підтримки починайте з /diagnostics [note] у розмові, де сталася помилка. Це створює один діагностичний звіт Gateway і, для сеансів обв’язування Codex, запитує схвалення на надсилання відповідного пакета відгуку Codex. Див. Експорт діагностики щодо моделі приватності та поведінки групового чату. Використовуйте /codex diagnostics [note] лише тоді, коли вам потрібне саме завантаження відгуку Codex для поточної прикріпленої гілки без повного діагностичного пакета Gateway.

Локальна перевірка гілок Codex

Найшвидший спосіб перевірити невдалий запуск Codex часто полягає в тому, щоб відкрити нативну гілку Codex напряму:
codex resume <thread-id>
Отримайте ідентифікатор гілки з завершеної відповіді /diagnostics, /codex binding або /codex threads [filter]. Щодо механіки завантаження та діагностичних меж на рівні середовища виконання див. Середовище виконання обв’язування Codex. У типовому домашньому каталозі на рівні агента автентифікація вибирається в такому порядку:
  1. Упорядковані профілі автентифікації OpenAI для агента, бажано під auth.order.openai. Запустіть openclaw doctor --fix, щоб мігрувати старі застарілі ідентифікатори профілів автентифікації Codex і застарілий порядок автентифікації Codex.
  2. Наявний обліковий запис сервера застосунку в домашньому каталозі Codex цього агента.
  3. Лише для локальних запусків сервера застосунку stdio: CODEX_API_KEY, потім OPENAI_API_KEY, коли обліковий запис сервера застосунку відсутній, а автентифікація OpenAI все ще потрібна.
Коли OpenClaw бачить профіль автентифікації Codex у стилі підписки ChatGPT, він вилучає CODEX_API_KEY і OPENAI_API_KEY із породженого дочірнього процесу Codex. Це зберігає ключі API рівня Gateway доступними для embeddings або прямих моделей OpenAI без випадкового виставлення рахунків за нативні ходи сервера застосунку Codex через API. Явні профілі ключів API Codex і локальний резервний варіант ключа середовища stdio використовують вхід сервера застосунку замість успадкованого env дочірнього процесу. Підключення до сервера застосунку WebSocket не отримують резервний ключ API середовища Gateway; використовуйте явний профіль автентифікації або власний обліковий запис віддаленого сервера застосунку. Коли налаштовані нативні Plugin Codex, OpenClaw встановлює або оновлює ці Plugin через підключений сервер застосунку перед наданням застосунків, що належать Plugin, гілці Codex. app/list залишається джерелом істини для ідентифікаторів застосунків, доступності та метаданих, але OpenClaw володіє рішенням увімкнення на рівні гілки: якщо політика дозволяє перелічений доступний застосунок, OpenClaw надсилає thread/start.config.apps[appId].enabled = true, навіть коли app/list наразі повідомляє, що цей застосунок вимкнено. Цей шлях не вигадує встановлення застосунку для невідомих ідентифікаторів; OpenClaw лише активує marketplace Plugin за допомогою plugin/install, а потім оновлює інвентар. Якщо профіль підписки досягає ліміту використання Codex, OpenClaw записує час скидання, коли Codex повідомляє його, і пробує наступний упорядкований профіль автентифікації для того самого запуску Codex. Коли час скидання минає, профіль підписки знову стає придатним без зміни вибраної моделі openai/gpt-* або середовища виконання Codex. Для локальних запусків app-server через stdio OpenClaw задає CODEX_HOME як каталог окремого агента, щоб конфігурація Codex, файли auth/account, кеш/дані Plugin і нативний стан thread за замовчуванням не читали й не записували особистий ~/.codex оператора. OpenClaw зберігає звичайний процесний HOME; підпроцеси, запущені Codex, усе ще можуть знаходити конфігурацію й токени домашнього каталогу користувача, а Codex може виявляти спільні записи $HOME/.agents/skills і $HOME/.agents/plugins/marketplace.json. З appServer.homeScope: "user" OpenClaw натомість використовує нативний користувацький домашній каталог Codex і його наявний account без ін’єкції auth профілю OpenClaw. Якщо розгортанню потрібна додаткова ізоляція середовища, додайте ці змінні до appServer.clearEnv:
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}
appServer.clearEnv впливає лише на породжений дочірній процес Codex app-server. Під час нормалізації локального запуску OpenClaw вилучає CODEX_HOME і HOME із цього списку: CODEX_HOME лишається спрямованим на вибрану область агента або користувача, а HOME лишається успадкованим, щоб підпроцеси могли використовувати звичайний стан домашнього каталогу користувача. Динамічні інструменти Codex за замовчуванням завантажуються як searchable. OpenClaw не відкриває динамічні інструменти, які дублюють нативні операції Codex із робочою областю: read, write, edit, apply_patch, exec, process і update_plan. Більшість решти інтеграційних інструментів OpenClaw, як-от обмін повідомленнями, медіа, Cron, браузер, вузли, Gateway і heartbeat_respond, доступні через пошук інструментів Codex у просторі імен openclaw, що зменшує початковий контекст моделі. Вебпошук за замовчуванням використовує розміщений інструмент Codex web_search, коли пошук увімкнено й не вибрано керованого провайдера. Нативний розміщений пошук і керований динамічний інструмент OpenClaw web_search взаємно виключають одне одного, щоб керований пошук не міг обійти нативні обмеження доменів. OpenClaw використовує керований інструмент, коли розміщений пошук недоступний, явно вимкнений або замінений вибраним керованим провайдером. OpenClaw тримає окреме розширення Codex web.run вимкненим, бо production-трафік app-server відхиляє його користувацький простір імен web. tools.web.search.enabled: false вимикає обидва шляхи, як і запуски лише LLM із вимкненими інструментами. Codex трактує "cached" як уподобання й розв’язує його в живий зовнішній доступ для необмежених ходів app-server. Автоматичний керований fallback завершується закрито, коли задано нативні allowedDomains, щоб список дозволених доменів не можна було обійти. Постійні зміни ефективної політики пошуку ротує прив’язаний thread Codex перед наступним ходом. Тимчасові обмеження на один хід використовують тимчасовий обмежений thread і зберігають наявну прив’язку для подальшого відновлення. sessions_yield і відповіді джерела лише через інструмент повідомлень лишаються прямими, бо це контракти керування ходом. sessions_spawn лишається searchable, щоб нативний spawn_agent Codex залишався основною поверхнею підагентів Codex, тоді як явне делегування OpenClaw або ACP і далі доступне через простір імен динамічних інструментів openclaw. Інструкції співпраці Heartbeat кажуть Codex шукати heartbeat_respond перед завершенням ходу Heartbeat, коли інструмент ще не завантажено. Встановлюйте codexDynamicToolsLoading: "direct" лише під час підключення до кастомного Codex app-server, який не може шукати відкладені динамічні інструменти, або під час налагодження повного payload інструментів. Підтримувані поля Plugin Codex верхнього рівня:
ПолеТипове значенняЗначення
codexDynamicToolsLoading"searchable"Використовуйте "direct", щоб помістити динамічні інструменти OpenClaw безпосередньо в початковий контекст інструментів Codex.
codexDynamicToolsExclude[]Додаткові назви динамічних інструментів OpenClaw, які слід пропустити в ходах Codex app-server.
codexPluginsвимкненоНативна підтримка Plugin/app Codex для мігрованих curated plugins, установлених із вихідного коду.
Підтримувані поля appServer:
ПолеТипове значенняЗначення
transport"stdio""stdio" запускає Codex; "websocket" підключається до url.
homeScope"agent""agent" ізолює стан Codex для кожного агента OpenClaw. "user" спільно використовує нативний $CODEX_HOME або ~/.codex, використовує нативну автентифікацію та вмикає керування потоками лише власником. Область користувача потребує stdio.
commandкерований двійковий файл CodexВиконуваний файл для транспорту stdio. Не задавайте, щоб використовувати керований двійковий файл; задавайте лише для явного перевизначення.
args["app-server", "--listen", "stdio://"]Аргументи для транспорту stdio.
urlне заданоURL WebSocket app-server.
authTokenне заданоBearer-токен для транспорту WebSocket. Приймає літеральний рядок або SecretInput, наприклад ${CODEX_APP_SERVER_TOKEN}.
headers{}Додаткові заголовки WebSocket. Значення заголовків приймають літеральні рядки або значення SecretInput, наприклад x-codex-client-session-token: "${CODEX_CLIENT_SESSION_TOKEN}".
clearEnv[]Додаткові назви змінних середовища, які видаляються із запущеного процесу stdio app-server після того, як OpenClaw сформує успадковане середовище. OpenClaw зберігає вибраний CODEX_HOME і успадкований HOME для локальних запусків.
codeModeOnlyfalseУвімкнути поверхню інструментів Codex лише для режиму коду. Динамічні інструменти OpenClaw залишаються зареєстрованими в Codex, тому вкладені виклики tools.* повертаються через міст app-server item/tool/call.
remoteWorkspaceRootне заданоКорінь робочої області віддаленого Codex app-server. Коли задано, OpenClaw виводить локальний корінь робочої області з розв’язаної робочої області OpenClaw, зберігає поточний суфікс cwd під цим віддаленим коренем і надсилає до Codex лише кінцевий cwd app-server. Якщо cwd перебуває поза розв’язаним коренем робочої області OpenClaw, OpenClaw fail-closed замість надсилання gateway-локального шляху до віддаленого app-server.
requestTimeoutMs60000Тайм-аут для викликів площини керування app-server.
turnCompletionIdleTimeoutMs60000Тиха пауза після того, як Codex приймає хід, або після запиту app-server в межах ходу, поки OpenClaw очікує на turn/completed.
postToolRawAssistantCompletionIdleTimeoutMs300000Запобіжник простою завершення та прогресу, який використовується після передавання інструменту, завершення нативного інструменту, прогресу сирого асистента після інструменту, завершення сирого reasoning або прогресу reasoning, поки OpenClaw очікує на turn/completed. Використовуйте це для довірених або важких навантажень, де синтез після інструменту може обґрунтовано залишатися тихим довше, ніж фінальний бюджет випуску асистента.
mode"yolo", якщо локальні вимоги Codex не забороняють YOLOПресет для виконання YOLO або виконання з перевіркою guardian. Локальні вимоги stdio, які пропускають danger-full-access, схвалення never або рецензента user, роблять неявним типовим значенням guardian.
approvalPolicy"never" або дозволена політика схвалення guardianНативна політика схвалення Codex, що надсилається під час запуску/відновлення потоку/ходу. Типові значення guardian надають перевагу "on-request", коли це дозволено.
sandbox"danger-full-access" або дозволена пісочниця guardianНативний режим пісочниці Codex, що надсилається під час запуску/відновлення потоку. Типові значення guardian надають перевагу "workspace-write", коли це дозволено, інакше "read-only". Коли пісочниця OpenClaw активна, ходи danger-full-access використовують Codex workspace-write з мережевим доступом, виведеним із налаштування вихідного трафіку пісочниці OpenClaw.
approvalsReviewer"user" або дозволений рецензент guardianВикористовуйте "auto_review", щоб дозволити Codex перевіряти нативні запити схвалення, коли це дозволено; інакше guardian_subagent або user. guardian_subagent залишається застарілим псевдонімом.
serviceTierне заданоНеобов’язковий рівень сервісу Codex app-server. "priority" вмикає маршрутизацію fast-mode, "flex" запитує flex-обробку, null очищає перевизначення, а застаріле "fast" приймається як "priority".
networkProxyвимкненоУвімкнути мережу профілю дозволів Codex для команд app-server. OpenClaw визначає вибрану конфігурацію permissions.<profile>.network і вибирає її через default_permissions замість надсилання sandbox.
experimental.sandboxExecServerfalseПопереднє opt-in, яке реєструє середовище Codex на основі пісочниці OpenClaw у Codex app-server 0.132.0 або новішому, щоб нативне виконання Codex могло працювати всередині активної пісочниці OpenClaw.
appServer.networkProxy є явним, бо змінює контракт пісочниці Codex. Коли його ввімкнено, OpenClaw також задає features.network_proxy.enabled і default_permissions у конфігурації потоку Codex, щоб згенерований профіль дозволів міг запустити керовану мережу Codex. Типово OpenClaw генерує стійку до колізій назву профілю openclaw-network-<fingerprint> з тіла профілю; використовуйте profileName лише тоді, коли потрібна стабільна локальна назва.
export default {
  plugins: {
    entries: {
      codex: {
        config: {
          appServer: {
            sandbox: "workspace-write",
            networkProxy: {
              enabled: true,
              domains: {
                "api.openai.com": "allow",
                "blocked.example.com": "deny",
              },
              unixSockets: {
                "/tmp/proxy.sock": "allow",
                "/tmp/blocked.sock": "none",
              },
              allowUpstreamProxy: true,
              proxyUrl: "http://127.0.0.1:3128",
            },
          },
        },
      },
    },
  },
};
Якщо звичайне середовище виконання сервера застосунку було б danger-full-access, увімкнення networkProxy використовує доступ до файлової системи в стилі робочої області для згенерованого профілю дозволів. Кероване Codex мережеве примусове застосування є ізольованою мережею, тому профіль повного доступу не захищав би вихідний трафік. Записи доменів використовують allow або deny; записи Unix-сокетів використовують значення Codex allow або none. Динамічні виклики інструментів, якими володіє OpenClaw, обмежуються незалежно від appServer.requestTimeoutMs: запити Codex item/tool/call типово використовують 90-секундний watchdog OpenClaw. Додатний аргумент timeoutMs для окремого виклику подовжує або скорочує бюджет саме цього інструмента. Інструмент image_generate використовує agents.defaults.imageGenerationModel.timeoutMs, коли виклик інструмента не надає власний timeout, або інакше 120-секундне типове значення для генерації зображень. Інструмент розуміння медіа image використовує tools.media.image.timeoutSeconds або своє 60-секундне типове значення для медіа. Для розуміння зображень цей timeout застосовується до самого запиту й не зменшується попередньою підготовчою роботою. Бюджети динамічних інструментів обмежені 600000 мс. У разі timeout OpenClaw перериває сигнал інструмента там, де це підтримується, і повертає Codex відповідь про невдалий динамічний інструмент, щоб хід міг продовжитися, а не залишати сеанс у processing. Цей watchdog є зовнішнім бюджетом динамічного item/tool/call; специфічні для провайдера timeouts запитів виконуються всередині цього виклику й зберігають власну семантику timeout. Після того як Codex приймає хід, і після того як OpenClaw відповідає на прив’язаний до ходу запит сервера застосунку, harness очікує, що Codex зробить поступ у поточному ході й зрештою завершить нативний хід через turn/completed. Якщо сервер застосунку мовчить протягом appServer.turnCompletionIdleTimeoutMs, OpenClaw best-effort перериває хід Codex, записує діагностичний timeout і звільняє смугу сеансу OpenClaw, щоб наступні повідомлення чату не ставали в чергу за застарілим нативним ходом. Більшість нетермінальних сповіщень для того самого ходу вимикають цей короткий watchdog, бо Codex довів, що хід усе ще активний. Передавання інструментам використовує довший post-tool бюджет простою: після того як OpenClaw повертає відповідь item/tool/call, після завершення нативних елементів інструментів, як-от commandExecution, після сирих завершень custom_tool_call_output, а також після post-tool сирого прогресу асистента, завершень reasoning або прогресу reasoning. Запобіжник використовує appServer.postToolRawAssistantCompletionIdleTimeoutMs, коли його налаштовано, і типово дорівнює п’яти хвилинам. Той самий post-tool бюджет також подовжує watchdog прогресу для тихого вікна синтезу до того, як Codex випустить наступну подію поточного ходу. Глобальні сповіщення сервера застосунку, як-от оновлення rate-limit, не скидають прогрес простою ходу. Завершення reasoning, завершення commentary agentMessage і pre-tool сирий reasoning або прогрес асистента можуть супроводжуватися автоматичною фінальною відповіддю, тому вони використовують post-progress запобіжник відповіді замість негайного звільнення смуги сеансу. Лише фінальні/не-commentary завершені елементи agentMessage і pre-tool сирі завершення асистента озброюють звільнення assistant-output: якщо Codex потім замовкає без turn/completed, OpenClaw best-effort перериває нативний хід і звільняє смугу сеансу. Якщо інший watch ходу виграє гонку за це звільнення, OpenClaw усе одно приймає завершений фінальний елемент асистента, щойно жоден нативний запит, елемент або завершення динамічного інструмента не залишається активним і звільнення assistant-output усе ще належить останньому завершеному елементу, без пізнішого завершення елемента. Це може зберегти фінальну відповідь після завершеної роботи інструмента без повторного відтворення ходу. Часткові дельти асистента, застарілі попередні відповіді й порожні пізніші завершення не підходять. Безпечні для replay збої stdio сервера застосунку, зокрема timeouts простою завершення ходу без доказів асистента, інструмента, активного елемента або побічного ефекту, повторюються один раз у свіжій спробі сервера застосунку. Небезпечні timeouts усе одно виводять застряглого клієнта сервера застосунку з обігу та звільняють смугу сеансу OpenClaw. Вони також очищають застарілу прив’язку нативного треду замість автоматичного повторного відтворення. Timeouts completion-watch показують специфічний для Codex текст timeout: безпечні для replay випадки кажуть, що відповідь може бути неповною, тоді як небезпечні випадки просять користувача перевірити поточний стан перед повторною спробою. Публічна діагностика timeout містить структурні поля, як-от останній метод сповіщення сервера застосунку, id/type/role сирого елемента відповіді асистента, кількість активних запитів/елементів і стан озброєного watch. Коли останнім сповіщенням є сирий елемент відповіді асистента, вона також містить обмежений попередній перегляд тексту асистента. Вона не містить сирий prompt або вміст інструментів. Перевизначення середовища залишаються доступними для локального тестування:
  • OPENCLAW_CODEX_APP_SERVER_BIN
  • OPENCLAW_CODEX_APP_SERVER_ARGS
  • OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
  • OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
  • OPENCLAW_CODEX_APP_SERVER_SANDBOX
OPENCLAW_CODEX_APP_SERVER_BIN обходить керований binary, коли appServer.command не задано. OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 було вилучено. Натомість використовуйте plugins.entries.codex.config.appServer.mode: "guardian" або OPENCLAW_CODEX_APP_SERVER_MODE=guardian для одноразового локального тестування. Config є бажаним для повторюваних розгортань, бо він тримає поведінку плагіна в тому самому перевіреному файлі, що й решту налаштування harness Codex.

Нативні плагіни Codex

Підтримка нативних плагінів Codex використовує власні можливості застосунків і плагінів сервера застосунку Codex у тому самому треді Codex, що й хід harness OpenClaw. OpenClaw не перетворює плагіни Codex на синтетичні динамічні інструменти OpenClaw codex_plugin_*. codexPlugins впливає лише на сеанси, які вибирають нативний harness Codex. Він не впливає на запуски вбудованого harness, звичайні запуски провайдера OpenAI, прив’язки розмов ACP або інші harness. Мінімальний мігрований config:
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
              },
            },
          },
        },
      },
    },
  },
}
Config застосунку треду обчислюється, коли OpenClaw встановлює сеанс harness Codex або замінює застарілу прив’язку треду Codex. Він не переобчислюється на кожному ході. Після зміни codexPlugins використайте /new, /reset або перезапустіть gateway, щоб майбутні сеанси harness Codex стартували з оновленим набором застосунків. Про право на міграцію, інвентар застосунків, політику руйнівних дій, elicitations і діагностику нативних плагінів див. Нативні плагіни Codex. Доступ до застосунків і плагінів на боці OpenAI контролюється обліковим записом Codex, у який виконано вхід, а для робочих областей Business і Enterprise/Edu — елементами керування застосунками робочої області. Див. Використання Codex із вашим планом ChatGPT для огляду облікового запису OpenAI і керування робочою областю.

Computer Use

Computer Use описано у власному посібнику з налаштування: Codex Computer Use. Коротко: OpenClaw не постачає в собі застосунок керування desktop і не виконує desktop-дії сам. Він готує сервер застосунку Codex, перевіряє, що MCP-сервер computer-use доступний, а потім дозволяє Codex володіти нативними викликами MCP-інструментів під час ходів у режимі Codex.

Межі середовища виконання

Harness Codex змінює лише низькорівневий вбудований виконавець агента.
  • Динамічні інструменти OpenClaw підтримуються. Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається в шляху виконання.
  • Codex-native shell, patch, MCP і нативні інструменти застосунків належать Codex. OpenClaw може спостерігати або блокувати вибрані нативні події через підтримуваний relay, але він не переписує аргументи нативних інструментів.
  • Codex володіє нативним Compaction. OpenClaw зберігає дзеркало transcript для історії каналу, пошуку, /new, /reset і майбутнього перемикання моделі або harness, але він не замінює compaction Codex summarizer OpenClaw або context-engine.
  • Генерація медіа, розуміння медіа, TTS, approvals і вивід messaging-tool продовжують проходити через відповідні налаштування провайдера/моделі OpenClaw.
  • tool_result_persist застосовується до результатів інструментів transcript, якими володіє OpenClaw, а не до нативних записів результатів інструментів Codex.
Про hook layers, підтримувані поверхні V1, нативну обробку дозволів, скеровування черги, механіку вивантаження feedback Codex і подробиці compaction див. Середовище виконання harness Codex.

Усунення несправностей

Codex не з’являється як звичайний провайдер /model: це очікувано для нових configs. Виберіть модель openai/gpt-*, увімкніть plugins.entries.codex.enabled і перевірте, чи plugins.allow не виключає codex. OpenClaw використовує вбудований harness замість Codex: переконайтеся, що model ref є openai/gpt-* на офіційному провайдері OpenAI і що плагін Codex встановлено й увімкнено. Якщо під час тестування потрібен строгий доказ, задайте для провайдера або моделі agentRuntime.id: "codex". Примусове середовище виконання Codex завершується помилкою замість fallback до OpenClaw. Середовище виконання OpenAI Codex повертається до шляху API-key: зберіть редагований фрагмент gateway, який показує модель, середовище виконання, вибраного провайдера і збій. Попросіть зачеплених співробітників запустити цю read-only команду на своєму хості OpenClaw:
(
  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'

  if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then
    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true
  else
    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \
      | grep -E -i "$pattern" || true
  fi
) | sed -E \
    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \
    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \
    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \
    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \
    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \
    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \
  | tail -200
Корисні фрагменти зазвичай містять openai/gpt-5.5 або openai/gpt-5.4, Runtime: OpenAI Codex, agentRuntime.id або harnessRuntime, candidateProvider: "openai" і результат 401, Incorrect API key або No API key. Виправлений запуск має показувати шлях OpenAI OAuth замість звичайної помилки OpenAI API-key. Config застарілих refs моделей Codex залишився: запустіть openclaw doctor --fix. Doctor переписує застарілі refs моделей на openai/*, видаляє застарілі session і whole-agent runtime pins і зберігає наявні перевизначення auth-profile. Сервер застосунку відхилено: використовуйте сервер застосунку Codex 0.125.0 або новіший. Prereleases тієї самої версії або версії з build-suffix, як-от 0.125.0-alpha.2 або 0.125.0+custom, відхиляються, бо OpenClaw перевіряє стабільну нижню межу протоколу 0.125.0. /codex status не може підключитися: перевірте, що bundled плагін codex увімкнено, що plugins.allow містить його, коли allowlist налаштовано, і що будь-які власні appServer.command, url, authToken або headers є чинними. Виявлення моделей повільне: зменште plugins.entries.codex.config.discovery.timeoutMs або вимкніть discovery. Див. Довідник harness Codex. WebSocket-транспорт одразу завершується з помилкою: перевірте appServer.url, authToken, headers і що віддалений сервер застосунку говорить тією самою версією протоколу сервера застосунку Codex. Власну оболонку або інструменти patch заблоковано з Native hook relay unavailable: потік Codex досі намагається використати ідентифікатор власного ретранслятора хуків, який OpenClaw більше не має зареєстрованим. Це проблема транспорту власного хука Codex, а не збій бекенда ACP, провайдера, GitHub або команди оболонки. Почніть нову сесію в ураженому чаті за допомогою /new або /reset, а потім повторіть нешкідливу команду. Якщо це спрацює один раз, але наступний виклик власного інструмента знову завершиться помилкою, розглядайте /new лише як тимчасовий обхідний шлях: скопіюйте запит у нову сесію після перезапуску app-server Codex або OpenClaw Gateway, щоб старі потоки було відкинуто, а реєстрації власних хуків створено повторно. Модель не Codex використовує вбудований harness: це очікувано, якщо політика runtime провайдера або моделі не спрямовує її до іншого harness. Прості посилання на провайдерів не OpenAI залишаються на своєму звичайному шляху провайдера в режимі auto. Computer Use встановлено, але інструменти не запускаються: перевірте /codex computer-use status з нової сесії. Якщо інструмент повідомляє Native hook relay unavailable, скористайтеся відновленням власного ретранслятора хуків вище. Див. Codex Computer Use.

Пов’язане