agent-zero-bridge

TotalClaw 作者 totalclaw

将复杂的编码、研究或自主任务委托给零号代理框架。当用户说“询问零号代理”、“委托给 A0”、“构建零号代理”或需要带有自我校正循环的长时间运行的自主编码时使用。支持双向通信、文件附件、任务分解和进度报告。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw skills install shop:totalclaw:totalclaw~dowingard-agent-zero-bridge

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~dowingard-agent-zero-bridge/file -o dowingard-agent-zero-bridge.md

# Agent Zero Bridge

Bidirectional communication between Clawdbot and [Agent Zero](https://github.com/frdel/agent-zero).

## When to Use

- Complex coding tasks requiring iteration/self-correction
- Long-running builds, tests, or infrastructure work
- Tasks needing persistent Docker execution environment
- Research with many sequential tool calls
- User explicitly asks for Agent Zero

## Setup (First Time Only)

### 1. Prerequisites
- Node.js 18+ (for built-in fetch)
- Agent Zero running (Docker recommended, port 50001)
- Clawdbot Gateway with HTTP endpoints enabled

### 2. Install
```bash
# Copy skill to Clawdbot skills directory
cp -r <this-skill-folder> ~/.clawdbot/skills/agent-zero-bridge

# Create config from template
cd ~/.clawdbot/skills/agent-zero-bridge
cp .env.example .env
```

### 3. Configure .env
```env
# Agent Zero (get token from A0 settings or calculate from runtime ID)
A0_API_URL=http://127.0.0.1:50001
A0_API_KEY=your_agent_zero_token

# Clawdbot Gateway
CLAWDBOT_API_URL=http://127.0.0.1:18789
CLAWDBOT_API_TOKEN=your_gateway_token

# For Docker containers reaching host (use your machine's LAN IP)
CLAWDBOT_API_URL_DOCKER=http://192.168.1.x:18789
```

### 4. Get Agent Zero Token
```python
# Calculate from A0's runtime ID
import hashlib, base64
runtime_id = "your_A0_PERSISTENT_RUNTIME_ID"  # from A0's .env
hash_bytes = hashlib.sha256(f"{runtime_id}::".encode()).digest()
token = base64.urlsafe_b64encode(hash_bytes).decode().replace("=", "")[:16]
print(token)
```

### 5. Enable Clawdbot Gateway Endpoints
Add to `~/.clawdbot/clawdbot.json`:
```json
{
  "gateway": {
    "bind": "0.0.0.0",
    "auth": { "mode": "token", "token": "your_token" },
    "http": { "endpoints": { "chatCompletions": { "enabled": true } } }
  }
}
```
Then: `clawdbot gateway restart`

### 6. Deploy Client to Agent Zero Container
```bash
docker exec <container> mkdir -p /a0/bridge/lib
docker cp scripts/lib/. <container>:/a0/bridge/lib/
docker cp scripts/clawdbot_client.js <container>:/a0/bridge/
docker cp .env <container>:/a0/bridge/
docker exec <container> sh -c 'echo "DOCKER_CONTAINER=true" >> /a0/bridge/.env'
```

## Usage

### Send Task to Agent Zero
```bash
node scripts/a0_client.js "Build a REST API with JWT authentication"
node scripts/a0_client.js "Review this code" --attach ./file.py
node scripts/a0_client.js "New task" --new  # Start fresh conversation
```

### Check Status
```bash
node scripts/a0_client.js status
node scripts/a0_client.js history
node scripts/a0_client.js reset  # Clear conversation
```

### Task Breakdown (Creates Tracked Project)
```bash
node scripts/task_breakdown.js "Build e-commerce platform"
# Creates notebook/tasks/projects/<name>.md with checkable steps
```

### From Agent Zero → Clawdbot
Inside A0 container:
```bash
# Report progress
node /a0/bridge/clawdbot_client.js notify "Working on step 3..."

# Ask for input
node /a0/bridge/clawdbot_client.js "Should I use PostgreSQL or SQLite?"

# Invoke Clawdbot tool
node /a0/bridge/clawdbot_client.js tool web_search '{"query":"Node.js best practices"}'
```

## Troubleshooting

| Error | Fix |
|-------|-----|
| 401 / API key error | Check A0_API_KEY matches Agent Zero's mcp_server_token |
| Connection refused from Docker | Use host LAN IP in CLAWDBOT_API_URL_DOCKER, ensure gateway binds 0.0.0.0 |
| A0 500 errors | Check Agent Zero's LLM API key (Gemini/OpenAI) is valid |

---

## 中文说明

# Agent Zero Bridge

Clawdbot 与 [Agent Zero](https://github.com/frdel/agent-zero) 之间的双向通信。

## 何时使用

- 需要迭代/自我校正的复杂编码任务
- 长时间运行的构建、测试或基础设施工作
- 需要持久化 Docker 执行环境的任务
- 包含大量顺序工具调用的研究
- 用户明确要求使用 Agent Zero

## 设置（仅首次）

### 1. 前提条件
- Node.js 18+（用于内置 fetch）
- 运行中的 Agent Zero（推荐 Docker，端口 50001）
- 已启用 HTTP 端点的 Clawdbot Gateway

### 2. 安装
```bash
# Copy skill to Clawdbot skills directory
cp -r <this-skill-folder> ~/.clawdbot/skills/agent-zero-bridge

# Create config from template
cd ~/.clawdbot/skills/agent-zero-bridge
cp .env.example .env
```

### 3. 配置 .env
```env
# Agent Zero (get token from A0 settings or calculate from runtime ID)
A0_API_URL=http://127.0.0.1:50001
A0_API_KEY=your_agent_zero_token

# Clawdbot Gateway
CLAWDBOT_API_URL=http://127.0.0.1:18789
CLAWDBOT_API_TOKEN=your_gateway_token

# For Docker containers reaching host (use your machine's LAN IP)
CLAWDBOT_API_URL_DOCKER=http://192.168.1.x:18789
```

### 4. 获取 Agent Zero 令牌
```python
# Calculate from A0's runtime ID
import hashlib, base64
runtime_id = "your_A0_PERSISTENT_RUNTIME_ID"  # from A0's .env
hash_bytes = hashlib.sha256(f"{runtime_id}::".encode()).digest()
token = base64.urlsafe_b64encode(hash_bytes).decode().replace("=", "")[:16]
print(token)
```

### 5. 启用 Clawdbot Gateway 端点
添加到 `~/.clawdbot/clawdbot.json`：
```json
{
  "gateway": {
    "bind": "0.0.0.0",
    "auth": { "mode": "token", "token": "your_token" },
    "http": { "endpoints": { "chatCompletions": { "enabled": true } } }
  }
}
```
然后：`clawdbot gateway restart`

### 6. 将客户端部署到 Agent Zero 容器
```bash
docker exec <container> mkdir -p /a0/bridge/lib
docker cp scripts/lib/. <container>:/a0/bridge/lib/
docker cp scripts/clawdbot_client.js <container>:/a0/bridge/
docker cp .env <container>:/a0/bridge/
docker exec <container> sh -c 'echo "DOCKER_CONTAINER=true" >> /a0/bridge/.env'
```

## 用法

### 向 Agent Zero 发送任务
```bash
node scripts/a0_client.js "Build a REST API with JWT authentication"
node scripts/a0_client.js "Review this code" --attach ./file.py
node scripts/a0_client.js "New task" --new  # Start fresh conversation
```

### 检查状态
```bash
node scripts/a0_client.js status
node scripts/a0_client.js history
node scripts/a0_client.js reset  # Clear conversation
```

### 任务分解（创建受跟踪的项目）
```bash
node scripts/task_breakdown.js "Build e-commerce platform"
# Creates notebook/tasks/projects/<name>.md with checkable steps
```

### 从 Agent Zero → Clawdbot
在 A0 容器内：
```bash
# Report progress
node /a0/bridge/clawdbot_client.js notify "Working on step 3..."

# Ask for input
node /a0/bridge/clawdbot_client.js "Should I use PostgreSQL or SQLite?"

# Invoke Clawdbot tool
node /a0/bridge/clawdbot_client.js tool web_search '{"query":"Node.js best practices"}'
```

## 故障排除

| 错误 | 修复 |
|-------|-----|
| 401 / API 密钥错误 | 检查 A0_API_KEY 是否与 Agent Zero 的 mcp_server_token 匹配 |
| 从 Docker 连接被拒绝 | 在 CLAWDBOT_API_URL_DOCKER 中使用主机 LAN IP，确保 gateway 绑定到 0.0.0.0 |
| A0 500 错误 | 检查 Agent Zero 的 LLM API 密钥（Gemini/OpenAI）是否有效 |