{"meta":{"title":"本地 CLI 设置","intro":"使用特定的 CLI 二进制文件，而不是 SDK 的自动 CLI 管理。 这是一个高级选项-你显式提供 CLI 路径，你负责确保与 SDK 的版本兼容性。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/how-tos","title":"操作方法"},{"href":"/zh/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/zh/copilot/how-tos/copilot-sdk/setup","title":"设置 Copilot SDK"},{"href":"/zh/copilot/how-tos/copilot-sdk/setup/local-cli","title":"本地 CLI"}],"documentType":"article"},"body":"# 本地 CLI 设置\n\n使用特定的 CLI 二进制文件，而不是 SDK 的自动 CLI 管理。 这是一个高级选项-你显式提供 CLI 路径，你负责确保与 SDK 的版本兼容性。\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n**在以下情况下使用：** 当您需要固定某个特定的 CLI 版本，或者使用 Go SDK（其不会自动包含 CLI）时。\n\n## 工作原理\n\n默认情况下，Node.js、Python和.NET SDK 包含自己的 CLI 依赖项（请参阅 [默认设置（随附的 CLI）](/zh/copilot/how-tos/copilot-sdk/setup/bundled-cli)）。 如果您需要覆盖此设置（例如，使用系统中已安装的 CLI），可以使用 `Connection` 选项。\n\n![图示：显示所述过程的流程图。](/assets/images/help/copilot/copilot-sdk/setup-local-cli-diagram-0.png)\n\n**主要特征：**\n\n* 你明确提供 CLI 二进制文件的路径\n* 你负责 CLI 版本与 SDK 的兼容性\n* 身份验证使用系统钥匙串（或环境变量）中已登录用户的凭据。\n* 通信通过 stdio 进行\n\n## 配置\n\n### 使用本地 CLI 二进制文件\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n    cliPath: \"/usr/local/bin/copilot\",\n});\n\nconst session = await client.createSession({ model: \"gpt-5.4\" });\nconst response = await session.sendAndWait({ prompt: \"Hello!\" });\nconsole.log(response?.data.content);\n\nawait client.stop();\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient\nfrom copilot.session_events import AssistantMessageData\nfrom copilot.session import PermissionHandler\n\nclient = CopilotClient({\n    \"cli_path\": \"/usr/local/bin/copilot\",\n})\nawait client.start()\n\nsession = await client.create_session(on_permission_request=PermissionHandler.approve_all, model=\"gpt-5.4\")\nresponse = await session.send_and_wait(\"Hello!\")\nif response:\n    match response.data:\n        case AssistantMessageData() as data:\n            print(data.content)\n\nawait client.stop()\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n> \\[!NOTE]\n> Go SDK 不会自动交付 CLI。 在 `PATH` 上安装 `copilot`，设置 `COPILOT_CLI_PATH` 环境变量，使用 [bundler 工具](https://github.com/github/copilot-sdk/tree/main/go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli)嵌入 CLI，或将 `StdioConnection.Path` 指向已安装的二进制文件。\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n    Connection: copilot.StdioConnection{Path: \"/usr/local/bin/copilot\"},\n})\nif err := client.Start(ctx); err != nil {\n    log.Fatal(err)\n}\ndefer client.Stop()\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: \"gpt-5.4\"})\nresponse, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: \"Hello!\"})\nif response != nil {\n    if d, ok := response.Data.(*copilot.AssistantMessageData); ok {\n        fmt.Println(d.Content)\n    }\n}\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n    Connection = RuntimeConnection.ForStdio(path: \"/usr/local/bin/copilot\"),\n});\n\nawait using var session = await client.CreateSessionAsync(\n    new SessionConfig { Model = \"gpt-5.4\" });\n\nvar response = await session.SendAndWaitAsync(\n    new MessageOptions { Prompt = \"Hello!\" });\nConsole.WriteLine(response?.Data.Content);\n```\n\n</div>\n\n</div>\n\n## 其他选项\n\n```typescript\nconst client = new CopilotClient({\n    cliPath: \"/usr/local/bin/copilot\",\n\n    // Set log level for debugging\n    logLevel: \"debug\",\n\n    // Pass extra CLI arguments\n    cliArgs: [\"--log-dir=/tmp/copilot-logs\"],\n\n    // Set working directory\n    cwd: \"/path/to/project\",\n});\n```\n\n## 使用环境变量\n\n你可以通过环境变量进行身份验证，而不是密钥链。 这对于 CI 或不需要交互式登录时非常有用。\n\n```bash\n# Set one of these (in priority order):\nexport COPILOT_GITHUB_TOKEN=\"gho_xxxx\"   # Recommended\nexport GH_TOKEN=\"gho_xxxx\"               # GitHub CLI compatible\nexport GITHUB_TOKEN=\"gho_xxxx\"           # GitHub Actions compatible\n```\n\nSDK 会自动选取这些内容， 无需更改代码。\n\n## 管理会话\n\n会话默认为临时会话。 若要创建可恢复会话，请提供自己的会话 ID：\n\n```typescript\n// Create a named session\nconst session = await client.createSession({\n    sessionId: \"my-project-analysis\",\n    model: \"gpt-5.4\",\n});\n\n// Later, resume it\nconst resumed = await client.resumeSession(\"my-project-analysis\");\n```\n\n会话状态存储在本地 。`~/.copilot/session-state/{sessionId}/`\n\n## 局限性\n\n| 限度        | 详细信息                  |\n| --------- | --------------------- |\n| **版本兼容性** | 必须确保 CLI 版本与 SDK 兼容   |\n| **单个用户**  | 凭据与登录到 CLI 的人员相关联     |\n| **仅限本地**  | CLI 在应用所在的同一台计算机上运行   |\n| **无多租户**  | 无法从一个 CLI 实例为多个用户提供服务 |\n\n## 后续步骤\n\n* **[默认设置（随附的 CLI）](/zh/copilot/how-tos/copilot-sdk/setup/bundled-cli)**：使用 SDK 的内置 CLI（建议用于大多数用例）\n* **[构建你的第一个由 Copilot 提供支持的应用](/zh/copilot/how-tos/copilot-sdk/getting-started)**：生成完整的交互式应用\n* **[Authentication](/zh/copilot/how-tos/copilot-sdk/auth/authenticate)**：所有身份验证方法的详细信息"}