遇到任何问题，都先让你的 Agent 排查和解决，例如 Claude Code、Codex。把现象和报错告诉它，它能登录服务器看日志、用 nb-studio 查 Studio 里的状态，对照这一页和相关文档找到原因并处理。需要你在网页上操作或提供凭据时，它会停下来告诉你。
安装和登录
打开地址看不到登录页。 地址要带上 /main/，例如 https://studio.example.com/main/。
不知道用什么账号登录。 用户名是 nocobase，密码在部署目录的 .env 里：grep INITIAL_ADMIN_PASSWORD .env。见 安装 Studio。
界面语言不对，或者登录页上有「注册」。 config.yml 里没有设置界面语言，或者没有关闭自助注册。把 i18n.defaultLocale 设为团队使用的语言，例如 zh-CN；加上 auth.emailAndPassword.disableSignUp: true。改完重启 Studio。
拉取镜像失败。 提示 unauthorized：token 不对，重新登录镜像源。拉取 postgres:16 超时：服务器访问不了 Docker Hub，配置镜像加速或改用已有的 PostgreSQL。下载镜像层卡住：放行和 token 一起提供的镜像层下载地址。见 安装 Studio。
容器起不来或反复重启。 运行 docker compose logs studio 看原因。常见的有：没有先取出 config.yml，Docker 建了一个同名目录；storage 目录的属主不是 UID 1000；没有设置加密密钥。
nb-studio login 批准后还是没登录上。 批准时，nb-studio login 要一直在运行；它退出后再批准，不会生效。重新运行 nb-studio login，用新的验证码批准。
连接 Git
创建 GitHub App 时，GitHub 报错 “Hook url is not supported because it isn't reachable over the public Internet”。 Studio 没有公网地址，却打开了 Webhook。关掉「Webhook」再创建，Studio 改为每分钟查询一次。见 连接 Git。
新建项目时提示“仓库已创建，但尚未确认 App 的访问权限”。 GitHub App 安装时只给了部分仓库的权限。到 GitHub 上 App 的安装设置里加上这个仓库，再新建项目，选「已有仓库」。
Agent 开 PR 时报没有推送权限。 成员连接了自己的 Git 账号，但这个账号对仓库只有读权限。给这个账号写权限，或者断开个人账号，改用工作区的连接。
运行环境和 Agent
运行环境显示离线。 执行机 150 秒没有联系 Studio 就显示离线。在那台机器上运行 nocobase-runner status，确认它在运行，且能访问 Studio 的地址。
编码工具显示「需要登录」或「未安装」。 在那台机器上，用运行执行机的系统用户安装、登录这个工具，再在运行环境详情里点「重新检测」。已经装了还显示未安装，是后台服务的 PATH 里没有它：在能运行 which claude 的终端里重新运行 nocobase-runner service install，再重启服务。见 接入共享运行环境。
Agent 列表里没有某个模型。 常用的模型上报后自动启用；其他的在「添加 Agent」的可用模型里添加。模型显示「需要设置」或「版本过低」时，按提示在运行环境上处理。
任务推进
任务一直没有开始。 看任务页的「现在」一行，写明在等什么：没有在线的运行环境、并发已满、这个 Agent 只在别人的个人运行环境上，或者在等前置任务、等“初始化项目”完成。待规划的任务要先点「开始」。
排队超过 24 小时，运行失败了。 没有运行环境领取这项工作。接入或启动运行环境后，在任务负责人收到的卡片上点重试。
调度 Agent 停下来问要不要补 CI。 项目还没有接 CI，PR 没有检查结果。接入 CI，或者回复不经 CI 直接验收。也可以在任务描述里事先写明。见 连接 CI。
Agent 之间来回很多次，暂停了。 一个任务 24 小时内由 Agent 评论触发的运行，默认最多 20 次。先看动态和运行记录，是不是在反复修同一个问题；确认要继续，在任务页点「继续（评论运行已达上限）」。见 回答 Agent 的提问。
交付报告里没有截图，或者说截图没做成。 运行环境上缺少浏览器。按 接入共享运行环境 的准备一节，装好 Chromium 和它的系统依赖。
编码工具的额度用完了。 调度 Agent 会立即把这一步交给另一个合适的 Agent，优先换一家厂商。这个工具在那台运行环境上暂停接活：恢复时间已知时，到点自动恢复；未知时，额度恢复后，由运行环境的主人或管理员在运行环境详情的「额度」里清除标记。
验收和合并
「合并」按钮不能点。 PR 有冲突、还是草稿，或者检查还在进行。冲突由调度 Agent 安排解决；检查完成后再合并。
按钮是「仍然合并」。 必需的检查失败，或者没有检查结果。确认可以合并时，填写原因后合并，这次合并会记在 PR 和任务动态里。
在 GitHub 上直接合并了 PR，Studio 里的任务没变。 Studio 每分钟查询一次（开了 Webhook 时会立即知道），稍等片刻，任务会自动变为已完成。
预览和部署
PR 没有预览。 项目还没有接入 CI，或者 CI 访问不到 Studio 的地址。见 连接 CI。
预览打开很慢。 预览一段时间没人访问会停止或休眠，再次打开时要重新启动或准备，稍等即可。
部署到生产没有反应。 生产环境受保护，部署变成了部署申请，在等审批人批准。审批人在收件箱的「待我决定」里处理。
通知
邀请邮件没有发出去。 Studio 还没有配置邮件通道，结果里显示「邮件未发送」。复制邀请链接发给同事，或者配置邮件，见 通知与推送。
手机收不到推送。 推送需要 Studio 通过 HTTPS 访问，并由管理员配置好推送私钥；iPhone 要先把 Studio 添加到主屏幕，再从主屏幕打开订阅。