跳转到主要内容

客户端选项参考

客户端在 config/copilot.php 中配置。 也可以将相同的选项以数组形式传给 Copilot::client()、useStdio() / useTcp() 或 new Client([...])。 本页列出配置文件中的选项,以及只能在代码中传入的选项。

配置文件中的选项

连接

  • mode:客户端模式,可选 'copilot-cli'(常规)或 'empty'。empty 会禁用 CLI 的隐式功能。在此模式下,必须显式设置 base directory、SessionFs 或 TCP URL。
  • url:现有 Copilot CLI 服务器的 URL(例如 tcp://127.0.0.1:12345)。设置后,SDK 会连接到该服务器,而不是启动新的 CLI 进程。详情请参阅 TCP 模式。
  • cli_path:CLI 可执行文件的路径。设为 null 时会自动查找 CLI。
  • cli_args:启动 CLI 时传入的额外参数(例如 ['--yolo'])。
  • cwd:CLI 进程的工作目录。
  • log_level:CLI 服务器的日志级别。可从 none、error、warning、info、debug、all 中选择。

默认值

  • timeout:sendAndWait() 的默认超时时间(秒)。Copilot::run() 也会使用它。
  • model:创建会话时未指定模型所使用的默认模型。
  • permission_approve:使用 Facade(Copilot::run() 等)时自动处理权限请求的方式。可选 'deny-all'(全部拒绝)、'approve-safety'(除 shell 和 write 外全部批准)、'approve-all'(全部批准)或 false(不注入处理器)。直接使用 Client 时,始终需要 onPermissionRequest 处理器。详情请参阅权限请求。

数据存储位置

  • copilot_home:Copilot 数据(会话状态和设置)的基础目录。SDK 会以 COPILOT_HOME 环境变量的形式将其传给所启动的 CLI 进程。未设置时使用 CLI 的默认值(~/.copilot)。
  • base_directory:使用官方 SDK 名称的 copilot_home 别名。两者都设置时,以 base_directory 为准。
  • session_fs:SessionFs 提供者的设置,用于将会话状态(文件和 SQLite)委托给自己的存储。initialCwd、sessionStatePath 和 conventions 为必填项。设置后,每个会话也必须指定 createSessionFsProvider。
  • builtin_plugin_directories:受信任的内置插件目录的绝对路径数组。SDK 会在客户端启动时将其注册到运行时。详情请参阅 Plugin Directories。

其他选项

  • telemetry:OpenTelemetry 设置数组(otlpEndpoint、filePath、exporterType、sourceName、captureContent)。SDK 会将其转换为所启动 CLI 进程的环境变量。详情请参阅 Telemetry。
  • session_idle_timeout_seconds:服务器范围内的会话空闲超时时间(秒)。0(默认值)表示禁用,会话将无限期保持。
  • request_handler:拦截发往模型层的 HTTP 请求的 CopilotRequestHandler 或闭包(experimental)。不适用于 WebSocket 请求。

不在配置文件中的选项

以下选项不在配置文件中,但可以作为参数传给 useStdio()、Copilot::client() 或 new Client([...])。 由于外部服务器自行管理认证,TCP 模式下无法使用 github_token 和 use_logged_in_user。 如果设置了其中任意一个并通过 TCP 连接,SDK 会抛出异常。 关于运行时切换 token,另请参阅 GitHub token。 许多选项同时接受 snake_case 和 camelCase 名称(例如 session_fs 与 sessionFs、builtin_plugin_directories 与 builtinPluginDirectories、request_handler 与 requestHandler)。
最后修改于 2026年11月16日