Обв’язка 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 MB). Встановлюйте його лише для агентів, які явно використовують це середовище виконання:

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 через стандартні допоміжні функції рушія. Після успішних ущільнень 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, доступних через міст, виконується всередині обгортки інструмента, а не через зворотний виклик onPermissionRequest SDK. Той самий 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). Еквівалент Copilot SDK — 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.

Міст також використовує спільний допоміжний засіб поверхні інструментів каркаса з 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)