Обвязка 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 выполняет контракт диагностики плагина для управления состоянием сеансов и будущих миграций конфигурации. Эта команда не проверяет среду 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, режим токена носителя, заголовки, идентификатор модели и ограничения контекста и вывода; логика транспорта провайдера остаётся в 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: когда SDK Copilot запрашивает ввод пользователя, 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, возвращаемый мостом инструментов Copilot, помечается:

• 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). Эквивалент в SDK Copilot — закрытый по умолчанию rejectAllPolicy для любого типа, отличного от custom-tool, который когда-либо достигает onPermissionRequest, — служит той же страховкой и на практике никогда не срабатывает, поскольку overridesBuiltInTool: true вытесняет каждый встроенный инструмент.

Чтобы уровень обёрнутых инструментов принимал решения по политикам, эквивалентные PI, обвязка передаёт полный контекст инструмента попытки PI в createOpenClawCodingTools: идентификационные данные (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.

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

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

Контракт SDK Copilot различает токен 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)