OpenClaw + Codex: настройка нативного рантайма | open-claw.su

Codex — это новый рантайм от OpenAI, встроенный в OpenClaw через плагин codex-harness. Вместо стандартного PI-рантайма агент запускается внутри нативного Codex app-server, получая доступ к продвинутым инструментам OpenAI: динамическим скиллам, Computer Use, нативному планированию и управлению сессиями.

Эта статья — пошаговая настройка: от авторизации до первого запуска Computer Use.

Когда использовать Codex

Сценарий	Рекомендация
Есть подписка ChatGPT Plus/Pro с Codex	Да — используйте нативный рантайм
Нужен Computer Use (управление рабочим столом)	Да — Codex поддерживает нативно
Хотите мигрировать скиллы из Codex CLI	Да — встроенная команда миграции
Работаете только с API-ключом OpenAI	Нет — используйте стандартный PI-рантайм (`openai/gpt-4o`)
Важна полная совместимость со всеми OpenClaw-инструментами	Осторожно — часть нативных фич Codex не транслируется в OpenClaw

Главное отличие: при стандартном PI-рантайме OpenClaw сам управляет циклом агента и инструментами. При Codex-рантайме циклом управляет нативный Codex app-server, а OpenClaw отвечает за доставку сообщений, каналы и динамические инструменты.

Пошаговая настройка

Шаг 1. Авторизация через Codex OAuth

Выполните в терминале:

openclaw models auth login --provider openai-codex

Откроется браузер для OAuth-авторизации. Войдите в аккаунт OpenAI с активной подпиской на Codex.

Требование: подписка ChatGPT Plus/Pro с доступом к Codex. API-ключ OpenAI не подходит для нативного рантайма.

Шаг 2. Включите плагин

Откройте ~/.openclaw/openclaw.json и добавьте:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "stdio",      // "stdio" | "websocket"
            mode: "guardian",        // "yolo" | "guardian"
            approvalPolicy: "on-request", // "never" | "on-request"
            sandbox: "workspace-write",   // "danger-full-access" | "workspace-write"
            serviceTier: null,       // "fast" | "flex" | null
          },
          computerUse: {
            autoInstall: false,      // true = автоустановка Computer Use
          },
          discovery: {
            enabled: true,
            timeoutMs: 30000,
          },
        },
      },
    },
    // Если у вас есть allowlist — добавьте codex:
    allow: ["codex"],
  },
}

Шаг 3. Переключите рантайм агента

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",         // или gpt-5.4, gpt-5.2
      agentRuntime: {
        id: "codex",                   // "codex" | "pi" | "auto" | "acp"
      },
    },
  },
}

Или через переменную окружения:

export OPENCLAW_AGENT_RUNTIME=codex

Шаг 4. Перезапустите сессию

Изменения рантайма применяются только к новым сессиям:

openclaw gateway restart

Затем в чате отправьте:

/new

Или /reset — это создаст новую сессию с Codex-рантаймом.

Важно: существующие сессии «запоминают» свой рантайм. Старые диалоги продолжат работать на PI, пока вы не создадите новую сессию.

Конфигурация appServer

Блок plugins.entries.codex.config.appServer управляет поведением Codex app-server:

Параметр	Значения	Описание
`transport`	`"stdio"` / `"websocket"`	Как подключаться к app-server. `stdio` — локальный бинарник, `websocket` — удалённый
`mode`	`"yolo"` / `"guardian""`	`"yolo"` — Codex сам решает, что делать. `"guardian"` — требует подтверждения на опасные действия
`approvalPolicy`	`"never"` / `"on-request"`	Когда запрашивать разрешение: никогда или по запросу
`sandbox`	`"danger-full-access"` / `"workspace-write"`	Уровень доступа к файловой системе
`serviceTier`	`"fast"` / `"flex"` / `null`	Приоритет скорости. `null` = по умолчанию

Режимы работы

Yolo mode — Codex самостоятельно выполняет действия без подтверждения. Быстро, но требует доверия. Подходит для песочниц и изолированных сред.

Guardian mode — Codex запрашивает подтверждение перед опасными операциями. Этот режим работает через approvalPolicy:

"on-request" — подтверждение запрашивается для каждого рискованного действия
"never" — подтверждение не требуется (эквивалент yolo, но в рамках guardian)

Рекомендуемая конфигурация для начала:

{
  appServer: {
    mode: "guardian",
    approvalPolicy: "on-request",
    sandbox: "workspace-write",
  },
}

Команды /codex

После включения плагина в чате доступны команды:

/codex status           — статус текущего Codex-рантайма
/codex threads          — список активных тредов
/codex resume <id>      — возобновить конкретный тред
/codex compact          — сжать контекст треда
/codex diagnostics      — диагностика подключения
/codex binding          — информация о привязке сессии
/codex account          — данные аккаунта Codex
/codex mcp              — статус MCP-серверов Codex
/codex skills           — список загруженных скиллов Codex
/codex stop             — остановить текущий тред
/codex steer            — направить ход разговора

Управление Computer Use

/codex computer-use status                    — проверить статус
/codex computer-use install                   — установить плагин Computer Use
/codex computer-use install --source <url>    — установить из произвольного источника

Computer Use (управление рабочим столом)

Codex поддерживает нативное управление рабочим столом через MCP-плагин computer-use. OpenClaw не выполняет desktop-действия сам — он подготавливает Codex app-server и проверяет доступность MCP-сервера.

Настройка

{
  plugins: {
    entries: {
      codex: {
        config: {
          computerUse: {
            autoInstall: true,   // автоустановка при старте
            enabled: true,       // явно включить
          },
        },
      },
    },
  },
}

После включения сбросьте сессию (/reset) и проверьте статус:

/codex computer-use status

macOS: требуется разрешение на доступ к экрану (Screen Recording) и управление (Accessibility). Плагин не установится без этих прав.

Ошибки:

marketplace_missing — не найден marketplace-источник
plugin_disabled — плагин computer-use отключён в Codex
mcp_missing — MCP-сервер computer-use недоступен
remote_install_unsupported — удалённая установка не поддерживается

Миграция скиллов из Codex CLI

Если у вас есть скиллы, созданные в нативном Codex CLI, их можно перенести в OpenClaw:

# Предпросмотр миграции
openclaw migrate codex --dry-run

# Применить миграцию
openclaw migrate apply codex --yes

Миграция переносит:

Описания скиллов
Конфигурации
Инструкции AGENTS.md

Проверьте результат после миграции:

openclaw doctor

Динамические инструменты

Codex runtime поддерживает два профиля динамических инструментов:

native-first (по умолчанию) — Codex использует свои нативные инструменты, если они доступны. OpenClaw-инструменты подключаются как fallback.

openclaw-compat — приоритет отдаётся OpenClaw-инструментам. Полезно, если нужна максимальная совместимость со стандартным рантаймом.

{
  plugins: {
    entries: {
      codex: {
        config: {
          codexDynamicToolsProfile: "openclaw-compat",
          codexDynamicToolsExclude: ["browser"],  // исключить конкретные инструменты
        },
      },
    },
  },
}

ACP fallback

Если плагин codex-harness недоступен, можно запустить Codex как внешний harness через ACP (Agent Client Protocol):

# Запуск Codex через ACP
/acp spawn codex

ACP-режим предоставляет:

Привязываемые сессии (bindable sessions)
Фоновые задачи (background tasks)
Привязку к тредам/темам (thread/topic bindings)
Управление рантаймом (/acp cancel, /acp steer)

Отличие от нативного плагина:

ACP — внешний процесс, запущенный отдельно
Нативный плагин — встроенный, работает внутри OpenClaw Gateway
Для ACP требуется отдельная авторизация claude auth login (если используется Claude Code) или эквивалент для Codex

Типичные проблемы

«Runtime selection failed»

Сессия была создана до включения Codex. Создайте новую:

/new

«App-server version mismatch»

Требуется версия Codex app-server 0.125.0+. Обновите:

openclaw update

«Auth routing failed»

Проверьте авторизацию:

openclaw models auth login --provider openai-codex
openclaw doctor

«Session pin conflict»

Старые сессии «запомнили” PI-рантайм. Отправьте /reset или /new для создания чистой Codex-сессии.

Codex не отвечает после переключения

Проверьте статус:

/codex status
/codex diagnostics

Если app-server не запущен:

openclaw gateway restart
openclaw health

Совместимость с OpenClaw-инструментами

Нативный Codex runtime владеет циклом модели и canonical thread state. OpenClaw владеет:

Доставкой сообщений через каналы
Динамическими инструментами
Зеркалированием транскриптов

Некоторые OpenClaw-фичи могут работать иначе или не поддерживаться в Codex-режиме. Полный список ограничений — в официальной документации.

Полная конфигурация (пример)

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "stdio",
            mode: "guardian",
            approvalPolicy: "on-request",
            sandbox: "workspace-write",
            serviceTier: null,
          },
          computerUse: {
            autoInstall: false,
          },
          discovery: {
            enabled: true,
            timeoutMs: 30000,
          },
          codexDynamicToolsProfile: "native-first",
        },
      },
    },
    allow: ["codex"],
  },
}

Что дальше

Какую модель выбрать для OpenClaw →
Настройка OpenAI-провайдера → (для стандартного PI-рантайма)
Плагины OpenClaw →
Агенты и мульти-агент →
Официальная документация Codex harness