Обв’язка Copilot SDK

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

Огляд ширшого розподілу між моделлю, постачальником і середовищем виконання почніть із розділу Середовища виконання агентів.

Вимоги

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

openclaw doctor виконує контракт doctor Plugin для володіння станом сеансів і майбутніх міграцій конфігурації. Він не перевіряє середовище Copilot CLI.

Встановлення

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

openclaw plugins install @openclaw/copilot

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

Середовище виконання шукає 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 проксі local loopback для кожної спроби, а потім переспрямовує трафік постачальника через захищений шлях отримання даних 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/:

Хуки Plugin 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 не потрібно знати про ці поля. Інші Plugins, канали та основний код бачать лише стандартну форму AgentHarnessAttemptParams / AgentHarnessAttemptResult.

Compaction

Коли виконується harness.compact, засіб виконання Copilot SDK:

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

Дзеркальна копія стенограми на боці OpenClaw (нижче) продовжує отримувати повідомлення після Compaction, тому історія чату, видима користувачеві, залишається узгодженою.

Дзеркальне відтворення стенограми

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.

Діагностика

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 з такою самою назвою (редагування, читання, запис, 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)