Copilot SDK ハーネス

​

要件

• @openclaw/copilot Plugin がインストールされた OpenClaw。
• 設定で plugins.allow を使っている場合は、copilot（Plugin が宣言するマニフェスト ID）を含めてください。npm パッケージ名 @openclaw/copilot の許可リストエントリは一致せず、agentRuntime.id: "copilot" が設定されていても Plugin はブロックされたままになります。
• Copilot CLI を駆動できる GitHub Copilot サブスクリプション、またはヘッドレス実行や Cron 実行用の gitHubToken 環境変数 / 認証プロファイルエントリ。
• 書き込み可能な copilotHome ディレクトリ。OpenClaw がエージェントディレクトリを提供する場合の既定値は <agentDir>/copilot、それ以外の場合は ~/.openclaw/agents/<agentId>/copilot です。

​

インストール

openclaw plugins install @openclaw/copilot

1. インストール済みの @openclaw/copilot パッケージから import("@github/copilot-sdk")。
2. フォールバックディレクトリ ~/.openclaw/npm-runtime/copilot/（レガシーのオンデマンドインストール先）。

​

クイックスタート

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

​

サポートされるプロバイダー

• anthropic-messages
• azure-openai-responses
• ollama（OpenAI 互換 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" }],
      },
    },
  },
}

​

認証

1. 試行入力の 明示的な useLoggedInUser: true — エージェントの copilotHome 配下にある Copilot CLI のログイン済みユーザーを使用します。
2. 試行入力の 明示的な gitHubToken（profileId + profileVersion が必要）。認証プロファイル解決をバイパスする必要がある直接 CLI 呼び出しやテスト用です。
3. コントラクトで解決された resolvedApiKey + authProfileId — 本番のメイン経路です。コアはハーネスを呼び出す前に、エージェントに設定された github-copilot 認証プロファイル（src/infra/provider-usage.auth.ts:resolveProviderAuths）を解決するため、github-copilot:<profile> 認証プロファイルは、環境変数なしでヘッドレス、Cron、またはマルチプロファイル構成でエンドツーエンドに機能します。
4. 環境変数フォールバック。次の順序で確認されます（最初の空でない値が採用され、空文字列は未指定として扱われます。extensions/github-copilot/auth.ts にある出荷済み github-copilot プロバイダーの優先順位を反映します）。
   1. OPENCLAW_GITHUB_TOKEN — ハーネス固有の上書き。システム全体の gh / Copilot CLI 設定を乱さずに、OpenClaw ハーネス用のトークンを固定できます。
   2. COPILOT_GITHUB_TOKEN — 標準の Copilot SDK / CLI 環境変数。
   3. GH_TOKEN — 標準の gh CLI 環境変数。
   4. GITHUB_TOKEN — 汎用 GitHub トークンフォールバック。
   合成されるプールプロファイル ID は env:<NAME> です。プロファイルバージョンはトークンの不可逆 sha256 フィンガープリントであるため、環境値をローテーションするとクライアントプールがきれいに無効化されます。
5. トークン信号が利用できない場合の 既定の useLoggedInUser。

​

設定サーフェス

​

Compaction

1. 保留中の作業を続行せずに、追跡されている SDK セッションを再開します。
2. SDK のセッションスコープの履歴 Compaction RPC を呼び出します。
3. ワークスペース配下に互換性マーカーファイルを書き込まずに、SDK Compaction の結果を返します。

​

トランスクリプトミラーリング

​

サイド質問 (/btw)

​

Doctor

• 空の legacyConfigRules（まだ廃止フィールドはありません）。
• 何もしない normalizeCompatibilityConfig（将来のフィールド廃止に安定したツリー内の置き場を持たせるために維持されています）。
• 1つの sessionRouteStateOwners エントリ: プロバイダー github-copilot、ランタイム copilot、CLI セッションキー copilot、認証プロファイルプレフィックス github-copilot:。

​

制限事項

• このハーネスは github-copilot と、所有者のいないカスタム BYOK プロバイダー ID を扱うものと主張します。マニフェスト所有のネイティブプロバイダー ID は、agentRuntime.id が copilot に強制されている場合でも、その所有ランタイムに残ります。
• TUI サーフェスはありません。ピアサーフェスのないランタイムでは、PI の TUI がフォールバックのままです。
• エージェントが copilot に切り替わっても、PI セッション状態は移行されません。選択は試行ごとです。既存の PI セッションは引き続き有効です。
• ask_user は Codex ハーネスと同じ OpenClaw のプロンプトおよび返信パスを使用します。Copilot SDK がユーザー入力を求めると、OpenClaw はアクティブなチャンネル/TUI にブロッキングプロンプトを投稿し、次にキューに入ったユーザーメッセージが SDK リクエストを解決します。

​

権限と ask_user

• overridesBuiltInTool: true — 同じ名前（edit、read、write、bash など）の Copilot CLI 組み込みツールを置き換え、すべてのツール呼び出しが OpenClaw に戻るようにします。
• skipPermission: true — ツールを呼び出す前に onPermissionRequest({kind: "custom-tool"}) を発火しないよう SDK に伝えます。ラップされた execute() はすでに、より豊かな OpenClaw ポリシーチェックを実行します。SDK レベルのプロンプトは、OpenClaw の強制を短絡する（すべて許可）か、すべてのツール呼び出しをブロックする（すべて拒否）ことになり、どちらも PI との同等性に一致しません。

​

セッションレベルの GitHub トークン

​

関連

• エージェントランタイム
• Codex ハーネス
• エージェントハーネス Plugin（SDK リファレンス）