--- read_when: - Вы хотите использовать среду GitHub Copilot SDK для агента - Вам нужны примеры конфигурации для среды выполнения `copilot` - Вы подключаете агента к Copilot по подписке (github / openclaw / copilot) и хотите запускать его через Copilot CLI summary: Запускайте циклы встроенного агента OpenClaw через внешний контур GitHub Copilot SDK title: Обвязка Copilot SDK x-i18n: generated_at: "2026-07-16T16:38:22Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: fb4a0a3bf1123c1c3cbbed2630476afb5df73bc61d47e8a3987a5d0d7f01f83a source_path: plugins/copilot.md workflow: 16 --- Внешний плагин `@openclaw/copilot` выполняет встроенные обращения агента Copilot по подписке через GitHub Copilot CLI (`@github/copilot-sdk`), а не через встроенную среду выполнения OpenClaw. Сеанс Copilot CLI управляет низкоуровневым циклом агента: нативным выполнением инструментов, нативной Compaction (`infiniteSessions`) и состоянием потока под управлением CLI в `copilotHome`. OpenClaw по-прежнему управляет каналами чата, файлами сеансов, выбором модели, динамическими инструментами (через мост), подтверждениями, доставкой медиа, видимым зеркалом расшифровки, побочными вопросами `/btw` (см. [Побочные вопросы (`/btw`)](#side-questions-btw)) и `openclaw doctor`. Общее разделение моделей, провайдеров и сред выполнения описано в разделе [Среды выполнения агентов](/ru/concepts/agent-runtimes). ## Требования - OpenClaw с установленным плагином `@openclaw/copilot`. - Если в конфигурации используется `plugins.allow`, включите `copilot` (идентификатор манифеста, объявленный плагином). Запись в списке разрешений с именем npm-пакета `@openclaw/copilot` не совпадёт, поэтому плагин останется заблокированным даже при заданном `agentRuntime.id: "copilot"`. - Подписка GitHub Copilot, позволяющая использовать Copilot CLI, либо переменная среды `gitHubToken` или запись профиля аутентификации для автономных запусков или запусков Cron. - Доступный для записи каталог `copilotHome`. По умолчанию используется `/copilot`, если OpenClaw предоставляет каталог агента; в противном случае — `~/.openclaw/agents//copilot`. `openclaw doctor` выполняет [контракт диагностики](#doctor) плагина для управления состоянием сеансов и будущих миграций конфигурации. Эта команда не проверяет среду Copilot CLI. ## Установка Среда выполнения Copilot поставляется как внешний плагин, чтобы основной пакет `openclaw` не включал `@github/copilot-sdk` и его платформозависимый исполняемый файл CLI `@github/copilot--` (вместе около 260 МБ). Устанавливайте его только для агентов, использующих эту среду выполнения: ```bash openclaw plugins install @openclaw/copilot ``` Мастер настройки автоматически устанавливает плагин при первом выборе модели `github-copilot/*`, **если** конфигурация направляет эту модель (или её провайдер) в среду выполнения Copilot через `agentRuntime: { id: "copilot" }`; см. [Краткое руководство](#quickstart). Без такого явного выбора OpenClaw использует встроенный провайдер GitHub Copilot и никогда не устанавливает этот плагин. Среда выполнения разрешает SDK в следующем порядке: 1. `import("@github/copilot-sdk")` из установленного пакета `@openclaw/copilot`. 2. Резервный каталог `~/.openclaw/npm-runtime/copilot/` (устаревшая цель установки по требованию). При отсутствии SDK выдаётся одна ошибка с кодом `COPILOT_SDK_MISSING` и приведённой выше командой переустановки. ## Краткое руководство Закрепите одну модель (или одного провайдера) за средой выполнения: ```json5 { 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, а не в ядре. ```json5 { 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:` полностью работает для автономных запусков, 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:`; версия профиля представляет собой необратимый отпечаток токена sha256, поэтому смена значения переменной среды корректно сбрасывает пул клиентов. 5. **Значение `useLoggedInUser` по умолчанию**, когда сигнал токена отсутствует. Каждый агент получает собственный каталог `copilotHome`, поэтому токены, сеансы и конфигурация Copilot CLI никогда не передаются между агентами на одной машине. По умолчанию: `/copilot` (состояние SDK хранится отдельно от каталога `models.json` / `auth-profiles.json` OpenClaw) либо `~/.openclaw/agents//copilot`, если каталог агента не указан. Чтобы задать другой каталог (например, общий подключённый том для миграции), переопределите `copilotHome: ` во входных данных попытки. В тестах рабочей среды выполнения для прямого указания токена используется `OPENCLAW_COPILOT_AGENT_LIVE_TOKEN`. Общая настройка рабочих тестов удаляет `COPILOT_GITHUB_TOKEN`, `GH_TOKEN` и `GITHUB_TOKEN` после размещения реальных профилей аутентификации в изолированном домашнем каталоге тестов, поэтому значение `gh auth token`, переданное через специальную переменную, предотвращает ложные пропуски, не попадая в несвязанные наборы тестов. ## Параметры конфигурации Среда выполнения считывает конфигурацию из входных данных каждой попытки (`runCopilotAttempt({...})`) и небольшого набора значений переменных среды по умолчанию внутри `extensions/copilot/src/`: | Поле | Назначение | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `copilotHome` | Каталог состояния CLI для отдельного агента (значения по умолчанию указаны выше). | | `model` | Строка или `{ provider, id, api?, baseUrl?, headers?, authHeader? }`. Не указывайте, чтобы использовать обычный выбор модели агента; среда выполнения проверяет поддержку разрешённого провайдера. | | `reasoningEffort` | `"low" \| "medium" \| "high" \| "xhigh"`. Соответствует разрешению `ThinkLevel` / `ReasoningLevel` OpenClaw в `auto-reply/thinking.ts`. | | `infiniteSessionConfig` | Необязательное переопределение блока SDK `infiniteSessions`, управляемого `harness.compact`. Можно безопасно оставить без изменений. | | `hooksConfig` | Необязательная нативная конфигурация `SessionHooks` Copilot SDK для обратных вызовов инструментов/MCP, пользовательских запросов, сеансов и ошибок. Отделена от переносимых обработчиков жизненного цикла OpenClaw. | | `permissionPolicy` | Необязательное переопределение обработчика SDK `onPermissionRequest` для встроенных типов инструментов SDK (`shell`, `write`, `read`, `url`, `mcp`, `memory`, `hook`). По умолчанию в качестве страховки используется `rejectAllPolicy`; почему он никогда не вызывается, см. в разделе [Разрешения и ask_user](#permissions-and-ask_user). | | `enableSessionTelemetry` | Необязательный флаг телеметрии сеанса SDK. | Для обработчиков плагинов 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. ## Связанные материалы - [Среды выполнения агентов](/ru/concepts/agent-runtimes) - [Обвязка Codex](/ru/plugins/codex-harness) - [Плагины обвязки агентов (справочник SDK)](/ru/plugins/sdk-agent-harness)