Skip to main content

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.1localhost。此時 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)。 若要對外開放,請適當設定防火牆。

重新連線

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

確認目前模式

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

疑難排解

無法連線

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

逾時錯誤

請調高 config/copilot.phptimeout 值。
最新資訊請參閱 GitHub 儲存庫
最後修改於 2026年8月2日