常见问题与排错

先打开控制台右上角的调试模式：它会在每条回复和状态行上显示执行 ID、调用次数和错误码。在终端中， agt --output json schedule status 显示调度器的视角，agt run info <执行 ID> 显示一次执行的详情。

Agent 不回复

按顺序检查：

1. Agent 是否已启用？ 在 Agent 团队中查看它的卡片，或使用 binding_list。只创建定义是不够的，它还需要身份和已启用的绑定。
2. 响应策略是否匹配？ mentioned（默认）在私聊中回复，在群里被提及时回复。手打但没有从列表中选择的 @名字 不算提及。 manual 从不自动回复。
3. 讨论是否已授权？ 关闭发送后自动回复时发送的消息只会被保存。点击继续回复。
4. 讨论是否仍然有效？ 讨论可能已暂停、已结束、超过 30 分钟期限，或该 Agent 已用完 100 次回复。消息区上方的状态栏会说明原因。发送新消息，或点击继续回复延长期限。
5. 是否有审批在等待？ 查看输入框上方的执行横条，或交互观察 → 权限审批。
6. 它是否决定保持沉默？ 在群聊中，成员状态面板会显示 Agent 的决定和原因。[[silent]] 表示它没有要补充的内容。
7. 调度器是否在运行？ 如果控制台显示回复服务未连接，请重启 agt web。如果你在克隆的仓库中运行控制台，请先重新构建，确保控制台和调度器来自同一个 agt。

模型调用失败

• 检查协议。 Model 的 API 格式（Chat Completions 或 Responses）必须是 Provider 对该模型支持的协议。agt 不会自动切换。
• 检查工具调用。 带任何工具的 Agent 都需要开启了工具调用的模型。
• 阅读错误。 在调试模式下，执行会显示 HTTP 状态码和尝试次数。agt 对连接错误和服务端错误最多重试 10 次；配置错误和明确拒绝会立即失败。
• 列出模型。 agt provider list-models <provider> 可以确认 base URL 和密钥是否正确。
• 推理强度。 设置推理强度后不会发送 temperature。有些 Provider 会拒绝不支持推理参数的模型收到这些参数。

MCP 服务无法使用

• agt mcp probe <名称> 会按真实执行的方式启动服务并报告错误。
• stdio 服务需要绝对路径的 cwd，其命令必须在运行 agt 的进程的 PATH 中（即 Web 控制台的环境，而不是你交互式 shell 的环境）。
• token 用的环境变量必须在启动控制台或调度器的地方设置。
• Agent 只能看到挂载给它的服务。用 agent_mcp_list 或 Agent 卡片检查。

Codex Agent 无法使用

• 确认在运行 agt 的同一用户账号下执行过 codex login。
• agt harness resource test <名称> 和 agt harness models <名称> 可以在不运行模型的情况下检查配置。
• 如果一轮的状态是需要处理，说明 agt 无法确认这一轮如何结束。请检查项目文件，然后使用 /new。

执行或任务显示结果不明确

interrupted 的执行和 outcome_unknown 的任务是在工具或模型调用进行中被中断的，例如因为重启。agt 不会自动重做它们，因为工具可能已经产生了效果。请检查实际发生了什么，然后发送新消息，或核对并重试任务（见任务协作）。

控制台提示“此工作空间的负责人是 …”

第一个在某个 home 上启动控制台的人会成为负责人。请用同一身份启动控制台：agt web --principal <负责人>。 agt im owner get 可以查看负责人。

更新 agt 之后

停止 agt web，重新运行安装脚本（或重新构建），再启动 agt web 并打开新链接。旧的控制台或调度器在新版 agt 下继续运行，会导致命令不存在等错误。

获取帮助

在 https://github.com/blacsheep/agt/issues 提交 issue，附上 agt 版本（agt --version）、你的操作以及调试模式下显示的错误码。不要粘贴 API Key 或控制台链接。