跳轉到主要內容

用戶端選項參考

用戶端在 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日