TCP 模式
通常，SDK 会为每个请求启动新的 Copilot CLI 进程（stdio 模式）。
使用 TCP 模式后，可以连接到预先启动的 Copilot CLI 服务器。
TCP 模式的优点
- 性能提升: 没有进程启动开销
- 资源共享: 多个 Laravel 进程可以共享同一个 CLI 服务器
- 进程管理: 可以在 Laravel Forge / Laravel Cloud 中作为后台进程管理
- 部署适配: 可以支持部署时的自动重启
使用方式
1. 启动 Copilot CLI 服务器
copilot --headless --port 12345
2. 设置环境变量
COPILOT_URL=tcp://127.0.0.1:12345
# COPILOT_URL=http://127.0.0.1:12345
# COPILOT_URL=127.0.0.1:12345
# COPILOT_URL=12345
# COPILOT_URL=127.0.0.1
# COPILOT_URL=localhost
tcp:// 是可选的。使用 http:// 或没有 scheme 也可以工作。- 也可以只指定端口。这种情况下 host 会自动为
127.0.0.1。
- 只指定 host 时仅
127.0.0.1 和 localhost 有效。这种情况下端口默认是 12345。
配置文件
可以在 config/copilot.php 中配置 TCP 连接。
return [
// TCP 连接目标 URL（设置后进入 TCP 模式）
'url' => env('COPILOT_URL'),
// 以下仅在 stdio 模式下使用
'cli_path' => env('COPILOT_CLI_PATH', 'copilot'),
'cli_args' => [],
'cwd' => null,
'log_level' => env('COPILOT_LOG_LEVEL', 'info'),
// 两种模式共通
'timeout' => env('COPILOT_TIMEOUT', 60),
'model' => env('COPILOT_MODEL'),
];
COPILOT_URL（cli_url）和 COPILOT_CLI_PATH 时，TCP 模式优先。
运行时切换模式
通常会根据配置文件自动选择 TCP 模式或 stdio 模式。
也可以在代码中显式切换。
use Revolution\Copilot\Facades\Copilot;
// 切换到 TCP 模式
$response = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->run(prompt: 'Hello, TCP mode!');
// 省略时使用配置文件的值
$response = Copilot::useTcp()->run(prompt: 'Hello, TCP mode!');
// 切换到 stdio 模式
$stdioConfig = [
'cli_path' => 'copilot',
'cli_args' => [],
'cwd' => base_path(),
'log_level' => 'info',
];
$response = Copilot::useStdio($stdioConfig)->run(prompt: 'Hello, stdio mode!');
// 省略时使用配置文件的值
// 两种模式都配置时 TCP 优先，因此可用于临时覆盖
$response = Copilot::useStdio()->run(prompt: 'Hello, stdio mode!');
在 Laravel Forge / Laravel Cloud 中的运行
Laravel Forge
-
创建 Daemon: 在 Forge 管理界面创建 Daemon。
Command: copilot --headless --port 12345
User: forge
Directory: /home/forge/your-app
-
设置环境变量: 在
.env 中添加 COPILOT_URL。
-
部署时重启: 在部署脚本中重启 Daemon。
在当前的 Forge 环境中，也许不需要。
sudo supervisorctl restart daemon-123456:*
Laravel Cloud
可以使用 Laravel Cloud 的 worker 功能，作为后台进程运行。
详情请参考 在 Laravel Cloud 中的使用。
注意事项
TCP 服务器请尽可能使用本地绑定（127.0.0.1）。
如需对外公开，请适当配置防火墙。
确认当前模式
可以在程序内确认客户端处于哪种模式。
use Revolution\Copilot\Facades\Copilot;
$client = Copilot::client();
if ($client->isTcpMode()) {
// TCP 模式
} else {
// stdio 模式
}
故障排查
无法连接
- 确认 Copilot CLI 服务器是否启动
- 确认端口是否正确
- 确认防火墙配置
超时错误
请增大 config/copilot.php 中 timeout 的值。
'timeout' => 120, // 2 分钟
