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

# 疑难解答 (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
bash: agy: command not found
```

### 原因

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

### 解决方案

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

#### macOS & Linux

1. 打开您的 Shell 配置文件（`~/.bashrc` 或 `~/.zshrc`）。
2. 在文件末尾验证或追加以下行：
   ```bash
   export PATH="~/.local/bin:$PATH"
   ```
3. 重新加载您的配置文件：
   ```bash
   source ~/.zshrc
   ```

#### Windows (PowerShell)

1. 以管理员身份打开 PowerShell 终端并执行：
   ```powershell
   [System.Environment]::SetEnvironmentVariable("Path", [System.Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Program Files\Google\antigravity-cli", "User")
   ```
2. 重启您的终端模拟器以刷新系统注册表环境。

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

### 症状

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

```text
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 会话中运行，请执行以下解锁命令序列：
   ```bash
   security unlock-keychain -p "your_keychain_password" login.keychain
   ```

#### Linux (gLinux / Cloudtop)

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

```bash
gcert
```

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

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

### 症状

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

```text
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` 中运行，请确保您当前活跃的配置正确映射了标准的剪贴板：
  ```text
  set -s set-clipboard on
  ```

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

### 症状

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

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

### 原因

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

### 解决方案

* **释放建议锁**：手动清除后台锁文件：
  ```bash
  rm -f ~/.gemini/antigravity-cli/updater/update.lock
  ```
* **选择退出/禁用自动更新**：在您的 Shell 配置文件（`~/.bashrc` 或 `~/.zshrc`）中将环境变量 `AGY_CLI_DISABLE_AUTO_UPDATE` 设置为 `true`：
  ```bash
  export AGY_CLI_DISABLE_AUTO_UPDATE=true
  ```
* **验证目录写权限**：确保您的用户帐户拥有目标安装目录（Unix 上的 `~/.local/bin/` 或 Windows 上的 `%LOCALAPPDATA%\agy\bin`）的所有权和写入权限。

## 下一步 (Next Steps)

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

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