跳轉到主要內容

TCP 模式

一般情況下,SDK 會為每個請求啟動新的 Copilot CLI 程序(stdio 模式)。 使用 TCP 模式後,可以連線至事先啟動的 Copilot CLI 伺服器。

TCP 模式的優點

  • 提升效能: 無程序啟動的額外負擔
  • 資源共用: 多個 Laravel 程序可共用同一個 CLI 伺服器
  • 程序管理: 可透過 Laravel Forge / Laravel Cloud 以背景程序方式管理
  • 部署支援: 可支援部署時的自動重啟

使用方法

1. 啟動 Copilot CLI 伺服器

2. 設定環境變數

只要這樣設定,SDK 就會自動從 stdio 模式切換到 TCP 模式。
  • tcp:// 為選填。使用 http:// 或無 scheme 也可運作。
  • 也可以只指定 port。此時 host 會自動設為 127.0.0.1。
  • 只指定 host 時僅支援 127.0.0.1 與 localhost。此時 port 預設為 12345。

設定檔

可在 config/copilot.php 中設定 TCP 連線。
同時設定 COPILOT_URL(cli_url)與 COPILOT_CLI_PATH 時,以 TCP 模式優先。

執行時切換模式

一般會依設定檔自動選擇 TCP 模式或 stdio 模式。 也可以在程式碼中明確切換。
某些伺服器在 TCP 模式下可能無法正常運作。 也可以分開使用,例如 Queue 處理使用 TCP 模式,HTTP 請求內處理使用 stdio 模式。

在 Laravel Forge / Laravel Cloud 運作

Laravel Forge

  1. 建立 Daemon: 在 Forge 管理畫面建立 Daemon。
  2. 設定環境變數: 在 .env 加入 COPILOT_URL。
  3. 部署時重啟: 在部署腳本中重啟 Daemon。
在目前的 Forge 環境中可能不需要。

Laravel Cloud

可使用 Laravel Cloud 的 worker 功能,以背景程序執行。 詳細請參閱 Laravel Cloud 使用方式。

注意事項

安全性

TCP 伺服器盡量使用本機綁定(127.0.0.1)。 若要對外開放,請適當設定防火牆。

重新連線

目前版本沒有自動重新連線功能。連線中斷時會拋出例外。

連線終止與啟動錯誤

在 stdio 模式下,Client::stop() 會停止由 SDK 啟動的執行環境。在 TCP 模式下,則不會停止共用伺服器,只會關閉用戶端的連線。 stdio 啟動交握逾時時,例外中會包含最多最近 8 KiB 的程序 stderr。診斷輸出可能含有機密資訊,因此在記錄至外部前請先確認內容。

確認目前模式

可在程式中確認 Client 目前使用哪種模式。

疑難排解

無法連線

  1. 確認 Copilot CLI 伺服器是否啟動
  1. 確認 port 是否正確
  1. 確認防火牆設定

逾時錯誤

請調高 config/copilot.php 的 timeout 值。
最新資訊請參閱 GitHub 儲存庫。
最後修改於 2026年10月26日