Copilot SDK harness

Copilot SDK harness 문서는 OpenClaw 공식 문서(plugins/copilot)를 한국어로 정리한 가이드입니다. Run OpenClaw embedded agent turns through the external GitHub Copilot SDK harness 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Run OpenClaw embedded agent turns through the external GitHub Copilot SDK harness

한국어 가이드 범위: plugins/copilot 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

요구사항
설치
Quickstart
Supported providers
BYOK
Auth
Configuration surface
Compaction
Transcript mirroring
Side questions (/btw)
Doctor
제한 사항
Permissions and ask_user
Session-level GitHub token
관련 문서

상세 내용

본문

The external @openclaw/copilot plugin runs embedded subscription Copilot agent turns through the GitHub Copilot CLI (@github/copilot-sdk) instead of OpenClaw's built-in harness. The Copilot CLI session owns the low-level agent loop: native tool execution, native compaction (infiniteSessions), and CLI-managed thread state under copilotHome. OpenClaw still owns chat channels, session files, model selection, dynamic tools (bridged), approvals, media delivery, the visible transcript mirror, /btw side questions (see Side questions (/btw)), and openclaw doctor.

요구사항

plugin declares). An allowlist entry for the npm package name @openclaw/copilot will not match and leaves the plugin blocked, even with agentRuntime.id: "copilot" set.

주요 항목:

OpenClaw with the @openclaw/copilot plugin installed.
If your config uses plugins.allow, include copilot (the manifest id the
A GitHub Copilot subscription that can drive the Copilot CLI, or a
A writable copilotHome directory. Defaults to <agentDir>/copilot when

설치

The Copilot runtime ships as an external plugin so the core openclaw package does not carry @github/copilot-sdk or its platform-specific @github/copilot-- CLI binary (roughly 260 MB together). Install it only for agents that opt into this runtime:

openclaw plugins install @openclaw/copilot

Quickstart

Pin one model (or one provider) to the harness:

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

Supported providers

The harness supports the canonical github-copilot provider (owned by extensions/github-copilot), plus custom models.providers entries when the model has a non-empty baseUrl and one of these api shapes:

주요 항목:

anthropic-messages
azure-openai-responses
ollama (OpenAI-compatible completions)
openai-completions
openai-responses

BYOK

Copilot BYOK uses the SDK's session-level custom provider contract. OpenClaw passes the resolved model endpoint, API key, bearer-token mode, headers, model id, and context/output limits; provider transport logic stays in the SDK, not core.

{
  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" }],
      },
    },
  },
}

Auth

Precedence, applied per agent during runCopilotAttempt:

Configuration surface

The harness reads config from per-attempt input (runCopilotAttempt({...})) plus a small set of env defaults inside extensions/copilot/src/:

Field	Purpose
`copilotHome`	Per-agent CLI state directory (defaults above).
`model`	String or `{ provider, id, api?, baseUrl?, headers?, authHeader? }`. Omit to use the agent's normal model selection; the harness verifies the resolved provider is supported.
`reasoningEffort`	`"low" \| "medium" \| "high" \| "xhigh"`. Maps from OpenClaw's `ThinkLevel` / `ReasoningLevel` resolution in `auto-reply/thinking.ts`.
`infiniteSessionConfig`	Optional override for the SDK `infiniteSessions` block driven by `harness.compact`. Safe to leave as-is.
`hooksConfig`	Optional native Copilot SDK `SessionHooks` config for tool/MCP, user-prompt, session, and error callbacks. Separate from OpenClaw's portable lifecycle hooks.
`permissionPolicy`	Optional override for the SDK's `onPermissionRequest` handler for built-in SDK tool kinds (`shell`, `write`, `read`, `url`, `mcp`, `memory`, `hook`). Defaults to `rejectAllPolicy` as a safety net; see Permissions and ask_user for why it never actually fires.
`enableSessionTelemetry`	Optional SDK session telemetry flag.

Compaction

When harness.compact runs, the Copilot SDK harness:

Transcript mirroring

runCopilotAttempt dual-writes each turn's mirrorable messages into the OpenClaw audit transcript via extensions/copilot/src/dual-write-transcripts.ts. The mirror is scoped per session (copilot:${sessionId}) and keyed per message (${role}:${sha256_16(role,content)}), so re-emitted prior-turn entries collide with existing on-disk keys instead of duplicating.

Side questions (/btw)

/btw is not native on this harness. createCopilotAgentHarness() deliberately leaves harness.runSideQuestion undefined (asserted in extensions/copilot/harness.test.ts, describe("runSideQuestion")), so OpenClaw's /btw dispatcher (src/agents/btw.ts) falls through to the same path it uses for every non-Codex runtime: the configured model provider is called directly with a short side-question prompt and streamed back via streamSimple (no CLI session, no extra pool slot).

Doctor

extensions/copilot/doctor-contract-api.ts is auto-loaded by src/plugins/doctor-contract-registry.ts. It contributes:

주요 항목:

An empty legacyConfigRules (no retired fields yet).
A no-op normalizeCompatibilityConfig (kept so future field retirements
One sessionRouteStateOwners entry: provider github-copilot, runtime

제한 사항

Manifest-owned native provider ids stay on their owning runtime even when agentRuntime.id is forced to copilot.

주요 항목:

The harness claims github-copilot plus unowned custom BYOK provider ids.
No TUI surface; PI's TUI remains the fallback for runtimes without a peer
PI session state does not migrate when an agent switches to copilot.
ask_user uses the provider-neutral gateway question runtime. The Control

Permissions and ask_user

Permission enforcement for bridged OpenClaw tools happens inside the tool wrapper, not via the SDK's onPermissionRequest callback. The same wrapToolWithBeforeToolCallHook that PI uses (src/agents/agent-tools.before-tool-call.ts) is applied by createOpenClawCodingTools to every coding tool: loop detection, trusted plugin policies, before-tool-call hooks, and two-phase plugin approvals via the gateway (plugin.approval.request) all run through the exact same code path as native PI attempts.

주요 항목:

overridesBuiltInTool: true — replaces the Copilot CLI's built-in tool of
skipPermission: true — tells the SDK not to fire

Session-level GitHub token

The Copilot SDK contract distinguishes the client-level GitHub token (CopilotClientOptions.gitHubToken, authenticates the CLI process itself) from the session-level token (SessionConfig.gitHubToken, determines content exclusion, model routing, and quota for that session; honored on both createSession and resumeSession). The harness resolves auth once via resolveCopilotAuth and sets both fields when the auth mode is gitHubToken (an explicit auth.gitHubToken or a contract-resolved resolvedApiKey from a configured github-copilot auth profile). When the resolved mode is useLoggedInUser, the session-level field is omitted so the SDK keeps deriving identity from the logged-in identity.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/copilot
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw plugins install @openclaw/copilot

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

{
  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" }],
      },
    },
  },
}

Copilot SDK harness

핵심 요약

Run OpenClaw embedded agent turns through the external GitHub Copilot SDK harness

한국어 가이드 범위: plugins/copilot 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

요구사항
설치
Quickstart
Supported providers
BYOK
Auth
Configuration surface
Compaction
Transcript mirroring
Side questions (/btw)
Doctor
제한 사항
Permissions and ask_user
Session-level GitHub token
관련 문서

상세 내용

본문

요구사항

plugin declares). An allowlist entry for the npm package name @openclaw/copilot will not match and leaves the plugin blocked, even with agentRuntime.id: "copilot" set.

주요 항목:

OpenClaw with the @openclaw/copilot plugin installed.
If your config uses plugins.allow, include copilot (the manifest id the
A GitHub Copilot subscription that can drive the Copilot CLI, or a
A writable copilotHome directory. Defaults to <agentDir>/copilot when

설치

openclaw plugins install @openclaw/copilot

Quickstart

Pin one model (or one provider) to the harness:

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

Supported providers

주요 항목:

anthropic-messages
azure-openai-responses
ollama (OpenAI-compatible completions)
openai-completions
openai-responses

BYOK

{
  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" }],
      },
    },
  },
}

Auth

Precedence, applied per agent during runCopilotAttempt:

Configuration surface

The harness reads config from per-attempt input (runCopilotAttempt({...})) plus a small set of env defaults inside extensions/copilot/src/:

Field	Purpose
`copilotHome`	Per-agent CLI state directory (defaults above).
`model`	String or `{ provider, id, api?, baseUrl?, headers?, authHeader? }`. Omit to use the agent's normal model selection; the harness verifies the resolved provider is supported.
`reasoningEffort`	`"low" \| "medium" \| "high" \| "xhigh"`. Maps from OpenClaw's `ThinkLevel` / `ReasoningLevel` resolution in `auto-reply/thinking.ts`.
`infiniteSessionConfig`	Optional override for the SDK `infiniteSessions` block driven by `harness.compact`. Safe to leave as-is.
`hooksConfig`	Optional native Copilot SDK `SessionHooks` config for tool/MCP, user-prompt, session, and error callbacks. Separate from OpenClaw's portable lifecycle hooks.
`permissionPolicy`	Optional override for the SDK's `onPermissionRequest` handler for built-in SDK tool kinds (`shell`, `write`, `read`, `url`, `mcp`, `memory`, `hook`). Defaults to `rejectAllPolicy` as a safety net; see Permissions and ask_user for why it never actually fires.
`enableSessionTelemetry`	Optional SDK session telemetry flag.

Compaction

When harness.compact runs, the Copilot SDK harness:

Transcript mirroring

Side questions (/btw)

Doctor

extensions/copilot/doctor-contract-api.ts is auto-loaded by src/plugins/doctor-contract-registry.ts. It contributes:

주요 항목:

An empty legacyConfigRules (no retired fields yet).
A no-op normalizeCompatibilityConfig (kept so future field retirements
One sessionRouteStateOwners entry: provider github-copilot, runtime

제한 사항

Manifest-owned native provider ids stay on their owning runtime even when agentRuntime.id is forced to copilot.

주요 항목:

The harness claims github-copilot plus unowned custom BYOK provider ids.
No TUI surface; PI's TUI remains the fallback for runtimes without a peer
PI session state does not migrate when an agent switches to copilot.
ask_user uses the provider-neutral gateway question runtime. The Control

Permissions and ask_user

주요 항목:

overridesBuiltInTool: true — replaces the Copilot CLI's built-in tool of
skipPermission: true — tells the SDK not to fire

Session-level GitHub token

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/copilot
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw plugins install @openclaw/copilot

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

{
  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" }],
      },
    },
  },
}

Copilot SDK harness

핵심 요약

문서 구성

상세 내용

본문

요구사항

설치

Quickstart

Supported providers

BYOK

Auth

Configuration surface

Compaction

Transcript mirroring

Side questions (/btw)

Doctor

제한 사항

Permissions and ask_user

Session-level GitHub token

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Copilot SDK harness

핵심 요약

문서 구성

상세 내용

본문

요구사항

설치

Quickstart

Supported providers

BYOK

Auth

Configuration surface

Compaction

Transcript mirroring

Side questions (/btw)

Doctor

제한 사항

Permissions and ask_user

Session-level GitHub token

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드