> ## 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-TW/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-TW/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-TW/packages/laravel-copilot-sdk/plugin-directories.md)。

### 其他選項

* `telemetry`：OpenTelemetry 設定陣列（`otlpEndpoint`、`filePath`、`exporterType`、`sourceName`、`captureContent`）。SDK 會將其轉換為所啟動 CLI 程序的環境變數。詳情請參閱 [Telemetry](https://kawax.biz/zh-TW/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` | 沙箱網路 Proxy 設定（`scope`、`resolveProxy`、`authenticateNegotiate`） | 共用 |

由於外部伺服器會自行管理驗證，TCP 模式下無法使用 `github_token` 與 `use_logged_in_user`。
若設定了其中任一項並透過 TCP 連線，SDK 會擲出例外。
關於執行時切換 Token，另請參閱 [GitHub Token](https://kawax.biz/zh-TW/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-TW/packages/laravel-copilot-sdk/tcp-mode.md)
- [官方 SDK 相容層的使用方式](https://kawax.biz/zh-TW/packages/laravel-copilot-sdk/bare-usage.md)
- [HTTP 用戶端](https://kawax.biz/zh-TW/http-client.md)
- [Telemetry](https://kawax.biz/zh-TW/packages/laravel-copilot-sdk/telemetry.md)
- [套件的 HTTP 用戶端與測試](https://kawax.biz/zh-TW/advanced/package-http-client.md)


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