故障排除 - Amazon Q 开发者版
配置错误自定义代理加载问题工具权限问题调试自定义代理行为获得更多帮助

故障排除

本节介绍您在使用自定义代理时可能遇到的常见问题及其解决方法。

配置错误

JSON 语法无效

问题：自定义代理加载失败，出现 JSON 解析错误。

症状：

  • 提及“JSON 无效”或“语法错误”的错误消息

  • 自定义代理未出现在 /agent list 中

  • 回退到默认代理行为

解决方案

  • 使用 JSON 验证器或 linter 验证 JSON

  • 检查常见的 JSON 错误：

    • 数组元素或对象属性之间缺少逗号

    • 最后一个元素后面有尾随逗号

    • 括号或大括号不匹配

    • 字符串值中未转义的引号

  • 使用 /agent schema 来验证配置结构

架构验证错误

问题：自定义代理配置与预期架构不匹配。

症状：

  • 有关未知配置字段的警告

  • 自定义代理行为与配置不匹配

  • 缺少必填字段错误

解决方案

  • 使用 /agent schema 来将您的配置与架构进行比较

  • 检查字段名称是否有拼写错误（例如 allowedTools 与 allowedTool）

  • 验证数据类型是否符合架构要求（数组与字符串、布尔值与字符串）

  • 请查看 Amazon Q 开发者版 CLI 补充文档中的 Agent Format 文档，以了解正确的语法

自定义代理加载问题

未找到自定义代理

问题：自定义代理未出现在列表中或无法使用。

症状：

  • /agent list 未显示您的自定义代理

  • /agent use [name] 失败，并显示“未找到代理”

  • 在没有警告的情况下回退到默认代理

解决方案

  • 验证自定义代理文件位于正确的位置：

    • 全局：~/.aws/amazonq/cli-agents/[name].json

    • 本地：amazonq/cli-agents/[name].json

  • 检查文件权限 - 确保文件可读

  • 验证文件名是否与您尝试使用的自定义代理名称相匹配

  • 确保文件具有 .json 扩展名

加载错误的自定义代理版本

问题：正在加载的自定义代理版本与预期版本不同。

症状：

  • 自定义代理行为与您最近的配置更改不符

  • 有关自定义代理冲突的警告消息

  • 意外的工具可用性或权限

解决方案

  • 检查本地目录和全局目录之间是否存在自定义代理名称冲突

  • 请记住，本地自定义代理优先于全局自定义代理

  • 使用 /agent list 查看正在加载哪个版本

  • 如有必要，移除或重命名冲突的自定义代理文件

工具权限问题

工具不可用

问题：自定义代理无法访问您配置的工具。

症状：

  • 有关未知或不可用工具的错误消息

  • 自定义代理请求对 allowedTools 中工具的权限

  • MCP 服务器工具不起作用

解决方案

  • 验证 tools 数组中工具名称的拼写是否正确

  • 对于 MCP 工具，请确保在 mcpServers 中正确配置了服务器

  • 检查 MCP 服务器是否正在运行且可访问

  • 为 MCP 工具使用正确的语法：@server_name/tool_name

  • 对照 Amazon Q 开发者版 CLI 补充文档中的 Built-in Tools 文档验证内置工具名称

/tools 命令返回空列表

问题：/tools 命令显示没有可用的工具或工具少于预期。

症状：

  • /tools 返回一个空列表

  • 工具列表中缺少预期的工具

  • 自定义代理似乎没有任何功能

常见原因：

  • 自定义代理配置中的 tools 数组为空

  • tools 数组中的工具名称有拼写错误

  • MCP 服务器工具名称不正确（缺少服务器前缀）

  • MCP 服务器配置问题导致无法加载工具

解决方案

  • 检查自定义代理配置中是否包含具有有效工具名称的 tools 数组

  • 验证工具名称拼写是否正确（区分大小写）

  • 对于 MCP 工具，请确保使用正确的服务器前缀格式：server-name___tool-name

  • 使用默认代理进行测试以确认工具可用：q chat，然后是 /tools

  • 如果使用外部工具，请检查 MCP 服务器状态

意外权限提示

问题：自定义代理提示您为您认为已预先批准的工具授予权限。

症状：

  • allowedTools 中列出的工具出现权限提示

  • 尽管配置了自定义代理，但工作流程仍中断

解决方案

  • 确保工具同时列在 tools 和 allowedTools 数组中

  • 检查两个数组之间的工具名称中是否有拼写错误

  • 对于 MCP 工具，请在 allowedTools 中使用具有服务器前缀的完整名称

  • 验证是否正确应用了 toolAliases

调试自定义代理行为

缺少上下文或资源

问题：自定义代理似乎无法访问预期的文件或上下文。

解决方案

  • 验证 resources 数组中的文件路径是否正确以及文件是否存在

  • 检查资源中的 glob 模式是否与预期文件匹配

  • 确保钩子命令成功执行并产生输出

  • 手动测试钩子命令以验证它们在您的环境中是否有效

  • 如果命令被切断，请检查钩子超时设置

MCP 服务器问题

问题：MCP 服务器无法运行或工具不可用。

解决方案

  • 验证 MCP 服务器命令正确且可执行文件在您的 PATH 中

  • 检查是否设置了必需的环境变量

  • 独立测试 MCP 服务器以确保其正常运行

  • 查看 MCP 服务器日志中的错误消息

  • 如果服务器启动速度很慢，请增加超时值

  • 有关 MCP 故障排除的更多信息，请参阅将 MCP 与 Amazon Q 开发者版结合使用

测试自定义代理配置

要系统化地测试自定义代理配置：

  1. 使用 JSON 验证器验证 JSON 语法

  2. 使用 /agent schema 对照架构检查配置

  3. 使用 /agent list 测试自定义代理加载

  4. 使用 /agent use [name] 切换到自定义代理

  5. 单独测试每个工具以验证访问和权限

  6. 验证资源和钩子是否提供了预期的上下文

  7. 测试常用工作流程以确保自定义代理按预期运行

获得更多帮助

如果您继续遇到代理问题：

  • 请查看 Amazon Q 开发者版 CLI 补充文档中的完整 agent configuration 文档

  • 查看 Built-in Tools 参考以了解工具特定的配置

  • 有关与 MCP 相关的问题，请查阅 MCP 文档

  • 从较简单的代理配置开始，然后逐渐增加复杂性

  • 将您的配置与代理示例和使用案例中的示例进行比较

  • 请记住，代理切换和编辑要求启动新的聊天会话，而不是使用会话中命令