> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 客户端选项参考

> Laravel Copilot SDK 所有客户端选项的参考，包括默认值、环境变量以及以 TCP 模式连接时的行为。

## 客户端选项参考

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

## 配置文件中的选项

| 选项 | 默认值 | 环境变量 | TCP 模式 |
| - | - | - | - |
| `mode` | `'copilot-cli'` | `COPILOT_MODE` | 通用 |
| `url` | `null` | `COPILOT_URL` | 设置后即启用 TCP 模式 |
| `cli_path` | `'copilot'` | `COPILOT_CLI_PATH` | 忽略 |
| `cli_args` | `[]` | - | 忽略 |
| `cwd` | `null`（应用的 base path） | - | 忽略 |
| `log_level` | `'info'` | `COPILOT_LOG_LEVEL` | 忽略 |
| `builtin_plugin_directories` | `[]` | - | 通用 |
| `timeout` | `60.0` | `COPILOT_TIMEOUT` | 通用 |
| `model` | `null` | `COPILOT_MODEL` | 通用 |
| `copilot_home` | `null` | `COPILOT_HOME` | 忽略 |
| `base_directory` | `null` | `COPILOT_BASE_DIRECTORY` | 忽略 |
| `session_fs` | `null` | - | 通用 |
| `permission_approve` | `'deny-all'` | `COPILOT_PERMISSION_APPROVE` | 通用（Facade 层） |
| `telemetry` | `null` | - | 忽略 |
| `session_idle_timeout_seconds` | `0` | `COPILOT_SESSION_IDLE_TIMEOUT` | 忽略 |
| `request_handler` | `null` | - | 通用 |

### 连接

* `mode`：客户端模式，可选 `'copilot-cli'`（常规）或 `'empty'`。`empty` 会禁用 CLI 的隐式功能。在此模式下，必须显式设置 base directory、SessionFs 或 TCP URL。
* `url`：现有 Copilot CLI 服务器的 URL（例如 `tcp://127.0.0.1:12345`）。设置后，SDK 会连接到该服务器，而不是启动新的 CLI 进程。详情请参阅 [TCP 模式](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/tcp-mode.md)。
* `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` 处理器。详情请参阅[权限请求](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/permission-request.md)。

### 数据存储位置

* `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](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/plugin-directories.md)。

### 其他选项

* `telemetry`：OpenTelemetry 设置数组（`otlpEndpoint`、`filePath`、`exporterType`、`sourceName`、`captureContent`）。SDK 会将其转换为所启动 CLI 进程的环境变量。详情请参阅 [Telemetry](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/telemetry.md)。
* `session_idle_timeout_seconds`：服务器范围内的会话空闲超时时间（秒）。`0`（默认值）表示禁用，会话将无限期保持。
* `request_handler`：拦截发往模型层的 HTTP 请求的 `CopilotRequestHandler` 或闭包（experimental）。不适用于 WebSocket 请求。

## 不在配置文件中的选项

以下选项不在配置文件中，但可以作为参数传给 `useStdio()`、`Copilot::client()` 或 `new Client([...])`。

| 选项 | 说明 | TCP 模式 |
| - | - | - |
| `env` | 传给 SDK 所启动 CLI 进程的额外环境变量数组 | 忽略 |
| `github_token` | 用于认证的 GitHub token | 不可用 |
| `use_logged_in_user` | 是否使用已登录 CLI 的用户 | 不可用 |
| `installation_confirmation_handler` | 确认 CLI 安装的回调 | 忽略 |
| `entra` | Microsoft Entra 认证设置（`EntraAuthConfig` 或数组） | 通用 |
| `on_github_telemetry` | 接收 GitHub 遥测通知的回调 | 通用 |
| `extension_launch_provider` | 决定扩展启动方式的回调 | 通用 |
| `network` | 沙箱网络代理设置（`scope`、`resolveProxy`、`authenticateNegotiate`） | 通用 |

由于外部服务器自行管理认证，TCP 模式下无法使用 `github_token` 和 `use_logged_in_user`。
如果设置了其中任意一个并通过 TCP 连接，SDK 会抛出异常。
关于运行时切换 token，另请参阅 [GitHub token](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/github-token.md)。

许多选项同时接受 snake\_case 和 camelCase 名称（例如 `session_fs` 与 `sessionFs`、`builtin_plugin_directories` 与 `builtinPluginDirectories`、`request_handler` 与 `requestHandler`）。


## Related topics

- [TCP 模式](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/tcp-mode.md)
- [官方 SDK 兼容层的使用方式](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/bare-usage.md)
- [HTTP 客户端](https://kawax.biz/zh-CN/http-client.md)
- [Telemetry](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/telemetry.md)
- [包的 HTTP 客户端与测试](https://kawax.biz/zh-CN/advanced/package-http-client.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.