常见问题与故障排查

模型连接验证失败

按界面显示的失败类型依次检查：

1. 网络或不可达：确认 Base URL、代理、DNS 和 HTTPS 证书；检查浏览器是否已允许 Panelot 访问端点域名。
2. Key 无效或权限不足：确认 Key 未过期，且能访问所选接口与模型。
3. 协议错误：确认 OpenAI 兼容与 Anthropic 类型没有选反；按服务文档检查 /v1、自定义 Header 和兼容性选项。
4. 工具调用失败：部分“OpenAI 兼容”端点只支持文本，不支持结构化工具调用。它们可能适合聊天，但不适合浏览器 Agent 任务。
5. 模型列表为空：在连接设置中手工填写准确模型 ID，每行一个，再选择默认模型。

验证通过后真实请求仍失败，说明具体模型、参数、上下文长度或流式细节存在差异。用短消息、无附件、默认参数进行最小测试，再逐项恢复设置。

提示“端点返回了不兼容的响应”

这通常表示流式响应没有正确结束、工具参数无法解析，或服务器返回了 Panelot 不支持的结束原因。检查接口类型和兼容性开关，并查看上游服务日志。Panelot 不会把已中断的响应当作完整成功，也不会自动重放原请求。

页面无法引用、读取或操作

• 确认目标是普通 http:// 或 https:// 页面；chrome://、edge://、扩展商店和其它受保护页面不能被普通扩展脚本访问。
• 刷新目标网页后重试。扩展更新或重新加载后，旧页面可能仍使用过期的内容脚本。
• 检查浏览器的 Panelot 扩展详情，确认目标域名的站点访问未被撤销。
• 页面正文为空时，网站可能主要使用 Canvas、跨域框架、封闭组件或动态加载。尝试明确让 Panelot 重新读取，必要时使用截图；仍不可靠时手动完成关键步骤。
• 若操作对象在任务期间变化，Panelot 会拒绝沿用旧目标。重新读取页面后再操作。

侧边栏显示页面标题不表示页面已附加。需要点击“附着到对话”或从 @ 菜单选择它。

点击或输入可能已经发生，但任务报错

网页通道可能在操作发出后、结果返回前断开。此时 Panelot 会把结果视为“不确定”，不会自动重复点击或输入。先手动查看网页状态，再在恢复卡片中选择已完成、重新执行或标记失败，避免重复提交表单或订单。

为什么出现浏览器调试横幅

某些截图、坐标操作、可信输入或深层页面读取需要浏览器调试接口。横幅是 Chrome/Edge 的正常提示。停止任务后连接通常会在空闲时断开；若持续不消失，请停止任务并在扩展管理页重新加载 Panelot。

上下文过长或回答被截断

• 新建会话，减少历史记录。
• 移除不必要的页面、文件和 MCP Resource 胶囊。
• 将大任务拆成多轮，并让模型先提取必要信息。
• 检查所选模型的真实上下文窗口与最大输出设置。

页面轻量引用会限制正文长度。需要后续内容时，让 Panelot 按范围继续读取，不必一次附加多个完整页面。

无法上传文件

• 新会话需要先发送第一条消息，创建正式会话后才能上传。
• 单文件不得超过 8 MB。
• 上传工具只会使用当前会话中由你提供的附件，不能把其它会话附件当作当前上传文件。

Skill 导入失败或运行不完整

• 文件必须包含由 --- 包裹的 YAML 头部，并具有合法的 name 和 description。
• URL 必须使用 HTTPS，并直接返回 SKILL.md 内容；GitHub 仓库页面或目录 URL 不会自动解析。
• URL 文件不得超过 1 MB。
• 单文件导入不会取得 scripts/、references/ 或 assets/。若正文依赖这些文件，需要改写为可独立运行的单文件 Skill。
• 同名 Skill 需要选择覆盖或自动改名。

Plugin 安装失败

确认 ZIP 或仓库包含有效的 .codex-plugin/plugin.json，且所有资产都在清单中声明。Panelot 会拒绝超限归档、路径穿越、符号链接和可执行内容。安装前分析需要访问 GitHub 或归档域名；检查浏览器是否授予对应站点权限。

Plugin 安装后默认停用。若资产没有生效，先在“设置 → Plugins”核对并启用它。

MCP 无法连接

• Panelot 只支持远端 Streamable HTTP，不支持本地 stdio 或旧式独立 SSE Server。
• 粘贴配置必须含 url；本地 command 会被忽略，若没有任何远端 URL 会直接报错。
• 检查服务器域名权限、Bearer Token 和远端 CORS/认证配置。
• OAuth 服务需要在设置页通过“授权”完成交互；后台任务无法自行打开登录流程。
• 授权元数据变化时，重新核对显示的资源服务器、签发方和端点，再确认新的权限计划。
• 连接成功后展开工具清单，确认所需工具没有被单独停用。

数据导入被阻止

关闭或结束正在运行的任务，处理待审批和待输入，再重新预检。排队、暂停或中断状态需要你明确勾选允许丢弃。导入成功后必须重载扩展；重载前聊天命令会被维护状态拒绝。

导入不会恢复附件二进制。若历史消息显示附件不可用，这是 JSON 备份格式的限制，重新加载扩展也无法恢复。

界面持续显示“重新连接”或提示协议不兼容

1. 打开 chrome://extensions 或 edge://extensions。
2. 找到 Panelot 并点击“重新加载”。
3. 刷新需要操作的网页，然后重新打开侧边栏。

只刷新网页不会重启扩展后台。若你刚升级了手动安装包，确认浏览器加载的是同一版本的完整目录，没有混用旧文件。

仍无法解决

在提交问题前，请记录 Panelot 版本、浏览器版本、接口类型、已脱敏的错误信息和可重复步骤。不要附上 API Key、Token、完整私人对话、浏览器配置文件或含隐私的截图。

可以前往 GitHub Issues 报告普通问题。安全问题不要公开提交，请按仓库的 Security Policy 使用私密漏洞报告。