疑难解答 (Troubleshooting)

诊断并解决有关安装 PATH、本地自更新锁、密钥环 (Keyring) 访问权限以及 SSH 剪贴板转发的常见异常。

快速参考 (Quick Reference)

浏览下表以识别症状并获取即时解决方案：

错误现象 (Error Symptom)	潜在原因 (Potential Cause)	解决方案 (Target Resolution)
agy: command not found	Shell 环境中缺少二进制文件目录。	配置您的 Shell PATH
keyring: secure lock out	缺少系统服务权限或处于锁定状态。	授权密钥环权限
SSH Clipboard paste failures	协议流被阻止或缺少转发配置。	启用模拟器剪贴板转发
Advisory lock / update failures	自更新线程锁定或目录路径只读。	解决自更新锁和更新失败问题

配置您的 Shell PATH (Configure your shell PATH)

症状

执行 agy 返回 Shell 终端错误：

bash: agy: command not found

原因

安装工具将二进制文件下载到 ~/.local/bin（或 C:\Users\<Username>\AppData\Local\agy\bin），但您 Shell 活跃的 $PATH 环境变量中没有索引此目录。

解决方案

确保您的终端会话加载了二进制路径。

macOS & Linux

1. 打开您的 Shell 配置文件（~/.bashrc 或 ~/.zshrc）。
2. 在文件末尾验证或追加以下行：

   export PATH="~/.local/bin:$PATH"

3. 重新加载您的配置文件：

   source ~/.zshrc

Windows (PowerShell)

1. 以管理员身份打开 PowerShell 终端并执行：

   [System.Environment]::SetEnvironmentVariable("Path", [System.Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Program Files\Google\antigravity-cli", "User")

2. 重启您的终端模拟器以刷新系统注册表环境。

授权密钥环权限 (Authorize keyring permissions)

症状

启动时，CLI 卡住、打印 DBUS 警告，或抛出密钥环访问异常：

Error: failed to retrieve token: secret keyring is locked

原因

Antigravity CLI 使用安全密钥链库（Apple Keychain、Linux 通过 DBUS 的 secret-service，或 Windows Credential Manager）来加密您的会话 Token。如果后台守护进程被锁定或处于无头 (headless) 状态，CLI 将无法读取凭据。

解决方案

macOS

1. 打开“钥匙串访问 (Keychain Access)”应用。
2. 搜索 Antigravity CLI 安全项。
3. 右键选择“显示简介 (Get Info)”，选择“访问控制 (Access Control)”选项卡，并验证 agy 是否在允许的应用程序列表中。
4. 如果在 Mac 上的无头 SSH 会话中运行，请执行以下解锁命令序列：

   security unlock-keychain -p "your_keychain_password" login.keychain

Linux (gLinux / Cloudtop)

Antigravity CLI 在 gLinux 上使用自动化的 LOAS 认证。运行以下命令确保您当前的 LOAS 票据有效：

gcert

如果您仍然遇到访问问题，请确保您的帐户属于已批准的企业访问组，或在支持空间联系我们。

启用模拟器剪贴板转发 (Enable emulator clipboard forwarding)

症状

在 SSH 终端内通过 Ctrl+V 粘贴屏幕截图或媒体文件时返回失败通知：

Error: local pasteboard is empty or unreachable over SSH connection

原因

标准的 SSH 流不会转发图形剪贴板。图形上传需要特定的终端复用器协议。

解决方案

验证您使用的是受支持的终端模拟器及其配置。

• 使用 iTerm2 或 Ghostty：这些模拟器支持先进的剪贴板通道。
• 配置 iTerm2 转发：
  1. 打开 iTerm2 偏好设置 (Cmd+,)。
  2. 转到 "General" 选项卡，选择 "Selection" 子菜单。
  3. 勾选 "Applications in terminal may access clipboard"（启用 OSC 52 写入通道）。
• 绕过复用器：如果在 tmux 中运行，请确保您当前活跃的配置正确映射了标准的剪贴板：

  set -s set-clipboard on

解决自更新锁和更新失败问题 (Resolve self-updater locks and failures)

症状

启动 agy 时卡住、无法应用升级，或返回建议锁警告：

Warning: another background updater process is already active (update.lock)

原因

Antigravity CLI 包含一个在后台运行的原生静态链接自更新程序。它使用 ~/.gemini/antigravity-cli/updater/ 内的 15 分钟生存时间 (TTL) 去抖标记 (last_check.timestamp) 和建议锁 (update.lock) 来防止并发进程冲突。如果后台更新程序进程卡住、崩溃且未释放锁，或者在可执行目录中具有不足的用户文件系统权限，则随后的更新将被阻止。

解决方案

• 释放建议锁：手动清除后台锁文件：

  rm -f ~/.gemini/antigravity-cli/updater/update.lock

• 选择退出/禁用自动更新：在您的 Shell 配置文件（~/.bashrc 或 ~/.zshrc）中将环境变量 AGY_CLI_DISABLE_AUTO_UPDATE 设置为 true：

  export AGY_CLI_DISABLE_AUTO_UPDATE=true

• 验证目录写权限：确保您的用户帐户拥有目标安装目录（Unix 上的 ~/.local/bin/ 或 Windows 上的 %LOCALAPPDATA%\agy\bin）的所有权和写入权限。

下一步 (Next Steps)

访问我们的快速参考表或配置高级权限：

• CLI 参考 (CLI Reference)：列出所有斜杠命令和视觉设置键的紧凑表格。
• 权限 (Permissions)：配置细粒度的允许与拒绝操作策略。
• 沙箱 (Sandbox)：强制执行系统级的容器隔离边界。
• 插件与技能 (Plugins & Skills)：创建您自己的自定义技能。