Hooks、MCP 和插件问题

本页帮助排查 Hooks、MCP 服务器与插件相关的问题。

​

先检查这两项

在深入具体组件之前，先排除两个最常见原因：

• 目录是否受信任：未信任的工作区不会加载项目级设置、Hooks、MCP 与项目级 Agent（交互式会话中 Hook 会被直接拦截）。首次进入目录时会弹出信任选择，可选“仅本次会话”或“记住”（写入 settings.local.json）；也可用 permissions.trustDirectories 永久信任常用目录。见 权限与目录信任。
• 改完配置是否重新加载：多数扩展支持热重载，比重启更快——/mcp reload、/plugins reload、/skills reload、/agents reload；标注“需重启”的配置项仍需重新启动 CLI。

​

Hooks 问题

Hook 未触发或行为异常时：

• 事件与匹配：确认 Hook 绑定的事件名正确，且 matcher 能匹配到目标（空或 * 匹配全部，精确值、| 多值或正则）。
• 退出码：command 类型 Hook 用退出码控制流程——0 成功、2 阻塞（stderr 反馈给 Agent）、其他为非阻塞错误。若 Hook 意外阻塞了操作，检查是否返回了 2。
• 输入解析：Hook 从 stdin 接收 JSON（含 session_id、cwd、hook_event_name 等），确认脚本正确读取。
• 可执行权限：command 指向的脚本需有可执行权限，路径正确。
• 用 /hooks 查看已注册的 Hooks。
• 完整参考见 Hooks 参考。

​

MCP 服务器问题

MCP 服务器未连接或工具不可用时：

• 用 /mcp 查看服务器连接状态。
• 命令与路径：stdio 类型确认 command、args、cwd 正确，服务器可独立启动。
• 项目级批准：项目级 MCP 服务器默认需逐个批准。用 mcp.enableAllProjectMcpServers 或 mcp.enabledProjectMcpServers 批准。
• 白名单限制：检查是否被 mcp.allowed / mcp.excluded、--allowed-mcp-server-names 或 --strict-mcp-config 过滤掉。
• 认证：HTTP/SSE 类型确认 headers 中的认证信息正确。
• 超时：连接慢可调整 timeout 字段。
• MCP 配置项标注“需重启”，修改后先试 /mcp reload，仍不生效再重新启动。
• 完整参考见 MCP 参考。

​

插件问题

插件未加载或组件缺失时：

• 用 /plugins 查看已安装插件。
• Manifest：manifest 位于 .qoder-plugin/plugin.json（可省略）；若已声明，确认 name 合法（kebab-case、无空格）。
• 目录结构：组件需位于约定目录（commands/、agents/、skills/、hooks/hooks.json、.mcp.json 等），或在 manifest 中显式声明路径。
• 安全限制：security.blockGitExtensions 为 true 时会阻止从 Git 加载插件；security.allowedExtensions 非空时仅允许匹配的来源。
• 完整参考见 插件参考。

​

下一步

• Hooks 参考：Hooks 参考。
• MCP 参考：MCP 参考。
• 插件参考：插件参考。
• 加载问题：Memory、Skills 和 Agent 未加载。