常见问题与排查

本页汇总使用中最常见的问题和处理办法。遇到没列出的问题，先按 通用排查步骤 收集信息。

通用排查步骤

1. 看状态：gg status 查看本机绑定的服务器和归属人。

2. 自检：gg doctor 依次检查服务器连接、Agent、git 凭据、磁盘、换行符，以及 macOS 上的屏幕录制与辅助功能权限。每行前的标记：✓ 正常、! 警告、✗ 错误、- 跳过；有错误时命令以非零状态退出。

   ✓ 服务器连接	HTTPS 正常
   ✓ Agent	Claude Code 2.1.3 · Codex 0.46.0 可用
   ✓ git 凭据	SSH · 可访问 · todo-app × 后端助手
   ✓ 磁盘	工作区 1.8 GB · 剩余 212 GB

3. 看日志：gg logs 显示最近的 daemon 日志，可用 --level error|warn|info|debug 和 --lines 数量 过滤。

4. 导出诊断包：gg logs --export 生成一个 zip（默认放在桌面，名为 gonggong-diag-日期-时间.zip，也可 gg logs --export 路径.zip 指定），内含脱敏后的日志、自检结果、版本信息和去掉 token 的本机配置，可以直接发给管理员。

桌面端用户在「日志与诊断」页可以完成同样的操作，见 功能页面。命令详情见 命令参考。

Bot 与运行

Bot 显示「离线」，消息一直「离线等待」

Bot 所在机器的 daemon 没有连上服务器。

• 命令行用户：确认那台机器上 gg run 还在运行（关掉终端窗口就会断开）。
• 桌面端用户：确认 App 在运行（关掉窗口后仍在菜单栏，选「退出」才会停止）。
• 运行 gg doctor 查看「服务器连接」一项的报错。

离线期间发给它的请求会等待上线，默认最多 30 分钟（群管理员可在群设置「群级参数」→「Bot 离线等待上线（分钟）」调整），超时后运行变为「已作废」，需要重新发起。

运行一直「排队中」

卡片上的步骤会写明原因，常见的有：

• 「本群上一轮未结束，排第 N」：同一个 Bot 在同一个群里一次只跑一轮，等上一轮结束即可，或用 /stop 停止上一轮。
• 工作区还在准备（如首次克隆仓库），克隆完成后自动开始。
• Bot 的并发已满：同时运行的轮次达到「并发上限」，其他群的任务结束后自动开始。

显示「无权触发」

你不在这个 Bot 的触发范围内。请 Bot 主人在 Bot 设置里把你加入「指定名单」，或把触发范围改为「任何群成员」。注意「完全访问」档位只允许指定名单触发。见 Bot 设置与权限。

「还没有工作区，本次未执行」或「所在机器无法访问仓库」

群里出现类似提示：

• 后端助手 还没有工作区，本次未执行；王磊 绑定工作区后重新发起即可
• 后端助手 所在机器无法访问仓库（无权限或仓库不存在），本次未执行；王磊 配置后点「重新检查」

Bot 用归属人机器上自己的 git 凭据访问仓库。请 Bot 主人在自己机器上确认能访问该仓库（例如 git ls-remote <仓库地址>，或看 gg doctor 的「git 凭据」一项），括号里的原因可能是「无权限或仓库不存在」「网络或证书问题」「连接超时」。配置好凭据后，在群设置「仓库与工作区」或群里的提示条上点击「重新检查」。见 仓库与工作区。

新建 Bot 时看不到 Claude Code / Codex，或 Bot 显示「agent 缺失」

daemon 没有在这台机器上检测到对应的 CLI。

1. 在终端确认 claude --version / codex --version 能运行，且已登录。
2. 版本不能太旧：Claude Code 需 2.0.0 及以上，Codex 需 0.40.0 及以上。
3. 运行 gg agents 查看 daemon 检测到的结果。daemon 每分钟会重新检测一次，装好后稍等即可自动上报；也可以在 Web 的机器详情「Agent 工具」里直接安装或升级。
4. CLI 装在非常规位置时，用 gg config agent claude --path /完整/路径/claude（Codex 同理）指定。

见 Agent 工具与供应商。

绑定与连接

绑定时报「绑定码已失效」「绑定码无效」

接入链接和绑定码只能用一次，而且有有效期（对话框里有倒计时）。

• 「绑定码已失效（已过期或已被使用），请在 Web 端重新生成」：重新打开「绑定新机器」生成新的。
• 「尝试次数过多，绑定码已锁定」：稍后重新生成。
• 「绑定码格式错误，应为 XXXX-XXXX」：检查复制是否完整。

连不上服务器

• 「无法连接服务器 …」：确认这台机器能访问服务器地址（防火墙、端口、内网/VPN），地址的 http:// / https:// 与网页地址一致。
• daemon 不校验服务器证书，自签证书、换证书、反向代理换证书都不影响绑定，换证书后也不用重新绑定。

局域网内其他机器怎么访问

• Web：局域网成员可以直接用服务器的地址打开网页。用自签证书时浏览器会提示不受信任，确认继续即可。
• daemon：用网页地址直接绑定即可，http:// 和 https:// 都行。想加密传输时，管理员用 bash scripts/dev-cert.sh 生成包含本机局域网 IP 的自签证书，按提示设置 GONGGONG_TLS_CERT / GONGGONG_TLS_KEY 后启动服务器与网页。网页开发服务器默认只监听本机，对局域网开放需设置 WEB_HOST=0.0.0.0。详见 HTTPS 与证书、本地开发与测试。
• 如果用纯 http:// 局域网地址打开网页，部分浏览器功能受限。点击「复制命令」后没有出现「已复制」提示时，请手动选中命令文本复制。

安装与系统

输入 gg 打开的是 git 图形界面

oh-my-zsh 的 git 插件把 gg 设成了 git gui citool 的别名。在 ~/.zshrc 末尾加一行后重开终端：

unalias gg 2>/dev/null

临时绕过可以用 command gg …。

macOS 拦截运行

• 下载的 gg 被拦截：去掉「来自互联网」标记：

  xattr -d com.apple.quarantine ~/.local/bin/gg

  本机从源码编译的 gg 不会被拦截。

• 桌面端提示「无法打开」：在「系统设置 → 隐私与安全性」底部点击「仍要打开」，或在「应用程序」里右键图标选「打开」。

• 实时画面、远程操作不可用：需要在「系统设置 → 隐私与安全性」的「屏幕录制」「辅助功能」中允许运行 gg 的程序（终端或桌面端）。gg doctor 会提示缺哪项。见 权限与系统设置。

下载 Agent 工具、适配器很慢或失败

daemon 首次运行会用 npm 下载 ACP 适配器，在 Web 或桌面端安装 Node.js / Claude Code / Codex 时也会下载。默认下载源是国内镜像 npmmirror，可以切换：

gg agents mirror                 # 查看当前下载源
gg agents mirror official        # 改用官方源
gg agents mirror https://registry.example.com --node-mirror https://example.com/node   # 自定义
gg agents mirror npmmirror       # 改回默认

共工空间只修改自己的配置，不会改动你的全局 npm 设置。

gg 提示 command not found

gg 所在目录不在 PATH 里。安装位置与 PATH 设置见 安装。

预览

预览卡片打不开

• 卡片显示「离线」：Bot 所在机器的 daemon 没有连上，预览流量经它转发，先让机器上线。
• 卡片显示「服务已停止」：预览背后的服务没在运行，在卡片上点击「启动服务」，或让 Bot 重新启动服务。
• 卡片显示「已关闭」：预览默认 24 小时无人访问会自动关闭（系统参数可调），让 Bot 重新发布即可。
• 局域网部署时每个预览占用服务器的一个端口（默认 41000–41099，可用 GONGGONG_PREVIEW_PORTS 调整）。服务器默认只监听本机，需要设置 GONGGONG_PREVIEW_HOST=0.0.0.0 让局域网能访问这些端口，防火墙也要放行。
• 正式部署建议用独立的预览域名（GONGGONG_PREVIEW_DOMAIN，必须是与主站不同的域名，并配置泛域名 DNS 与证书），同时设置 GONGGONG_PUBLIC_URL 为主站地址。

详见 结果预览、反向代理与预览域名。

账号与机器

• 换机器或不再使用：在旧机器上执行 gg logout 解除本机绑定。再次 gg login 绑定同一台机器会恢复原有机器记录和其上的 Bot。
• 账号被停用或机器被吊销：daemon 下次连接会被拒绝，并清除本机凭据和托管工作区（本机 /cd 绑定的目录不会被删除）。需要恢复请联系系统管理员。

相关页面

• 命令参考
• 本地数据与日志
• HTTPS 与证书
• 术语表