Мультиагентность: несколько агентов, субагенты, ACP

Никогда не используйте один agentDir для разных агентов — это вызовет коллизии auth и сессий. Если нужно общие credentials, скопируйте auth-profiles.json в другой агент.

| Что | ACP | Субагент |

|——|——|———-|

| Рантайм | Внешний (acpx) | OpenClaw native |

| Сессия | agent::acp: | agent::subagent: |

| Команды | /acp ... | /subagents ... |

| Запуск | sessions_spawn(runtime="acp") | sessions_spawn() |

Используйте ACP, когда нужен именно внешний харнес. Используйте субагенты для OpenClaw-native задач.

ACP-сессии работают неинтерактивно — нет TTY для подтверждения. Настройки:

• permissionMode: "approve-all" — разрешить всё
• permissionMode: "approve-reads" — только чтение (по умолчанию)
• nonInteractivePermissions: "deny" — молча отказать (graceful degradation)

Встроенный плагин codex позволяет OpenClaw запускать embedded agent turns через Codex app-server вместо встроенного PI harness.

Используйте это, когда хотите, чтобы Codex управлял низкоуровневой сессией агента: discovery моделей, нативный thread resume, нативная компактация и выполнение через app-server. OpenClaw по-прежнему управляет каналами чата, файлами сессий, выбором моделей, инструментами, approval’ами, доставкой медиа и зеркалом транскрипта.

Harness выключен по умолчанию. Он выбирается только когда плагин codex включён и резолвная модель — codex/*, или когда вы явно задаёте embeddedHarness.runtime: "codex" / OPENCLAW_AGENT_RUNTIME=codex.

Выберите правильный префикс модели

В OpenClaw отдельные маршруты для OpenAI и Codex-доступа:

Codex harness работает только с codex/* ссылками. Все остальные провайдеры сохраняют обычные пути.

Требования

• OpenClaw с встроенным плагином codex.
• Codex app-server 0.118.0 или новее.
• Codex auth доступен для процесса app-server.

Плагин блокирует старые или неверсионные handshake’ы app-server.

Минимальная конфигурация

{
  plugins: {
    entries: {
      codex: { enabled: true },
    },
  },
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

Если в конфиге используется plugins.allow — добавьте "codex":

{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: { enabled: true },
    },
  },
}

Добавить Codex без замены других моделей

Оставьте runtime: "auto", чтобы Codex работал для codex/* моделей, а PI — для всего остального:

{
  plugins: {
    entries: {
      codex: { enabled: true },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "codex/gpt-5.4",
        fallbacks: ["openai/gpt-5.4", "anthropic/claude-opus-4-6"],
      },
      models: {
        "codex/gpt-5.4": { alias: "codex" },
        "codex/gpt-5.4-mini": { alias: "codex-mini" },
        "openai/gpt-5.4": { alias: "gpt" },
        "anthropic/claude-opus-4-6": { alias: "opus" },
      },
      embeddedHarness: {
        runtime: "auto",
        fallback: "pi",
      },
    },
  },
}

• /model codex или /model codex/gpt-5.4 → Codex app-server harness
• /model gpt или /model openai/gpt-5.4 → OpenAI provider
• /model opus → Anthropic provider
• Если выбрана не-Codex модель — PI остаётся совместимым harness

Развёртывания только-Codex

Отключите PI fallback, чтобы доказать, что каждый embedded turn идёт через Codex harness:

{
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

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

OPENCLAW_AGENT_RUNTIME=codex \
OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run

Per-agent Codex

Можно сделать одного агента Codex-only, а default — с обычным auto-selection:

{
  agents: {
    defaults: {
      embeddedHarness: {
        runtime: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "codex/gpt-5.4",
        embeddedHarness: {
          runtime: "codex",
          fallback: "none",
        },
      },
    ],
  },
}

Discovery моделей

По умолчанию плагин запрашивает app-server для списка доступных моделей. Если discovery не удался — используется fallback-каталог:

• codex/gpt-5.4
• codex/gpt-5.4-mini
• codex/gpt-5.2

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,      // false — использовать только fallback
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}

Подключение к app-server

По умолчанию плагин запускает Codex локально:

codex app-server --listen stdio://

По умолчанию локальные сессии запускаются без ограничений: approvalPolicy: "never" и sandbox: "danger-full-access". Можно ужесточить:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            approvalPolicy: "untrusted",
            approvalsReviewer: "guardian_subagent",
            sandbox: "workspace-write",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

Для уже запущенного app-server — WebSocket транспорт:

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

Параметры appServer

Готовые рецепты

{
  plugins: {
    entries: {
      codex: { enabled: true },
    },
  },
}

{
  embeddedHarness: { fallback: "none" },
  plugins: {
    entries: {
      codex: { enabled: true },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            approvalPolicy: "on-request",
            approvalsReviewer: "guardian_subagent",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: { "X-OpenClaw-Agent": "main" },
          },
        },
      },
    },
  },
}

Команда /codex

Встроенный плагин регистрирует /codex как авторизованную slash-команду. Работает на любом канале с текстовыми командами OpenClaw.

Команды требуют Codex app-server 0.118.0+. Если метод не поддерживается — показывается unsupported by this Codex app-server.