Обвязка Copilot SDK

Внешний плагин @openclaw/copilot выполняет встроенные в подписку ходы агента Copilot через GitHub Copilot CLI (@github/copilot-sdk), а не через встроенный исполнитель OpenClaw. Сеанс Copilot CLI управляет низкоуровневым циклом агента: нативным выполнением инструментов, нативным Compaction (infiniteSessions) и состоянием ветки обсуждения, которым управляет CLI, в copilotHome. OpenClaw по-прежнему управляет чат- каналами, файлами сеансов, выбором модели, динамическими инструментами (через мост), подтверждениями, доставкой медиафайлов, видимой копией стенограммы, побочными вопросами /btw (см. Побочные вопросы (/btw)) и openclaw doctor.

Общее описание разделения модели, провайдера и среды выполнения см. в разделе Среды выполнения агентов.

Требования

• OpenClaw с установленным плагином @openclaw/copilot.
• Если в вашей конфигурации используется plugins.allow, включите copilot (идентификатор манифеста, объявленный плагином). Запись в списке разрешений с именем npm-пакета @openclaw/copilot не совпадёт, поэтому плагин останется заблокированным, даже если задано agentRuntime.id: "copilot".
• Подписка GitHub Copilot, позволяющая использовать Copilot CLI, либо переменная среды gitHubToken или запись профиля аутентификации для запуска без интерфейса или через Cron.
• Доступный для записи каталог copilotHome. По умолчанию используется <agentDir>/copilot, когда OpenClaw предоставляет каталог агента, иначе — ~/.openclaw/agents/<agentId>/copilot.

openclaw doctor выполняет контракт doctor плагина для управления состоянием сеанса и будущих миграций конфигурации. Он не проверяет окружение Copilot CLI.

Установка

Среда выполнения Copilot поставляется как внешний плагин, чтобы основной пакет openclaw не включал @github/copilot-sdk и его платформозависимый CLI-бинарный файл @github/copilot-<platform>-<arch> (вместе около 260 МБ). Устанавливайте его только для агентов, использующих эту среду выполнения:

openclaw plugins install @openclaw/copilot

Мастер настройки автоматически устанавливает плагин при первом выборе модели github-copilot/*, если конфигурация направляет эту модель (или её провайдер) в среду выполнения Copilot через agentRuntime: { id: "copilot" }; см. Быстрый старт. Без такого явного выбора OpenClaw использует встроенный провайдер GitHub Copilot и никогда не устанавливает этот плагин.

Среда выполнения разрешает SDK в следующем порядке:

1. import("@github/copilot-sdk") из установленного пакета @openclaw/copilot.
2. Резервный каталог ~/.openclaw/npm-runtime/copilot/ (устаревшее целевое расположение для установки по требованию).

При отсутствии SDK выводится одна ошибка с кодом COPILOT_SDK_MISSING и приведённая выше команда переустановки.

Быстрый старт

Закрепите одну модель (или одного провайдера) за исполнителем:

{  agents: {    defaults: {      model: "github-copilot/auto",      models: {        "github-copilot/auto": {          agentRuntime: { id: "copilot" },        },      },    },  },}

Задайте agentRuntime.id для записи одной модели, чтобы направить через исполнитель только её, либо для провайдера, чтобы направить все его модели.

github-copilot/auto — универсальная отправная точка. Доступность именованных моделей Copilot зависит от политики учётной записи и организации; прежде чем закреплять модель, убедитесь, что аутентифицированный Copilot CLI действительно предоставляет её.

Поддерживаемые провайдеры

Исполнитель поддерживает канонический провайдер github-copilot (принадлежащий extensions/github-copilot), а также пользовательские записи models.providers, если у модели есть непустое значение baseUrl и одна из следующих форм api:

• anthropic-messages
• azure-openai-responses
• ollama (завершения, совместимые с OpenAI)
• openai-completions
• openai-responses

Нативные идентификаторы провайдеров (openai, anthropic, google, ollama) остаются в ведении соответствующих нативных сред выполнения. Чтобы направить конечную точку через Copilot BYOK, используйте отдельный идентификатор пользовательского провайдера.

Конечные точки Copilot BYOK должны быть общедоступными URL-адресами HTTPS. Исполнитель предоставляет Copilot SDK локальный прокси-сервер для каждой попытки, а затем направляет трафик провайдера через защищённый механизм запросов OpenClaw, чтобы закрепление DNS и политика SSRF оставались под управлением OpenClaw. Для локальных Ollama, LM Studio или серверов моделей в локальной сети используйте нативную среду выполнения OpenClaw.

BYOK

Copilot BYOK использует контракт пользовательского провайдера SDK на уровне сеанса. OpenClaw передаёт разрешённую конечную точку модели, ключ API, режим bearer-токена, заголовки, идентификатор модели и ограничения контекста/вывода; логика транспорта провайдера остаётся в SDK, а не в основном коде.

{  agents: {    defaults: {      model: "custom-proxy/llama-3.1-8b",      models: {        "custom-proxy/llama-3.1-8b": {          agentRuntime: { id: "copilot" },        },      },    },  },  models: {    mode: "merge",    providers: {      "custom-proxy": {        baseUrl: "https://api.example.com/v1",        apiKey: "${CUSTOM_PROXY_API_KEY}",        api: "openai-responses",        authHeader: true,        models: [{ id: "llama-3.1-8b", name: "Llama 3.1 8B" }],      },    },  },}

Сеансы BYOK отделены ключами от сеансов подписки, а также от других конечных точек и учётных данных BYOK. При смене ключа, заголовков, модели или конечной точки запускается новый сеанс Copilot SDK вместо возобновления несовместимого состояния.

Аутентификация

Порядок приоритетов, применяемый для каждого агента во время runCopilotAttempt:

1. Явное useLoggedInUser: true во входных данных попытки — используется пользователь, вошедший в Copilot CLI в каталоге copilotHome агента.

2. Явное gitHubToken во входных данных попытки (требует profileId + profileVersion). Для прямых вызовов CLI и тестов, которым нужно обойти разрешение профиля аутентификации.

3. Разрешённые по контракту resolvedApiKey + authProfileId — основной рабочий путь. Перед вызовом исполнителя основной код разрешает настроенный для агента профиль аутентификации github-copilot (src/infra/provider-usage.auth.ts:resolveProviderAuths), поэтому профиль аутентификации github-copilot:<profile> работает сквозным образом для запусков без интерфейса, через Cron или с несколькими профилями без переменных среды.

4. Резервный вариант с переменными среды, проверяемыми в следующем порядке (используется первое непустое значение, пустые строки считаются отсутствующими; соответствует приоритету поставляемого провайдера github-copilot в extensions/github-copilot/auth.ts):

   1. OPENCLAW_GITHUB_TOKEN — переопределение для конкретного исполнителя; позволяет закрепить токен за исполнителем OpenClaw, не затрагивая общесистемную конфигурацию gh / Copilot CLI.
   2. COPILOT_GITHUB_TOKEN — стандартная переменная среды Copilot SDK / CLI.
   3. GH_TOKEN — стандартная переменная среды CLI gh.
   4. GITHUB_TOKEN — универсальный резервный токен GitHub.

   Идентификатор синтезированного профиля пула — env:<NAME>; версия профиля представляет собой необратимый отпечаток токена sha256, поэтому смена значения переменной среды корректно сбрасывает пул клиентов.

5. Значение по умолчанию useLoggedInUser, если признаки токена отсутствуют.

Каждый агент получает собственный copilotHome, поэтому токены, сеансы и конфигурация Copilot CLI никогда не переходят между агентами на одном компьютере. По умолчанию: <agentDir>/copilot (состояние SDK хранится отдельно от каталога models.json / auth-profiles.json OpenClaw) или ~/.openclaw/agents/<agentId>/copilot, если каталог агента не указан. Чтобы задать другое расположение (например, общий подключённый том для миграции), переопределите copilotHome: <path> во входных данных попытки.

Интерактивные тесты исполнителя используют OPENCLAW_COPILOT_AGENT_LIVE_TOKEN для прямой передачи токена. Общая настройка интерактивных тестов удаляет COPILOT_GITHUB_TOKEN, GH_TOKEN и GITHUB_TOKEN после размещения реальных профилей аутентификации в изолированном тестовом домашнем каталоге, поэтому значение gh auth token, переданное через специальную переменную, позволяет избежать ложных пропусков без утечки в несвязанные наборы тестов.

Поверхность конфигурации

Исполнитель считывает конфигурацию из входных данных каждой попытки (runCopilotAttempt({...})) и небольшого набора значений среды по умолчанию внутри extensions/copilot/src/:

Хуки плагинов OpenClaw не требуют конфигурации попытки, специфичной для Copilot. Исполнитель запускает before_prompt_build (а также устаревший хук совместимости before_agent_start), llm_input, llm_output и agent_end через стандартные вспомогательные функции исполнителя. После успешного Compaction в SDK также запускаются before_compaction и after_compaction. Инструменты OpenClaw, подключённые через мост, запускают before_tool_call и сообщают after_tool_call; hooksConfig остаётся для обратных вызовов только нативного SDK, у которых нет переносимого аналога.

Остальным компонентам OpenClaw не требуется знать об этих полях. Другие плагины, каналы и основной код видят только стандартную форму AgentHarnessAttemptParams / AgentHarnessAttemptResult.

Compaction

При выполнении harness.compact исполнитель Copilot SDK:

1. Возобновляет отслеживаемый сеанс SDK, не продолжая ожидающую работу.
2. Вызывает RPC сжатия истории на уровне сеанса SDK.
3. Возвращает результат сжатия SDK, не записывая файлы-маркеры совместимости в рабочую область.

Копия стенограммы на стороне OpenClaw (см. ниже) продолжает получать сообщения после сжатия, поэтому отображаемая пользователю история чата остаётся согласованной.

Зеркалирование стенограммы

runCopilotAttempt выполняет двойную запись сообщений каждого хода, которые можно зеркалировать, в аудиторскую стенограмму OpenClaw через extensions/copilot/src/dual-write-transcripts.ts. Зеркало ограничено рамками отдельного сеанса (copilot:${sessionId}), а ключ задаётся для каждого сообщения (${role}:${sha256_16(role,content)}), поэтому повторно отправленные записи предыдущих ходов совпадают с существующими ключами на диске, а не дублируются.

Зеркало окружено двумя уровнями изоляции сбоев, поэтому ошибка записи стенограммы никогда не приводит к сбою попытки: внутренняя обёртка, работающая по принципу максимальных усилий, и дополнительная защита .catch(...) на уровне попытки. Сбои записываются в журнал, но не выводятся наружу.

Побочные вопросы (/btw)

/btw не является нативным для этой обвязки. createCopilotAgentHarness() намеренно оставляет harness.runSideQuestion неопределённым (это проверяется в extensions/copilot/harness.test.ts, describe("runSideQuestion")), поэтому диспетчер /btw OpenClaw (src/agents/btw.ts) переходит к тому же пути, который используется для всех сред выполнения, отличных от Codex: настроенный поставщик модели вызывается напрямую с коротким запросом побочного вопроса, а ответ передаётся потоком через streamSimple (без сеанса CLI и без дополнительного слота пула).

Это сохраняет сеансы Copilot CLI для основного цикла ходов агента и обеспечивает поведение /btw, идентичное другим средам выполнения, отличным от Codex.

Doctor

extensions/copilot/doctor-contract-api.ts автоматически загружается через src/plugins/doctor-contract-registry.ts. Он предоставляет:

• Пустой legacyConfigRules (устаревших полей пока нет).
• Ничего не выполняющий normalizeCompatibilityConfig (сохранён, чтобы для будущего вывода полей из эксплуатации было стабильное место в дереве исходного кода).
• Одна запись sessionRouteStateOwners: поставщик github-copilot, среда выполнения copilot, ключ сеанса CLI copilot, префикс профиля аутентификации github-copilot:.

Ограничения

• Обвязка заявляет github-copilot, а также пользовательские идентификаторы поставщиков BYOK без владельца. Нативные идентификаторы поставщиков, принадлежащие манифесту, остаются в среде выполнения своего владельца, даже если agentRuntime.id принудительно задан как copilot.
• Интерфейс TUI отсутствует; TUI среды PI остаётся резервным вариантом для сред выполнения без собственного интерфейса.
• Состояние сеанса PI не переносится при переключении агента на copilot. Выбор выполняется для каждой попытки; существующие сеансы PI остаются действительными.
• ask_user использует тот же путь запросов и ответов OpenClaw, что и обвязка Codex: когда Copilot SDK запрашивает ввод пользователя, OpenClaw отправляет блокирующий запрос в активный канал/TUI, а следующее поставленное в очередь сообщение пользователя разрешает запрос SDK.

Разрешения и ask_user

Проверка разрешений для мостовых инструментов OpenClaw выполняется внутри обёртки инструмента, а не через обратный вызов SDK onPermissionRequest. Тот же wrapToolWithBeforeToolCallHook, который использует PI (src/agents/agent-tools.before-tool-call.ts), применяется createOpenClawCodingTools ко всем инструментам программирования: обнаружение циклов, политики доверенных плагинов, хуки перед вызовом инструмента и двухэтапные подтверждения плагинов через Gateway (plugin.approval.request) выполняются по тому же пути кода, что и в нативных попытках PI.

Инструмент SDK, возвращаемый convertOpenClawToolToSdkTool, имеет следующие признаки:

• overridesBuiltInTool: true — заменяет встроенный инструмент Copilot CLI с тем же именем (edit, read, write, bash, ...), чтобы каждый вызов инструмента направлялся обратно в OpenClaw.
• skipPermission: true — указывает SDK не вызывать onPermissionRequest({kind: "custom-tool"}) перед запуском инструмента. Обёрнутый execute() уже выполняет более полную проверку политик OpenClaw; запрос на уровне SDK либо обходил бы проверку OpenClaw (разрешать всё), либо блокировал бы каждый вызов инструмента (отклонять всё) — ни один вариант не обеспечивает соответствие PI.

Встроенная в дерево исходного кода обвязка Codex использует такое же разделение: мостовые инструменты OpenClaw оборачиваются (extensions/codex/src/app-server/dynamic-tools.ts), а собственные нативные типы подтверждений codex-app-server (item/commandExecution/requestApproval, item/fileChange/requestApproval, item/permissions/requestApproval) направляются через plugin.approval.request (extensions/codex/src/app-server/approval-bridge.ts). Эквивалент в Copilot SDK — закрытый по умолчанию rejectAllPolicy для любого типа, отличного от custom-tool, который когда-либо достигает onPermissionRequest, — представляет собой такую же защитную меру, и на практике она никогда не срабатывает, поскольку overridesBuiltInTool: true вытесняет все встроенные инструменты.

Чтобы уровень обёрнутых инструментов мог принимать решения по политикам, эквивалентные PI, обвязка передаёт в createOpenClawCodingTools полный контекст инструментов попытки PI: идентификационные данные (senderIsOwner, memberRoleIds, ownerOnlyToolAllowlist, ...), канал и маршрутизацию (groupId, currentChannelId, replyToMode, переключатели инструментов сообщений), аутентификацию (authProfileStore), идентификационные данные запуска (sessionKey / runSessionKey, полученные из sandboxSessionKey, runId), контекст модели (modelApi, modelContextWindowTokens, modelCompat, modelHasVision) и хуки запуска (onToolOutcome, onYield). Без этих полей списки разрешений только для владельцев по умолчанию молча отклоняют запросы, политики доверия плагинов не могут определить правильную область действия, а session_status: "current" разрешается в устаревший ключ песочницы. Построитель моста — extensions/copilot/src/tool-bridge.ts, повторяющий эталонный вызов PI в src/agents/embedded-agent-runner/run/attempt.ts:1262. runAttempt разрешает контекст песочницы через общий интерфейс resolveSandboxContext, передаёт SDK фактический рабочий каталог и передаёт sandbox, а также рабочую область создания субагента в мост инструментов. Мост также передаёт ограниченные элементы управления построением инструментов, соблюдение которых он может обеспечить на границе SDK: includeCoreTools, список разрешённых инструментов среды выполнения и toolConstructionPlan.

Мост также использует общий вспомогательный компонент поверхности инструментов обвязки из openclaw/plugin-sdk/agent-harness-tool-runtime для соответствия PI. Когда поиск инструментов включён, SDK видит компактные инструменты управления и скрытый исполнитель каталога вместо схем всех инструментов OpenClaw. Когда включён режим кода, вспомогательный компонент создаёт ту же поверхность управления режима кода и тот же жизненный цикл каталога, которые используются другими обвязками агентов. Облегчённые настройки по умолчанию для локальных моделей, совместимая со средой выполнения фильтрация схем, наполнение каталогов и очистка каталога остаются в общем вспомогательном компоненте, чтобы обвязки Copilot и смежные с Codex обвязки не расходились.

Токен GitHub уровня сеанса

Контракт Copilot SDK различает токен GitHub уровня клиента (CopilotClientOptions.gitHubToken, аутентифицирует сам процесс CLI) и токен уровня сеанса (SessionConfig.gitHubToken, определяет исключение содержимого, маршрутизацию модели и квоту для этого сеанса; учитывается как в createSession, так и в resumeSession). Обвязка однократно разрешает аутентификацию через resolveCopilotAuth и задаёт оба поля, когда режим аутентификации — gitHubToken (явный auth.gitHubToken или разрешённый согласно контракту resolvedApiKey из настроенного профиля аутентификации github-copilot). Когда разрешённый режим — useLoggedInUser, поле уровня сеанса опускается, чтобы SDK продолжал определять идентификационные данные из выполненного входа.

ask_user использует SessionConfig.onUserInputRequest. Мост принимает индексы или метки вариантов для запросов с фиксированным выбором, принимает ответы в свободной форме, когда запрос SDK допускает их, и отменяет ожидающий запрос, когда попытка OpenClaw прерывается.

Связанные материалы

• Среды выполнения агентов
• Обвязка Codex
• Плагины обвязок агентов (справочник SDK)