agentgate

用于个人数据的 API 网关，具有人机交互写入批准功能。将代理连接到 GitHub、Bluesky、Google Calendar、Home Assistant 等 — 全部通过具有安全控制的单个 API。

# agentgate

API gateway for AI agents to access personal data with human-in-the-loop write approval.

- **Reads** (GET) execute immediately
- **Writes** (POST/PUT/PATCH/DELETE) go through an approval queue
- **Bypass mode** available for trusted agents (writes execute immediately)

GitHub: <https://github.com/monteslu/agentgate>
Docs: <https://agentgate.org>

## Setup

**agentgate server runs on a separate machine from OpenClaw.** This is by design — your agent should not have direct access to the server holding your credentials. Install and run agentgate on a different computer (or VPS/container on a different host). See <https://agentgate.org> for setup instructions.

Once agentgate is running, configure these environment variables for your OpenClaw agent:

- `AGENT_GATE_URL` — agentgate base URL (e.g., `http://your-agentgate-host:3050`)
- `AGENT_GATE_TOKEN` — your agent's API key (create in the agentgate Admin UI → API Keys)

## Authentication

All requests require the API key in the Authorization header:

```
Authorization: Bearer $AGENT_GATE_TOKEN
```

## First Steps — Service Discovery

After connecting, discover what's available on your instance:

```
GET $AGENT_GATE_URL/api/agent_start_here
Authorization: Bearer $AGENT_GATE_TOKEN
```

Returns your agent's config, available services, accounts, and full API documentation.

## Instance-Specific Skills

agentgate generates additional skills tailored to your instance with your specific accounts and endpoints. See the [agentgate skills documentation](https://agentgate.org/docs/skills) for details on how to install and update them.

## Supported Services

agentgate supports many services out of the box. Common ones include:

- **Code:** GitHub, Jira
- **Social:** Bluesky, Mastodon, LinkedIn
- **Search:** Brave Search, Google Search
- **Personal:** Google Calendar, YouTube, Fitbit
- **IoT:** Home Assistant
- **Messaging:** Twilio, Plivo

New services are added regularly. Check `GET /api/agent_start_here` for what's configured on your instance.

## Reading Data

```
GET $AGENT_GATE_URL/api/{service}/{accountName}/{path}
Authorization: Bearer $AGENT_GATE_TOKEN
```

Example: `GET $AGENT_GATE_URL/api/github/myaccount/repos/owner/repo`

## Writing Data

Writes go through the approval queue:

```
POST $AGENT_GATE_URL/api/queue/{service}/{accountName}/submit
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{
  "requests": [
    {
      "method": "POST",
      "path": "/the/api/path",
      "body": { "your": "payload" }
    }
  ],
  "comment": "Explain what you are doing and why"
}
```

**Always include a clear comment** explaining your intent. Include links to relevant resources.

### Check write status

```
GET $AGENT_GATE_URL/api/queue/{service}/{accountName}/status/{id}
Authorization: Bearer $AGENT_GATE_TOKEN
```

Statuses: `pending` → `approved` → `executing` → `completed` (or `rejected`/`failed`/`withdrawn`)

### Withdraw a pending request

```
DELETE $AGENT_GATE_URL/api/queue/{service}/{accountName}/status/{id}
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "reason": "No longer needed" }
```

### Binary uploads

For binary data (images, files), set `binaryBase64: true` in the request body:

```json
{
  "method": "POST",
  "path": "com.atproto.repo.uploadBlob",
  "binaryBase64": true,
  "headers": { "Content-Type": "image/jpeg" },
  "body": "<base64 encoded data>"
}
```

## Inter-Agent Messaging

Agents can message each other through agentgate for multi-agent coordination.

### Send a message

```
POST $AGENT_GATE_URL/api/agents/message
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "to_agent": "agent_name", "message": "Hello!" }
```

### Read messages

```
GET $AGENT_GATE_URL/api/agents/messages?unread=true
Authorization: Bearer $AGENT_GATE_TOKEN
```

### Mark as read

```
POST $AGENT_GATE_URL/api/agents/messages/{id}/read
Authorization: Bearer $AGENT_GATE_TOKEN
```

### Broadcast to all agents

```
POST $AGENT_GATE_URL/api/agents/broadcast
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "message": "Team announcement" }
```

### Discover agents

```
GET $AGENT_GATE_URL/api/agents/messageable
Authorization: Bearer $AGENT_GATE_TOKEN
```

Messaging modes (configured by admin): `off`, `supervised` (requires approval), `open` (immediate delivery).

---

## 中文说明

# agentgate

供 AI 代理访问个人数据的 API 网关，带有人机协同的写入审批。

- **读取** (GET) 立即执行
- **写入** (POST/PUT/PATCH/DELETE) 进入审批队列
- 针对可信代理提供 **旁路模式**（写入立即执行）

GitHub: <https://github.com/monteslu/agentgate>
文档: <https://agentgate.org>

## 设置

**agentgate 服务器运行在与 OpenClaw 不同的机器上。** 这是有意为之的设计——你的代理不应直接访问持有你凭据的服务器。请在另一台计算机（或位于不同主机上的 VPS/容器）上安装并运行 agentgate。设置说明参见 <https://agentgate.org>。

agentgate 运行后，为你的 OpenClaw 代理配置以下环境变量：

- `AGENT_GATE_URL` — agentgate 基础 URL（例如 `http://your-agentgate-host:3050`）
- `AGENT_GATE_TOKEN` — 你的代理 API 密钥（在 agentgate Admin UI → API Keys 中创建）

## 身份验证

所有请求都需要在 Authorization 头中携带 API 密钥：

```
Authorization: Bearer $AGENT_GATE_TOKEN
```

## 第一步——服务发现

连接后，发现你的实例上有哪些可用项：

```
GET $AGENT_GATE_URL/api/agent_start_here
Authorization: Bearer $AGENT_GATE_TOKEN
```

返回你的代理配置、可用服务、账户以及完整的 API 文档。

## 实例专属技能

agentgate 会针对你的实例生成额外的技能，配套你特定的账户和端点。有关如何安装和更新这些技能的详细信息，参见 [agentgate skills documentation](https://agentgate.org/docs/skills)。

## 支持的服务

agentgate 开箱即用地支持许多服务。常见的包括：

- **Code:** GitHub, Jira
- **Social:** Bluesky, Mastodon, LinkedIn
- **Search:** Brave Search, Google Search
- **Personal:** Google Calendar, YouTube, Fitbit
- **IoT:** Home Assistant
- **Messaging:** Twilio, Plivo

新服务会定期添加。检查 `GET /api/agent_start_here` 以查看你的实例上配置了哪些服务。

## 读取数据

```
GET $AGENT_GATE_URL/api/{service}/{accountName}/{path}
Authorization: Bearer $AGENT_GATE_TOKEN
```

示例：`GET $AGENT_GATE_URL/api/github/myaccount/repos/owner/repo`

## 写入数据

写入会进入审批队列：

```
POST $AGENT_GATE_URL/api/queue/{service}/{accountName}/submit
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{
  "requests": [
    {
      "method": "POST",
      "path": "/the/api/path",
      "body": { "your": "payload" }
    }
  ],
  "comment": "Explain what you are doing and why"
}
```

**务必包含清晰的 comment**，说明你的意图。附上相关资源的链接。

### 检查写入状态

```
GET $AGENT_GATE_URL/api/queue/{service}/{accountName}/status/{id}
Authorization: Bearer $AGENT_GATE_TOKEN
```

状态：`pending` → `approved` → `executing` → `completed`（或 `rejected`/`failed`/`withdrawn`）

### 撤回待处理的请求

```
DELETE $AGENT_GATE_URL/api/queue/{service}/{accountName}/status/{id}
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "reason": "No longer needed" }
```

### 二进制上传

对于二进制数据（图片、文件），在请求体中设置 `binaryBase64: true`：

```json
{
  "method": "POST",
  "path": "com.atproto.repo.uploadBlob",
  "binaryBase64": true,
  "headers": { "Content-Type": "image/jpeg" },
  "body": "<base64 encoded data>"
}
```

## 代理间消息传递

代理之间可以通过 agentgate 互相发送消息，以进行多代理协调。

### 发送消息

```
POST $AGENT_GATE_URL/api/agents/message
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "to_agent": "agent_name", "message": "Hello!" }
```

### 读取消息

```
GET $AGENT_GATE_URL/api/agents/messages?unread=true
Authorization: Bearer $AGENT_GATE_TOKEN
```

### 标记为已读

```
POST $AGENT_GATE_URL/api/agents/messages/{id}/read
Authorization: Bearer $AGENT_GATE_TOKEN
```

### 广播给所有代理

```
POST $AGENT_GATE_URL/api/agents/broadcast
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "message": "Team announcement" }
```

### 发现代理

```
GET $AGENT_GATE_URL/api/agents/messageable
Authorization: Bearer $AGENT_GATE_TOKEN
```

消息传递模式（由管理员配置）：`off`、`supervised`（需要审批）、`open`（立即送达）。

## Mementos（持久记忆）

使用关键词标签跨会话存储和检索笔记。

### 存储一条 memento

```
POST $AGENT_GATE_URL/api/agents/memento
Authorization: Bearer $AGENT_GATE_TOKEN
Content-Type: application/json

{ "content": "Important info to remember", "keywords": ["project", "notes"] }
```

### 按关键词搜索

```
GET $AGENT_GATE_URL/api/agents/memento/search?keywords=project&limit=10
Authorization