企业官网建设流程全解析

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 端口，连接被拒绝（没有服务在该端口监听）。

这通常意味着两种可能：

1. 某个本该在 57959 端口上运行的服务崩溃了
2. 某个进程在尝试连接一个已不存在的服务端口

第二步：确认端口状态

通过lsof命令直接验证：

$lsof-i:57959# 返回空——没有任何进程监听该端口$lsof-i:49214# 返回 connector-proxy 正在监听该端口，运行正常

这一步排除了"端口被占用"的可能，也确认了 57959 确实没有服务在跑。

第三步：检查进程树

通过ps aux | grep -i workbuddy发现了多个相关进程：

同时发现用户机器上还运行着 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

2. 排查命令速查

# 查看端口占用lsof-i:端口号# 查看进程及端口监听状态lsof-p<PID>-i-P|grepLISTEN# 查看所有 WorkBuddy 相关进程psaux|grep-iworkbuddy|grep-vgrep# 查看所有 codebuddy 进程（包括 CLI）psaux|grepcodebuddy|grep-vgrep

3. 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日。