排查问题

先确认失败发生在哪一步，再检查那一步需要的连接和权限。保留页面上的具体错误、发生时间与操作对象，避免只记录“不能用”。

网页打不开或无法登录

• Server 本机也打不开：检查进程、监听地址和实际端口。
• 本机可用，其他设备不行：检查网络、访问地址和“允许远程管理”，或反向代理是否正确转发。
• 提示尚未设置登录：从 Desktop 或 Server 本机执行账户初始化。
• Passkey 不可用：确认使用注册时的 HTTPS 域名和兼容浏览器。
• 忘记密码或失去验证方式：使用恢复码，或在 Server 本机执行账号重置。

不要用旧版 Owner Token 或已移除的 TLS 启动参数尝试修复当前登录流程。

模型能连接，但任务不能执行

检查是否已经为会话选定具体模型、模型是否支持所需工具，以及 Bot 是否获准使用当前电脑。服务连接成功、模型可调用、电脑在线是不同状态。

自定义模型地址必须从 Server 可达，不能只在浏览器所在设备上测试。

电脑一直离线

检查目标机器是否休眠、后台服务是否运行、保存的服务器地址是否仍可达。改过 Server 地址后，已有电脑不会自动改用新地址。

接入命令过期时重新生成。安装资源下载失败与连接 Server 失败应分别处理；尚未发布对应版本资源时，重复生成命令不会补出安装包。

平台账号已连接，但 Bot 不回复

依次检查账号是否启用、聊天是否获准、是否绑定会话、Bot 的模型和电脑是否可用。群里先用明确提及或回复测试。

然后检查平台差异：Telegram 隐私模式或 webhook、QQ 应用权限与 openid、微信是否收到过目标用户消息、飞书发布范围和事件权限。

文件打不开或没发出去

先检查文件来源电脑是否在线、文件是否仍存在、Bot 是否仍有访问权限。Web 中生成文件与平台发送成功是两件事。

查看发送的实际结果。结果不确定时，先到目标聊天确认，避免把一次暂时超时变成重复发送。

反馈问题时提供什么

提供 Astral 版本、操作系统、发生步骤、期望与实际结果，以及删去凭据后的错误信息。涉及电脑时说明类型与版本；涉及聊天时说明平台和接入方式。不要提交 API Key、Bot Token、密码、恢复码或完整个人聊天记录。

确认是程序问题后，可到 GitHub Issues提交可复现描述。