Claude-Mem Worker 启动报端口占用失败怎么排查与换端口

Claude-Mem Worker 启动报端口占用失败怎么排查与换端口

【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem

当 Claude-Mem 的 Worker（负责处理观察记录、生成摘要并对外提供 HTTP API 的常驻进程）启动时，如果目标端口已被其他进程占用，Worker 会直接启动失败，常见报错为 "port already in use" 或EADDRINUSE: address already in use。Claude-Mem 的 Worker 默认使用按用户分配的端口：37700 + (uid % 100)，同一 OS 用户的不同 OS 账号天然错开，但在同 UID 下跑多套配置、或机器上已有其他进程占着该端口时仍会冲突。本文基于 troubleshooting 文档、配置文档 和 Worker 架构文档 说明完整的排查与换端口操作。

先确认 Worker 当前配置的是哪个端口

排查的第一步是搞清楚报错的端口到底是多少。端口可能来自三处，优先级从高到低：

• 环境变量CLAUDE_MEM_WORKER_PORT；
• ~/.claude-mem/settings.json中的CLAUDE_MEM_WORKER_PORT配置项；
• 未配置时的 per-user 默认值37700 + (uid % 100)。

PORT这个变量在后续命令中反复出现，先执行一次取出实际值：

PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json) echo $PORT

如果输出为空，说明没有显式配置，实际生效的就是默认公式算出的端口，可以自己按uid算一下。此外，运行中的 Worker 会在~/.claude-mem/.worker.port里记录当前端口，Worker 健康后也可以通过GET /api/health响应里的port字段确认。

检查占用端口的进程

拿到端口号后，用lsof看是谁占着它：

lsof -i :$PORT

输出会列出监听该端口的进程 PID 和进程名。根据结果分两条路：

• 如果占着端口的是一个旧的 Claude-Mem Worker 残留进程，可以走「杀掉冲突进程」路径，在原文端口上重启；
• 如果是别的服务，或者你本来就希望 Claude-Mem 固定用一个自己的端口，走下面「换端口」路径，不要动别人的进程。

路径一：杀掉冲突进程后在原文口重启

适用于确认占用者是 Claude-Mem 自己的残留 Worker 的情况。

注意：kill -9会强制终止该端口上的进程，不可撤销。执行前务必用上一条lsof的输出确认 PID 属于残留的 claude-mem Worker，而不是其他服务。

kill -9 $(lsof -t -i:$PORT) npm run worker:restart

npm run worker:restart会重启 Claude-Mem 的 Worker 服务，是 troubleshooting 文档 中「Port Allocation Failed」一节给出的标准操作。重启后按下一节验证。

路径二：换端口重启

如果冲突进程不该被杀，或你想让 Claude-Mem 固定占用一个端口避免再次碰撞，就通过CLAUDE_MEM_WORKER_PORT指定新端口。文档示例中使用的示例值是38000，你可以选一个机器上空闲的端口：

export CLAUDE_MEM_WORKER_PORT=38000 npm run worker:restart

两点说明：

• export只影响当前 shell 会话。要让端口配置持久化，把CLAUDE_MEM_WORKER_PORT写入~/.claude-mem/settings.json（配置文档 中展示了"CLAUDE_MEM_WORKER_PORT": "38000"的配置示例），之后通过环境变量或配置文件都能被 Worker 读取。
• 如果端口号本身不合法（比如非数字、超范围），日志中会出现Invalid port X，此时按 pm2-to-bun-migration 文档 的错误表处理：检查并更新CLAUDE_MEM_WORKER_PORT的取值。

验证新端口已生效

换端口或重启完成后，请求 Worker 的健康检查接口确认：

curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health | jq .port

Worker 架构文档给出的健康检查响应示例（文档示例，port值随你的配置不同而变化）：

{ "status": "ok", "uptime": 12345, "port": 37742 }

判断方式：响应中status为"ok"且port字段等于你刚设置的端口值，说明 Worker 已在新端口上正常监听。另外两个辅助确认手段：

# 查看 Worker 运行状态 npm run worker:status # 查看 Worker 日志，确认无端口相关报错 npm run worker:logs

限制与补充说明

• 端口被占用时 Worker 的行为是直接启动失败，不会自动换端口重试，必须按上述两条路径之一处理后npm run worker:restart。
• production-guide 记录过一个历史场景：两个会话同时启动时可能各自认为端口空闲（HTTP 检查非原子）导致启动冲突，表现为Worker failed to start... Is port 37777 in use?。该问题在后续版本中已通过原子 socket bind 修复；如果你升级后仍偶发此类报错且lsof查不到占用进程，先升级到包含该修复的版本再排查。
• ~/.claude-mem/目录下还有worker.pid（进程跟踪文件）和logs/（按天滚动的 Worker 日志）。如果npm run worker:status显示异常但端口实际空闲，查日志确认具体错误后再操作，不要盲目清理文件。

【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem