Claude-to-IM-skill doctor诊断指南：快速修复桥接不启动、机器人没反应等5大故障场景-创锋一号

Claude-to-IM-skill doctor诊断指南：快速修复桥接不启动、机器人没反应等5大故障场景

【免费下载链接】Claude-to-IM-skillBridge Claude Code / Codex to IM platforms — chat with AI coding agents from Telegram, Discord, or Feishu/Lark.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-to-IM-skill

Claude-to-IM-skill 可以把 Claude Code / Codex 桥接到 Telegram、Discord、飞书、QQ、微信，让你在手机上和 AI 编码智能体对话。当桥接不启动、机器人没反应或会话卡住时，不用满屏日志翻找——项目自带的doctor 诊断命令会一次性体检 Node 版本、CLI 可用性、配置文件权限、Token 有效性、PID 文件和日志错误，并直接告诉你怎么修。本文带你跑通 doctor，并覆盖新手最常遇到的 5 大故障场景。

一、doctor 是什么：给桥接做一次"体检"

doctor 的本质是一个健康检查脚本 scripts/doctor.sh，它会按顺序执行：

✅ Node.js 是否 ≥ 20
✅ Claude Code CLI / Codex CLI 是否存在、版本是否兼容、是否已登录
✅ SDK 依赖（cli.js、@openai/codex-sdk）是否安装
✅dist/daemon.mjs是否为最新构建
✅config.env是否存在且权限为 600
✅ 各平台 Token 是否真实有效（会实时调用平台 API 验证）
✅ 日志目录可写、PID 文件与进程是否一致、近期日志有无 ERROR

每项输出[OK]或[FAIL]，末尾汇总"通过 N 项、失败 M 项"，有失败还会附上常见修复命令。

二、一键运行 doctor 的3个步骤

在 Claude Code 中：

/claude-to-im doctor

在 Codex 中：直接说自然语言

doctor

也可以说"诊断"、"挂了"、"bot 没反应"，系统会自动识别为 doctor 命令（见 SKILL.md 的命令解析表）。

建议流程：

运行doctor，记录所有[FAIL]项
按本文对应场景修复
再跑一次doctor，直到显示0 failed

三、5大故障场景排查

场景1：桥接不启动（start 失败或进程秒退）

典型症状：/claude-to-im start报错，或 daemon 启动后立即退出。

排查清单：

检查项	命令 / 操作	说明
Node 版本	`node --version`	必须 ≥ 20，低版本是新手第一杀手
Claude CLI	`claude --version`	runtime 为 claude/auto 时必须可用
配置文件	`ls -la ~/.claude-to-im/config.env`	缺失时先跑`/claude-to-im setup`
构建产物	看 doctor 的`dist/daemon.mjs`项	过期就执行`npm run build`
启动日志	`/claude-to-im logs`	查看具体报错

⚠️重点提醒：没有config.env就强行启动，进程会崩溃并留下残留 PID 文件，之后每次 start 都会被卡住——所以"先 setup、后 start"是最省时间的习惯。

场景2：机器人没反应（在线但收不到/不回消息）

典型症状：daemon 状态显示 running，但发消息过去机器人不理你。

这是新手反馈最多的问题，按平台逐个查：

Telegram：先确认是否给机器人发过/start；检查CTI_TG_CHAT_ID或CTI_TG_ALLOWED_USERS是否配置——两者都空时机器人会拒绝所有消息
Discord：确认 Bot 已用带botscope 的链接邀请进服务器，并开启了Message Content Intent；注意默认拒绝策略，Allowed Users / Channels 至少要配一个
飞书：应用版本必须审核发布通过后才生效，事件订阅要选"长连接"方式并添加im.message.receive_v1
QQ：目前仅支持 C2C 私聊沙箱，CTI_QQ_ALLOWED_USERS填的是user_openid而不是 QQ 号

最后一步兜底：/claude-to-im logs 200里看有没有 incoming message 事件，能区分"消息根本没进来"还是"进来了但被权限拦截"。

场景3：权限审批超时（Permission timeout）

典型症状：Claude 要用工具时弹出 Allow / Deny 按钮，但等你反应过来，审批已超时、工具调用被自动拒绝。

原因：桥接在非交互模式运行，canUseTool等待用户响应有5 分钟超时，超时自动拒绝。

解决办法：

手机上尽快点 Allow（收到审批提示尽量及时）
常用工具可通过配置预授权，减少逐次审批
如果超时发生在 API 调用阶段，检查网络连通性

场景4：PID 文件过期（状态显示运行但进程不存在）

典型症状：status显示 running 但实际没有进程；或 start 直接拒绝，提示已有 daemon 在运行。

修复三步走：

/claude-to-im stop—— scripts/daemon.sh 会自动清理残留 PID
若 stop 也失败，手动删除 PID 文件：rm ~/.claude-to-im/runtime/bridge.pid
/claude-to-im start启动全新实例

doctor 的"PID file consistent"检查项正是为此设计：它读取 PID 文件并用kill -0验证进程是否真的活着。

场景5：内存占用持续升高

典型症状：daemon 运行几天后内存越吃越多，系统开始变卡。

处理建议：

/claude-to-im status查看当前内存与运行时长
重启 daemon 立即释放：/claude-to-im stop→/claude-to-im start
长期高占用时，检查并发会话数量——每个 Claude Code 会话都会占用内存
用/claude-to-im logs 200排查是否存在错误循环（反复重试的错误最容易"吃"内存）

四、常见修复命令速查表

把 doctor 输出的 FAIL 对号入座，基本都在这张表里：

故障提示	修复命令
SDK cli.js 缺失	`cd ~/.claude/skills/claude-to-im && npm install`
dist/daemon.mjs 过期	`npm run build`
config.env 缺失	`/claude-to-im setup`重新跑配置向导
微信未关联账号	`cd ~/.claude/skills/claude-to-im && npm run weixin:login`扫码登录
PID 文件残留	先`stop`再`start`
Token 验证失败	`/claude-to-im reconfigure`重新填写凭据

各平台凭据的申请位置、格式和注意事项，完整见 references/setup-guides.md；配置项含义可参考 config.env.example。

五、相关文件导读

诊断脚本源码：scripts/doctor.sh
故障排查参考：references/troubleshooting.md
完整命令用法：references/usage.md
进程管理脚本：scripts/daemon.sh
技能定义与命令解析：SKILL.md

小结

记住一个排查口诀：先 doctor、再看 logs、后动配置。doctor 把环境层的问题（Node、CLI、依赖、权限、Token）一网打尽，logs 负责定位消息层的行为，剩下才是配置与平台设置的问题。按本文 5 大场景对号入座，绝大多数"桥接挂了"的情况都能在 10 分钟内恢复。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析