客户端选项参考
客户端在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)。