Довідник з обв’язки Codex

У цьому довіднику описано детальну конфігурацію для вбудованого плагіна codex. Для налаштування й рішень щодо маршрутизації почніть із Codex harness.

Поверхня конфігурації Plugin

Усі налаштування Codex harness розташовані в plugins.entries.codex.config.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
          appServer: {
            mode: "guardian",
          },
        },
      },
    },
  },
}

Підтримувані поля верхнього рівня:

Поле	Типове значення	Значення
`discovery`	увімкнено	Налаштування виявлення моделей для Codex app-server `model/list`.
`appServer`	керований stdio app-server	Налаштування транспорту, команди, автентифікації, схвалення, sandbox і тайм-аутів.
`codexDynamicToolsLoading`	`"searchable"`	Використайте `"direct"`, щоб розмістити динамічні інструменти OpenClaw безпосередньо в початковому контексті інструментів Codex.
`codexDynamicToolsExclude`	`[]`	Додаткові назви динамічних інструментів OpenClaw, які потрібно пропускати в ходах Codex app-server.
`codexPlugins`	вимкнено	Нативна підтримка плагінів/app Codex для мігрованих curated plugins, установлених із вихідного коду. Див. Нативні плагіни Codex.
`computerUse`	вимкнено	Налаштування Codex Computer Use. Див. Codex Computer Use.

Транспорт app-server

За замовчуванням OpenClaw запускає керований бінарний файл Codex, що постачається з вбудованим плагіном:

codex app-server --listen stdio://

Це прив’язує версію app-server до вбудованого плагіна codex, а не до будь-якого окремого Codex CLI, який може бути встановлений локально. Установлюйте appServer.command лише тоді, коли свідомо хочете запускати інший виконуваний файл. Для app-server, який уже запущений, використовуйте транспорт WebSocket:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}

Підтримувані поля appServer:

Поле	Типове значення	Значення
`transport`	`"stdio"`	`"stdio"` породжує Codex; `"websocket"` підключається до `url`.
`command`	керований бінарний файл Codex	Виконуваний файл для транспорту stdio. Залиште невстановленим, щоб використовувати керований бінарний файл.
`args`	`["app-server", "--listen", "stdio://"]`	Аргументи для транспорту stdio.
`url`	не встановлено	URL WebSocket app-server.
`authToken`	не встановлено	Bearer token для транспорту WebSocket.
`headers`	`{}`	Додаткові заголовки WebSocket.
`clearEnv`	`[]`	Додаткові назви змінних середовища, які видаляються з породженого процесу stdio app-server після того, як OpenClaw сформує успадковане середовище.
`requestTimeoutMs`	`60000`	Тайм-аут для викликів площини керування app-server.
`turnCompletionIdleTimeoutMs`	`60000`	Тихе вікно після запиту app-server у межах ходу, поки OpenClaw очікує на `turn/completed`.
`mode`	`"yolo"`, якщо локальні вимоги Codex не забороняють YOLO	Пресет для виконання YOLO або виконання з перевіркою guardian.
`approvalPolicy`	`"never"` або дозволена політика схвалення guardian	Нативна політика схвалення Codex, надіслана під час запуску thread, resume і turn.
`sandbox`	`"danger-full-access"` або дозволений sandbox guardian	Нативний режим sandbox Codex, надісланий під час запуску й resume thread.
`approvalsReviewer`	`"user"` або дозволений рецензент guardian	Використайте `"auto_review"`, щоб дозволити Codex переглядати нативні запити схвалення, коли це дозволено.
`defaultWorkspaceDir`	поточний каталог процесу	Робочий простір, який використовується `/codex bind`, коли `--cwd` пропущено.
`serviceTier`	не встановлено	Необов’язковий рівень сервісу Codex app-server. `"priority"` вмикає маршрутизацію fast-mode, `"flex"` запитує flex-обробку, а `null` очищає перевизначення. Застаріле `"fast"` приймається як `"priority"`.

Плагін блокує старіші або неверсійовані handshake app-server. Codex app-server має повідомляти стабільну версію 0.125.0 або новішу.

Режими схвалення й sandbox

Локальні сеанси stdio app-server типово використовують режим YOLO: approvalPolicy: "never", approvalsReviewer: "user" і sandbox: "danger-full-access". Така довірена локальна операторська позиція дає змогу не супроводжуваним ходам OpenClaw і heartbeats просуватися без нативних запитів схвалення, на які ніхто не зможе відповісти. Якщо файл локальних системних вимог Codex забороняє неявні значення схвалення YOLO, reviewer або sandbox, OpenClaw натомість розглядає неявне типове значення як guardian і вибирає дозволені дозволи guardian. Записи [[remote_sandbox_config]] у тому самому файлі вимог, що збігаються з hostname, враховуються під час вибору типового sandbox. Установіть appServer.mode: "guardian" для схвалень Codex із перевіркою guardian:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

Пресет guardian розгортається в approvalPolicy: "on-request", approvalsReviewer: "auto_review" і sandbox: "workspace-write", коли ці значення дозволені. Окремі поля політики перевизначають mode. Старіше значення reviewer guardian_subagent усе ще приймається як сумісний псевдонім, але в нових конфігураціях слід використовувати auto_review.

Автентифікація та ізоляція середовища

Автентифікація вибирається в такому порядку:

Явний профіль автентифікації OpenClaw Codex для агента.
Наявний обліковий запис app-server у Codex home цього агента.
Лише для локальних запусків stdio app-server: CODEX_API_KEY, потім OPENAI_API_KEY, коли облікового запису app-server немає, а автентифікація OpenAI усе ще потрібна.

Коли OpenClaw бачить профіль автентифікації Codex у стилі підписки ChatGPT, він видаляє CODEX_API_KEY і OPENAI_API_KEY із породженого дочірнього процесу Codex. Це зберігає API-ключі рівня Gateway доступними для embeddings або прямих моделей OpenAI, не дозволяючи нативним ходам Codex app-server випадково оплачуватися через API. Явні профілі API-ключів Codex і локальний резервний варіант env-key для stdio використовують login app-server замість успадкованого середовища дочірнього процесу. Підключення WebSocket app-server не отримують резервний API-key середовища Gateway; використовуйте явний профіль автентифікації або власний обліковий запис віддаленого app-server. Запуски stdio app-server типово успадковують середовище процесу OpenClaw, але OpenClaw керує мостом облікового запису Codex app-server і встановлює як CODEX_HOME, так і HOME у каталоги для кожного агента в межах стану OpenClaw цього агента. Власний завантажувач Skills Codex читає $CODEX_HOME/skills і $HOME/.agents/skills, тому обидва значення ізольовані для локальних запусків app-server. Це утримує нативні для Codex skills, plugins, config, accounts і thread state у межах агента OpenClaw, замість витоку з особистого Codex CLI home оператора. Плагіни OpenClaw і snapshots Skills OpenClaw усе ще проходять через власний реєстр плагінів і завантажувач Skills OpenClaw. Особисті ресурси Codex CLI не проходять. Якщо у вас є корисні Skills або plugins Codex CLI, які мають стати частиною агента OpenClaw, внесіть їх в інвентар явно:

openclaw migrate codex --dry-run
openclaw migrate apply codex --yes

Якщо розгортанню потрібна додаткова ізоляція середовища, додайте ці змінні до appServer.clearEnv:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],
          },
        },
      },
    },
  },
}

appServer.clearEnv впливає лише на породжений дочірній процес Codex app-server. CODEX_HOME і HOME залишаються зарезервованими для ізоляції Codex для кожного агента OpenClaw під час локальних запусків.

Динамічні інструменти

Динамічні інструменти Codex типово використовують завантаження searchable. OpenClaw не відкриває динамічні інструменти, які дублюють нативні операції робочого простору Codex:

read
write
edit
apply_patch
exec
process
update_plan

Інші інструменти інтеграції OpenClaw, як-от обмін повідомленнями, сеанси, медіа, cron, браузер, вузли, gateway, heartbeat_respond і web_search, доступні через пошук інструментів Codex у просторі імен openclaw. Це зменшує початковий контекст моделі. sessions_yield і відповіді джерела лише через інструмент повідомлень залишаються прямими, оскільки це контракти керування ходом. Встановлюйте codexDynamicToolsLoading: "direct" лише під час підключення до користувацького Codex app-server, який не може шукати відкладені динамічні інструменти, або під час налагодження повного навантаження інструментів.

Тайм-аути

Динамічні виклики інструментів, якими володіє OpenClaw, обмежуються незалежно від appServer.requestTimeoutMs. Кожен запит Codex item/tool/call використовує перший доступний тайм-аут у такому порядку:

Позитивний аргумент timeoutMs для окремого виклику.
Для image_generate, agents.defaults.imageGenerationModel.timeoutMs.
Для інструмента image розуміння медіа, tools.media.image.timeoutSeconds, перетворений у мілісекунди, або стандартне значення 60 секунд для медіа.
Стандартне значення 30 секунд для динамічних інструментів.

Бюджети динамічних інструментів обмежені 600000 мс. У разі тайм-ауту OpenClaw перериває сигнал інструмента там, де це підтримується, і повертає Codex відповідь про невдале виконання динамічного інструмента, щоб хід міг продовжитися, замість залишати сеанс у стані processing. Після того як OpenClaw відповідає на обмежений ходом запит Codex app-server, harness також очікує, що Codex завершить нативний хід через turn/completed. Якщо app-server мовчить протягом appServer.turnCompletionIdleTimeoutMs після цієї відповіді, OpenClaw у міру можливості перериває хід Codex, записує діагностичний тайм-аут і звільняє смугу сеансу OpenClaw, щоб подальші повідомлення чату не ставали в чергу за застарілим нативним ходом. Будь-яке нетермінальне сповіщення для того самого ходу, зокрема rawResponseItem/completed, вимикає цей короткий сторожовий таймер, оскільки Codex довів, що хід усе ще живий. Довший термінальний сторожовий таймер продовжує захищати справді завислі ходи. Діагностика тайм-аутів містить останній метод сповіщення app-server і, для сирих елементів відповіді асистента, тип елемента, роль, id та обмежений попередній перегляд тексту асистента.

Виявлення моделей

За замовчуванням Codex Plugin запитує в app-server доступні моделі. Доступністю моделей володіє Codex app-server, тому список може змінюватися, коли OpenClaw оновлює вбудовану версію @openai/codex або коли розгортання вказує appServer.command на інший бінарний файл Codex. Доступність також може залежати від облікового запису. Використовуйте /codex models на запущеному gateway, щоб побачити живий каталог для цього harness і облікового запису. Якщо виявлення завершується помилкою або тайм-аутом, OpenClaw використовує вбудований резервний каталог для:

GPT-5.5
GPT-5.4 mini
GPT-5.2

Поточний вбудований harness — @openai/codex 0.130.0. Зонд model/list для цього вбудованого app-server повернув:

ID моделі	За замовчуванням	Прихована	Модальності вводу	Зусилля reasoning
`gpt-5.5`	Так	Ні	text, image	low, medium, high, xhigh
`gpt-5.4`	Ні	Ні	text, image	low, medium, high, xhigh
`gpt-5.4-mini`	Ні	Ні	text, image	low, medium, high, xhigh
`gpt-5.3-codex`	Ні	Ні	text, image	low, medium, high, xhigh
`gpt-5.3-codex-spark`	Ні	Ні	text	low, medium, high, xhigh
`gpt-5.2`	Ні	Ні	text, image	low, medium, high, xhigh

Приховані моделі можуть повертатися каталогом app-server для внутрішніх або спеціалізованих потоків, але вони не є звичайними варіантами у виборі моделі. Налаштуйте виявлення в plugins.entries.codex.config.discovery:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}

Вимкніть виявлення, якщо хочете, щоб запуск не зондував Codex і використовував лише резервний каталог:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}

Файли початкового налаштування робочого простору

Codex сам обробляє AGENTS.md через нативне виявлення документації проєкту. OpenClaw не записує синтетичні файли документації проєкту Codex і не залежить від резервних імен файлів Codex для файлів персони, оскільки резервні варіанти Codex застосовуються лише тоді, коли AGENTS.md відсутній. Для паритету робочого простору OpenClaw harness Codex розв’язує інші файли початкового налаштування, зокрема SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md і MEMORY.md, коли вони присутні, і пересилає їх через інструкції розробника Codex у thread/start і thread/resume. Це зберігає контекст персони й профілю робочого простору видимим на нативній смузі формування поведінки Codex без дублювання AGENTS.md.

Перевизначення середовища

Перевизначення середовища залишаються доступними для локального тестування:

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 обходить керований бінарний файл, коли appServer.command не задано. OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 було видалено. Натомість використовуйте plugins.entries.codex.config.appServer.mode: "guardian" або OPENCLAW_CODEX_APP_SERVER_MODE=guardian для разового локального тестування. Конфігурація є бажаною для повторюваних розгортань, оскільки вона зберігає поведінку Plugin у тому самому переглянутому файлі, що й решта налаштування harness Codex.

CLI commands

RPC and API

Codex harness

Templates

Technical reference

Concept internals

Project

Release and CI

Довідник з обв’язки Codex

Поверхня конфігурації Plugin

Транспорт app-server

Режими схвалення й sandbox

Автентифікація та ізоляція середовища

Динамічні інструменти

Тайм-аути

Виявлення моделей

Файли початкового налаштування робочого простору

Перевизначення середовища

Пов’язане

CLI commands

RPC and API

Codex harness

Templates

Technical reference

Concept internals

Project

Release and CI

Documentation Index

​Поверхня конфігурації Plugin

​Транспорт app-server

​Режими схвалення й sandbox

​Автентифікація та ізоляція середовища

​Динамічні інструменти

​Тайм-аути

​Виявлення моделей

​Файли початкового налаштування робочого простору

​Перевизначення середовища

​Пов’язане

Поверхня конфігурації Plugin

Транспорт app-server

Режими схвалення й sandbox

Автентифікація та ізоляція середовища

Динамічні інструменти

Тайм-аути

Виявлення моделей

Файли початкового налаштування робочого простору

Перевизначення середовища

Пов’язане