---
url: /antigravity/sidecars.md
description: >-
  了解如何在 Antigravity 2.0 中配置与管理后台运行的边车服务（Sidecars），包括 sidecar.json
  配置、运行时数据、定时调度以及使用 agentapi CLI 进行编程式交互。
---

# 边车服务 (Sidecars)

边车服务（Sidecars）是与 Antigravity 并行运行的后台进程。Antigravity 负责管理边车服务的生命周期，自动启动它们，并在它们崩溃或报错时重新启动。它们对于持久后台脚本、定时循环任务以及响应事件非常有用。

## 配置方式 (Configuration)

Antigravity 通过搜索 `sidecar.json` 配置文件来发现边车服务。它们可以定义在两个位置：

* **全局边车服务**：位于 `~/.gemini/config/sidecars/`
* **插件边车服务**：位于 `~/.gemini/config/plugins/<pluginName>/sidecars/`

每个边车服务都有自己的专属目录，且该目录名称将被用作边车服务的 ID。从插件加载的边车服务，其 ID 格式为 `<pluginName>/<sidecarName>`。

边车服务的目录必须包含一个 `sidecar.json` 文件，也可以包含其他辅助文件（如待运行的脚本）。该目录同时也会作为执行边车服务命令的当前工作目录。

### 示例目录结构

```
~/.gemini/config/sidecars/
├── sidecar1/
│   ├── sidecar.json
│   └── script.py
└── sidecar2/
    └── sidecar.json

~/.gemini/config/plugins/
└── my-plugin/
      └── sidecars/
            └── plugin-sidecar/
                  └── sidecar.json
```

## 配置模式 (Config Schema - `sidecar.json`)

* **command** (string)：要执行的命令/可执行文件（例如 `python3` 或 `/bin/bash`）。与 `builtin` 互斥。
* **builtin** (string)：要执行的内置命令。目前支持 `schedule`。与 `command` 互斥。
* **args** (string\[])：可选。传递给命令或内置函数的参数。
* **restart\_policy** (string)：可选。重启行为。可选值为 `always`、`on-failure` 或 `never`。默认为 `always`。
* **description** (string)：可选。关于边车服务作用的易读描述。
* **env** (object)：可选。为边车服务进程设置的环境变量映射。
* **display\_name** (string)：可选。在用户界面（UI）中显示的名称。

> `command` 或 `builtin` 必须设置其中之一。

### 示例

```json
{
  "description": "Background worker",
  "command": "python3",
  "args": [
    "worker.py"
  ],
  "restart_policy": "on-failure"
}
```

```json
{
  "description": "Hourly agent to triage review requests.",
  "builtin": "schedule",
  "args": [
    "0 * * * *",
    "agentapi",
    "new-conversation",
    "Give me a summary of incoming review requests."
  ]
}
```

## 用户启用配置 (User Configuration - `config.json`)

除非用户在全局配置文件（位于 `~/.gemini/config/config.json`）中显式启用，否则边车服务默认是禁用的。

* **enabled** (boolean)：是否启用该边车服务。
* **projectId** (string)：可选。在使用 `agentapi` 创建对话时关联的项目 ID。

### 示例

```json
{
  "sidecars": {
    "sidecar1": {
      "enabled": true
    },
    "my-plugin/plugin-sidecar": {
      "enabled": true,
      "projectId": "<projectId>"
    }
  }
}
```

## 运行时数据 (Runtime Data)

边车服务产生的运行时数据存储在 `~/.gemini/antigravity/sidecar_data/<sidecarId>/` 中。

包括以下内容：

* **data/**：存放任何持久化数据的子目录。该路径可以通过环境变量 `ANTIGRAVITY_EXECUTABLE_DATA_DIR` 获取。
* **logs/**：自动生成的带时间戳的 `stdout` 和 `stderr` 日志。
* **events/**：为 `agentapi` 调用记录的 JSON 文件。

## `schedule` 内置命令 (Builtin)

`schedule` 是用于运行周期性循环命令的内置调度程序。

```json
{
  "builtin": "schedule",
  "args": [
    "* * * * *",
    "<command>",
    "<arg1>",
    "<arg2>"
  ]
}
```

第一个参数是标准的 5 字段 Cron 表达式。其余参数是要在指定计划中运行的命令及其参数。

## `agentapi` 工具

边车服务可以使用 `agentapi` CLI 来以编程方式与 Antigravity 交互。该可执行文件会被自动添加到边车服务的环境变量 `PATH` 中，直接调用 `agentapi` 即可。

### 创建新对话

```bash
agentapi new-conversation <prompt>
```

> \[!IMPORTANT]
> 边车服务在创建新对话时必须已设置 `projectId`。

### 发送消息

```bash
agentapi send-message <conversation_id> <prompt>
```