The harness claims its provider, runtime, CLI session key, and auth profile

prefix in `extensions/copilot/doctor-contract-api.ts`, which

`openclaw doctor` auto-loads. For configuration, auth, transcript mirroring,

compaction, the doctor probe surface, and the broader PI vs Codex vs Copilot

SDK decision, see [GitHub Copilot agent runtime](/plugins/copilot).

compaction, the declarative doctor contract, and the broader PI vs Codex vs

Copilot SDK decision, see [GitHub Copilot agent runtime](/plugins/copilot).

## Compatibility contract

- A GitHub Copilot subscription that can drive the Copilot CLI (or a

`gitHubToken` env / auth-profile entry for headless / cron runs).

- A writable `copilotHome` directory. The harness defaults to

`~/.openclaw/agents/<agentId>/copilot` for full per-agent isolation. The

platform default (`%APPDATA%\copilot` on Windows, `$XDG_CONFIG_HOME/copilot`

or `~/.config/copilot` elsewhere) is used as the doctor probe fallback when

no explicit home is set.

`<agentDir>/copilot` when OpenClaw provides an agent directory, otherwise

`~/.openclaw/agents/<agentId>/copilot` for full per-agent isolation.

`openclaw doctor` runs the plugin

[doctor contract](#doctor-and-probes) for the extension; failures there are

the canonical way to confirm the environment is ready before opting an agent

in.

[doctor contract](#doctor) for declarative session-state ownership and future

compatibility migrations. It does not run Copilot CLI environment probes.

## Plugin install

Override with `copilotHome: <path>` on the attempt input when you need a

custom location (for example, a shared mount for migration).

`probeCopilotAuthShape` (see [Doctor and probes](#doctor-and-probes)) is the

pure shape check that validates which of the modes above will be used.

It does not perform a live SDK handshake.

## Configuration surface

The harness reads its config from per-attempt input

[`extensions/copilot/harness.test.ts`](https://github.com/openclaw/openclaw/blob/main/extensions/copilot/harness.test.ts)

under `describe("runSideQuestion")`.

## Doctor and probes

## Doctor

`extensions/copilot/doctor-contract-api.ts` is auto-loaded by

`src/plugins/doctor-contract-registry.ts`. It contributes:

runtime `copilot`; CLI session key `copilot`; auth profile

prefix `github-copilot:`.

`extensions/copilot/src/doctor-probes.ts` exports three imperative probes

that hosts (including `openclaw doctor`) can call to verify the environment:

| Probe | What it checks | Reasons it can fail |

| -------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |

| `probeCopilotCliVersion` | `copilot --version` exits 0 with a non-empty version string | `non-zero-exit`, `empty-version`, `spawn-failed`, `spawn-error`, `probe-timeout` |

| `probeCopilotHomeWritable` | `mkdir -p copilotHome` + write + rm a marker file | `copilothome-not-writable` (with the underlying fs error in `details.rawError`) |

| `probeCopilotAuthShape` | At least one of `useLoggedInUser`, `gitHubToken`, or `profileId`+`profileVersion` | `no-auth-source` |

Each probe accepts a DI seam (`spawnFn`, `fsApi`) so tests do not spawn the

real Copilot CLI or touch the host fs.

## Limitations

- The harness only claims the canonical `github-copilot` provider at MVP.

embedded runtime.

See [GitHub Copilot agent runtime](../../docs/plugins/copilot.md) for

configuration, doctor probes, transcript mirroring, compaction, side

configuration, the doctor contract, transcript mirroring, compaction, side

questions, replay, and the supported-surface contract.

See [qa/copilot-capabilities.md](../../qa/copilot-capabilities.md)

for the SDK capability inventory the harness is pinned to.

* fields exist for copilot yet; the array is empty by design

* and normalizeCompatibilityConfig is a structural no-op so

* future retirements have a stable in-tree home.

*

* The deeper runtime probes (copilot CLI version, copilot auth,

* copilotHome writability) live in {@link ./src/doctor-probes.ts}

* because they have side effects (subprocess spawn, fs touch) and

* need to be invoked imperatively, not declaratively, from the

* doctor command. They are exported separately so callers can opt

* in. Auto-discovery of doctor-contract-api.ts at the plugin root

* keeps this file purely declarative.

*/

import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";