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

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

故障排除

本节介绍您在使用自定义代理时可能遇到的常见问题以及如何解决这些问题。

配置错误

无效的 JSON

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

症状：

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

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

  • 回退到默认代理行为

解决方案

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

  • 检查常见的 JSON 错误：

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

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

    • 不匹配的括号或大括号

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

  • /agent schema用于验证您的配置结构

架构验证错误

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

症状：

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

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

  • 缺少必填字段错误

解决方案

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

  • 检查字段名称是否有错别字（例如 allowedTools v allowedTool s）

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

  • 请查看 Amazon Q Developer CLI 补充文档中的代理格式文档，了解正确的语法

自定义代理加载问题

未找到定制代理

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

症状：

  • /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 补充文档中的内置工具文档验证内置工具名称

/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 疑难解答的更多信息，请参阅在 Amazon Q 开发者中使用 MCP

测试自定义代理配置

要系统地测试您的自定义代理配置，请执行以下操作：

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

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

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

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

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

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

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

获取更多帮助

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