故障排查
Agent 无法连接 Studio、等待文件夹授权时如何处理，以及各拒绝代码的含义
Agent 无法连接
先查看设置 → Agent 接入。端点提供服务时 地址 下显示运行中，关闭时显示未运行，启动失败时显示 无法启动： 及原因
| 现象 | 原因 | 处理 |
|---|---|---|
| Agent 没有 NarraLeaf 的工具 | Studio 未运行，或 允许 Agent 连接 未打开 | 打开 Studio 并开启该开关，然后重启 Agent 或重新连接 |
| 连接被拒绝 | 配置 Agent 之后端口改过 | 对照 地址 中的端口检查 Agent 的配置，重新复制配置并重启 Agent |
| 地址 显示 无法启动：端口 … 已被其他程序占用 或 …已被系统保留 | 其他程序占着该端口，或 Windows 把它保留给了 Hyper-V、WSL 或 Docker。Studio 不会自己换端口 | 在 端点端口 里填一个空闲端口，重新复制配置并重启 Agent |
| Agent 报告令牌缺失或错误 | 令牌已重新生成，或配置是手工输入的 | 重新复制配置 |
| Agent 报告不接受来自网页的请求 | 客户端像浏览器一样发送了 Origin 请求头 | 改用在本机作为独立程序运行的客户端 |
| 客户端始终连不上，或以 HTTP 405 失败 | 客户端配置为旧的 HTTP+SSE 传输方式 | 改为 Streamable HTTP |
| Claude Code 只在某一个文件夹中有这些工具 | 添加服务器时没有加 --scope user | 在该文件夹中运行 claude mcp remove narraleaf -s local，再运行复制配置 → Claude Code 给出的命令 |
| Claude Desktop 提示 Agent 接入已关闭 | stdio 桥接程序已连上 Studio，但 允许 Agent 连接 未打开 | 打开该开关即可，桥接程序无需重启 |
| Claude Desktop 等待后提示 Studio 未运行或未能及时启动 | Studio 在一分钟内没有开始提供服务，或桥接程序带有 --user-data-dir 参数，此时它只连接、不启动 Studio | 打开 Studio，检查设置 → Agent 接入，然后重新连接 |
| Agent 操作了错误的项目 | 同时打开了多个项目 | 让 Agent 指明项目目录，或关闭其他项目 |
Agent 看不到某个插件的工具
插件的工具只在加载了该插件的项目处于打开状态时存在。agent_status 会列出每个已打开项目提供的插件工具
| 原因 | 处理 |
|---|---|
| 客户端在插件加载之前获取了工具列表，并沿用旧列表 | 让 Agent 重新获取工具列表，或重新连接。保持 Studio 通知流打开的客户端会在列表变化时收到通知，其他客户端在下次获取列表时看到变化 |
| 使用该插件的项目没有打开 | 打开该项目。已关闭项目中插件的工具不会提供 |
| 该插件在项目中未启用，或加载失败 | 在项目中启用它，并在控制台中查看加载错误 |
| 该插件的工具已被关闭 | 在设置 → Agent 接入 → 插件工具中重新打开。调用已关闭的工具会以 unavailable 被拒绝 |
| 打开了多个项目，调用落到了没有加载该插件的项目 | 拒绝代码为 unknown_tool，消息中列出提供该工具的项目，让 Agent 指明其中一个 |
文件夹询问
Agent 需要项目目录和允许的文件夹以外的文件时，Studio 会用 允许 Agent 读取文件夹？ 窗口询问作者。在该文件夹获得允许之前，调用会以 path_not_allowed 被拒绝，Agent 日志 中显示为 目录未授权，该行的 建议 说明属于哪种情况，详见项目以外的文件夹
| Agent 报告的内容 | 原因 | 处理 |
|---|---|---|
Waiting for the author: 加文件夹路径，或结果为 pending | 询问窗口已打开，作者尚未回答。调用最多等待约 50 秒后返回，询问窗口保持打开 | 回答询问。允许之后，Agent 的下一次尝试即可通过。如果看不到询问窗口，请查看 Agent 所操作的项目窗口，此时 Studio 的程序坞图标（macOS）会跳动，或任务栏按钮（Windows、Linux）会闪烁；排在其他询问之后的窗口，会在前一个得到回答后打开 |
| Declined by the author: 加文件夹路径 | 作者选择了 拒绝、关闭了询问窗口或按了 Escape，Agent 已被告知不要再次请求 | 如需改为允许，在 允许导入素材的文件夹 中用 添加文件夹… 添加该文件夹，再让 Agent 重试。拒绝之后的 60 秒内，Studio 对同一文件夹直接答复为已拒绝而不弹窗，因此立即让 Agent 重试不会出现新的询问 |
| Not allowed: 加文件夹路径和原因，且没有弹出询问 | 该文件夹是磁盘根目录、整个主文件夹、包含主文件夹的文件夹或 Studio 自身的文件夹，这些永远不会开放 | 让 Agent 指明实际存放文件的那个文件夹，或把文件复制到项目目录中 |
| 请求超过五个文件夹时只得到部分答复 | 一个询问窗口最多列出五个文件夹 | 无需处理，Agent 会为其余文件夹再次请求 |
开启完全访问后，Studio 不再询问任何文件夹，永远不会开放的文件夹仍然关闭
拒绝代码
Studio 拒绝一次调用时，Agent 会收到一个代码、一条消息，通常还有下一步建议；Agent 日志 中对应的行显示该代码的名称。指南已告诉 Agent 遇到每个代码该怎么做，下表说明作者需要做什么
| 代码 | Agent 日志显示 | 含义 | 作者的处理 |
|---|---|---|---|
writes_disabled | 未允许修改 | 允许 Agent 修改工程 和 完全访问 均未打开 | 需要 Agent 编辑时打开 允许 Agent 修改工程，读取不受影响 |
paused | 已暂停 | 作者在本项目中暂停了 Agent | 可以继续时选择 继续 Agent |
frozen | 工程已冻结 | 项目暂不接受修改：正在查看历史版本、被手动冻结、合并未完成、Studio 处于恢复模式，或项目已被另一个窗口接管 | 完成或退出该状态，Agent 会重试 |
live_session | 实时会话进行中 | 项目中正在进行 Team 实时会话 | 退出会话，或让 Agent 在会话结束前只读工作 |
stale_revision | 内容已变更 | Agent 读取之后页面或场景发生了变化，通常是作者编辑了它 | 无需处理，Agent 会重新读取，并在作者的版本上重做修改 |
check_failed | 检查未通过 | Agent 提交的文本无法编译，或检查发现了错误，没有写入任何内容 | 除非反复出现，否则无需处理，Agent 会修正问题后重新写入 |
not_found | 未找到 | 调用中指定的场景、页面、元素、资产或角色不存在 | 除非反复出现，否则无需处理，Agent 会列出现有内容后重试 |
path_not_allowed | 目录未授权 | 要读取的文件位于项目目录和允许的文件夹之外，且未获允许：询问仍在等待答复、作者已拒绝，或该文件夹永远不会开放 | 见文件夹询问 |
untrusted | 工程未受信任 | 项目未受信任，不能试玩、测试或构建 | 确认来源可信后，点击状态栏中的 未受信任 信任该项目 |
no_workspace | 没有打开的工程 | 没有打开的项目，或打开了多个项目而调用没有指明是哪一个 | 打开项目，或让 Agent 指明项目目录 |
invalid_args | 参数无效 | 参数不符合该工具的要求 | 无需处理，Agent 会修正调用 |
unknown_tool | 未知工具 | 没有该名称的工具 | 无需处理，Agent 会重新获取工具列表 |
unavailable | 无法执行 | 调用本身有效，但在当前状态下无法执行，例如推进一个并未运行的游戏、删除仍被使用的页面、场景、章节或资产、项目窗口没有及时响应，或调用了已被关闭的插件工具 | 查看 Agent 日志 中的消息，其中说明了缺少什么 |
internal | 内部错误 | Studio 内部出错，并非 Agent 的问题 | 如果反复出现，查看控制台中的错误并反馈 |
对于 Agent 无法自行处理的代码，例如 writes_disabled、paused 或 path_not_allowed，它会停下来询问作者