---
url: /antigravity/cli-settings.md
description: 配置持久化首选项、自定义键盘快捷键、切换终端显示缓冲区，以及管理运行时 CLI 参数的覆盖。
---

# 设置、渲染与按键绑定 (Settings, Rendering & Keybindings)

配置持久化首选项、自定义键盘快捷键、切换终端显示缓冲区，以及管理运行时 CLI 参数的覆盖。

## 设定偏好设置 (Setting up preferences)

Antigravity CLI 将用户偏好设置存储在一个极简的、向前兼容的 JSON 配置配置文件中。

### 配置文件位置

持久化设置以纯 JSON 格式保存：

```text
~/.gemini/antigravity-cli/settings.json
```

CLI 通过只将与系统默认值不同的值写入磁盘，来实现稀疏持久化 (sparse persistence)。这可以保持您的配置文件整洁、最小化，并与未来的更新完全向前兼容。

### 交互式设置面板

要在当前活跃的终端会话中直接编辑设置而无需打开原始 JSON 文件：

1. 在提示面板中输入 `/config`（或其别名 `/settings`），然后按 `Enter`。
2. 全屏的“设置编辑器浮层 (Settings Editor Overlay)”将被打开。
3. 使用 `↑/↓` 在可用选项之间进行导航。
4. 在高亮参数上按 `Enter` 以切换其状态或打开文本输入框。
5. 按 `Esc` 保存您的修改并关闭编辑器。

### 命令行覆盖 (Command-line overrides)

您可以使用 CLI 命令参数为单个终端会话临时覆盖持久化偏好：

```bash
agy --sandbox=false --notifications=false
```

当覆盖参数处于活动状态时，交互式的 `/config` 菜单会在修改后的设置旁边显示一个警告指示器：

```text
! Tool Permission: strict (overridden by command flag)
```

您在这些会话期间仍然可以修改磁盘上的持久化值，但在您关闭该会话之前，CLI 会强制执行活跃的运行时参数覆盖。

## 视觉渲染模式 (Visual rendering modes)

TUI 根据您的终端能力和连接延迟，在以下两种视觉渲染模式之一中运行。

### 备用屏幕模式 (Alt-screen mode - `always`)

此模式使用终端的备用缓冲区打开一个专用的显示屏幕，从而创建一个沉浸式的独立应用程序界面。

* **关键特性**：集成了回滚机制、鼠标滚轮滚动支持、自定义渲染滚动条，以及在退出时清洁地恢复终端状态。
* **最佳用途**：在先进的终端模拟器（例如 iTerm2、Ghostty 或 WezTerm）中运行标准的本地开发会话。

### 行内模式 (Inline mode - `never`)

此模式在您终端的标准 `stdout` 管道中按顺序渲染输出。

* **关键特性**：在您模拟器的原生回滚缓冲区中保留整个会话历史记录，不捕获鼠标输入，并能与标准的命令输出无缝配合工作。
* **最佳用途**：远程 SSH 终端、像 `tmux` 或 `screen` 这样的终端复用器，以及低带宽的远程会话。

> \[!INFO]
> **自适应渲染 (Adaptive Rendering)**：将备用屏幕模式设置为默认 (default) 允许 TUI 自动检测您的环境。它会在先进的本地 Shell 上默认采用备用屏幕模式，并在通过 SSH 运行或在非交互式会话中运行时降级为行内模式。

### 自定义状态栏与终端标题

对于高级 TUI 环境集成，您可以切换活跃指标或部署自定义脚本以生成动态状态栏并修改您的终端窗口标题：

* **状态栏自定义**：了解如何管理状态指标面板，以及如何构建自定义格式的状态栏 Shell 脚本。
* **终端标题自定义**：了解如何切换窗口标题输出，并将实时的 Agent 状态传送到您的窗口标题栏中。

## 按键绑定配置 (Keybindings configuration)

您可以通过将按键映射到特定的工作空间命令，来自定义 TUI 中的几乎所有键盘快捷键。

### 按键绑定文件位置

自定义映射表与您的主设置配置文件保存在一起：

```text
~/.gemini/antigravity-cli/keybindings.json
```

### 格式与自定义

该 JSON 结构将单个 TUI 命令操作映射到一个热键序列数组：

```json
{
  "cli.clear_screen": [
    "ctrl+l"
  ],
  "prompt.insert_newline": [
    "shift+enter",
    "ctrl+j"
  ],
  "edit.open_editor": [
    "ctrl+g"
  ]
}
```

要完全禁用默认热键，请将其操作映射到空数组 `[]`。如果您的 JSON 模式格式错误或无效，CLI 会针对这些特定操作回退到系统默认值，并加载其余有效的映射。

> \[!WARNING]
> **受保护的按键**：关键的导航快捷键（如 `cli.exit` (Ctrl+D / Ctrl+C) 和 `cli.enter` (Enter)）受到系统的保护，无法被禁用。

### 恢复默认设置

要将所有按键恢复为系统默认设置，只需删除按键绑定配置文件即可：

```bash
rm ~/.gemini/antigravity-cli/keybindings.json
```

## 下一步 (Next Steps)

配置完环境后，审查安全控制和可扩展性选项：

* **权限与沙箱 (Permissions & Sandbox)**：管理安全执行容器化隔离边界。
* **插件与技能 (Plugins & Skills)**：创建您自己的自定义技能并导入旧版插件。
* **CLI 参考 (CLI Reference)**：访问快速参考表，其中列出了所有配置选项、命令和默认按键映射。