Appearance
使用 Copilot Cloud Agent 时遇到任务卡住、Copilot 不响应 PR 评论、GitHub Actions 未自动运行等问题？本页整理常见故障的排查步骤和解决方法。
GitHub Copilot Cloud Agent 故障排查：常见问题和解决方法
检查前提条件
出现任何问题，先确认：
- 套餐支持：Cloud Agent 需要 Pro、Pro+、Business 或 Enterprise 套餐，Free 不支持
- 仓库权限：对于组织仓库，Cloud Agent 功能需要管理员在组织/仓库设置中启用
- 账号类型：托管用户账号（Managed User Account，即企业 SSO 用户）的个人仓库不支持 Cloud Agent，需要使用组织仓库
问题一：分配 Issue 后 Copilot 没有反应
表现：将 Issue 分配给 Copilot 后，没有出现 👀 反应，也没有创建 PR。
排查步骤：
- 等待 1~2 分钟后刷新页面
- 检查仓库设置 → Copilot → Cloud agent：确认 Cloud Agent 功能已启用
- 确认你的 Copilot 套餐支持 Cloud Agent（Pro+ 以上或 Business/Enterprise）
- 如果是组织仓库，确认组织管理员已开启 Cloud Agent 权限
解决：取消分配后重新分配即可重试。
问题二：Copilot 不回复 PR 评论中的 @copilot
表现：在 PR 评论中 @copilot 发出指令，没有得到任何响应。
原因和解决：
- 权限不足：你必须对该仓库有 write 权限才能通过 PR 评论 steer Copilot
- PR 状态：只能在 open 状态的 PR 上 steer，已关闭或合并的 PR 不可用
- 格式正确性：确保评论包含完整的
@copilot和具体指令
问题三：GitHub Actions 工作流未触发
表现：Copilot 提了 PR 但 CI 没有自动运行。
原因：这是默认行为——GitHub 要求人工审批 Copilot 提的 PR 才能运行 Actions。
解决：
- 在 PR 页面点击「Approve and run workflows」手动触发
- 如果希望自动触发：仓库设置 → Copilot → Cloud agent → 关闭「Require approval for workflow runs」
⚠️ 关闭审批前请评估安全风险（参见Cloud Agent 设置配置）
问题四：Session 日志显示 Copilot 卡住
表现：任务长时间没有进展，Session 日志不再更新。
解决：
- 在 Session 日志页面点击「Stop session」停止当前任务
- 取消 Issue 的 Copilot 分配
- 重新分配，触发新的 session
问题五：网络访问被防火墙阻止
表现：Session 日志或 PR 评论中出现防火墙拦截警告。
原因：Cloud Agent 的运行环境有防火墙限制，只允许访问必要的外部服务，防止数据泄露。部分依赖外部 API 的任务可能会遇到网络限制。
处理：查看 PR body 或评论中的具体警告信息，了解哪个外部请求被拦截。如果是必要的外部访问，可能需要联系管理员配置例外规则。
问题六：图片上传失败
表现：向 Cloud Agent 提供截图或图片时出错。
限制：单张图片最大 3 MiB，超过此大小的图片会被拒绝。
解决：压缩图片后重新上传。
常见问题
Q: Copilot 的代码有 Bug，它能自己发现并修复吗？
A: 如果配置了 GitHub Actions 并允许运行，Copilot 会在 CI 失败后尝试修复。如果 CI 未运行或未配置，需要你在 PR 评论中指出具体问题，@copilot 请它修改。
Q: Cloud Agent 任务失败但不知道原因，怎么调试？
A: 打开 Session 日志（PR 中每个 commit 包含日志链接，或从 Agents 面板进入），查看 Copilot 的操作记录。日志包含所有工具调用和错误信息，通常能定位问题所在。
Q: 组织管理员如何为所有仓库批量禁用 Cloud Agent？
A: 在组织设置 → GitHub Copilot 中，可以配置 Cloud Agent 策略，选择允许所有仓库、特定仓库或完全禁用。