GitHub Copilot is GitHub's AI coding assistant. It provides access to Copilot models for your GitHub account and plan. Apus can use Copilot as a model provider or agent runtime in three different ways.

Three ways to use Copilot in Apus

Built-in provider (github-copilot)

Use the native device-login flow to obtain a GitHub token. By default,
Apus puts the token in its protected local secret store and saves only a
`tokenRef` in the auth profile. When Apus runs, it validates Copilot access
and resolves the account-specific Copilot API endpoint. This is the **default**
and simplest path because it does not require VS Code.

Run the login command

    ```bash
    apus models auth login-github-copilot
    ```

    You will be prompted to visit a URL and enter a one-time code. Keep the
    terminal open until it completes.

Set a default model

    ```bash
    apus models set github-copilot/claude-sonnet-5
    ```

    Or in config:

    ```json5
    {
      agents: {
        defaults: { model: { primary: "github-copilot/claude-sonnet-5" } },
      },
    }
    ```

Copilot SDK harness plugin (copilot)

Install the external `@openclaw/copilot` plugin when you want GitHub's
Copilot CLI and SDK to own the low-level agent loop for selected
`github-copilot/*` models.

```bash
apus plugins install @openclaw/copilot
```

Then opt a model or provider into the runtime:

```json5
{
  agents: {
    defaults: {
      model: "github-copilot/gpt-5.6-sol",
      models: {
        "github-copilot/gpt-5.6-sol": {
          agentRuntime: { id: "copilot" },
        },
      },
    },
  },
}
```

Choose this when you want native Copilot CLI sessions, SDK-managed thread
state, and Copilot-owned compaction for those agent turns. Without the
explicit `agentRuntime` opt-in, `github-copilot/*` models keep using the
built-in provider. See [Copilot SDK harness](/plugins/copilot) for the full
runtime contract.

Copilot Proxy plugin (copilot-proxy)

Use the **Copilot Proxy** VS Code extension as a local bridge. Apus talks to
the proxy's `/v1` endpoint (default `http://localhost:3000/v1`) and uses the
model list you configure.

The `copilot-proxy` plugin ships with Apus and is enabled by default.
Configure the base URL and model ids with:

```bash
apus models auth login --provider copilot-proxy --set-default
```

Choose this when you already run Copilot Proxy in VS Code or need to route
through it. The VS Code extension must stay running.

GitHub Enterprise (data residency)

If your organization uses a data-residency GitHub Enterprise tenant (a *.ghe.com host such as your-org.ghe.com), Copilot lives on tenant-local endpoints rather than public github.com. Apus exposes this as a first-class auth choice so you do not have to hand-edit URLs.

Pick the Enterprise auth choice

In onboarding or `apus models auth`, choose
**GitHub Copilot (Enterprise / data residency)**. You will be prompted for
your Enterprise domain (for example `your-org.ghe.com`), then the device
login runs against that tenant.

Enter the tenant root only (`your-org.ghe.com`). Derived service hosts such
as `api.your-org.ghe.com` or `copilot-api.your-org.ghe.com` are not accepted;
Apus derives those endpoints from the tenant root automatically.

```bash
apus models auth login --provider github-copilot --method device-enterprise
```

Domain is persisted to config

The chosen host is stored under the provider params so later account
validation and completions target the tenant automatically:

```json5
{
  models: {
    providers: {
      "github-copilot": { params: { githubDomain: "your-org.ghe.com" } },
    },
  },
}
```

The device flow and account validation use the tenant's GitHub endpoints, and Copilot requests use https://copilot-api.your-org.ghe.com. This keeps both authentication and inference on the configured data-residency tenant instead of the public endpoints.

Switching domains always re-runs the device login. If you already have a stored Copilot token and pick a different domain (public github.com ↔ a *.ghe.com tenant, or one tenant to another), Apus will not reuse the existing token — it forces a fresh login so the token is scoped to the domain being written to config. Re-running login for the same domain still offers to reuse the current token. Switching back to public github.com clears the persisted githubDomain so config returns to the default.

Agents share Copilot credentials only when their normalized, supported tenant scopes match; Doctor preserves credentials for different tenants, so authenticate each affected agent for its intended tenant instead of deleting its local credential.

The COPILOT_GITHUB_DOMAIN environment variable overrides the resolved domain for every Copilot path that resolves it — the Enterprise device login (--method device-enterprise), the standalone apus models auth login-github-copilot shortcut, account validation, embeddings, and completions. Set it to your *.ghe.com host for fully headless or CI setups. Leave it unset (and the config param absent) to use public github.com. Logins persist the domain they minted the token for (and clear it when logging in against public github.com), so routing stays correct even after the environment variable is unset.

Tenant request identity

Apus uses the copilot-developer-cli request identity by default, including for data-residency tenants. First confirm that your enterprise permits Copilot CLI and the selected model. A *.ghe.com hostname does not imply a different integration policy.

If your tenant administrator or GitHub support requires a different identity, use the existing provider header setting:

{
  models: {
    providers: {
      "github-copilot": {
        params: { githubDomain: "your-org.ghe.com" },
        headers: { "Copilot-Integration-Id": "vscode-chat" },
      },
    },
  },
}

The provider identity applies to model selection during setup, live model discovery, inference, and embeddings. Header names are case-insensitive; request.headers takes precedence over provider headers. Embedding-specific memory.search.remote.headers still takes precedence for embedding discovery and requests. Unrelated provider headers are not forwarded to the catalog or embedding endpoints. Changing the identity does not grant access to models or clients disabled by your organization's policy.

Optional flags

Command Flag Description
apus models auth login-github-copilot --yes Overwrite an existing auth profile without prompting
apus models auth login --provider github-copilot --method device --set-default Also apply the provider's recommended default model 
# Skip the re-login confirmation
apus models auth login-github-copilot --yes

# Login and set the default model in one step
apus models auth login --provider github-copilot --method device --set-default

Non-interactive onboarding

The device-login flow requires an interactive TTY. For headless setup, import an existing GitHub OAuth access token with apus onboard --non-interactive:

apus onboard --non-interactive --accept-risk \
  --auth-choice github-copilot \
  --github-copilot-token "$COPILOT_GITHUB_TOKEN" \
  --skip-channels --skip-health

You can also omit --auth-choice; passing --github-copilot-token infers the GitHub Copilot provider auth choice. If the flag is omitted, onboarding falls back to COPILOT_GITHUB_TOKEN. Generic GH_TOKEN and GITHUB_TOKEN do not enable or authenticate the provider. Use --secret-input-mode ref with COPILOT_GITHUB_TOKEN set to store an env-backed tokenRef instead of plaintext in the auth profile store.

Fresh non-interactive setup validates the token before saving it. When setup must choose a default, it also checks the live Copilot model catalog. Apus prefers the provider's current general-purpose model when that model is enabled for the account; otherwise it chooses a deterministic eligible fallback. Setup fails without writing a new auth profile if the account has no picker-visible model that supports streaming and tool calls. An explicitly configured default model is never replaced.

Interactive TTY required 
The device-login flow requires an interactive TTY. Run it directly in a
terminal, not in a non-interactive script or CI pipeline.
Model availability depends on your plan 
Copilot model availability depends on your GitHub plan and organization
policy. Interactive onboarding uses the live catalog for its model picker,
while non-interactive onboarding selects an eligible model automatically. See
GitHub's [supported models per Copilot plan](https://docs.github.com/en/copilot/reference/ai-models/supported-models#supported-ai-models-per-copilot-plan)
for the current model list.
Live catalog refresh from the Copilot API 
Once the device-login (or env-var) auth path has resolved a GitHub token,
Apus refreshes the model catalog on demand from `${baseUrl}/models`
(the same endpoint VS Code Copilot uses) so the runtime tracks
per-account entitlement and accurate context windows without manifest
churn. The visible live catalog excludes models hidden from GitHub's picker
or disabled by account policy. Automatic setup defaults additionally require
streaming and tool-call support.
Newly published Copilot models become visible without an Apus upgrade,
and context windows reflect the real per-model limits
(e.g. 400k for the gpt-5.x series, 1M for the internal
`claude-opus-*-1m` variants).

Failed refreshes report the failure and retain the last successful inventory,
or bundled models before the first success. A successful empty response clears
discovered models. Missing Copilot credentials makes no live request.
Copilot requires explicit provider configuration, a saved Copilot auth
profile, or `COPILOT_GITHUB_TOKEN`, within the agent's model scope.
The old `plugins.entries.github-copilot.config.discovery.enabled` switch
is retired. Config loading ignores it, and Doctor removes it when saving
the config. It no longer prevents live requests for configured Copilot auth.
Transport selection 
Claude model IDs use the Anthropic Messages transport automatically.
Gemini models use the OpenAI Chat Completions transport; GPT and o-series
models keep the OpenAI Responses transport. The bundled static catalog
includes these transports and request compatibility settings, so Gemini
keeps using Chat Completions when live discovery is unavailable. When your
account's model list names the endpoints a model supports and the default
transport is not among them, Apus uses a listed endpoint instead, so
Chat Completions-only models such as `kimi-k3` work.
Thinking levels 
Use `/think xhigh` or `/think max` when the selected model exposes that
level. Copilot's live catalog determines the supported efforts for your
account, and Apus preserves those efforts in Responses requests.
When a Responses model starts its native effort range at `low`, `minimal`
maps to `low` instead of sending an unsupported value.
Explicit live limits take precedence over the bundled catalog. Gemini's
Chat Completions transport does not expose `max`. A Claude model whose live
entry lists `xhigh` uses adaptive thinking even before Apus recognizes
its model ID.
See [Thinking levels](/tools/thinking) for session and per-message controls.
Request compatibility 
Apus sends Copilot-compatible request headers with a Copilot CLI request
identity, marks tool-result follow-up turns as agent-initiated, and sets the
Copilot vision header when a turn carries image input.
Environment credentials 
`COPILOT_GITHUB_TOKEN` is the only automatic environment credential for
this provider. Generic `GH_TOKEN` and `GITHUB_TOKEN` remain available to
other GitHub tools and remain covered by secret auditing and cleanup.
Doctor reports the activation change once when only generic GitHub auth
is present, with instructions to sign in or set `COPILOT_GITHUB_TOKEN`.

The device-login flow stores a protected-store `tokenRef` in the Copilot
auth profile. An explicitly selected profile stays selected; an unscoped
lookup can use `COPILOT_GITHUB_TOKEN` before the first saved profile.
Token storage 
By default, device login stores the GitHub token in Apus's protected local
secret store and writes only a `tokenRef` to the auth profile (profile id
`github-copilot:github`). The built-in store does not require a configured
external secret provider. If Apus cannot write the store, login stops
before replacing the auth profile and reports that the state-directory or
database permissions need repair.

Interactive onboarding honors an explicit `--secret-input-mode plaintext`
choice for compatibility. That mode stores the token inline, reports the
choice, and remains visible to `apus secrets audit --check`.

The protected store is write-only through Apus's user-facing secret APIs,
but it is not encrypted at rest; its SQLite file relies on state-directory
permissions. At runtime, Apus resolves the reference, validates Copilot
access, resolves the account-specific API endpoint, and uses the GitHub token
for Copilot requests. You do not need to manage runtime authentication
manually.

Usage checks also use the selected profile's GitHub token. For OAuth profiles
that carry a tenant domain, usage follows that domain before the provider's
configured domain. `COPILOT_GITHUB_DOMAIN` still takes precedence.

Memory search embeddings

GitHub Copilot can also serve as an embedding provider for memory search. If you have a Copilot subscription and have logged in, Apus can use it for embeddings without a separate API key.

Config

Set memory.search.provider explicitly to use GitHub Copilot embeddings. If a GitHub token is available, Apus discovers available embedding models from the Copilot API and picks the best one automatically.

{
  memory: {
    search: {
      provider: "github-copilot",
      // Optional: override the auto-discovered model
      model: "text-embedding-3-small",
    },
  },
}

How it works

  1. Apus resolves your GitHub token (from env vars or auth profile).
  2. Validates Copilot access and resolves the account-specific API endpoint.
  3. Queries the Copilot /models endpoint to discover available embedding models, with a 10-second deadline that includes reading the response body.
  4. Picks the best model (preference order: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002).
  5. Sends embedding requests to the Copilot /embeddings endpoint.

Model availability depends on your GitHub plan. If discovery fails or no embedding models are available, Apus uses memory.search.fallback only when you explicitly configure another provider. Otherwise, setup reports the error instead of silently selecting a different provider.

Related

Model selection

Choosing providers, model refs, and failover behavior.

OAuth and auth

Auth details and credential reuse rules.