# Copilot CLI

使用 XMEMO_KEY 和稳定的实例归属配置直接承载令牌 Copilot CLI MCP 客户端。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/copilot-cli
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 3d18b1df6bc7de8f1e1af14a294640eb5bf7a2d0176a2523f2f62b790b975e99
- Edition-Digest: 40ff6eef9ebc31690f44a757a8b71e56a5689b7fcc2d8624b1c1f3c2213034f9
- Source-Revision: sha256:96e19501d8a5b0d1cc66043cdcd452344580fd7ffafd84f8562409ac6df29e12

## 前置条件

使用支持 MCP 配置的 GitHub Copilot CLI。该路径特意与 VS Code / GitHub Copilot Chat 的 OAuth 路径区分开。Copilot CLI 支持在 ~/.copilot/mcp-config.json 中配置自定义 HTTP 请求头，或通过 memory-os-cli 接入本地代理。

- 端点：https://xmemo.dev/mcp。
- 传输协议：Streamable HTTP（配置中声明 type: "http"）或本地代理（xmemo mcp proxy）。
- 认证方式：通过 Copilot 官方 MCP UI/CLI 或受支持的密钥引用填入 Authorization；请勿假设请求头中会自动展开环境变量（${env:…}）。
- 配置文件：~/.copilot/mcp-config.json。
- 就绪状态：Copilot CLI 请求头中的环境变量直接展开为 not-tested；本地代理路径已通过 memory-os-cli 的 MCP-SETUP-GUIDE.md 验证。

## 安装 / 设置

将 XMemo 服务块添加至 ~/.copilot/mcp-config.json 的 mcpServers 下，或通过 memory-os-cli 本地代理运行。不要复用 VS Code 的 servers 键配置；Copilot CLI 属于不同的客户端路径。

- 直接远程 HTTP：在 ~/.copilot/mcp-config.json 中添加带有 type: "http", url: "https://xmemo.dev/mcp", timeout: 30000 及 tools: ["*"] 的 XMemo 配置块。
- 本地代理路径：运行 xmemo setup copilot，并在后台终端保持运行 xmemo mcp proxy（参考 memory-os-cli 的 MCP-SETUP-GUIDE.md）。
- 请求头中直接展开环境变量（${env:XMEMO_KEY}）属于 not-tested 状态，Core 模板暂不提供支持。

```bash
# Local proxy path (recommended if direct remote HTTP is unsupported):
xmemo login
xmemo setup copilot
xmemo mcp proxy  # keep running in a background terminal
```

## 设置凭据

使用 Copilot 官方 MCP UI/CLI 或受支持的密钥引用设置 Authorization 请求头的值（将 <replace-with-XMEMO_KEY-or-supported-secret-reference> 替换为您真实的 Token）。使用本地代理时，xmemo login 会自动管理该凭据。

```bash
# For local proxy:
xmemo login
# For direct configuration, apply token through Copilot CLI or supported secret reference
```

## 生成 / 确认 XMEMO_AGENT_INSTANCE_ID

每个本地 Copilot CLI install 生成一个非机密值，将它保存在 git 外，并在重启后复用，使 attribution 保持稳定。

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-copilot-cli-instance-id>'
# Persist and reuse this value for the same local install
```

## 保留现有配置块

使用与 Core 模板（mcp_config.py:267）匹配的权威 Copilot CLI XMemo 配置块。通过 Copilot 官方 MCP UI/CLI 或受支持的密钥引用填入真实的 Authorization 值；请勿依赖未经检验的 ${env:XMEMO_KEY} 请求头展开。

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "tools": [
        "*"
      ],
      "timeout": 30000,
      "headers": {
        "Authorization": "Bearer <replace-with-XMEMO_KEY-or-supported-secret-reference>",
        "X-Memory-OS-Agent-ID": "copilot-cli",
        "X-Memory-OS-Agent-Instance-ID": "<stable-local-copilot-cli-instance-id>"
      }
    }
  }
}
```

## 重启客户端

修改 mcp-config.json 后重启 Copilot CLI。如果使用本地代理，请在重启 Copilot CLI 前确保后台终端中的 'xmemo mcp proxy' 保持运行状态。

## 使用真实 recall call 测试

第一次 MCP call 应为只读。这是实际的 recall invocation，不是 health-check placeholder，也不会写入 memory。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（literal shape）

成功调用会返回下面的公开 ranked text shape；reference 和 content 是来自已授权 memory space 的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## 常见错误

Copilot CLI 属于直接 Token 或代理型客户端；常见错误多与认证 Token、代理生命周期或权限范围授权相关。

- 401 invalid_token — XMEMO_KEY 缺失、已过期、已被撤销或未展开：检查当前生效的密钥引用，或为本地代理重新运行 xmemo login。
- 403 insufficient_scope — Token 未授予 memory:read 权限：请颁发包含必要权限范围的 Token。
- Connection refused — 若使用本地代理，请确认后台终端中的 xmemo mcp proxy 正常运行。
- 请求头中发送了字面量 '${env:XMEMO_KEY}' — Copilot CLI 可能不会展开请求头中的环境变量；请使用密钥引用或本地代理。
- 无效的 XMEMO_AGENT_INSTANCE_ID 值会被规范化为不附加实例归属，而不会触发认证错误。

## Copilot CLI

Direct client: set XMEMO_KEY in the user environment or a supported secret reference, then replace the stable instance placeholder before applying the reviewed config.

```
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```