Copilot SDK harness

​

要求

• 安装了 @openclaw/copilot 插件的 OpenClaw。
• 如果你的配置使用了 plugins.allow，请包含 copilot（插件声明的 manifest id）。针对 npm 包名 @openclaw/copilot 的允许列表项不会匹配，即使设置了 agentRuntime.id: "copilot" 也会使插件被阻止。
• 一个可以驱动 Copilot CLI 的 GitHub Copilot 订阅，或者用于无头运行或定时任务运行的 gitHubToken 环境变量 / auth-profile 条目。
• 一个可写的 copilotHome 目录。当 OpenClaw 提供 agent 目录时，默认为 <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" },
        },
      },
    },
  },
}

​

支持的 provider

• 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. 在 attempt 输入中显式设置 useLoggedInUser: true —— 使用 该 agent 的 copilotHome 下 Copilot CLI 已登录的用户。
2. 在 attempt 输入中显式设置 gitHubToken（需要 profileId + profileVersion）。用于直接调用 CLI 和需要绕过 auth-profile 解析的测试。
3. 合约解析得到的 resolvedApiKey + authProfileId —— 生产环境 主路径。Core 在调用 harness 之前会先解析 agent 配置的 github-copilot auth profile（src/infra/provider-usage.auth.ts:resolveProviderAuths）， 因此 github-copilot:<profile> auth profile 可以在无头、cron 或多 profile 场景中端到端工作，而无需环境变量。
4. 环境变量回退，按以下顺序检查（第一个非空值生效，空字符串视为缺失；与 已发布的 github-copilot provider 优先级一致，见 extensions/github-copilot/auth.ts）：
   1. OPENCLAW_GITHUB_TOKEN —— harness 专用覆盖；可让你为 OpenClaw harness 固定一个 token，而不影响系统范围的 gh / Copilot CLI 配置。
   2. COPILOT_GITHUB_TOKEN —— 标准 Copilot SDK / CLI 环境变量。
   3. GH_TOKEN —— 标准 gh CLI 环境变量。
   4. GITHUB_TOKEN —— 通用 GitHub token 回退。
   合成的 pool profile id 为 env:<NAME>；profile version 是 token 的 不可逆 sha256 指纹，因此轮换环境变量值时会干净地使客户端池失效。
5. 在没有 token 信号时的默认 useLoggedInUser。

​

配置面

​

压缩

1. 在不继续未完成工作的情况下恢复已跟踪的 SDK 会话。
2. 调用 SDK 的会话作用域历史压缩 RPC。
3. 返回 SDK 的压缩结果，而不在工作区下写入兼容性标记 文件。

​

转录镜像

​

侧边问题（/btw）

​

Doctor

• 空的 legacyConfigRules（目前尚无已弃用字段）。
• 无操作的 normalizeCompatibilityConfig（保留此项，以便未来弃用字段时 在代码库中拥有稳定的归属位置）。
• 其清单声明了一个 sessionRouteStateOwners 条目：提供方为 github-copilot，运行时为 copilot，CLI 会话键为 copilot，身份验证配置文件前缀为 github-copilot:。

​

局限性

• 该 harness 声称支持 github-copilot 以及未被拥有的自定义 BYOK provider id。 Manifest 所拥有的原生 provider id 仍由其所属的 runtime 处理，即使将 agentRuntime.id 强制设为 copilot。
• 没有 TUI 界面；对于没有对等界面的 runtime，PI 的 TUI 仍是备用方案。
• 当 agent 切换到 copilot 时，PI 会话状态不会迁移。 选择按每次尝试进行；现有的 PI 会话仍然有效。
• ask_user 使用与 provider 无关的网关提问 runtime。Control UI 显示与其他 OpenClaw 问题相同的问题卡片，受支持的渠道会渲染选项按钮，并且下一条排队中的纯文本消息会在 SDK 请求返回前解析该网关记录。

​

权限和 ask_user

• overridesBuiltInTool: true — 替换 Copilot CLI 中同名的内置工具（edit、read、write、bash、…），因此每次工具调用都会路由回 OpenClaw。
• skipPermission: true — 告诉 SDK 在调用工具之前不要触发 onPermissionRequest({kind: "custom-tool"})。包装后的 execute() 已经执行了更丰富的 OpenClaw 策略检查；如果在 SDK 层再弹出提示，要么会短路 OpenClaw 的强制执行（全部允许），要么会阻止每一次工具调用（全部拒绝）——这两种情况都不符合 PI 的对等行为。

​

会话级 GitHub token

​

相关

• Agent 运行时
• Codex harness
• Agent harness 插件（SDK 参考）