CodeBuddy 客户端 ECONNREFUSED 错误排查实录
CodeBuddy 客户端 ECONNREFUSED 错误排查实录
问题描述
用户在使用 CodeBuddy（WorkBuddy）时，遇到以下报错：
connect ECONNREFUSED 127.0.0.1:57959 Error Code: UNKNOWN Request ID: 96d2964018214cd9b8658637f4451693-1778504946924 Timestamp: 2026/05/11 21:09:07 (UTC+8)报错信息友好度较高，但"ECONNREFUSED 127.0.0.1:57959"这条技术细节是排查的关键入口。
排查过程
第一步：了解报错含义
connect ECONNREFUSED 127.0.0.1:57959的含义很明确：本机尝试连接 localhost 的 57959 端口，连接被拒绝（没有服务在该端口监听）。
这通常意味着两种可能：
- 某个本该在 57959 端口上运行的服务崩溃了
- 某个进程在尝试连接一个已不存在的服务端口
第二步：确认端口状态
通过lsof命令直接验证：
$lsof-i:57959# 返回空——没有任何进程监听该端口$lsof-i:49214# 返回 connector-proxy 正在监听该端口，运行正常这一步排除了"端口被占用"的可能，也确认了 57959 确实没有服务在跑。
第三步：检查进程树
通过ps aux | grep -i workbuddy发现了多个相关进程：
| PID | 进程名 | 端口 | 状态 |
|---|---|---|---|
| 614 | Electron（主进程） | 49209, 49214 | LISTEN |
| 12422 | sidecar-entry.js | - | 存活但未监听 57959 |
| 12423 | codebuddy CLI | 52308 | LISTEN |
| 12424 | codebuddy CLI | 52317 | LISTEN |
| 12451 | codebuddy CLI | 52354 | LISTEN |
同时发现用户机器上还运行着 QClaw 和 myclaw（同样基于 Electron 的应用），可能是端口分配产生过冲突。
通过lsof -p 12422 -i -P | grep LISTEN进一步确认：sidecar 进程本身还在，但并没有监听 57959 端口。
第四步：观察连接器状态
虽然报 ECONNREFUSED，但通过/workbuddy status查看连接器状态：
- GitHub：✅ connected
- Notion：✅ connected
- QQ邮箱：✅ connected
所有连接器均正常工作，说明核心功能未受影响。
第五步：问题定位
综合以上排查结果，根本原因是：
CodeBuddy 的某个 Agent session（从 Request ID96d2964018214cd9b8658637f4451693可以看出是一个独立的会话实例）曾经连接过本机的 57959 端口，但该端口上的服务（很可能是 sidecar 的某个子功能）已经退出。报错是这个旧 session 的残留连接尝试——属于无害的残留状态，不影响实际功能。
第六步：修复
操作：完全退出 CodeBuddy（Cmd+Q），等待几秒后重新打开。
效果：报错消失，所有连接器恢复正常。
技术要点总结
1. localhost 端口拒绝连接的常见原因
ECONNREFUSED 127.0.0.1:XXXXX| 原因 | 特征 | 解决方法 |
|---|---|---|
| 服务进程崩溃 | 进程存在但端口未监听 | 重启服务或主应用 |
| 端口被其他进程占用 | lsof 显示另一个进程占用 | 结束冲突进程 |
| 残留连接 | 服务正常但有旧连接尝试 | 重启主应用清理 session |
| 防火墙阻止 | macOS 防火墙规则 | 检查防火墙设置 |
2. 排查命令速查
# 查看端口占用lsof-i:端口号# 查看进程及端口监听状态lsof-p<PID>-i-P|grepLISTEN# 查看所有 WorkBuddy 相关进程psaux|grep-iworkbuddy|grep-vgrep# 查看所有 codebuddy 进程（包括 CLI）psaux|grepcodebuddy|grep-vgrep3. Electron 多进程架构认知
CodeBuddy 基于 Electron 构建，典型的进程结构包括：
Electron 主进程（PID 614） ├── WorkBuddy Helper（GPU 进程） ├── WorkBuddy Helper（Utility 进程，Network Service） ├── WorkBuddy Helper (Renderer)（UI 渲染进程） ├── sidecar-entry.js（辅助进程） └── codebuddy CLI（Agent 进程 × N）每个新 session 会启动一个独立的 codebuddy CLI 进程（监听随机高端口），由主进程的 connector-proxy（49214 端口）统一代理。
4. 连接器与端口的关系
连接器（GitHub、Notion、QQ邮箱等）通过 connector-proxy（49214 端口）与外部服务通信，与 Agent session 的端口（52308、52317、52354）是完全独立的两个层面。前者是主进程的常驻服务，后者是按需创建的临时进程。
因此连接器正常 ≠ 不会有端口相关报错，两者互不影响。
经验教训
报错 ≠ 功能失效。ECONNREFUSED 是一个连接层的报错，反映的是"尝试连接失败"，而不是"功能不可用"。在这个案例中，sidecar 进程和 connector-proxy 均正常运行，只是某个旧 session 的连接尝试碰了壁。
进程还在 ≠ 端口在监听。ps aux显示进程存在，不等于该进程在监听预期端口。通过lsof -p PID -i -P | grep LISTEN可以确认进程实际监听了哪些端口，这是排查端口类问题的重要手段。
多款 Electron 应用共存需注意端口冲突。本案例中用户同时运行了 QClaw、myclaw 和 CodeBuddy，三者均基于 Electron，可能在端口分配上存在竞争关系。如果频繁遇到异常端口问题，可以考虑在不需要时关闭其他应用进行隔离验证。
本文基于真实排查过程整理，记录时间：2026年5月11日。