排查智能体连接故障

先从 Chorus 中可见的症状入手。排查时尽可能在前台运行后台服务，因为启动错误在前台更容易看到。

本地账号登录或邀请失败

• 托管本地账号不是 DEFAULT_USER / DEFAULT_PASSWORD 演示登录。请超级管理员创建本地账号工作区并邀请首位工作区管理员，再由该管理员管理后续用户和重置。此流程不靠本地认证环境变量或邮件服务启用。
• 输入用户名或邮箱，出现选择时确认正确的工作区或角色。本地账号不能登录 OIDC 工作区。统一的凭据无效响应可能表示密码错误、账号不存在，或账号仍待邀请确认、被禁用或删除，不能据此判断账号是否存在。
• 必须先接受邀请再登录。邀请／重置链接有效期为 24 小时，只能使用一次，重新生成或相关账号变更会使其失效。请向相应管理员索取新链接，Chorus 不会自动发送邮件。设置密码后仍需单独登录。密码至少 8 个字符，最多 72 个 UTF-8 字节。
• 密码重置或账号变更后，旧本地会话可能因版本过期被拒绝。禁用或删除的用户、不兼容的工作区模式都不能访问；无法读取当前账号状态也不会授予权限。应恢复数据库连接，而不是绕过账号检查。
• 登录成功后立即失效时，检查公开源、Cookie 策略，以及所有副本共享的持久化 NEXTAUTH_SECRET。HTTPS 使用 COOKIE_SECURE=true，false 仅用于可信的 HTTP 试用环境。移除 Default Auth 变量不会关闭托管本地账号的密码登录。

参见认证配置和运维指南。排障材料中不得分享凭据链接 URL、令牌、密码、Cookie 或签名密钥。

登录返回 429 或各副本限流不一致

HTTP 429 和 RATE_LIMITED 表示触发认证限流。等待 Retry-After 指定的秒数再试，反复重试不是恢复方法。身份查找每 60 秒允许 30 次，本地密码登录和邀请／重置确认分别每 60 秒允许 10 次。启用可信代理地址时，共用地址的用户可能共用该操作的限额。

确认每个副本使用同一 Redis 配置。非空 REDIS_URL 优先于基于 host 的 TLS 配置。REDIS_URL 和 REDIS_HOST 均未设置时仅在进程内限流；Redis 故障时，每进程备用计数器也只能维持本地限制。检查 auth-throttle 和 Redis 日志中的连接或命令错误，包括 READONLY/OOM；SSE 正常并不代表独立的认证连接正常。意外的限流后端错误可能放行，因此仍需边缘层限流。Redis 故障不是有意拒绝所有登录的 fail-closed 策略。

根据实际强制执行的代理链核对 AUTH_TRUST_PROXY 和 AUTH_TRUST_PROXY_HOPS，不要相信任意客户端请求头。缺失或无效的可信地址会停用地址计数器，但身份限流仍然生效。不要为了消除错误而启用信任，也不要允许绕过代理直接访问。默认值、超时与恢复边界参见共享认证限流。收集时间和脱敏错误码，不要收集凭据或原始请求头。

智能体一直不上线

1. 运行 chorus agents，确认该智能体已在本机配置（它会列出每个智能体的名称、UUID 和运行后端；绝不会打印 API 密钥）。
2. 在预期的工作目录中运行 chorus daemon。
3. 确认所选运行后端的 CLI 已安装，并且可以在 PATH 中找到。
4. 如果凭据缺失或有误，运行 chorus agents add（或 chorus login），填入正确的 Chorus 网址和智能体 API 密钥。
5. 打开设置 → 智能体，检查是否出现新的在线心跳。

HTTP 401 通常表示密钥无效或已撤销。HTTP 403 表示凭据有效，但缺少执行当前操作所需的权限。请修正凭据或补上所需权限，不要为此授予宽泛的管理员访问权限。

服务已停止或反复重启

运行：

chorus daemon status
chorus daemon logs
chorus daemon restart

如果服务的 PATH 中找不到智能体 CLI，请修复安装，然后带上预期的运行后端和工作目录重新运行 chorus daemon install。在 Linux 上，请使用 Chorus 生成的服务，不要再同时使用 -d 后台分离模式。

Chorus 显示的工作目录不对

停止后台服务，并用预期的路径启动它：

chorus daemon --cwd /path/to/your/project --chorus-only

有多个项目时，重复使用 --cwd。如果你修改的是已安装的服务，请用完整的目标目录列表重新安装它。然后在设置 → 智能体中确认每个预期路径都出现在该连接下。

发起远程工作后没有反应

请检查：

• 所选连接仍处于在线状态；
• 项目或任务没有固定到另一个已离线的连接；
• 工作目录已由后台服务注册；
• 智能体有权读取该条目并执行所请求的操作。

请恢复已固定的连接，或明确选择一个新目标。不要仅仅为了让缺失的目标出现而扩大文件系统访问范围。

无法打断或恢复

打开对话，检查它的当前状态是否允许你请求的打断或恢复。持有该会话的后台服务必须在线。恢复始终回到原来的连接和工作目录。

如果进程崩溃了，恢复之前请检查文件系统中已产生的部分修改。完整的恢复步骤见中断与恢复会话。

智能体尚未回复，回合就失败了

打开失败的对话回合，阅读 Agent 唤醒失败摘要；有详情时选择展开错误详情。没有回复不代表没有记录诊断，重试前先看失败回合诊断。

--chorus-only 违规（Claude Code，Chorus 0.22.2 及更高版本）。 如果详情显示 --chorus-only is not being enforced by this Claude Code build，并列出仍可用的工具，说明后台服务在唤醒启动时发现了 Chorus 允许列表之外的工具。它已终止整个进程树且不再转发任何输出，因此受限唤醒无法在该 Claude Code 版本上运行。后台服务给出的处理方式是 --yolo；只有在你确实打算让智能体使用完整工具集时才改用它，否则请保留 --chorus-only 并尝试其他 Claude Code 版本。参见 --chorus-only 的强制范围。

错误详情中的已知凭据会被替换为 [redacted]。其他文本不会脱敏，分享前请先检查。

若 Linux 后台服务在 SSH 退出或重启后离线，请检查 chorus daemon status 和用户驻留设置。若 Codex 配置后仍用旧凭据，请按 App Server 安全重启流程操作，而不只是运行 chorus daemon restart。

收集有用的诊断信息

在受限的前台模式下复现一次问题：

chorus daemon --verbose --chorus-only --cwd /path/to/your/project

记录失败的步骤、时间、运行后端、状态信息和相关日志行。绝不要分享 API 密钥。删除与问题无关的私有网址、用户名、仓库路径、提示词和命令输出。