# GoClaw — Full Documentation

> Enterprise AI Agent Platform — multi-tenant gateway for AI agents


---

# What Is GoClaw

> A multi-tenant AI agent gateway that connects LLMs to messaging channels, tools, and teams.

## Overview

GoClaw is an open-source AI agent gateway written in Go. It lets you run AI agents that can chat on Telegram, Discord, WhatsApp, and other channels — while sharing tools, memory, and context across a team. Think of it as the bridge between your LLM providers and the real world.

## Key Features

| Category | What You Get |
|----------|-------------|
| **Multi-Tenant v3** | Per-user isolation for context, sessions, memory, and traces; per-edition rate limits |
| **8-Stage Agent Pipeline** | context → history → prompt → think → act → observe → memory → summarize (v3, always-on) |
| **22 Provider Types** | OpenAI, Anthropic, Google, Groq, DeepSeek, Mistral, xAI, and more (15 LLM APIs + local models + ACP CLI agents + media) |
| **ACP Provider** | Agentic Claude Protocol — runs Claude Code, Codex, Gemini CLI as agents via JSON-RPC 2.0 stdio subprocess |
| **Hooks System** | 7 lifecycle events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart/Stop) — sync/async, SSRF-hardened HTTP handlers, audit logging |
| **Audio / TTS Manager** | Unified audio manager with 4 TTS providers: ElevenLabs (streaming), OpenAI, Edge TTS, MiniMax; voice LRU cache (1 000 tenants, 1 h TTL) |
| **Messaging Channels** | Telegram, Discord, WhatsApp (native), Zalo, Zalo Personal, Larksuite, Slack, WebSocket |
| **32 Built-in Tools** | File system, web search, browser, code execution, memory, and more |
| **64+ WebSocket RPC Methods** | Real-time control — chat, agent management, traces, and more via `/ws` |
| **Agent Orchestration** | Delegation (sync/async), teams, handoff, evaluate loops, WaitAll via `BatchQueue[T]` |
| **3-Tier Memory** | L0/L1/L2 with consolidation workers (episodic, semantic, dreaming, dedup) |
| **Knowledge Vault** | Wikilink document mesh, LLM auto-summary + semantic auto-linking, hybrid BM25 + vector search |
| **Knowledge Graph** | LLM-powered entity/relationship extraction with graph traversal |
| **Agent Evolution** | Guardrails + suggestion engine; predefined agents refine SOUL.md / CAPABILITIES.md and grow skills |
| **Mode Prompt System** | Switchable prompt modes (full / task / minimal / none) with per-agent overrides |
| **MCP Support** | Connect to Model Context Protocol servers (stdio/SSE/HTTP) |
| **Skills System** | SKILL.md-based knowledge base with hybrid search; publishing, grants, evolution-driven drafts |
| **Quality Gates** | Hook-based output validation with configurable feedback loops |
| **Extended Thinking** | Per-provider reasoning modes (Anthropic, OpenAI, DashScope) |
| **Prompt Caching** | Up to ~90% cost reduction on repeated prefixes; v3 cache-boundary markers |
| **Web Dashboard** | Visual management for agents, providers, channels, vault, traces |
| **Security** | Rate limiting, SSRF protection, credential scrubbing, RBAC, session IDOR hardening |
| **Dual-DB** | PostgreSQL (full) or SQLite desktop variant via unified store Dialect |
| **Single Binary** | ~25 MB, <1s startup, runs on a $5 VPS |

## Who Is It For?

- **Developers** building AI-powered chatbots and assistants
- **Teams** that need shared AI agents with role-based access
- **Enterprises** requiring multi-tenant isolation and audit trails

## Operating Mode

GoClaw runs on **PostgreSQL** (full multi-tenant production) or **SQLite** (single-user desktop). Both paths support encrypted credentials, per-user isolated workspaces, and persistent memory — giving you full isolation, complete activity logs, and smart search across all conversations. SQLite omits pgvector-only features (vault semantic auto-linking falls back to lexical).

## How It Works

```mermaid
graph LR
    U[User] --> C[Channel<br/>Telegram / Discord / WS]
    C --> G[GoClaw Gateway]
    G --> PL[8-Stage Pipeline<br/>context → history → prompt →<br/>think → act → observe → memory → summarize]
    PL --> P[LLM Provider<br/>OpenAI / Anthropic / ...]
    PL --> T[Tools<br/>Search / Code / Memory / Vault / ...]
    PL --> D[Database<br/>Sessions / Memory / Vault / Traces]
```

1. A user sends a message through a **channel** (Telegram, WebSocket, etc.)
2. The **gateway** routes it to the right agent based on channel bindings
3. The **8-stage pipeline** runs: it assembles context, pulls history, builds the prompt, thinks (LLM call), acts (tool calls), observes results, updates memory, and summarizes
4. Tools can **search the web, run code, query memory, knowledge graph, or knowledge vault**
5. The agent can **delegate** tasks to subagents (with `BatchQueue[T]` for parallel waits), **hand off** conversations, or run **evaluate loops** for quality-gated output
6. Background **consolidation workers** promote episodic facts into semantic memory; the **vault enrich worker** auto-summarizes and semantically links new documents
7. The response flows back through the channel to the user

## What's Next

- [Installation](/installation) — Get GoClaw running on your machine
- [Quick Start](/quick-start) — Your first agent in 5 minutes
- [How GoClaw Works](/how-goclaw-works) — Deep dive into the architecture



---

# Installation

> Get GoClaw running on your machine in minutes. Four paths: quick binary install, bare metal, Docker (local), or Docker on a VPS.

## Overview

GoClaw compiles to a single static binary (~25 MB). Pick the path that fits your setup:

| Path | Best for | What you need |
|------|----------|---------------|
| Quick Install (Binary) | Fastest single-command setup on Linux/macOS | curl, PostgreSQL |
| Bare Metal | Developers who want full control | Go 1.26+, PostgreSQL 15+ with pgvector |
| **Docker (Local) ⭐** | **Run everything via Docker Compose (recommended)** | **Docker + Docker Compose, 2 GB+ RAM** |
| VPS (Production) | Self-hosted production deployment | VPS $5+, Docker, 2 GB+ RAM |


## Path 2: Bare Metal

Install GoClaw directly on your machine. You manage Go, PostgreSQL, and the binary yourself.

### Step 1: Install PostgreSQL + pgvector

GoClaw requires **PostgreSQL 15+** with the **pgvector** extension (for vector similarity search in memory and skills). Docker deployments use **PostgreSQL 18** with pgvector (`pgvector/pgvector:pg18` image).

<details>
<summary><strong>Ubuntu 24.04+ / Debian 12+</strong></summary>

```bash
sudo apt update
sudo apt install -y postgresql postgresql-common

# Install pgvector (replace 17 with your PG version — check with: pg_config --version)
sudo apt install -y postgresql-17-pgvector

# Create database and enable extension
sudo -u postgres createdb goclaw
sudo -u postgres psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

> **Note:** Ubuntu 22.04 and older ship PostgreSQL 14, which is not supported. Please upgrade to Ubuntu 24.04+ or use the Docker installation path.

</details>

<details>
<summary><strong>macOS (Homebrew)</strong></summary>

```bash
brew install postgresql pgvector
brew services start postgresql
createdb goclaw
psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

</details>

<details>
<summary><strong>Fedora / RHEL</strong></summary>

```bash
sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

sudo dnf install -y postgresql-devel git make gcc
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

sudo -u postgres createdb goclaw
sudo -u postgres psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

</details>

**Verify installation:**

```bash
psql -d goclaw -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"
# Should show: vector | 0.x.x
```

> On Linux, prefix with `sudo -u postgres` if your user doesn't have direct database access.

### Step 2: Clone & Build

```bash
git clone https://github.com/nextlevelbuilder/goclaw.git
cd goclaw
go build -o goclaw .
./goclaw version
```

> **Python runtime (optional):** Some built-in skills require Python 3. Install it with `sudo apt install -y python3 python3-pip` (Ubuntu/Debian) or `brew install python` (macOS) if you plan to use those skills.

**Build Tags (Optional):** Enable extra features at compile time:

```bash
go build -tags embedui -o goclaw .           # Embed web UI in binary (serves dashboard at gateway port)
go build -tags otel -o goclaw .              # OpenTelemetry tracing
go build -tags tsnet -o goclaw .             # Tailscale networking
go build -tags redis -o goclaw .             # Redis caching
go build -tags "otel,tsnet" -o goclaw .      # Combine multiple
```

### Step 3: Run Setup Wizard

```bash
./goclaw onboard
```

The wizard guides you through:
1. **Database connection** — enter host, port, database name, username, password (defaults work for typical local PostgreSQL)
2. **Connection test** — verifies PostgreSQL is reachable
3. **Migrations** — creates all required tables automatically
4. **Key generation** — auto-generates `GOCLAW_GATEWAY_TOKEN` and `GOCLAW_ENCRYPTION_KEY`
5. **Seed providers** — inserts placeholder provider records so the dashboard UI is ready on first login
6. **Save secrets** — writes everything to `.env.local`

### Step 4: Start the Gateway

```bash
source .env.local && ./goclaw
```

### Step 5: Open the Dashboard

If you built with the `embedui` tag, the dashboard is served directly at `http://localhost:18790`. Log in with:
- **User ID:** `system`
- **Gateway Token:** found in `.env.local` (look for `GOCLAW_GATEWAY_TOKEN`)

Without `embedui`, run the dashboard as a separate React dev server in a new terminal:

```bash
cd ui/web
cp .env.example .env    # Required — configures backend connection
pnpm install
pnpm dev
```

Open `http://localhost:5173` and log in with the same credentials above.

After login, follow the [Quick Start](/quick-start) guide to add an LLM provider, create your first agent, and start chatting.

---

## Path 3: Docker (Local)

Run GoClaw with Docker Compose — PostgreSQL and the web dashboard included. This is the **recommended path** for most users.

> **Note:** This setup includes PostgreSQL automatically via `docker-compose.postgres.yml`. You don't need to install it separately.

> **Minimum RAM:** 2 GB. The gateway, PostgreSQL, and dashboard containers together use ~1.2 GB at idle.

### Step 1: Clone & Configure

```bash
git clone https://github.com/nextlevelbuilder/goclaw.git
cd goclaw

# Auto-generate encryption key + gateway token
./prepare-env.sh
```

Optionally add an LLM provider API key to `.env` now (or add it later via the dashboard):

```env
GOCLAW_OPENROUTER_API_KEY=sk-or-xxxxx
# or GOCLAW_ANTHROPIC_API_KEY=sk-ant-xxxxx
```

> **Note:** You do **not** need to run `goclaw onboard` for Docker — the onboard wizard is for bare metal only. Docker reads all configuration from `.env` and auto-runs migrations on startup.

### Step 2: Start Services

GoClaw uses modular Docker Compose files:
- `docker-compose.yml` — Core GoClaw gateway and API server (includes embedded Web UI by default)
- `docker-compose.postgres.yml` — PostgreSQL database with pgvector extension
- `docker-compose.selfservice.yml` — Optional: nginx reverse proxy + separate UI container at port 3000

The default `docker-compose.yml` sets `ENABLE_EMBEDUI: true`, so the dashboard is served directly at the gateway port (`http://localhost:18790`). You only need two files for a complete local setup:

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d --build
```

This starts:
- **GoClaw gateway + embedded dashboard** — `http://localhost:18790`
- **PostgreSQL** with pgvector — port `5432`

GoClaw automatically runs pending database migrations on every start. No need to run `goclaw onboard` or `goclaw migrate` manually.

Open `http://localhost:18790` and log in:
- **User ID:** `system`
- **Gateway Token:** found in `.env` (look for `GOCLAW_GATEWAY_TOKEN`)

<details>
<summary><strong>Optional: nginx + separate UI (selfservice)</strong></summary>

If you prefer a separate UI container at port 3000 (e.g. for nginx reverse proxy with a distinct UI port), add the selfservice overlay:

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.selfservice.yml \
  up -d --build
```

Dashboard will be available at `http://localhost:3000`.

</details>

After login, follow the [Quick Start](/quick-start) guide to add an LLM provider, create your first agent, and start chatting.

### Optional Add-ons

Add more capabilities with Docker Compose overlay files:

| Overlay file | What it adds |
|---|---|
| `docker-compose.sandbox.yml` | Code sandbox for isolated script execution |
| `docker-compose.tailscale.yml` | Secure remote access via Tailscale |
| `docker-compose.otel.yml` | OpenTelemetry tracing (Jaeger UI on `:16686`) |
| `docker-compose.redis.yml` | Redis caching layer |
| `docker-compose.browser.yml` | Browser automation (Chrome sidecar) |
| `docker-compose.upgrade.yml` | Database upgrade service |

Append any overlay with `-f` when starting services:

```bash
# Example: add Redis caching
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.redis.yml \
  up -d --build
```

> **Note:** Redis and OTel overlays require rebuilding the GoClaw image with the corresponding build args (`ENABLE_REDIS=true`, `ENABLE_OTEL=true`). Set `ENABLE_EMBEDUI=false` to disable the embedded UI (e.g. when using the selfservice nginx overlay). See the overlay files for details.

> **Python runtime:** The default `docker-compose.yml` builds GoClaw with `ENABLE_PYTHON: "true"`, so Python-based skills work out of the box in Docker.

> **Privilege separation:** The Docker image runs GoClaw as a non-root `goclaw` user (UID 1000). A separate `pkg-helper` binary runs as root to manage system (apk) package installs via a Unix socket (`/tmp/pkg.sock`), keeping the app process unprivileged. This is managed automatically by the `docker-entrypoint.sh` script.

---

## Path 4: VPS (Production)

Deploy GoClaw on a VPS with Docker. Suitable for always-on, internet-accessible setups.

> **Note:** PostgreSQL runs inside Docker. The compose file handles setup — you don't install it on the VPS system.

### Requirements

- **VPS**: 1 vCPU, **2 GB RAM minimum** ($6 tier). 2 vCPU / 4 GB recommended for heavier workloads.
- **OS**: Ubuntu 24.04+ or Debian 12+
- **Domain** (optional): For HTTPS/SSL via reverse proxy

### Step 1: Server Setup

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker (official script — includes Compose plugin)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group change to take effect
```

### Step 2: Firewall

```bash
sudo apt install -y ufw
sudo ufw allow 22/tcp     # SSH
sudo ufw allow 80/tcp     # HTTP
sudo ufw allow 443/tcp    # HTTPS
sudo ufw --force enable
```

### Step 3: Create Working Directory & Clone

```bash
sudo mkdir -p /opt/goclaw
sudo chown $(whoami):$(whoami) /opt/goclaw
git clone https://github.com/nextlevelbuilder/goclaw.git /opt/goclaw
cd /opt/goclaw

# Auto-generate secrets
./prepare-env.sh
```

### Step 4: Start Services

The default compose includes the embedded Web UI. Two files are sufficient for a complete production setup:

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d --build
```

GoClaw automatically runs pending database migrations on every start. No need to run `goclaw onboard` or `goclaw migrate` manually.

The dashboard is available at `http://localhost:18790`.

> **Optional:** To use nginx + a separate UI container at port 3000, add `-f docker-compose.selfservice.yml`. See the [Optional: nginx + separate UI](#optional-nginx--separate-ui-selfservice) section in Path 3 for details.

### Step 4.5: Verify Services Started

Before setting up reverse proxy, make sure everything is running:

```bash
docker compose ps
# Should show all services as "Up"

docker compose logs goclaw | grep "gateway starting"
# Should see: "goclaw gateway starting"
```

### Step 5: Reverse Proxy with SSL

**DNS setup:** Create an A record pointing to your VPS IP:

| Record | Type | Value |
|--------|------|-------|
| `yourdomain.com` | A | `YOUR_VPS_IP` |

**Caddy (Recommended):**

```bash
sudo apt install -y caddy
```

Create `/etc/caddy/Caddyfile`:

```
yourdomain.com {
    reverse_proxy localhost:18790
}
```

> **Note:** With `ENABLE_EMBEDUI: true` (default), both the dashboard and API/WebSocket are served from the same port (`18790`). If using `docker-compose.selfservice.yml`, point the dashboard domain to `localhost:3000` instead.

```bash
sudo systemctl reload caddy
```

Caddy auto-provisions SSL certificates via Let's Encrypt.

**Nginx:**

```bash
sudo apt install -y nginx certbot python3-certbot-nginx
```

Create `/etc/nginx/sites-available/goclaw`:

```nginx
server {
    server_name yourdomain.com;
    location / {
        proxy_pass http://localhost:18790;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

> **Note:** With `ENABLE_EMBEDUI: true` (default), all traffic (dashboard + API + WebSocket) goes through the single gateway port. If using `docker-compose.selfservice.yml`, configure a separate server block pointing to `localhost:3000` for the UI and `localhost:18790` for the WebSocket gateway.

```bash
sudo ln -s /etc/nginx/sites-available/goclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d yourdomain.com
```

### Step 6: Backup (Recommended)

Add a daily PostgreSQL backup cron job:

```bash
sudo mkdir -p /backup
(crontab -l 2>/dev/null; echo "0 2 * * * cd /opt/goclaw && docker compose -f docker-compose.yml -f docker-compose.postgres.yml exec -T postgres pg_dump -U goclaw goclaw | gzip > /backup/goclaw-\$(date +\%Y\%m\%d).sql.gz") | crontab -
```

---

## Updating to Latest Version

Already running GoClaw and want to upgrade? Follow the steps for your installation path.

### Path 1: Quick Install (Binary)

Re-run the install script — it downloads the latest release and overwrites the existing binary:

```bash
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash
```

Then upgrade the database schema:

```bash
source .env.local && goclaw upgrade
```

> **Tip:** Run `goclaw upgrade --status` first to check if a schema upgrade is needed, or `goclaw upgrade --dry-run` to preview changes.

### Path 2: Bare Metal

```bash
cd goclaw
git pull origin main
go build -o goclaw .
./goclaw upgrade
```

The `goclaw upgrade` command applies pending SQL migrations and runs data hooks. It is safe to run multiple times (idempotent).

### Path 3 & 4: Docker (Local / VPS)

```bash
cd /path/to/goclaw     # or /opt/goclaw on VPS
git pull origin main
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d --build
```

GoClaw automatically runs pending migrations on startup — no manual `goclaw upgrade` needed.

**Alternative: use the upgrade overlay** for a one-shot database upgrade without restarting the gateway:

```bash
# Preview changes
docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml run --rm upgrade --dry-run

# Apply upgrade
docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml run --rm upgrade
```

### Auto-upgrade on Startup

Set the `GOCLAW_AUTO_UPGRADE` environment variable to automatically run migrations when the gateway starts — useful for CI/CD and Docker deployments:

```bash
# .env or .env.local
GOCLAW_AUTO_UPGRADE=true
```

When enabled, GoClaw applies pending SQL migrations and data hooks inline during startup. If you prefer manual control, leave this unset and run `goclaw upgrade` yourself.

### Troubleshooting Upgrades

| Problem | Solution |
|---------|----------|
| `database schema is dirty` | A previous migration failed. Run `goclaw migrate force <version-1>` then `goclaw upgrade` |
| `schema is newer than this binary` | Your binary is older than your database. Update the binary first |
| `UPGRADE NEEDED` on gateway start | Run `goclaw upgrade` or set `GOCLAW_AUTO_UPGRADE=true` |

---

## Verify Installation

Works for all three paths:

```bash
# Health check
curl http://localhost:18790/health
# Expected: {"status":"ok"}

# Docker logs (Docker/VPS paths)
docker compose logs goclaw
# Look for: "goclaw gateway starting"

# Diagnostic check (bare metal)
./goclaw doctor
```

## Common Issues

| Problem | Solution |
|---------|----------|
| `go: module requires Go >= 1.26` | Update Go: `go install golang.org/dl/go1.26@latest` |
| `pgvector extension not found` | Run `CREATE EXTENSION vector;` in your goclaw database |
| Port 18790 already in use | Set `GOCLAW_PORT=18791` in `.env` (Docker) or `.env.local` (bare metal) |
| Docker build fails on ARM Mac | Enable Rosetta in Docker Desktop settings |
| `no provider API key found` | Add an LLM provider & API key through the Dashboard |
| `encryption key not set` | Run `./goclaw onboard` (bare metal) or `./prepare-env.sh` (Docker) |
| `Cannot connect to the Docker daemon` | Start Docker Desktop first: `open -a Docker` (macOS) or `sudo systemctl start docker` (Linux) |

## What's Next

- [Quick Start](/quick-start) — Run your first agent
- [Configuration](/configuration) — Customize GoClaw settings



---

# Quick Start

> Your first AI agent conversation in 5 minutes.

## Prerequisites

You've completed [Installation](/installation) and the gateway is running on `http://localhost:18790`.

## Step 1: Open the Dashboard & Complete Setup

Open `http://localhost:3000` (Docker) or `http://localhost:5173` (bare metal dev server) and log in:

- **User ID:** `system`
- **Gateway Token:** found in `.env.local` (or `.env` for Docker) — look for `GOCLAW_GATEWAY_TOKEN`

On first login, the dashboard automatically navigates to the **Setup Wizard**. The wizard walks you through:

1. **Add an LLM provider** — choose from OpenRouter, Anthropic, OpenAI, Groq, DeepSeek, Gemini, Mistral, xAI, MiniMax, DashScope (Alibaba Cloud Model Studio — Qwen API), Bailian (Alibaba Cloud Model Studio — Coding Plan), GLM (Zhipu), and more. Enter your API key and select a model.
2. **Create your first agent** — give it a name, system prompt, and select the provider/model from above.
3. **Connect a channel** (optional) — link Telegram, Discord, WhatsApp, Zalo, Larksuite, or Slack.

> **Tip:** You can click **"Skip setup and go to dashboard"** at the top of the wizard to skip it entirely and configure everything manually later. The Channel step (step 3) also has a **Skip** button if you don't need Telegram/Discord/etc. yet — you can always add channels later.

After completing the wizard, you're ready to chat.

## Step 2: Add More Providers (Optional)

To add additional providers later:

1. Go to **Providers** (under **SYSTEM** in the sidebar)
2. Click **Add Provider**
3. Choose a provider, enter API key, and select a model

## Step 3: Chat

> **Note:** Before making API or WebSocket calls, make sure you've added at least one provider during the Setup Wizard (Step 1 above). Without a provider, requests will return `no provider API key found`.

> **Tip:** To verify GoClaw is running: `curl http://localhost:18790/health`

### Using the Dashboard

Go to **Chat** (under **CORE** in the sidebar) and select the agent you created during setup.

To create additional agents, go to **Agents** (also under **CORE**) and click **Create Agent**. See [Creating Agents](/creating-agents) for details.

### Using the HTTP API

The HTTP API is OpenAI-compatible. Use the `goclaw:<agent-key>` format in the `model` field to specify the target agent:

```bash
curl -X POST http://localhost:18790/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "X-GoClaw-User-Id: system" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "goclaw:your-agent-key",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

Replace `YOUR_GATEWAY_TOKEN` with the value from `.env.local` (bare metal) or `.env` (Docker) and `your-agent-key` with the agent key shown in the Agents page (e.g., `goclaw:my-assistant`).

> **Agent identifier tip:** The Dashboard shows two identifiers per agent — `agent_key` (a human-readable display name) and `id` (a UUID). For HTTP API calls use `agent_key` in the `model` field. For WebSocket `chat.send`, use the agent's `id` (UUID) as `agentId`. Both are visible on the Agents page.

### Using WebSocket

Connect with any WebSocket client:

```bash
# Using websocat (install: cargo install websocat)
websocat ws://localhost:18790/ws
```

**First**, send a `connect` frame to authenticate:

```json
{"type":"req","id":"1","method":"connect","params":{"token":"YOUR_GATEWAY_TOKEN","user_id":"system"}}
```

**Then**, send a chat message:

```json
{"type":"req","id":"2","method":"chat.send","params":{"agentId":"your-agent-key","message":"Hello! What can you do?"}}
```

> **Tip:** If you omit `agentId`, GoClaw uses the `default` agent.

**Response:**

```json
{
  "type": "res",
  "id": "2",
  "ok": true,
  "payload": {
    "runId": "uuid-string",
    "content": "Hello! How can I help you today?",
    "usage": { "input_tokens": 150, "output_tokens": 25 }
  }
}
```

The `media` field appears in the payload only when the agent returns generated media files.

## Common Issues

| Problem | Solution |
|---------|----------|
| `no provider API key found` | Add a provider & API key in the Dashboard |
| `unauthorized` on WebSocket | Check the `token` in your `connect` frame matches `GOCLAW_GATEWAY_TOKEN` |
| Dashboard shows blank page | Ensure the web UI service is running |

## What's Next

- [Configuration](/configuration) — Fine-tune your setup
- [Dashboard Tour](/dashboard-tour) — Explore the visual interface
- [Agents Explained](/agents-explained) — Understand agent types and context



---

# Configuration

> How to configure GoClaw with config.json and environment variables.

## Overview

GoClaw uses two layers of configuration: a `config.json` file for structure and environment variables for secrets. The config file supports JSON5 (comments allowed) and hot-reloads on save.

## Config File Location

By default, GoClaw looks for `config.json` in the current directory. Override with:

```bash
export GOCLAW_CONFIG=/path/to/config.json
```

## Config Structure

Top-level sections at a glance:

```jsonc
{
  "gateway": { ... },      // HTTP/WS server settings, auth, quotas
  "agents": {              // Defaults + per-agent overrides
    "defaults": { ... },
    "list": { ... }
  },
  "memory": { ... },       // Semantic memory (embedding, retrieval)
  "compaction": { ... },   // Context compaction thresholds
  "context_pruning": { ... }, // Context pruning policy
  "subagents": { ... },    // Subagent concurrency limits
  "sandbox": { ... },      // Docker sandbox defaults
  "providers": { ... },    // LLM provider API keys
  "channels": { ... },     // Messaging channel integrations
  "tools": { ... },        // Tool policies, MCP servers
  "tts": { ... },          // Text-to-speech
  "sessions": { ... },     // Session storage & scoping
  "cron": [],              // Scheduled tasks
  "bindings": {},          // Agent routing by channel/peer
  "telemetry": { ... },    // OpenTelemetry export
  "tailscale": { ... }     // Tailscale/tsnet networking
}
```

**Important:** The `env:` prefix tells GoClaw to read the value from an environment variable instead of using a literal string.

- `"env:GOCLAW_OPENROUTER_API_KEY"` → reads `$GOCLAW_OPENROUTER_API_KEY`
- `"my-secret-key"` (no `env:`) → uses the literal string (**not recommended** for secrets)

Always use `env:` for sensitive values like API keys, tokens, and passwords.

## Environment Variables

### Required

| Variable | Purpose |
|----------|---------|
| `GOCLAW_GATEWAY_TOKEN` | Bearer token for API/WebSocket auth |
| `GOCLAW_ENCRYPTION_KEY` | AES-256-GCM key for encrypting credentials in DB |
| `GOCLAW_POSTGRES_DSN` | PostgreSQL connection string |

### Provider API Keys

| Variable | Provider |
|----------|----------|
| `GOCLAW_ANTHROPIC_API_KEY` | Anthropic |
| `GOCLAW_OPENAI_API_KEY` | OpenAI |
| `GOCLAW_OPENROUTER_API_KEY` | OpenRouter |
| `GOCLAW_GROQ_API_KEY` | Groq |
| `GOCLAW_GEMINI_API_KEY` | Google Gemini |
| `GOCLAW_DEEPSEEK_API_KEY` | DeepSeek |
| `GOCLAW_MISTRAL_API_KEY` | Mistral |
| `GOCLAW_XAI_API_KEY` | xAI |
| `GOCLAW_MINIMAX_API_KEY` | MiniMax |
| `GOCLAW_COHERE_API_KEY` | Cohere |
| `GOCLAW_PERPLEXITY_API_KEY` | Perplexity |
| `GOCLAW_DASHSCOPE_API_KEY` | DashScope (Alibaba Cloud Model Studio — Qwen API) |
| `GOCLAW_BAILIAN_API_KEY` | Bailian (Alibaba Cloud Model Studio — Coding Plan) |
| `GOCLAW_ZAI_API_KEY` | ZAI |
| `GOCLAW_ZAI_CODING_API_KEY` | ZAI Coding |
| `GOCLAW_OLLAMA_CLOUD_API_KEY` | Ollama Cloud |

### Optional

| Variable | Default | Purpose |
|----------|---------|---------|
| `GOCLAW_CONFIG` | `./config.json` | Config file path |
| `GOCLAW_WORKSPACE` | `./workspace` | Agent workspace directory |
| `GOCLAW_DATA_DIR` | `./data` | Data directory |
| `GOCLAW_REDIS_DSN` | — | Redis DSN (if using Redis session storage) |
| `GOCLAW_TSNET_AUTH_KEY` | — | Tailscale auth key |
| `GOCLAW_TRACE_VERBOSE` | `0` | Set to `1` for debug LLM traces |

## Hot Reload

GoClaw watches `config.json` for changes using `fsnotify` with a 300ms debounce. Agents, channels, and provider credentials reload automatically.

**Exception:** Gateway settings (host, port) require a full restart.

## Gateway Configuration

```jsonc
"gateway": {
  "host": "0.0.0.0",
  "port": 18790,
  "token": "env:GOCLAW_GATEWAY_TOKEN",
  "owner_ids": ["user123"],
  "max_message_chars": 32000,
  "rate_limit_rpm": 20,
  "allowed_origins": ["https://app.example.com"],
  "injection_action": "warn",
  "inbound_debounce_ms": 1000,
  "block_reply": false,
  "tool_status": true,
  "quota": {
    "enabled": true,
    "default": { "hour": 100, "day": 500 },
    "providers": { "anthropic": { "hour": 50 } },
    "channels": { "telegram": { "day": 200 } },
    "groups": { "group_vip": { "hour": 0 } }
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `host` | string | `"0.0.0.0"` | Bind address |
| `port` | int | `18790` | HTTP/WS port |
| `token` | string | — | Bearer token for WS/HTTP auth |
| `owner_ids` | []string | — | Sender IDs treated as "owner" (bypass quotas/limits) |
| `max_message_chars` | int | `32000` | Max inbound message length |
| `rate_limit_rpm` | int | `20` | Global rate limit (requests per minute) |
| `allowed_origins` | []string | — | WebSocket CORS whitelist; empty = allow all |
| `injection_action` | string | `"warn"` | Prompt-injection response: `"log"`, `"warn"`, `"block"`, `"off"` |
| `inbound_debounce_ms` | int | `1000` | Merge rapid messages within window; `-1` = disabled |
| `block_reply` | bool | `false` | If true, suppress intermediate text during tool iterations |
| `tool_status` | bool | `true` | Show tool name in streaming preview |
| `task_recovery_interval_sec` | int | `300` | How often (seconds) to check for and recover stalled team tasks |
| `quota` | object | — | Per-user/group request quotas (see below) |

**Quota fields** (`quota.default`, `quota.providers.*`, `quota.channels.*`, `quota.groups.*`):

| Field | Type | Description |
|-------|------|-------------|
| `hour` | int | Max requests per hour; `0` = unlimited |
| `day` | int | Max requests per day |
| `week` | int | Max requests per week |

## Agent Configuration

### Defaults

Settings in `agents.defaults` apply to all agents unless overridden.

```jsonc
"agents": {
  "defaults": {
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929",
    "max_tokens": 8192,
    "temperature": 0.7,
    "max_tool_iterations": 20,
    "max_tool_calls": 25,
    "context_window": 200000,
    "agent_type": "open",
    "workspace": "./workspace",
    "restrict_to_workspace": false,
    "bootstrapMaxChars": 20000,
    "bootstrapTotalMaxChars": 24000,
    "memory": { "enabled": true }
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | string | — | LLM provider ID |
| `model` | string | — | Model name |
| `max_tokens` | int | — | Max output tokens |
| `temperature` | float | `0.7` | Sampling temperature |
| `max_tool_iterations` | int | `20` | Max LLM→tool loops per request |
| `max_tool_calls` | int | `25` | Max total tool calls per request |
| `context_window` | int | — | Context window size in tokens |
| `agent_type` | string | `"open"` | `"open"` (per-session context: identity/soul/user files refresh each session) or `"predefined"` (persistent context: shared identity/soul files + per-user USER.md across sessions) |
| `workspace` | string | `"./workspace"` | Working directory for file ops |
| `restrict_to_workspace` | bool | `false` | Block file access outside workspace |
| `bootstrapMaxChars` | int | `20000` | Max chars for a single bootstrap doc |
| `bootstrapTotalMaxChars` | int | `24000` | Max total chars across all bootstrap docs |

> **Note:** `intent_classify` is not a config.json field. It is configured per-agent via the Dashboard (Agent settings → Behavior & UX section) and stored on the agent record in the database.

### Per-Agent Overrides

```jsonc
"agents": {
  "list": {
    "code-helper": {
      "displayName": "Code Helper",
      "model": "anthropic/claude-opus-4-6",
      "temperature": 0.3,
      "max_tool_iterations": 50,
      "max_tool_calls": 40,
      "default": false,
      "skills": ["git", "code-review"],
      "workspace": "./workspace/code",
      "identity": { "name": "CodeBot", "emoji": "🤖" },
      "tools": {
        "profile": "coding",
        "deny": ["web_search"]
      },
      "sandbox": { "mode": "non-main" }
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `displayName` | string | Human-readable agent name shown in UI |
| `default` | bool | Mark as default agent for unmatched requests |
| `skills` | []string | Skill IDs to enable; `null` = all available |
| `tools` | object | Per-agent tool policy (see Tools section) |
| `workspace` | string | Override workspace path for this agent |
| `sandbox` | object | Override sandbox config for this agent |
| `identity` | object | `{ "name": "...", "emoji": "..." }` display identity |
| All defaults fields | — | Any `defaults` field can be overridden here |

## Memory

Semantic memory stores and retrieves conversation context using vector embeddings.

```jsonc
"memory": {
  "enabled": true,
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "embedding_api_base": "",
  "max_results": 6,
  "max_chunk_len": 1000,
  "vector_weight": 0.7,
  "text_weight": 0.3,
  "min_score": 0.35
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Enable semantic memory |
| `embedding_provider` | string | auto | `"openai"`, `"gemini"`, `"openrouter"`, or `""` (auto-detect) |
| `embedding_model` | string | `"text-embedding-3-small"` | Embedding model |
| `embedding_api_base` | string | — | Custom API base URL for embeddings |
| `max_results` | int | `6` | Max memory chunks retrieved per query |
| `max_chunk_len` | int | `1000` | Max characters per memory chunk |
| `vector_weight` | float | `0.7` | Weight for vector similarity score |
| `text_weight` | float | `0.3` | Weight for text (BM25) score |
| `min_score` | float | `0.35` | Minimum score threshold for retrieval |

## Compaction

Controls when and how GoClaw compacts long conversation histories to stay within context limits.

```jsonc
"compaction": {
  "reserveTokensFloor": 20000,
  "maxHistoryShare": 0.75,
  "minMessages": 50,
  "keepLastMessages": 4,
  "memoryFlush": {
    "enabled": true,
    "softThresholdTokens": 4000,
    "prompt": "",
    "systemPrompt": ""
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `reserveTokensFloor` | int | `20000` | Minimum tokens always reserved for response |
| `maxHistoryShare` | float | `0.75` | Max fraction of context window used by history |
| `minMessages` | int | `50` | Don't compact until history has this many messages |
| `keepLastMessages` | int | `4` | Always keep the N most recent messages |
| `memoryFlush.enabled` | bool | `true` | Flush summarized content to memory on compaction |
| `memoryFlush.softThresholdTokens` | int | `4000` | Trigger flush when approaching this token count |
| `memoryFlush.prompt` | string | — | Custom user prompt for summarization |
| `memoryFlush.systemPrompt` | string | — | Custom system prompt for summarization |

## Context Pruning

Prunes old tool results from context when approaching limits.

```jsonc
"context_pruning": {
  "mode": "cache-ttl",
  "keepLastAssistants": 3,
  "softTrimRatio": 0.3,
  "hardClearRatio": 0.5,
  "minPrunableToolChars": 50000,
  "softTrim": {
    "maxChars": 4000,
    "headChars": 1500,
    "tailChars": 1500
  },
  "hardClear": {
    "enabled": true,
    "placeholder": "[Old tool result content cleared]"
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `"off"` | `"off"` or `"cache-ttl"` (prune by age) |
| `keepLastAssistants` | int | `3` | Keep N most recent assistant turns intact |
| `softTrimRatio` | float | `0.3` | Start soft trim when context exceeds this ratio of context window |
| `hardClearRatio` | float | `0.5` | Start hard clear when context exceeds this ratio |
| `minPrunableToolChars` | int | `50000` | Minimum total tool chars before pruning activates |
| `softTrim.maxChars` | int | `4000` | Tool results longer than this are trimmed |
| `softTrim.headChars` | int | `1500` | Chars to keep from the start of a trimmed result |
| `softTrim.tailChars` | int | `1500` | Chars to keep from the end of a trimmed result |
| `hardClear.enabled` | bool | `true` | Enable hard clear of very old tool results |
| `hardClear.placeholder` | string | `"[Old tool result content cleared]"` | Text to replace cleared results |

## Subagents

Controls how agents can spawn child agents.

```jsonc
"subagents": {
  "maxConcurrent": 20,
  "maxSpawnDepth": 1,
  "maxChildrenPerAgent": 5,
  "archiveAfterMinutes": 60,
  "model": "anthropic/claude-haiku-4-5-20251001"
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `maxConcurrent` | int | `20` | Max subagents running simultaneously (code fallback when no config.json: `8`) |
| `maxSpawnDepth` | int | `1` | Max nesting depth (1–5); `1` = only root can spawn |
| `maxChildrenPerAgent` | int | `5` | Max children per parent agent (1–20) |
| `archiveAfterMinutes` | int | `60` | Archive idle subagents after this duration |
| `model` | string | — | Default model for subagents (overrides agent defaults) |

## Sandbox

Docker-based isolation for code execution. Can be set globally or overridden per agent.

```jsonc
"sandbox": {
  "mode": "non-main",
  "image": "goclaw-sandbox:bookworm-slim",
  "workspace_access": "rw",
  "scope": "session",
  "memory_mb": 512,
  "cpus": 1.0,
  "timeout_sec": 300,
  "network_enabled": false,
  "read_only_root": true,
  "setup_command": "",
  "env": { "MY_VAR": "value" },
  "user": "",
  "tmpfs_size_mb": 0,
  "max_output_bytes": 1048576,
  "idle_hours": 24,
  "max_age_days": 7,
  "prune_interval_min": 5
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `"off"` | `"off"`, `"non-main"` (sandbox subagents only), `"all"` |
| `image` | string | `"goclaw-sandbox:bookworm-slim"` | Docker image |
| `workspace_access` | string | `"rw"` | Mount workspace: `"none"`, `"ro"`, `"rw"` |
| `scope` | string | `"session"` | Container lifetime: `"session"`, `"agent"`, `"shared"` |
| `memory_mb` | int | `512` | Memory limit (MB) |
| `cpus` | float | `1.0` | CPU quota |
| `timeout_sec` | int | `300` | Max execution time per command |
| `network_enabled` | bool | `false` | Allow network access inside container |
| `read_only_root` | bool | `true` | Read-only root filesystem |
| `setup_command` | string | — | Shell command run on container start |
| `env` | map | — | Extra environment variables |
| `max_output_bytes` | int | `1048576` | Max stdout+stderr per command (default 1 MB) |
| `idle_hours` | int | `24` | Prune containers idle longer than this |
| `max_age_days` | int | `7` | Prune containers older than this |
| `prune_interval_min` | int | `5` | How often to run container pruning |

## Providers

```jsonc
"providers": {
  "anthropic":   { "api_key": "env:GOCLAW_ANTHROPIC_API_KEY" },
  "openai":      { "api_key": "env:GOCLAW_OPENAI_API_KEY" },
  "openrouter":  { "api_key": "env:GOCLAW_OPENROUTER_API_KEY" },
  "groq":        { "api_key": "env:GOCLAW_GROQ_API_KEY" },
  "gemini":      { "api_key": "env:GOCLAW_GEMINI_API_KEY" },
  "deepseek":    { "api_key": "env:GOCLAW_DEEPSEEK_API_KEY" },
  "mistral":     { "api_key": "env:GOCLAW_MISTRAL_API_KEY" },
  "xai":         { "api_key": "env:GOCLAW_XAI_API_KEY" },
  "minimax":     { "api_key": "env:GOCLAW_MINIMAX_API_KEY" },
  "cohere":      { "api_key": "env:GOCLAW_COHERE_API_KEY" },
  "perplexity":  { "api_key": "env:GOCLAW_PERPLEXITY_API_KEY" },
  "dashscope":   { "api_key": "env:GOCLAW_DASHSCOPE_API_KEY" },
  "bailian":     { "api_key": "env:GOCLAW_BAILIAN_API_KEY" },
  "zai":         { "api_key": "env:GOCLAW_ZAI_API_KEY" },
  "zai_coding":  { "api_key": "env:GOCLAW_ZAI_CODING_API_KEY" },
  "ollama":      { "host": "http://localhost:11434" },
  "ollama_cloud":{ "api_key": "env:GOCLAW_OLLAMA_CLOUD_API_KEY" },
  "claude_cli":  {
    "cli_path": "/usr/local/bin/claude",
    "model": "claude-opus-4-5",
    "base_work_dir": "/tmp/claude-work",
    "perm_mode": "bypassPermissions"
  },
  "acp": {
    "binary": "claude",
    "args": [],
    "model": "claude-sonnet-4-5",
    "work_dir": "/tmp/acp-work",
    "idle_ttl": "5m",
    "perm_mode": "approve-all"
  }
}
```

**Notes:**
- `ollama` — local Ollama; no API key required, only `host`
- `claude_cli` — runs Claude via CLI subprocess; special fields: `cli_path`, `base_work_dir`, `perm_mode`
- `acp` — orchestrates any ACP-compatible agent (Claude Code, Codex CLI, Gemini CLI) as a subprocess over JSON-RPC 2.0 stdio

**ACP provider fields:**

| Field | Type | Description |
|-------|------|-------------|
| `binary` | string | Agent binary name or path (e.g. `"claude"`, `"codex"`) |
| `args` | []string | Extra arguments passed on spawn |
| `model` | string | Default model/agent name |
| `work_dir` | string | Base workspace directory for agent processes |
| `idle_ttl` | string | How long an idle process is kept alive (Go duration, e.g. `"5m"`) |
| `perm_mode` | string | Tool permission mode: `"approve-all"` (default), `"approve-reads"`, `"deny-all"` |

## Channels

### Telegram

```jsonc
"telegram": {
  "enabled": true,
  "token": "env:TELEGRAM_BOT_TOKEN",
  "proxy": "",
  "api_server": "",
  "allow_from": ["123456789"],
  "dm_policy": "pairing",
  "group_policy": "allowlist",
  "require_mention": true,
  "history_limit": 50,
  "dm_stream": false,
  "group_stream": false,
  "draft_transport": true,
  "reasoning_stream": true,
  "reaction_level": "full",
  "media_max_bytes": 20971520,
  "link_preview": true,
  "block_reply": false,
  "stt_proxy_url": "",
  "stt_api_key": "env:GOCLAW_STT_API_KEY",
  "stt_tenant_id": "",
  "stt_timeout_seconds": 30,
  "voice_agent_id": "",
  "groups": {
    "-100123456789": { "agent_id": "code-helper", "require_mention": false }
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `token` | string | — | Bot token from @BotFather |
| `proxy` | string | — | HTTP/SOCKS5 proxy URL |
| `api_server` | string | — | Custom Telegram Bot API server URL (e.g. `"http://localhost:8081"`) |
| `allow_from` | []string | — | Allowlisted user/chat IDs; empty = allow all |
| `dm_policy` | string | `"pairing"` | DM access: `"pairing"`, `"allowlist"`, `"open"`, `"disabled"` |
| `group_policy` | string | `"open"` | Group access: `"open"`, `"allowlist"`, `"disabled"` |
| `require_mention` | bool | `true` | Require @bot mention in groups |
| `history_limit` | int | `50` | Messages fetched for context on new conversation |
| `dm_stream` | bool | `false` | Stream responses in DMs |
| `group_stream` | bool | `false` | Stream responses in groups |
| `draft_transport` | bool | `true` | Use `sendMessageDraft` for DM streaming (stealth preview — no per-edit notifications) |
| `reasoning_stream` | bool | `true` | Show reasoning as a separate message when the provider emits thinking events |
| `reaction_level` | string | `"full"` | Emoji reactions: `"off"`, `"minimal"`, `"full"` |
| `media_max_bytes` | int | `20971520` | Max media file size (default 20 MB) |
| `link_preview` | bool | `true` | Show link previews |
| `block_reply` | bool | `false` | Override gateway `block_reply` for this channel |
| `stt_*` | — | — | Speech-to-text config (proxy URL, API key, tenant, timeout) |
| `voice_agent_id` | string | — | Agent to handle voice messages |
| `groups` | map | — | Per-group overrides keyed by chat ID |

### Discord

```jsonc
"discord": {
  "enabled": true,
  "token": "env:DISCORD_BOT_TOKEN",
  "allow_from": [],
  "dm_policy": "open",
  "group_policy": "open",
  "require_mention": true,
  "history_limit": 50,
  "block_reply": false,
  "media_max_bytes": 26214400,
  "stt_api_key": "env:GOCLAW_STT_API_KEY",
  "stt_timeout_seconds": 30,
  "voice_agent_id": ""
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `token` | string | — | Discord bot token |
| `allow_from` | []string | — | Allowlisted user IDs |
| `dm_policy` | string | `"open"` | DM policy |
| `group_policy` | string | `"open"` | Server/channel policy |
| `require_mention` | bool | `true` | Require @mention in channels |
| `history_limit` | int | `50` | Context history limit |
| `media_max_bytes` | int | `26214400` | Max media size (default 25 MB) |
| `block_reply` | bool | `false` | Suppress intermediate replies |
| `stt_*` | — | — | Speech-to-text config |
| `voice_agent_id` | string | — | Agent for voice messages |

### Slack

```jsonc
"slack": {
  "enabled": true,
  "bot_token": "env:SLACK_BOT_TOKEN",
  "app_token": "env:SLACK_APP_TOKEN",
  "user_token": "env:SLACK_USER_TOKEN",
  "allow_from": [],
  "dm_policy": "pairing",
  "group_policy": "open",
  "require_mention": true,
  "history_limit": 50,
  "dm_stream": false,
  "group_stream": false,
  "native_stream": false,
  "reaction_level": "minimal",
  "block_reply": false,
  "debounce_delay": 300,
  "thread_ttl": 24,
  "media_max_bytes": 20971520
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `bot_token` | string | — | Bot OAuth token (`xoxb-...`) |
| `app_token` | string | — | App-level token for Socket Mode (`xapp-...`) |
| `user_token` | string | — | User OAuth token (`xoxp-...`) |
| `allow_from` | []string | — | Allowlisted user IDs |
| `dm_policy` | string | `"pairing"` | DM access policy |
| `group_policy` | string | `"open"` | Channel access policy |
| `require_mention` | bool | `true` | Require @mention in channels |
| `native_stream` | bool | `false` | Use Slack native streaming API |
| `debounce_delay` | int | `300` | Message debounce in milliseconds |
| `thread_ttl` | int | `24` | Hours to maintain thread context; `0` = disabled (always require @mention) |
| `media_max_bytes` | int | `20971520` | Max media size (default 20 MB) |

### WhatsApp

```jsonc
"whatsapp": {
  "enabled": true,
  "allow_from": [],
  "dm_policy": "pairing",
  "group_policy": "pairing",
  "require_mention": false,
  "history_limit": 200,
  "block_reply": false
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `allow_from` | []string | — | Allowlisted phone numbers/JIDs |
| `dm_policy` | string | `"pairing"` | DM access policy |
| `group_policy` | string | `"pairing"` (DB) / `"open"` (config) | Group access policy |
| `require_mention` | bool | `false` | Only respond in groups when @mentioned |
| `history_limit` | int | `200` | Max pending group messages for context |
| `block_reply` | bool | `false` | Suppress intermediate replies |

### Zalo

```jsonc
"zalo": {
  "enabled": true,
  "token": "env:ZALO_OA_TOKEN",
  "allow_from": [],
  "dm_policy": "pairing",
  "webhook_url": "https://example.com/zalo/webhook",
  "webhook_secret": "env:ZALO_WEBHOOK_SECRET",
  "media_max_mb": 5,
  "block_reply": false
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `token` | string | — | Zalo OA access token |
| `allow_from` | []string | — | Allowlisted user IDs |
| `dm_policy` | string | `"pairing"` | DM access policy |
| `webhook_url` | string | — | Public webhook URL for Zalo callbacks |
| `webhook_secret` | string | — | Webhook signature secret |
| `media_max_mb` | int | `5` | Max media size (MB) |
| `block_reply` | bool | `false` | Suppress intermediate replies |

### Zalo Personal

```jsonc
"zalo_personal": {
  "enabled": true,
  "allow_from": [],
  "dm_policy": "pairing",
  "group_policy": "disabled",
  "require_mention": false,
  "history_limit": 50,
  "credentials_path": "./zalo-creds.json",
  "block_reply": false
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `allow_from` | []string | — | Allowlisted user IDs |
| `dm_policy` | string | `"pairing"` | DM access policy |
| `group_policy` | string | `"disabled"` | Group access policy |
| `require_mention` | bool | `false` | Require mention in groups |
| `history_limit` | int | `50` | Context history limit |
| `credentials_path` | string | — | Path to Zalo session credentials file |
| `block_reply` | bool | `false` | Suppress intermediate replies |

### Larksuite

JSON key: `"feishu"`

```jsonc
"feishu": {
  "enabled": true,
  "app_id": "env:LARK_APP_ID",
  "app_secret": "env:LARK_APP_SECRET",
  "encrypt_key": "env:LARK_ENCRYPT_KEY",
  "verification_token": "env:LARK_VERIFICATION_TOKEN",
  "domain": "lark",
  "connection_mode": "websocket",
  "webhook_port": 3000,
  "webhook_path": "/feishu/events",
  "allow_from": [],
  "dm_policy": "pairing",
  "group_policy": "open",
  "group_allow_from": [],
  "require_mention": true,
  "topic_session_mode": "disabled",
  "text_chunk_limit": 4000,
  "media_max_mb": 30,
  "render_mode": "auto",
  "streaming": true,
  "reaction_level": "minimal",
  "history_limit": 50,
  "block_reply": false,
  "stt_api_key": "env:GOCLAW_STT_API_KEY",
  "stt_timeout_seconds": 30,
  "voice_agent_id": ""
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `app_id` / `app_secret` | string | — | Larksuite app credentials |
| `encrypt_key` | string | — | Event encryption key |
| `verification_token` | string | — | Webhook verification token |
| `domain` | string | `"lark"` | `"lark"`, `"feishu"`, or custom base URL |
| `connection_mode` | string | `"websocket"` | `"websocket"` or `"webhook"` |
| `webhook_port` | int | `3000` | Port for webhook mode |
| `webhook_path` | string | `"/feishu/events"` | Path for webhook events |
| `group_allow_from` | []string | — | Allowlisted group IDs |
| `topic_session_mode` | string | `"disabled"` | Thread/topic session handling |
| `text_chunk_limit` | int | `4000` | Max characters per message chunk |
| `render_mode` | string | `"auto"` | Message rendering: `"auto"`, `"raw"`, `"card"` |
| `streaming` | bool | `true` | Enable streaming responses |
| `media_max_mb` | int | `30` | Max media size (MB) |

### Pending Compaction

Auto-compacts long channel histories.

```jsonc
"channels": {
  "pending_compaction": {
    "threshold": 50,
    "keep_recent": 15,
    "max_tokens": 4096,
    "provider": "openrouter",
    "model": "anthropic/claude-haiku-4-5-20251001"
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `threshold` | int | `50` | Compact when pending messages exceed this count |
| `keep_recent` | int | `15` | Always keep this many recent messages |
| `max_tokens` | int | `4096` | Max tokens for compaction summary |
| `provider` | string | — | Provider for compaction LLM call |
| `model` | string | — | Model for compaction LLM call |

## Tools

```jsonc
"tools": {
  "profile": "coding",
  "allow": ["bash", "read_file"],
  "deny": ["web_search"],
  "alsoAllow": ["special_tool"],
  "rate_limit_per_hour": 500,
  "scrub_credentials": true,
  "execApproval": {
    "security": "allowlist",
    "ask": "on-miss"
  },
  "web": {
    "duckduckgo": { "enabled": true },
    "fetch": {
      "policy": "allow_all",
      "allowed_domains": [],
      "blocked_domains": []
    }
  },
  "browser": { "enabled": true, "headless": true },
  "byProvider": {
    "anthropic": { "profile": "full" }
  },
  "mcp_servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "enabled": true,
      "tool_prefix": "fs_",
      "timeout_sec": 60
    },
    "remote-api": {
      "transport": "streamable-http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "env:MCP_API_KEY" },
      "enabled": true
    }
  }
}
```

**Tool policy fields:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `profile` | string | — | Tool preset: `"minimal"`, `"coding"`, `"messaging"`, `"full"` |
| `allow` | []string | — | Explicitly allowed tool IDs |
| `deny` | []string | — | Explicitly denied tool IDs |
| `alsoAllow` | []string | — | Add tools on top of current profile |
| `rate_limit_per_hour` | int | — | Max tool calls per hour globally |
| `scrub_credentials` | bool | `true` | Redact credentials from tool outputs |

**Web fetch policy (`tools.web.fetch`):**

| Field | Type | Description |
|-------|------|-------------|
| `policy` | string | `"allow_all"` or `"allowlist"` |
| `allowed_domains` | []string | Domains allowed when policy is `"allowlist"` |
| `blocked_domains` | []string | Domains always blocked |

**MCP server fields (`tools.mcp_servers.*`):**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `transport` | string | — | `"stdio"`, `"sse"`, `"streamable-http"` |
| `command` | string | — | Executable for stdio transport |
| `args` | []string | — | Args for stdio command |
| `env` | map | — | Environment variables for stdio process |
| `url` | string | — | URL for SSE/HTTP transport |
| `headers` | map | — | HTTP headers (supports `env:` prefix) |
| `enabled` | bool | `true` | Enable/disable this server |
| `tool_prefix` | string | — | Prefix added to all tools from this server |
| `timeout_sec` | int | `60` | Request timeout |

**Per-agent/per-provider tool policy** supports the same fields plus:

| Field | Type | Description |
|-------|------|-------------|
| `vision` | object | `{ "provider": "...", "model": "..." }` for vision tasks |
| `imageGen` | object | `{ "provider": "...", "model": "...", "size": "...", "quality": "..." }` |

## Exec Approval

Controls code execution safety:

**`security`** — What commands are allowed:

| Value | Behavior |
|-------|----------|
| `deny` | Block all shell commands |
| `allowlist` | Only execute allowlisted commands |
| `full` | Allow all shell commands |

**`ask`** — When to prompt for approval:

| Value | Behavior |
|-------|----------|
| `off` | Never ask, auto-approve based on security level |
| `on-miss` | Ask when command is not in the allowlist |
| `always` | Ask for every command |

```jsonc
// Restrictive: only allowlisted commands, ask for anything else
"execApproval": { "security": "allowlist", "ask": "on-miss" }

// Permissive: allow all, never ask
"execApproval": { "security": "full", "ask": "off" }

// Locked down: block all execution
"execApproval": { "security": "deny", "ask": "off" }
```

| Scenario | Recommended setting |
|----------|---------------------|
| Learning / Local | `"security": "allowlist", "ask": "on-miss"` |
| Personal Use | `"security": "full", "ask": "always"` |
| Production | `"security": "deny", "ask": "off"` |
| Experimental | `"security": "full", "ask": "off"` |

## TTS

Text-to-speech for voice output on supported channels.

```jsonc
"tts": {
  "provider": "openai",
  "auto": "off",
  "mode": "final",
  "max_length": 1500,
  "timeout_ms": 30000,
  "openai": {
    "api_key": "env:GOCLAW_OPENAI_API_KEY",
    "api_base": "",
    "model": "gpt-4o-mini-tts",
    "voice": "alloy"
  },
  "elevenlabs": {
    "api_key": "env:ELEVENLABS_API_KEY",
    "base_url": "",
    "voice_id": "",
    "model_id": "eleven_multilingual_v2"
  },
  "edge": {
    "enabled": true,
    "voice": "en-US-MichelleNeural",
    "rate": ""
  },
  "minimax": {
    "api_key": "env:GOCLAW_MINIMAX_API_KEY",
    "group_id": "",
    "api_base": "",
    "model": "speech-02-hd",
    "voice_id": "Wise_Woman"
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | string | — | Active TTS provider: `"openai"`, `"elevenlabs"`, `"edge"`, `"minimax"` |
| `auto` | string | `"off"` | Auto-speak mode: `"off"`, `"always"`, `"inbound"`, `"tagged"` |
| `mode` | string | `"final"` | Speak `"final"` response only, or `"all"` chunks |
| `max_length` | int | `1500` | Max characters per TTS request |
| `timeout_ms` | int | `30000` | TTS request timeout (ms) |

## Sessions

Controls how conversation sessions are scoped and stored.

```jsonc
"sessions": {
  "scope": "per-sender",
  "dm_scope": "per-channel-peer",
  "main_key": "main"
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `scope` | string | `"per-sender"` | Session scope: `"per-sender"` or `"global"` |
| `dm_scope` | string | `"per-channel-peer"` | DM session granularity: `"main"`, `"per-peer"`, `"per-channel-peer"`, `"per-account-channel-peer"` |
| `main_key` | string | `"main"` | Key used for the primary/default session |

> **Note:** The storage backend (PostgreSQL or Redis) is determined by build flags and environment variables (`GOCLAW_POSTGRES_DSN`, `GOCLAW_REDIS_DSN`), not by a field in config.json.

## Cron

Scheduled tasks that trigger agent actions.

```jsonc
"cron": [
  {
    "schedule": "0 9 * * *",
    "agent_id": "assistant",
    "message": "Good morning! Summarize today's agenda.",
    "channel": "telegram",
    "target": "123456789"
  }
],
"cron_config": {
  "max_retries": 3,
  "retry_base_delay": "2s",
  "retry_max_delay": "30s",
  "default_timezone": "America/New_York"
}
```

**cron_config fields:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max_retries` | int | `3` | Retry count on failure |
| `retry_base_delay` | string | `"2s"` | Initial backoff delay |
| `retry_max_delay` | string | `"30s"` | Max backoff delay |
| `default_timezone` | string | — | IANA timezone for cron expressions (e.g. `"America/New_York"`) |

## Bindings

Routes specific channels/peers to specific agents.

```jsonc
"bindings": [
  {
    "agentId": "code-helper",
    "match": {
      "channel": "telegram",
      "accountId": "",
      "peer": { "kind": "direct", "id": "123456789" }
    }
  },
  {
    "agentId": "support-bot",
    "match": {
      "channel": "discord",
      "guildId": "987654321"
    }
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `agentId` | string | Target agent ID from `agents.list` |
| `match.channel` | string | Channel name: `"telegram"`, `"discord"`, `"slack"`, etc. |
| `match.accountId` | string | Specific account/bot ID (for multi-account setups) |
| `match.peer.kind` | string | `"direct"` (DM) or `"group"` |
| `match.peer.id` | string | User ID or group/chat ID |
| `match.guildId` | string | Discord server ID |

## Telemetry

OpenTelemetry export for traces and metrics.

```jsonc
"telemetry": {
  "enabled": false,
  "endpoint": "http://otel-collector:4317",
  "protocol": "grpc",
  "insecure": false,
  "service_name": "goclaw-gateway",
  "headers": {
    "x-api-key": "env:OTEL_API_KEY"
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `false` | Enable OTLP export |
| `endpoint` | string | — | OTLP collector endpoint |
| `protocol` | string | `"grpc"` | `"grpc"` or `"http"` |
| `insecure` | bool | `false` | Skip TLS verification |
| `service_name` | string | `"goclaw-gateway"` | Service name in traces |
| `headers` | map | — | Additional headers (supports `env:` prefix) |

## Tailscale

Expose GoClaw on a Tailscale network using tsnet.

```jsonc
"tailscale": {
  "hostname": "goclaw",
  "state_dir": "./data/tailscale",
  "ephemeral": false,
  "enable_tls": true
}
```

> **Note:** Auth key must be set via `GOCLAW_TSNET_AUTH_KEY` environment variable — it cannot be set in config.json.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `hostname` | string | — | Hostname on your Tailnet |
| `state_dir` | string | — | Directory for Tailscale state files |
| `ephemeral` | bool | `false` | Register as ephemeral node (removed on disconnect) |
| `enable_tls` | bool | `false` | Enable automatic HTTPS certs via Tailscale |

## Common Issues

| Problem | Solution |
|---------|----------|
| Config not loading | Check `GOCLAW_CONFIG` path; ensure valid JSON5 syntax |
| Hot reload not working | Verify file is saved; check fsnotify support on your OS |
| API key not found | Ensure env var is exported in current shell session |
| Quota errors | Check `gateway.quota` settings; verify `owner_ids` for bypass |
| Sandbox not starting | Ensure Docker is running; verify image name in `sandbox.image` |
| MCP server not connecting | Check `transport` type, `command`/`url`, and server logs |

## What's Next

- [Web Dashboard Tour](/dashboard-tour) — Configure visually instead of editing JSON
- [Agents Explained](/agents-explained) — Deep dive into agent configuration
- [Tools Overview](/tools-overview) — Available tools and categories



---

# Web Dashboard Tour

> A visual guide to the GoClaw management dashboard.

## Overview

The web dashboard gives you a point-and-click interface for everything you can do with config files. It's built with React and connects to GoClaw's HTTP API.

## Accessing the Dashboard

### With Docker Compose

If you started with the self-service overlay, the dashboard is already running:

```bash
docker compose -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.selfservice.yml up -d --build
```

Open `http://localhost:3000` in your browser.

### Building from Source

```bash
cd ui/web
pnpm install
pnpm dev
# Dashboard runs at http://localhost:5173
```

For production:

```bash
pnpm build
# Serve the dist/ folder with any static file server
```

## Dashboard Sidebar

The dashboard organizes features into groups in the sidebar.

### Core

#### Overview

System-wide dashboard with key metrics at a glance.

#### Chat

Test chat interface — interact with any agent directly from the browser.

#### Agents

Create, edit, and delete agents. Each agent card shows:
- Name and model
- Provider and temperature
- Tool access permissions
- Active sessions count

Click an agent to open its detail page with these tabs:
- **General** — Agent metadata and basic info
- **Config** — Model, temperature, system prompt, tool permissions; includes a **Model Fallback** section (drag-and-drop ordered list of fallback provider/model candidates triggered when the primary model is unavailable)
- **Files** — Context files (IDENTITY.md, USER.md, etc.)
- **Permissions** — Grant or deny specific users the ability to modify agent config types (`file_writer`, `heartbeat`, `cron`, `context_files`), scoped to DM, all groups, or a specific group. Includes a "Check Access" helper to test a user's effective permission before committing a rule. See [Config Permissions System](/deploy-security).
- **Shares** — Share agents across tenants
- **Links** — Configure which agents this agent can delegate to (permissions, concurrency limits, handoff rules)
- **Skills** — Agent-specific skill assignments
- **Evolution** — Agent evolution history
- **Hooks** — Quality-gate hooks for this agent
- **Instances** — Predefined agent instances (only for predefined agents)

#### Agent Teams

Create agent teams for collaborative tasks. The teams list supports card/list view toggle.


Schedule tasks via a redesigned detail page with markdown support. Fill in a name, select an agent, choose a schedule type, and write a message telling the agent what to do. Three schedule types:
- **Every** — run at a fixed interval (in seconds)
- **Cron** — run on a cron expression (e.g. `0 9 * * *`)
- **Once** — run once after a short delay

**Example:**
- **Name:** `daily-feedback`
- **Agent ID:** your assistant agent
- **Schedule Type:** Cron — `0 9 * * *`
- **Message:** "Summarize yesterday's customer feedback and email it to me."

### Data

#### Memory

Vector memory document management powered by pgvector. Store, search, and manage documents that agents can retrieve via semantic search.

#### Knowledge Graph

Knowledge graph management — view and manage entity relationships that agents build over conversations.

#### Vault

Knowledge Vault — store and manage structured documents (notes, references, guides) that agents can link and retrieve. Features:
- Document list with pagination (100 per page, Previous/Next navigation with "Showing X-Y of Z" indicator)
- Team filter dropdown alongside agent selector for multi-team document filtering
- Interactive knowledge graph visualizing document relationships (degree centrality limited for performance)
- `vault_link` tool infers document type from file path and supports `link_type` param (`wikilink` or `reference`)

#### Storage

File and storage management for agent-uploaded or user-uploaded files.

### Monitoring

#### Traces

LLM call history with:
- Token usage and cost tracking
- Request/response pairs
- Tool call sequences
- Latency metrics

#### Activity

Agent lifecycle history — shows when agents were created, updated, or deleted, with timestamps and actor info.

#### Events

Real-time event stream — watch agent activity, tool calls, and system events as they happen.

#### Usage

Usage metrics and cost tracking — monitor token consumption, API calls, and costs per agent/channel. Accessed via the **Usage** tab on the Overview page, not a separate sidebar item.

#### Logs

System logs for debugging and monitoring gateway operations.

### System

#### Packages

Manage runtime packages installed in the Docker container. The page uses a **4-tab layout**:
- **System** — apk packages (managed by the root-privileged `pkg-helper` binary via Unix socket)
- **Python** — pip packages
- **Node** — npm packages
- **GitHub** — GitHub release binaries installed via the built-in GitHub installer

All tabs show installed versions and allow install/uninstall without rebuilding the image. An updates strip at the top of the page lists available upgrades across all sources (pip, npm, GitHub). The **CLI Credentials** tab is also embedded here for admins — see [CLI Credentials](#cli-credentials) below.

#### Providers


Manage tenants in SaaS deployment mode — create tenants, assign users, configure per-tenant overrides for providers, tools, skills, and MCP servers. Only visible when running in multi-tenant mode.

## Desktop Edition

The Desktop Edition is a native app (built with Wails) that wraps the full dashboard in a standalone window. It includes additional features not available in the web-only dashboard.

### Version Display

The sidebar header shows the current app version next to the GoClaw logo in monospace font (e.g., `v1.2.3`). Click the **Lite** badge to open an edition comparison modal.

### Check for Updates

Next to the version number, there is a refresh button (↻):

- Click it to check if a newer version is available
- While checking, the button shows `...`
- If an update is found, it shows the new version number (e.g., `v1.3.0`)
- If already up to date, it shows `✓`
- If the check fails, it shows `✗`

The Lite edition supports up to 5 agents. When the limit is reached, the "New agent" button is disabled.

### Update Banner

When a new version is detected automatically (via background event), a banner appears at the top of the app:

- **Available** — shows the new version with an "Update Now" button. Click it to download and install.
- **Downloading** — shows a spinner while the update is downloading.
- **Done** — shows a "Restart Now" button. Click to apply the update.
- **Error** — shows a "Retry" button. The banner can be dismissed with the X button.

### Team Settings Modal

Open Team Settings from the Agent Teams view. The modal has three sections:

**Team Info**
- Edit team name and description
- View current status and lead agent

**Members**
- List of all team members with their roles (lead, reviewer, member)
- Add new members by searching agents in a combobox
- Remove non-lead members (hover to reveal the remove button)

**Notifications**
Toggle per-event notifications on or off:
- `dispatched` — task dispatched to an agent
- `progress` — task progress updates
- `failed` — task failed
- `completed` — task completed
- `new_task` — new task added to the team

Notification mode:
- **Direct** — all team members receive notifications
- **Leader** — only the lead agent receives notifications

### Task Detail Modal

Click any task card to open the Task Detail modal. It shows:

- **Identifier** — short task ID (monospace badge)
- **Status badge** — current status with color coding; shows an animated "Running" badge if actively executing
- **Progress bar** — shows percentage and current step (when task is in progress)
- **Metadata grid** — priority, owner agent, task type, created/updated timestamps
- **Blocked by** — list of blocking task IDs shown as amber badges
- **Description** — collapsible section with markdown rendering
- **Result** — collapsible section with markdown rendering (when task completes)
- **Attachments** — collapsible section listing files attached to the task; each entry shows file name, size, and a Download button

Footer actions:
- **Assign to** — combobox to reassign the task to another team member (only shown for non-terminal tasks)
- **Delete** — shown only for completed/failed/cancelled tasks; triggers a confirmation dialog before deletion

## Common Issues

| Problem | Solution |
|---------|----------|
| Dashboard won't load | Check that the self-service container is running: `docker compose ps` |
| Can't connect to API | Verify `GOCLAW_GATEWAY_TOKEN` is set correctly |
| Changes not reflecting | Hard refresh the browser (Ctrl+Shift+R) |

## What's Next

- [Configuration](/configuration) — Edit settings via config file instead
- [How GoClaw Works](/how-goclaw-works) — Understand the architecture
- [Agents Explained](/agents-explained) — Learn about agent types



---

# Migrating from OpenClaw

> What's different in GoClaw and how to move your setup over.

## Overview

GoClaw is the multi-tenant evolution of OpenClaw. If you've been running OpenClaw as a personal assistant, GoClaw gives you teams, delegation, encrypted credentials, tracing, and per-user isolation — while keeping the same agent concepts you already know.

## Why Migrate?

| Feature | OpenClaw | GoClaw |
|---------|----------|--------|
| Multi-tenant | No (single user) | Yes (per-user isolation) |
| Agent teams | Sub-agent delegation | Full team collaboration (shared task board, delegation) |
| Credential storage | Plain text in config | AES-256-GCM encrypted in DB |
| Memory | SQLite + QMD semantic search | PostgreSQL + SQLite (FTS5 hybrid search) |
| Tracing | No | Full LLM call traces with cost tracking |
| MCP support | Yes (via mcporter bridge) | Yes (stdio, SSE, streamable-http) |
| Custom tools | Yes (52+ built-in skills) | Yes (define via dashboard or API) |
| Code sandbox | Yes (Docker-based) | Yes (Docker-based with per-agent config) |
| Database | SQLite | PostgreSQL |
| Channels | 6 core (Telegram, Discord, Slack, Signal, iMessage, Web) + 35+ extension channels | 7 (Telegram, Discord, Slack, WhatsApp, Zalo OA, Zalo Personal, Feishu) |
| Dashboard | Basic web UI | Full management dashboard |

## Config Mapping

### Agent Configuration

| OpenClaw | GoClaw | Notes |
|----------|--------|-------|
| `ai.provider` | `agents.defaults.provider` | Same provider names |
| `ai.model` | `agents.defaults.model` | Same model identifiers |
| `ai.maxTokens` | `agents.defaults.max_tokens` | Snake case in GoClaw |
| `ai.temperature` | `agents.defaults.temperature` | Same range (0-2) |
| `commands.*` | `tools.*` | Tools replace commands |

### Channel Setup

Channels work the same conceptually but use a different config format:

**OpenClaw:**
```json
{
  "telegram": {
    "botToken": "123:ABC"
  }
}
```

**GoClaw:**
```jsonc
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "env:TELEGRAM_BOT_TOKEN"
    }
  }
}
```

Note: GoClaw keeps tokens in environment variables, not in the config file.

### Context Files

GoClaw uses context files (similar concepts to OpenClaw). The 6 core files loaded every session:

| File | Purpose |
|------|---------|
| `AGENTS.md` | Operating instructions and safety rules |
| `SOUL.md` | Agent personality and behavior |
| `IDENTITY.md` | Name, avatar, greeting |
| `USER.md` | User profile and preferences |
| `BOOTSTRAP.md` | First-run onboarding ritual (auto-deleted after completion) |

> **Note:** `TOOLS.md` is not used in GoClaw — tool configuration is managed via the Dashboard. Do not migrate this file.

Additional context files for advanced features:

| File | Purpose |
|------|---------|
| `MEMORY.md` | Long-term curated memory |
| `DELEGATION.md` | Delegation instructions for sub-agents |
| `TEAM.md` | Team coordination rules |

GoClaw supports both agent-level (shared) and per-user context file overrides. The file names listed are conventions, not requirements.

**Key difference:** OpenClaw stores these on the filesystem. GoClaw stores them in PostgreSQL with per-user scoping — each user can have their own version of context files for the same agent.

## What Migrates (and What Doesn't)

| Migrates | Doesn't Migrate |
|----------|----------------|
| Agent config (provider, model, tools) | Message history (fresh start) |
| Context files (manual upload) | Session state |
| Channel tokens (via env vars) | User profiles (recreated on first login) |

## Migration Steps

1. **Set up GoClaw** — Follow the [Installation](/installation) and [Quick Start](/quick-start) guides
2. **Map your config** — Translate your OpenClaw config using the mapping table above
3. **Move context files** — Copy your `.md` context files (excluding `TOOLS.md` — not used in GoClaw); upload via the dashboard or API
4. **Update channel tokens** — Move tokens from config to environment variables
5. **Test** — Verify your agents respond correctly through each channel

> **Security note:** GoClaw encrypts all credentials with AES-256-GCM in the database, which is more secure than OpenClaw's plaintext config approach. Once you move your API keys and tokens to GoClaw, they are stored encrypted at rest.

## What's New in GoClaw

Features you gain after migrating:

- **Agent Teams** — Multiple agents collaborating on tasks with a shared board
- **Delegation** — Agent A calls Agent B for specialized subtasks
- **Multi-Tenancy** — Each user gets isolated sessions, memory, and context
- **Traces** — See every LLM call, tool use, and token cost
- **Custom Tools** — Define your own tools without touching Go code
- **MCP Integration** — Connect external tool servers
- **Cron Jobs** — Schedule recurring agent tasks
- **Encrypted Credentials** — API keys stored with AES-256-GCM encryption

## Common Issues

| Problem | Solution |
|---------|----------|
| Context files not loading | Upload via dashboard or API; filesystem path differs from OpenClaw |
| Different response behavior | Check `max_tool_iterations` — GoClaw default (20) may differ from your OpenClaw setup |
| Missing channels | GoClaw focuses on 7 core channels; some OpenClaw channels (IRC, Signal, iMessage, LINE, etc.) aren't ported yet |

## What's Next

- [How GoClaw Works](/how-goclaw-works) — Understand the new architecture
- [Multi-Tenancy](/multi-tenancy) — Learn about per-user isolation
- [Configuration](/configuration) — Full config reference



---

# How GoClaw Works

> The architecture behind GoClaw's AI agent gateway.

## Overview

GoClaw is a gateway that sits between your users and LLM providers. It manages the full lifecycle of AI conversations: receiving messages, routing them to agents, calling LLMs, executing tools, and delivering responses back through messaging channels.

## Architecture Diagram

```mermaid
graph TD
    U[Users] --> CH[Channels<br/>Telegram / Discord / WS / ...]
    CH --> GW[Gateway<br/>7 modules · HTTP + WebSocket]
    GW --> BUS[Domain Event Bus]
    GW --> SC[Scheduler<br/>4 lanes]
    SC --> PL[8-Stage Pipeline<br/>context → history → prompt → think → act → observe → memory → summarize]
    PL --> PR[Provider Adapter System<br/>18+ LLM providers]
    PL --> TR[Tool Registry<br/>50+ built-in tools]
    PL --> SS[Store Layer<br/>PostgreSQL + SQLite · dual-DB]
    PL --> MM[3-Tier Memory<br/>episodic · semantic · dreaming]
    BUS --> CW[Consolidation Workers]
    CW --> MM
    PR --> LLM[LLM APIs<br/>OpenAI / Anthropic / ...]
```

## The 8-Stage Pipeline

In v3, every agent run goes through a **pluggable 8-stage pipeline**. The legacy two-mode gate has been removed — all agents always use this pipeline.

```
Setup (runs once)
└─ ContextStage — inject agent/user/workspace context

Iteration loop (up to 20 × per turn)
├─ ThinkStage   — build system prompt, filter tools, call LLM
├─ PruneStage   — soft/hard trim context, trigger memory flush if needed
├─ ToolStage    — execute tool calls (read-only batches in bounded parallel; others sequential)
├─ ObserveStage — process tool results, append to message buffer
└─ CheckpointStage — track iterations, check exit conditions

Finalize (runs once, survives cancellation)
└─ FinalizeStage — sanitize output, flush messages, update session metadata
```

### Stage Details

| Stage | Phase | What it does |
|-------|-------|-------------|
| **ContextStage** | Setup | Injects agent/user/workspace context; resolves per-user files |
| **ThinkStage** | Iteration | Builds system prompt (15+ sections), calls LLM, emits streaming chunks |
| **PruneStage** | Iteration | Trims context when ≥ 30% full (soft) or ≥ 50% full (hard); triggers memory flush |
| **ToolStage** | Iteration | Executes tool calls. Only registered **read-only** tools run in bounded parallel; mutating, async, MCP-bridged (`mcp_*`), `exec`/`bash`, `wait`, unknown/unregistered tools, and over-budget batches run **sequentially**. A mixed batch with any ineligible call runs entirely sequentially. `PreToolUse` hooks run before any parallel I/O, and results are processed in original assistant order |
| **ObserveStage** | Iteration | Processes tool results; handles `NO_REPLY` silent completion |
| **CheckpointStage** | Iteration | Increments counter; breaks loop on max-iter or context cancellation |
| **FinalizeStage** | Finalize | Runs 7-step output sanitization; atomically flushes messages; updates session metadata |

## Message Flow

Here's what happens when a user sends a message:

1. **Receive** — Message arrives via channel (Telegram, WebSocket, etc.)
2. **Validate** — Input guard checks for injection patterns; message truncated at 32 KB
3. **Route** — Scheduler assigns the message to an agent based on channel bindings
4. **Queue** — Per-session queue manages concurrency (1 per DM session by default; up to 3 for groups)
5. **Build Context** — ContextStage injects identity, workspace, per-user files
6. **Pipeline Loop** — 8-stage pipeline runs up to 20 iterations per turn
7. **Sanitize** — FinalizeStage cleans output (removes thinking tags, garbled XML, duplicates)
8. **Deliver** — Response sent back through the originating channel

## Scheduler Lanes

GoClaw uses a lane-based scheduler to manage concurrency:

| Lane | Concurrency | Purpose |
|------|:-----------:|---------|
| `main` | 30 | Channel messages and WebSocket requests |
| `subagent` | 50 | Spawned subagent tasks |
| `team` | 100 | Agent-to-agent delegation |
| `cron` | 30 | Scheduled cron jobs |

Each lane has its own semaphore. This prevents cron jobs from starving user messages, and keeps delegation from overwhelming the system.

> Concurrency limits are configurable via env vars: `GOCLAW_LANE_MAIN`, `GOCLAW_LANE_SUBAGENT`, `GOCLAW_LANE_TEAM`, `GOCLAW_LANE_CRON`.

## Components

| Component | What It Does |
|-----------|-------------|
| **Gateway** | HTTP + WebSocket server; decomposed into 7 modules (deps, http_wiring, events, lifecycle, tools_wiring, methods, router) |
| **Domain Event Bus** | Typed event publishing with worker pool, dedup, and retry — drives consolidation workers |
| **Provider Adapter System** | Manages 18+ LLM providers; Anthropic native, OpenAI-compatible, ACP (JSON-RPC 2.0 stdio — Claude Code, Codex, Gemini CLI) |
| **Hooks Dispatcher** | Wired into `PipelineDeps.HookDispatcher`; 7 lifecycle events (sync/async), SSRF-hardened HTTP + Command handlers, audit logging, circuit breaker |
| **Audio / TTS Manager** | `internal/audio/` unified manager: ElevenLabs (streaming), OpenAI, Edge, MiniMax TTS providers; voice LRU cache (1 000 tenants, 1 h TTL); per-agent voice/model via `other_config` JSONB |
| **Tool Registry** | 50+ built-in tools with policy-based access control (extensible via MCP and custom tools) |
| **Store Layer** | Dual-DB: PostgreSQL (`pgx/v5`) for production + SQLite (`modernc.org/sqlite`) for desktop; shared base/ dialect |
| **3-Tier Memory** | Episodic (recent facts) → Semantic (abstracted summaries) → Dreaming (novel synthesis); driven by consolidation workers |
| **Orchestration Module** | `BatchQueue[T]` generic for result aggregation; ChildResult capture; media conversion helpers |
| **Consolidation Workers** | Episodic, semantic, dreaming, dedup workers consume events from DomainEventBus |
| **Channel Managers** | Telegram, Discord, WhatsApp (native via Baileys bridge), Zalo, Feishu adapters |
| **Scheduler** | 4-lane concurrency with per-session queues |

## v3 System Overview

GoClaw v3 ships five new systems — each has its own dedicated page:

| System | What it adds |
|--------|-------------|
| [Knowledge Vault](/knowledge-vault) | Wikilinks semantic mesh, BM25 + vector hybrid search, L0 auto-injection into prompts |
| [3-Tier Memory](../core-concepts/memory-system.md) | Episodic → Semantic → Dreaming consolidation pipeline driven by DomainEventBus |
| [Agent Evolution](/agent-evolution) | Tracks tool/retrieval patterns; auto-suggests and applies prompt/tool adaptations |
| [Mode Prompt System](/model-steering) | Switchable prompt modes (PromptFull vs PromptMinimal) with per-agent overrides |
| [Multi-Tenant v3](/multi-tenancy) | Compound user ID scoping across all 22+ store interfaces; vault grants; skill grants |

## Common Issues

| Problem | Solution |
|---------|----------|
| Agent not responding | Check scheduler lane concurrency; verify provider API key |
| Slow responses | Large context window + many tools = slower LLM calls; reduce tool count or context |
| Tool calls failing | Check `tools.exec_approval` level; review deny patterns for shell commands |

## What's Next

- [Agents Explained](/agents-explained) — Deep dive into agent types and context files
- [Tools Overview](/tools-overview) — The full tool catalog
- [Sessions and History](../core-concepts/sessions-and-history.md) — How conversations persist



---

# Agents Explained

> What agents are, how they work, and the difference between open and predefined.

## Overview

An agent in GoClaw is an LLM with a personality, tools, and memory. You configure what it knows (context files), what it can do (tools), and which LLM powers it (provider + model). Each agent runs in its own pipeline, handling conversations independently.

## What Makes an Agent

An agent combines four things:

1. **LLM** — The language model that generates responses (provider + model)
2. **Context Files** — Markdown files that define personality, knowledge, and rules
3. **Tools** — What the agent can do (search, code, browse, etc.)
4. **Memory** — Long-term facts persisted across conversations

## How the Agent Pipeline Works

Every turn runs through the **8-stage pipeline** (context → think → prune → act → observe → checkpoint → memory → finalize). There is no legacy "think → act → observe" shortcut — all agents always use the full pipeline.

```mermaid
graph LR
    CTX[ContextStage<br/>inject workspace] --> TH[ThinkStage<br/>call LLM]
    TH --> PR[PruneStage<br/>trim context]
    PR --> AC{Tools needed?}
    AC -->|Yes| TO[ToolStage<br/>execute tools]
    TO --> OB[ObserveStage<br/>process results]
    OB --> TH
    AC -->|No| CP[CheckpointStage<br/>exit check]
    CP --> FI[FinalizeStage<br/>sanitize + flush]
```

The loop repeats up to 20 iterations per turn. GoClaw detects tool loop patterns: a **warning** is raised after 3 identical consecutive calls, and the loop is **force-stopped** after 5 identical no-progress calls. `exec`/`bash` tools and MCP bridge tools (`mcp_*` prefix) are treated as **neutral** — they neither reset nor increment the read-only streak.

## Agent Types

GoClaw has two agent types with different sharing models:

### Open Agents

Each user gets their own complete copy of all context files. Every user can fully customize the agent's personality, instructions, and behavior — the agent adapts independently per user. Files persist across sessions.

- All 7 context files are per-user (including MEMORY.md)
- Users can read and edit any file (SOUL.md, IDENTITY.md, AGENTS.md, USER.md, etc.)
- New users start from agent-level templates, then diverge as they customize
- Best for: personal assistants, individual workflows, rapid prototyping and testing (each user can tweak personality without affecting others)

### Predefined Agents

The agent has a fixed, shared personality that no user can change through chat. Each user only gets personal profile files. Think of it as a company chatbot — same brand voice for everyone, but it knows who you are.

- 4 context files shared across all users (SOUL, IDENTITY, AGENTS, TOOLS) — read-only from chat
- 3 files per-user (USER.md, USER_PREDEFINED.md, BOOTSTRAP.md)
- Shared files can only be edited from the management dashboard (not through conversations)
- Best for: team bots, branded assistants, customer support where consistent personality matters

| Aspect | Open | Predefined |
|--------|------|-----------|
| Agent-level files | Templates (copied to each user) | 4 shared (SOUL, IDENTITY, AGENTS, TOOLS) |
| Per-user files | All 7 | 3 (USER.md, USER_PREDEFINED.md, BOOTSTRAP.md) |
| User can edit via chat | All files | USER.md only |
| Personality | Diverges per user | Fixed, same for everyone |
| Use case | Personal assistant | Team/company bot |

## Context Files

Every agent has up to 7 context files that shape its behavior:

| File | Purpose | Example Content |
|------|---------|----------------|
| `AGENTS.md` | Operating instructions, memory rules, safety guidelines | "Always save important facts to memory..." |
| `SOUL.md` | Personality and tone | "You are a friendly coding mentor..." |
| `IDENTITY.md` | Name, avatar, greeting | "Name: CodeBot, Emoji: 🤖" |
| `TOOLS.md` | Tool usage guidance *(loaded from filesystem only — not DB-routed, excluded from context file interceptor)* | "Use web_search for current events..." |
| `USER.md` | User profile, timezone, preferences | "Timezone: Asia/Saigon, Language: Vietnamese" |
| `USER_PREDEFINED.md` | Predefined agent user profile *(predefined agents only, replaces USER.md at agent level)* | "Team member info, shared preferences..." |
| `BOOTSTRAP.md` | First-run ritual (auto-deleted after completion) | "Introduce yourself and learn about the user..." |

Plus `MEMORY.md` — persistent notes auto-updated by the agent (routed to the memory system).

Context files are Markdown. Edit them via the web dashboard, API, or let the agent modify them during conversations.

### Truncation

Large context files are automatically truncated to fit the LLM's context window:
- Per-file limit: 20,000 characters
- Total budget: 24,000 characters
- Truncation keeps 70% from the start and 20% from the end

## Agent Lifecycle

```mermaid
graph LR
    C[Create] --> CF[Configure<br/>Context + Tools]
    CF --> S[Summon<br/>First message]
    S --> CH[Chat<br/>Conversations]
    CH --> E[Edit<br/>Refine over time]
    E --> CH
```

1. **Create** — Define agent name, provider, model via dashboard or API
2. **Configure** — Write context files, set tool permissions
3. **Summon** — Send the first message; bootstrap files are seeded automatically
4. **Chat** — Ongoing conversations with memory and tool use
5. **Edit** — Refine context files, adjust settings as needed

## Agent Access Control

When a user tries to access an agent, GoClaw checks in order:

1. Does the agent exist?
2. Is it the default agent? → Allow (everyone can use the default)
3. Is the user the owner? → Allow with owner role
4. Does the user have a share record? → Allow with shared role

Roles: `admin` (full control), `operator` (use + edit), `viewer` (read-only)

## Agent Routing

The `bindings` config maps channels to agents:

```jsonc
{
  "bindings": {
    "telegram": {
      "direct": {
        "386246614": "code-helper"  // This user talks to code-helper
      },
      "group": {
        "-100123456": "team-bot"    // This group uses team-bot
      }
    }
  }
}
```

Unbound conversations go to the default agent.

## Common Issues

| Problem | Solution |
|---------|----------|
| Agent ignores instructions | Check SOUL.md and AGENTS.md content; ensure context files aren't truncated |
| "Agent not found" error | Verify agent exists in dashboard; check `agents.list` in config |
| Context files not updating | For predefined agents, shared files update for all users; per-user files need per-user edits |

## Agent Status

An agent can be in one of four states:

| Status | Meaning |
|--------|---------|
| `active` | Agent is running and accepting conversations |
| `inactive` | Agent is disabled; conversations are rejected |
| `summoning` | Agent is being initialized for the first time |
| `summon_failed` | Initialization failed; check provider config and model availability |

## Self-Evolution

Predefined agents with `self_evolve` enabled can update their own `SOUL.md` during conversations. This allows the agent's tone and style to evolve over time based on interactions. The update is applied at the agent level and affects all users. Other shared files (IDENTITY.md, AGENTS.md) remain protected and can only be edited from the dashboard.

In v3, evolution goes further: agents with `self_evolution_metrics` enabled track tool usage and retrieval patterns, and agents with `self_evolution_suggestions` enabled can auto-apply prompt/tool adaptations. See [Agent Evolution](/agent-evolution) for details.

## System Prompt Modes

GoClaw builds the system prompt in two modes:

- **PromptFull** — used for main agent runs. Includes all 19+ sections: skills, MCP tools, memory recall, user identity, messaging, silent-reply rules, and full context files.
- **PromptMinimal** — used for subagents (spawned via `spawn` tool) and cron jobs. Stripped-down context with only the essential sections (tooling, safety, workspace, bootstrap files). Reduces startup time and token usage for lightweight operations.

For **group chat** sessions, the system prompt additionally injects group-chat context — participant and group information — so the agent knows it is one of several speakers and can address participants appropriately.

## NO_REPLY Suppression

Agents can signal `NO_REPLY` in their final response to suppress sending a visible reply to the user. GoClaw detects this string during response finalization and skips message delivery entirely — a "silent completion." This is used internally by the memory flush agent when it has nothing to store, and can be used in custom agent instructions for similar silent-operation scenarios.

## Mid-Loop Compaction

During long-running tasks, GoClaw triggers context compaction **mid-loop** — not just after a run completes. When prompt tokens exceed 75% of the context window (configurable via `MaxHistoryShare`, default `0.75`), the agent summarizes the first ~70% of in-memory messages, keeping the last ~30%, then continues iterating. This prevents context overflow without aborting the current task.

## Auto-Summarization and Memory Flush

After each conversation run, GoClaw evaluates whether to compact session history:

- **Trigger**: history exceeds 50 messages OR estimated tokens exceed 75% of context window
- **Memory flush first** (synchronous): agent writes important facts to `memory/YYYY-MM-DD.md` files before history is truncated
- **Summarize** (background): LLM summarizes older messages; history is truncated to the last 4 messages; summary is saved for the next session

In v3, the [3-Tier Memory](../core-concepts/memory-system.md) system adds async consolidation on top: episodic workers extract facts, semantic workers abstract them, and dreaming workers synthesize novel insights — all driven by the DomainEventBus.

## Identity Anchoring

Predefined agents have built-in protection against social engineering. If a user tries to convince the agent to ignore its SOUL.md or act outside its defined identity, the agent is designed to resist. Shared identity files are injected into the system prompt at a level that takes precedence over user instructions.

## Subagent Enhancements

When an agent spawns subagents via the `spawn` tool, the following capabilities apply:

### Per-Edition Rate Limiting

The `Edition` struct enforces two tenant-scoped limits on subagent usage:

| Field | Description |
|-------|-------------|
| `MaxSubagentConcurrent` | Max number of subagents running in parallel per tenant |
| `MaxSubagentDepth` | Max nesting depth — prevents unbounded delegation chains |

These are set per edition and enforced at spawn time.

### Token Cost Tracking

Each subagent accumulates per-call input and output token counts. Totals are persisted in the database and included in announce messages, giving the parent agent full visibility into delegation cost.

### WaitAll Orchestration

`spawn(action=wait, timeout=N)` blocks the parent until all previously spawned children complete. This enables fan-out/fan-in patterns without polling.

### Auto-Retry with Backoff

Configurable `MaxRetries` (default `2`) with linear backoff handles transient LLM failures automatically. The parent is only notified on permanent failure after all retries are exhausted.

### SubagentDenyAlways

Subagents cannot spawn nested subagents — the `team_tasks` tool is blocked in subagent context. All delegation must originate from a top-level agent.

### Producer-Consumer Announce Queue

Staggered subagent results are queued and merged into a single LLM run announcement on the parent side. This reduces unnecessary parent wake-ups when multiple subagents finish at different times.

## What's Next

- [Sessions and History](../core-concepts/sessions-and-history.md) — How conversations persist
- [Tools Overview](/tools-overview) — What tools agents can use
- [Memory System](../core-concepts/memory-system.md) — Long-term memory and search



---

# Sessions and History

> How GoClaw tracks conversations and manages message history.

## Overview

A session is a conversation thread between a user and an agent on a specific channel. GoClaw stores message history in PostgreSQL, automatically compacts long conversations, and manages concurrency so agents don't trip over each other.

## Session Keys

Every session has a unique key that identifies the user, agent, channel, and chat type:

```
agent:{agentId}:{channel}:{kind}:{chatId}
```

| Type | Key Format | Example |
|------|-----------|---------|
| DM | `agent:default:telegram:direct:386246614` | Private chat |
| Group | `agent:default:telegram:group:-100123456` | Group chat |
| Topic | `agent:default:telegram:group:-100123456:topic:99` | Forum topic |
| Thread | `agent:default:telegram:direct:386246614:thread:5` | Threaded reply |
| Subagent | `agent:default:subagent:my-task` | Spawned subtask |
| Cron | `agent:default:cron:reminder-job` | Scheduled job |

This key format means the same user talking to the same agent on Telegram and Discord has two separate sessions with independent history.

> **Session Metadata:** Each session tracks additional fields alongside the key: `label` (display name), `channel`, `model`, `provider`, `spawned_by` (parent session ID for subagents), `spawn_depth`, `input_tokens`, `output_tokens`, `compaction_count`, `context_window`, `last_prompt_tokens`, and `last_message_count`. These fields are queryable for analytics and debugging purposes.
>
> `last_prompt_tokens` and `last_message_count` are written by FinalizeStage at the end of every run and are read by the session-list query to display accurate token and message counts in the UI. Older sessions that pre-date this field fall back to an octet-length estimate (`octet_length(messages) / 4 + 12000`) so the UI always has a number to display.

## Message Storage

Messages are stored as JSONB in PostgreSQL with a write-behind cache:

1. **Read** — On first access, load from DB into memory cache
2. **Write** — Messages accumulate in memory during a turn
3. **Flush** — At the end of the turn, all messages write to DB atomically
4. **List** — Session listing always reads from DB (not cache)

This approach minimizes DB writes while ensuring durability.

## History Pipeline

Before sending history to the LLM, GoClaw runs a 3-stage pipeline:

### 1. Limit Turns

Keep only the last N user turns (and their associated assistant/tool messages). Older turns are dropped to stay within the context window.

### 2. Prune Context

Tool results can be large. GoClaw trims them in two passes:

| Condition | Action |
|-----------|--------|
| Token ratio ≥ 0.3 | **Soft trim**: Tool results exceeding 4,000 chars → keep first 1,500 + last 1,500 |
| Token ratio ≥ 0.5 | **Hard clear**: Replace entire tool result with `[Old tool result content cleared]` |

Protected messages (never pruned): last 3 assistant messages. System message(s) and the first user message form a stable prefix that is never pruned.

### 3. Sanitize

Repair broken tool_use/tool_result pairs that were split by truncation. The LLM expects matched pairs — orphaned tool calls cause errors.

## V3 Pipeline Architecture

In v3 (enabled via `pipeline_enabled` feature flag), the agent loop is restructured into an **8-stage pipeline** that replaces the v2 monolithic `runLoop()`. The session flow maps to these stages:

| Stage | What happens |
|-------|-------------|
| **ContextStage** (once) | Inject context values, resolve per-user workspace, ensure per-user files |
| **ThinkStage** | Build system prompt, run history pipeline, filter tools (PolicyEngine), call LLM |
| **PruneStage** | Estimate token ratio; soft trim at ≥30%, hard clear at ≥50%; trigger memory flush if compaction threshold hit |
| **ToolStage** | Execute tool calls — single tool sequential, multiple tools parallel with result sorting |
| **ObserveStage** | Process tool results, handle `NO_REPLY`, append assistant message |
| **CheckpointStage** | Increment iteration counter; break on max iterations or cancellation |
| **FinalizeStage** (once) | Sanitize output, flush messages atomically, update session metadata, emit run event |

**Memory consolidation in v3**: The PruneStage triggers memory flush **synchronously during the iteration loop** (not only at end-of-session). This means long-running turns extract episodic facts before history is pruned, rather than waiting for the post-turn compaction phase. The same 75% context window threshold applies.

Both v2 and v3 expose identical external behavior; the pipeline difference is internal architecture.

## Auto-Compaction

Long conversations trigger automatic compaction:

**Triggers:**
- More than 50 messages in the session, OR
- History exceeds 75% of the agent's context window

**What happens:**

```mermaid
graph LR
    T[Trigger<br/>50+ msgs or 75% ctx] --> MF[Memory Flush<br/>Extract facts → memory]
    MF --> SUM[Summarize<br/>Condense history]
    SUM --> INJ[Inject<br/>Summary replaces old msgs]
```

1. **Memory flush** (synchronous, 90s timeout) — Important facts are extracted and saved to the memory system
2. **Summarize** (background, 120s timeout) — Old messages are condensed into a summary
3. **Inject** — The summary replaces old messages; at least 4 messages (or 30% of total, whichever is greater) are kept verbatim

A per-session lock prevents concurrent compaction. If a second compaction triggers while one is running, it's skipped.

### Mid-Loop Compaction

GoClaw may also compact history **during a long agent turn** if the context exceeds the threshold mid-loop. The same 75% summarization logic applies. This is transparent to the agent — it continues running with the compacted history injected.

### Compaction Overflow Recovery

If the context budget is still exceeded **after** a compaction sweep (for example, when the system prompt and tool schemas alone nearly fill the window), GoClaw performs a secondary recovery sweep before returning an error. This overflow recovery path (introduced in PR #958) caps the number of retry attempts at one and surfaces an error to the caller only if the context is still over budget after the recovery sweep. In practice this prevents hard context-overflow failures for agents with very large tool schemas or system prompts.

## Concurrency

| Chat Type | Max Concurrent | Notes |
|-----------|:-----------:|-------|
| DM | 1 | Single-threaded — messages queue up |
| Group | 1 (configurable) | Serial by default; can be increased via `ScheduleOpts.MaxConcurrent` |

Group sessions may reduce concurrency when context usage is high.

> **Configuring concurrency:** Both DM and Group default to serial processing (`MaxConcurrent: 1`). Higher values (e.g. 3) can be set for team members or agent links via `ScheduleOpts.MaxConcurrent`.

### Queue Modes

| Mode | Behavior |
|------|----------|
| `queue` | FIFO — messages processed in order |
| `followup` | New message merges with the queued one |
| `interrupt` | Cancel current task, process new message |

Queue capacity is 10 by default. When full, the oldest message is dropped (drop policy: `old`). The default debounce window is 800ms — rapid messages within this window are merged before processing.

### User Controls

- `/stop` — Cancel the oldest running task
- `/stopall` — Cancel all tasks and drain the queue

## Common Issues

| Problem | Solution |
|---------|----------|
| Agent "forgot" earlier messages | History was compacted; check memory for extracted facts |
| Slow responses in groups | Reduce group concurrency or context window size |
| Duplicate responses | Check queue mode; `queue` mode prevents this |

## What's Next

- [Memory System](../core-concepts/memory-system.md) — How long-term memory works
- [Tools Overview](/tools-overview) — Available tools for agents
- [Multi-Tenancy](/multi-tenancy) — Per-user session isolation



---

# Tools Overview

> The 50+ built-in tools agents can use, organized by category.

## Overview

Tools are how agents interact with the world beyond generating text. An agent can search the web, read files, run code, query memory, collaborate via agent teams, and more. GoClaw includes 50+ built-in tools (extensible via MCP and custom tools per agent) across 14 categories.

## Tool Categories

| Category | Tools | What They Do |
|----------|-------|-------------|
| **Filesystem** (`group:fs`) | read_file, write_file, edit, list_files, search, glob, send_file | Read, write, edit, and search files in the agent workspace; `send_file` delivers an existing file as an attachment |
| **Runtime** (`group:runtime`) | exec, credentialed_exec | Run shell commands; execute CLI tools with injected credentials |
| **Web** (`group:web`) | web_search, web_fetch | Search the web (Exa, Tavily, Brave, DuckDuckGo) and fetch pages |
| **Memory** (`group:memory`) | memory_search, memory_get, memory_expand | Query long-term memory (hybrid vector + FTS search); expand full episodic content by ID (L2 retrieval) |
| **Knowledge** (`group:knowledge`) | vault_search, knowledge_graph_search, skill_search | Unified vault/memory/knowledge-graph search; search entities and relationships; discover skills |
| **Vault** (`group:vault`) | vault_search, vault_read | Search and read vault documents; governed by the `group:vault` policy group |
| **Sessions** (`group:sessions`) | sessions_list, sessions_history, sessions_send, session_status, spawn | Manage conversation sessions; spawn subagents |
| **Teams** (`group:teams`) | team_tasks, team_message | Collaborate with agent teams via shared task board and mailbox |
| **Automation** (`group:automation`) | cron, datetime, wait | Schedule recurring jobs; get current date/time; pause execution between tool calls (`wait` — see below) |
| **Messaging** (`group:messaging`) | message, create_forum_topic | Send messages; create Telegram forum topics |
| **Media Generation** (`group:media_gen`) | create_image, create_image_byteplus, create_audio, create_video, create_video_byteplus, tts, image_generation | Generate images, audio, video, and text-to-speech; `image_generation` is a native tool for Codex/OpenAI-compat (tri-level gate: provider capability + `other_config.allow_image_generation` + header `x-goclaw-no-image-gen`) — see [Media Generation](/advanced/media-generation) |
| **Browser** | browser | Navigate web pages, take screenshots, interact with elements |
| **Media Reading** (`group:media_read`) | read_image, read_audio, read_document, read_video | Analyze images (file, attachment, or URL), transcribe audio, extract documents (PDF, DOCX, images; optional local-first extraction via pdftotext/pandoc), analyze video (file or URL) — see [Media Generation](/advanced/media-generation) |
| **Skills** (`group:skills`) | use_skill, publish_skill | Invoke and publish skills |
| **Workspace** | workspace_dir | Resolve workspace directory for team/user context |
| **AI** | openai_compat_call | Call OpenAI-compatible endpoints with custom request formats |

### web_search Providers

`web_search` supports four providers, tried in order:

| Provider | Notes |
|----------|-------|
| **Exa** | Requires `EXA_API_KEY` |
| **Tavily** | Requires `TAVILY_API_KEY` |
| **Brave** | Requires `BRAVE_API_KEY` |
| **DuckDuckGo** | Free fallback — used last if no API keys for the others |

> **Breaking change (v3.2+):** `config.json5 tools.web.*` has been removed. Configuration is now tenant-only. Existing keys are auto-migrated on first startup (data hook 055).

Configure `web_search` via the dashboard (**Config → Tools → Web Search**) or the API:

```bash
# Set provider order via tenant-config API
PUT /v1/tools/builtin/web_search/tenant-config
{
  "provider_order": ["exa", "tavily", "brave", "duckduckgo"],
  "brave": { "enabled": true, "max_results": 5 },
  "exa": { "enabled": false }
}
```

DuckDuckGo requires no API key and is always available as the final fallback — it cannot be disabled.

### v3 Memory & Vault Tools

**Memory layers** (v3 two-tier retrieval):

| Tool | Layer | Description |
|------|-------|-------------|
| `memory_search` | L1 | BM25 + vector hybrid search; returns abstracts and scores |
| `memory_expand` | L2 | Load full episodic summary by ID from `memory_search` results |

Use `memory_search` first to discover relevant episodic IDs, then `memory_expand` for the complete content. This saves tokens when only a few entries are relevant.

**Vault linking** is now handled automatically by the enrichment pipeline. See [Knowledge Vault](../advanced/knowledge-vault.md).

> `vault_link` and `vault_backlinks` have been removed. Explicit wikilink creation and backlink tracing are no longer needed — the enrichment pipeline manages document relationships automatically.

**BytePlus media tools** (`create_image_byteplus`, `create_video_byteplus`) are available when a `byteplus` provider is configured. Both use async job polling: image generation via Seedream returns a URL once the job completes; video generation via Seedance polls `/text-to-video-pro/status/{id}` for the result.

> Additional tools like `mcp_tool_search` and channel-specific tools are registered dynamically. Tool groups can be referenced with `group:` prefix in allow/deny lists (e.g., `group:fs`).

> **Delegation note**: The `delegate` tool has been removed. Delegation is now handled exclusively via agent teams: leads create tasks on the shared board (`team_tasks`) and delegate to member agents via `spawn`. See [Agent Teams](#agent-teams) for the current model.

### `wait` — Pause Between Tool Calls

The built-in `wait` tool suspends the current agent's tool sequence for a bounded duration. It is useful for rate-limit spacing, polling intervals, or waiting for an external async job to finish before the next tool call.

| Field | Type | Notes |
|------|------|-------|
| `timeMs` | integer (required) | Duration in milliseconds. Default bounds: `100` ≤ `timeMs` ≤ `300000` (5 minutes). |
| `reason` | string (optional) | Free-form reason logged with the wait result; useful in traces and debugging. |

The minimum and maximum bounds can be tuned per-deployment via the tool's runtime config; defaults are 100 ms and 300 000 ms.

> **Not the same as `spawn(action=wait)`:** `wait` is a top-level built-in tool that pauses **the calling agent** for `timeMs` milliseconds. The `spawn(action=wait)` pattern (also called **WaitAll**, see below) is a delegation primitive that blocks the parent **until previously spawned subagents finish**. Use `wait` for time-based pauses; use `spawn(action=wait)` for fan-out/fan-in delegation.

### `read_document` Local-First Extraction

`read_document` analyzes PDF, DOCX, and images of documents. By default it sends the file to a cloud vision provider. You can opt into **local-first extraction** that runs `pdftotext` (PDF) and `pandoc --sandbox` (DOCX) on the host *before* any cloud call, configured via the `document_parser` block:

```json
{
  "local_first": false,
  "max_pages": 200,
  "timeout_sec": 30,
  "min_text_len": 16
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `local_first` | `false` | Enable local extraction (opt-in). Requires `pdftotext`/`pandoc` on PATH — present in the `full` Docker variant or builds with `ENABLE_FULL_SKILLS=true` |
| `max_pages` | `200` | PDF page limit; passed to `pdftotext -l` |
| `timeout_sec` | `30` | Per-extraction timeout; the process group is killed on timeout |
| `min_text_len` | `16` | Minimum characters (after trim) for a successful extraction; shorter output triggers cloud fallback |

Config is captured at startup (not hot-reloaded), but binary availability is re-checked per call so a runtime install is detected without a restart. Any extraction miss — disabled, unsupported MIME, missing binary, timeout, or too-little text (e.g. a scanned image-only PDF) — transparently falls back to the cloud vision chain with no caller-visible difference.

## Tool Execution Flow

When an agent calls a tool:

```mermaid
graph LR
    A[Agent calls tool] --> C[Inject context<br/>channel, user, session]
    C --> R[Rate limit check]
    R --> E[Execute tool]
    E --> S[Scrub credentials]
    S --> L[Return to LLM]
```

1. **Context injection** — Channel, chat ID, user ID, and sandbox key are injected
2. **Rate limit** — Per-session rate limiter prevents abuse
3. **Execute** — The tool runs and produces output
4. **Scrub** — Credentials and sensitive data are removed from output
5. **Return** — Clean result goes back to the LLM for the next iteration

### Parallel vs Sequential Scheduling

When the LLM emits **multiple** tool calls in one turn, GoClaw decides whether to run them concurrently. Only registered **read-only** tools are eligible for bounded-parallel raw I/O. Mutating, async, MCP-bridged (`mcp_*`), `exec`/`bash`, `wait`, unknown/unregistered tools, and batches that exceed the tool-call budget run **sequentially**. A mixed batch containing any ineligible call runs entirely sequentially. `PreToolUse` hooks run before any parallel execution, and results are always processed in the original assistant order. This eligibility is driven by each tool's capability metadata (the side-effect class), so custom tools default to sequential unless registered read-only.

## Tool Profiles

Profiles control which tools an agent can access:

| Profile | Available Tools |
|---------|----------------|
| `full` | All registered tools (no restriction) |
| `coding` | `group:fs`, `group:runtime`, `group:sessions`, `group:memory`, `group:web`, `group:knowledge`, `group:media_gen`, `group:media_read`, `group:skills` |
| `messaging` | `group:messaging`, `group:web`, `group:sessions`, `group:media_read`, `skill_search` |
| `minimal` | `session_status` only |

Set the profile in agent config:

```jsonc
{
  "agents": {
    "defaults": {
      "tools_profile": "full"
    },
    "list": {
      "readonly-bot": {
        "tools_profile": "messaging"
      }
    }
  }
}
```

## Tool Aliases

GoClaw registers aliases so agents can reference tools by alternative names. This enables compatibility with Claude Code skills and legacy tool names:

| Alias | Maps to |
|-------|---------|
| `Read` | `read_file` |
| `Write` | `write_file` |
| `Edit` | `edit` |
| `Bash` | `exec` |
| `WebFetch` | `web_fetch` |
| `WebSearch` | `web_search` |
| `edit_file` | `edit` |

Aliases appear as one-line descriptions in the system prompt. They are not separate tools — calling an alias invokes the underlying tool.

### Deterministic Ordering

All tool names, aliases, and MCP tool descriptions are sorted lexicographically before being included in the system prompt. This ensures identical prompt prefixes across requests, maximizing LLM prompt cache hit rates (Anthropic and OpenAI cache by exact prefix match).

## Policy Engine

Beyond profiles, a 7-step policy engine gives fine-grained control:

1. Global profile (base set)
2. Provider-specific profile override
3. Global allow list (intersection)
4. Provider-specific allow override
5. Per-agent allow list
6. Per-agent per-provider allow
7. Group-level allow

After allow lists, **deny lists** remove tools, then **alsoAllow** adds them back (union). Tool groups (`group:fs`, `group:runtime`, etc.) can be used in any allow/deny list.

### Example: Restrict an Agent

```jsonc
{
  "agents": {
    "list": {
      "safe-bot": {
        "tools_profile": "full",
        "tools_deny": ["exec", "write_file"],
        "tools_also_allow": ["read_file"]
      }
    }
  }
}
```

## Filesystem Interceptors

Two special interceptors route file operations to the database:

### Context File Interceptor

When an agent reads/writes context files (SOUL.md, IDENTITY.md, AGENTS.md, USER.md, USER_PREDEFINED.md, BOOTSTRAP.md, HEARTBEAT.md), the operation is routed to the `user_context_files` table instead of the filesystem. TOOLS.md is explicitly excluded from routing. This enables per-user customization and multi-tenant isolation.

### Memory Interceptor

Writes to `MEMORY.md`, `memory.md`, or `memory/*` are routed to the `memory_documents` table, automatically chunked and embedded for search.

## Shell Safety

### `credentialed_exec` — Secure CLI Credential Injection

The `credentialed_exec` tool runs CLI tools (gh, gcloud, aws, kubectl, terraform) with credentials auto-injected as environment variables directly into the child process — no shell, no credential leakage. Security layers: path verification (blocks `./gh` spoofing), shell operator blocking (`;`, `|`, `&&`), per-binary deny patterns (e.g., block `auth\s+`), and output scrubbing.

A registered secure-CLI binary is gated even when reached through the plain `exec` tool: if the agent has no grant for it, `exec` refuses with `Binary "<name>" requires a secure CLI grant. Ask admin to grant access to this agent.` rather than running it with the host environment. The gate also unwraps shell wrappers (`sh -c`, `bash -c`, `env …`) up to 3 levels deep and fails closed if the grant lookup is unavailable.

**Windows environment inheritance:** On Windows, credentialed exec inherits system environment variables required by native CLIs — `SYSTEMROOT`, `SYSTEMDRIVE`, `WINDIR`, `COMSPEC`, `PATHEXT`, `TEMP`, `TMP`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`, and `PROGRAMFILES`. These are non-secret runtime variables that most Win32 programs need to function. Credential values are still injected separately and scrubbed from output.

### `exec` — Shell Safety

The `exec` tool enforces 15 deny groups — all enabled by default:

| Group | Blocked Patterns |
|-------|-----------------|
| `destructive_ops` | `rm -rf`, `del /f`, `mkfs`, `dd`, `shutdown`, fork bombs |
| `data_exfiltration` | `curl\|sh`, `wget\|sh`, DNS exfil, `/dev/tcp/`, curl POST/PUT, localhost access |
| `reverse_shell` | `nc`/`ncat`/`netcat`, `socat`, `openssl s_client`, `telnet`, python/perl/ruby/node sockets, `mkfifo` |
| `code_injection` | `eval $`, `base64 -d\|sh` |
| `privilege_escalation` | `sudo`, `su -`, `nsenter`, `unshare`, `mount`, `capsh`/`setcap` |
| `dangerous_paths` | `chmod` on `/`, `chown` on `/`, `chmod +x` on `/tmp` `/var/tmp` `/dev/shm` |
| `env_injection` | `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, `LD_LIBRARY_PATH`, `GIT_EXTERNAL_DIFF`, `BASH_ENV` |
| `container_escape` | `docker.sock`, `/proc/sys/`, `/sys/` |
| `crypto_mining` | `xmrig`, `cpuminer`, `stratum+tcp://` |
| `filter_bypass` | `sed /e`, `sort --compress-program`, `git --upload-pack`, `rg --pre=`, `man --html=` |
| `network_recon` | `nmap`/`masscan`/`zmap`, `ssh/scp@`, `chisel`/`ngrok`/`cloudflared` tunneling |
| `package_install` | `pip install`, `npm install`, `apk add`, `yarn add`, `pnpm add` |
| `persistence` | `crontab`, writes to `.bashrc`/`.profile`/`.zshrc` |
| `process_control` | `kill -9`, `killall`, `pkill` |
| `env_dump` | `env`, `printenv`, `/proc/*/environ`, `echo $GOCLAW_*` secrets |

### Execution Timeout

The host `exec` tool aborts a command that runs too long. The timeout is a per-tool builtin setting named `timeout_seconds`, stored under the `exec` tool's settings:

```json
{
  "timeout_seconds": 120
}
```

| Property | Value |
|----------|-------|
| Default / fallback | 60 seconds |
| Minimum | 1 second |
| Maximum | 3600 seconds (1 hour) — values above are clamped down |
| Invalid / missing value | Falls back to 60 seconds |

Set it from the dashboard (**Config → Tools → Built-in Tools → exec**) or via the builtin-tool settings API. A tenant-level setting overrides the global one. When the command exceeds the timeout, the process group is killed (SIGTERM, then SIGKILL after a 3-second grace period) and the tool returns `command timed out after <duration>`.

> This setting governs only the host `exec` tool. It is **distinct** from the per-custom-tool `timeout_seconds` and the sandbox `sandbox_config.timeout_sec` — see [Custom Tools](/custom-tools).

### Command Keyword Allowlist

When an agent runs a credentialed CLI (via `credentialed_exec` / the secure-CLI gate), the per-binary `deny_args` patterns scan argument values for dangerous vocabulary. This can produce false positives: legitimate product or security content passed as an argument (for example, a post body or message that mentions a flagged word) gets blocked even though it is plain data, not a command.

The command keyword allowlist solves this without weakening `deny_args`. Configure scoped rules via `tools.commandKeywordAllowlist`:

```json
{
  "tools": {
    "commandKeywordAllowlist": [
      {
        "id": "social-post-content",
        "command": "zernio",
        "subcommands": ["posts:create"],
        "args": ["--text"],
        "keywords": ["install", "exec"],
        "reason": "marketing copy may mention these words as content",
        "enabled": true
      }
    ]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Identifier for the rule (used in audit logs) |
| `command` | string | Binary the rule applies to (case- and path-normalized) |
| `subcommands` | string[] | Optional subcommands that must match (e.g. `"posts:create"`) |
| `args` | string[] | Argument flags whose values are scanned (e.g. `"--text"`) |
| `argPositions` | int[] | Optional 0-based positional args (after the matched subcommand) |
| `keywords` | string[] | Vocabulary that is allowed inside the matched argument values |
| `reason` | string | Free-form note recorded in the audit log |
| `enabled` | bool | Defaults to enabled when omitted |

How it works: before the `deny_args` check runs, the allowlisted keyword is masked (replaced with a placeholder) **only inside the matched argument value**. The deny scan no longer trips on that word, but command-path deny patterns and shell-operator blocking stay fully active — the allowlist never disables `deny_args`, it only exempts specific flagged vocabulary inside specific content arguments. Each match is recorded in a `security.command_keyword_allowlist` audit log with the binary, subcommand, argument, keyword, rule ID, and agent/tenant context.

This config is **reloaded at runtime** via the `TopicConfigChanged` bus — no gateway restart required.

### Global shellDenyGroups (Runtime-Reloadable)

In addition to per-agent overrides, admins can enable or disable deny groups **globally** via `config.tools.shellDenyGroups` (`map[string]bool`):

```json
{
  "tools": {
    "shellDenyGroups": {
      "package_install": true,
      "env_dump": true
    }
  }
}
```

This config is **reloaded at runtime** via the `TopicConfigChanged` bus — no gateway restart required. Per-agent overrides (`shell_deny_groups` in agent config) take precedence per-key over the global setting.

See also: [deployment/security-hardening](/deployment/security-hardening).

### Per-Agent Override

Admins can disable specific groups per agent:

```jsonc
{
  "agents": {
    "list": {
      "dev-bot": {
        "shell_deny_groups": {
          "package_install": false,
          "process_control": false
        }
      }
    }
  }
}
```

### Hardened Exemption Matching

When a shell command matches a deny pattern, GoClaw checks path exemptions (e.g., `.goclaw/skills-store/`). The exemption logic is strict:

- **All-or-nothing** — Every field in the command that triggers the deny pattern must be individually covered by an exemption. A single unexempted field blocks the entire command
- **Path traversal blocked** — Fields containing `..` are never exempt, preventing exemption escape via `../../etc/passwd`
- **Quote stripping** — Surrounding quotes (`"`, `'`) are stripped before matching, since LLMs often quote paths

This prevents pipe/comment bypass attacks like `cat /app/data/skills-store/tool.py | cat /app/data/secret` — the second field matches deny but has no exemption, so the entire command is blocked.

The `tools.exec_approval` setting adds an additional approval layer (`full`, `light`, or `none`).

## spawn — Subagent Orchestration

The `spawn` tool (part of `group:sessions`) creates and runs subagents. Key capabilities:

| Capability | Detail |
|-----------|--------|
| **WaitAll** | `spawn(action=wait, timeout=N)` blocks the parent until all previously spawned children complete. Useful for fan-out/fan-in patterns. Distinct from the built-in `wait` tool above, which pauses for a fixed duration regardless of subagent state. |
| **Auto-retry** | Configurable `MaxRetries` (default `2`) with linear backoff on LLM failures. Transient errors are retried automatically. |
| **Token tracking** | Each subagent accumulates per-call input/output token counts. Totals are included in announce messages so the parent can account for cost. |
| **SubagentDenyAlways** | Subagents cannot spawn nested subagents — the `team_tasks` tool is blocked in subagent context. Prevents unbounded delegation chains. |
| **Producer-consumer announce queue** | Staggered subagent results are queued and merged into a single LLM run announcement on the parent side, reducing unnecessary wake-ups. |

```jsonc
// Example: fan-out then wait
spawn(action=start, prompt="Summarize part A")
spawn(action=start, prompt="Summarize part B")
spawn(action=wait, timeout=120)  // blocks until both finish
```

## Session Tool Security

Session tools (`sessions_list`, `sessions_history`, `sessions_send`) are hardened with fail-closed validation:

- **Phantom session prevention**: session lookups use read-only Get, never GetOrCreate, preventing accidental session creation
- **Ownership validation**: session keys must match the calling agent's prefix (`agent:{agentID}:*`)
- **Fail-closed design**: missing agentID or invalid ownership immediately returns an error — never falls through
- **Self-send blocking**: the `message` tool blocks agents from sending to their own current channel/chat, preventing duplicate media delivery

## Adaptive Tool Timing

GoClaw tracks execution time per tool in each session. If a tool call takes longer than 2× its historical maximum (with at least 3 prior samples), a slow-tool notification is emitted. The default threshold for tools without history is 120 seconds.

## Custom Tools & MCP

Beyond built-in tools, you can extend agents with:

- **Custom Tools** — Define tools via the dashboard or API with input schemas and handlers
- **MCP Servers** — Connect Model Context Protocol servers for dynamic tool registration

See [Custom Tools](/custom-tools) and [MCP Integration](/mcp-integration) for details.

## Common Issues

| Problem | Solution |
|---------|----------|
| Agent can't use a tool | Check tools_profile and deny lists; verify tool exists for the profile |
| Shell command blocked | Review deny patterns; adjust `exec_approval` level |
| Tool results too large | GoClaw auto-trims results >4,000 chars; consider more specific queries |

### Browser Automation

The `browser` tool lets agents control a headless browser (Chrome/Chromium). It must be enabled in config (`tools.browser.enabled: true`).

**Safety mechanisms:**

| Parameter | Default | Config Key | Description |
|-----------|---------|------------|-------------|
| Action timeout | 30 s | `tools.browser.action_timeout_ms` | Max time per browser action |
| Idle timeout | 10 min | `tools.browser.idle_timeout_ms` | Auto-close pages after idle (0 = disabled, negative = disabled) |
| Max pages | 5 | `tools.browser.max_pages` | Max open pages per tenant |

All parameters are optional — defaults apply when not configured.

## What's Next

- [Memory System](../core-concepts/memory-system.md) — How long-term memory and search work
- [Multi-Tenancy](/multi-tenancy) — Per-user tool access and isolation
- [Custom Tools](/custom-tools) — Build your own tools



---

# Memory System

> How agents remember facts across conversations using a 3-tier architecture with automatic consolidation.

## Overview

GoClaw v3 gives agents long-term memory that persists across sessions. Memory is organized into three tiers — working memory, episodic memory, and semantic memory — each serving a distinct purpose in the recall lifecycle. A background consolidation pipeline automatically promotes memories across tiers without any agent action required.

## 3-Tier Memory Architecture

```mermaid
graph TD
    L0["L0 — Working Memory<br/>(MEMORY.md, memory/*.md)<br/>FTS + Vector, per-agent/user"]
    L1["L1 — Episodic Memory<br/>(episodic_summaries table)<br/>Session summaries, 90-day TTL"]
    L2["L2 — Semantic Memory<br/>(Knowledge Graph)<br/>Entities + relations, temporal"]

    L0 -->|"dreaming_worker promotes<br/>after ≥5 unpromoted episodes"| L0
    L1 -->|"episodic_worker creates<br/>on session.completed"| L1
    L1 -->|"semantic_worker extracts<br/>KG facts on episodic.created"| L2
    L1 -->|"dreaming_worker synthesizes<br/>into long-term MEMORY.md"| L0
```

| Tier | Storage | Content | Lifespan | Search |
|------|---------|---------|---------|--------|
| **L0 Working** | `memory_documents` + `memory_embeddings` | Agent-curated facts, auto-flush notes, dreaming output | Permanent until deleted | FTS + vector hybrid |
| **L1 Episodic** | `episodic_summaries` | Session summaries, key topics, L0 abstracts (plus approved [passive channel facts](#passive-channel-memory-extraction)) | 90 days (configurable) | FTS + HNSW vector |
| **L2 Semantic** | Knowledge Graph tables | Entities, relations, temporal validity windows | Permanent | Graph traversal |

### Tier Boundaries and Promotion Rules

- **Session → L1**: When a session completes, `episodic_worker` summarizes it into an `episodic_summaries` row. Uses the compaction summary if available; otherwise calls the LLM with the session messages (30-second timeout, max 1,024 tokens).
- **L1 → L2**: After each episodic summary is created, `semantic_worker` extracts KG entities and relations from the summary text and ingests them into the knowledge graph with temporal validity (`valid_from` = now).
- **L1 → L0**: When ≥5 unpromoted episodic entries accumulate for an agent/user pair, `dreaming_worker` synthesizes them into a long-term Markdown document written to `_system/dreaming/YYYYMMDD-consolidated.md` and marks the episodes as promoted.

## How It Works

```mermaid
graph LR
    W[Agent writes<br/>MEMORY.md or memory/*] --> CH[Chunk<br/>Split by paragraphs]
    CH --> EM[Embed<br/>Generate vectors]
    EM --> DB[(PostgreSQL<br/>memory_documents +<br/>memory_embeddings)]
    Q[Agent queries memory] --> HS[Hybrid Search<br/>FTS + Vector]
    HS --> DB
    DB --> R[Ranked Results]
```

### Writing Memory (L0)

When an agent writes to `MEMORY.md` or files in `memory/*`, GoClaw:

1. **Intercepts** the file write (routed to DB, not filesystem)
2. **Chunks** the text by paragraph boundaries (max 1,000 chars per chunk)
3. **Embeds** each chunk using the configured embedding provider
4. **Stores** both the text (with tsvector for FTS) and the embedding vector

> Only `.md` files are chunked and embedded. Non-markdown files (e.g., `.json`, `.txt`) are stored in the DB but are **not indexed or searchable** via `memory_search`.

### Searching Memory

When an agent calls `memory_search`, GoClaw runs a hybrid search combining FTS and vector similarity:

| Method | Weight | How It Works |
|--------|:------:|-------------|
| Full-text search (FTS) | 0.3 | PostgreSQL `tsvector` + `plainto_tsquery('simple')` — good for exact terms |
| Vector similarity | 0.7 | `pgvector` cosine distance — good for semantic meaning |

**Weighted merge algorithm**: FTS scores are normalized to 0..1 range (vector scores are already 0..1), then combined as `(FTS × 0.3) + (vector × 0.7)`. When only one channel returns results, its scores are used directly (effective weight normalized to 1.0).

Results are then ranked:

1. Per-user boost: results scoped to the current user get a 1.2× multiplier
2. Deduplication: if both user-scoped and global results match, user copy wins
3. Final sort by weighted score

**Embedding cache**: The `embedding_cache` table is wired into the `IndexDocument` hot path. Repeated re-indexing of unchanged content reuses cached embeddings instead of calling the embedding provider, reducing latency and API cost.

**Fallback behavior**: if per-user search returns no results, GoClaw falls back to the global memory pool. This applies to both `MEMORY.md` and `memory/*.md` files.

### Knowledge Graph Search

`knowledge_graph_search` complements `memory_search` for relationship and entity queries. While `memory_search` retrieves factual text chunks, `knowledge_graph_search` traverses entity relationships — useful for questions like "what projects is Alice working on?" or "which tools does this agent use?"

## Consolidation Workers

The consolidation pipeline runs entirely in the background, event-driven via the internal event bus. Workers are registered once at startup via `consolidation.Register()` and subscribe to domain events.

```mermaid
sequenceDiagram
    participant S as Session
    participant EW as episodic_worker
    participant SW as semantic_worker
    participant DW as dedup_worker
    participant DR as dreaming_worker
    participant L0A as l0_abstract

    S->>EW: session.completed event
    EW->>EW: LLM summarize (or use compaction summary)
    EW->>EW: l0_abstract (extractive, no LLM)
    EW-->>SW: episodic.created event
    EW-->>DR: episodic.created event
    SW->>SW: Extract KG entities + relations
    SW-->>DW: entity.upserted event
    DW->>DW: Merge/flag duplicate entities
    DR->>DR: Count unpromoted (debounce 10min, threshold 5)
    DR->>DR: LLM synthesis → _system/dreaming/YYYYMMDD.md
    DR->>DR: Mark episodes as promoted
```

### `episodic_worker`

**Trigger**: `session.completed` event
**Action**: Creates an `episodic_summaries` row for each completed session.

- Checks `source_id` (`sessionKey:compactionCount`) to prevent duplicate summaries.
- Uses the compaction summary if present; otherwise reads session messages and calls the LLM with a 30-second timeout.
- Generates an **L0 abstract** — a 1-sentence extractive summary (~200 runes) for fast context injection, with no LLM call.
- Extracts `key_topics` as capitalized proper noun phrases for FTS boosting.
- Sets `expires_at` to 90 days from creation (configurable via `episodic_ttl_days`).
- Publishes `episodic.created` for downstream workers.

### `semantic_worker`

**Trigger**: `episodic.created` event
**Action**: Extracts knowledge graph entities and relations from the episodic summary text.

- Calls the `EntityExtractor` (KG extraction, not a raw LLM call).
- Stamps extracted entities with `valid_from = now()` and scopes them to `agent_id` + `user_id`.
- Ingests into the KG store via `IngestExtraction`.
- Publishes `entity.upserted` for the dedup worker.
- Failures are non-fatal — extraction errors are logged as warnings and do not block the pipeline.

### `dedup_worker`

**Trigger**: `entity.upserted` event
**Action**: Detects and merges duplicate KG entities after each extraction batch.

- Calls `kgStore.DedupAfterExtraction` with the newly upserted entity IDs.
- Merges semantically equivalent entities and flags ambiguous ones.
- Terminal worker — no downstream events.
- Failures are non-fatal.

### `dreaming_worker`

**Trigger**: `episodic.created` event
**Action**: Consolidates unpromoted episodic summaries into long-term L0 memory.

- **Debounce**: skips if already ran within the last 10 minutes for the same agent/user pair.
- **Threshold**: requires ≥5 unpromoted episodic entries before running (configurable).
- Fetches up to 10 unpromoted entries and calls the LLM to synthesize long-term facts (max 4,096 tokens).
- Synthesis prompt extracts: user preferences, project facts, recurring patterns, key decisions.
- Writes output to `_system/dreaming/YYYYMMDD-consolidated.md` in L0 memory and indexes it for search.
- Marks all processed entries as `promoted_at = now()`.

### `l0_abstract`

Not a standalone worker — a utility called by `episodic_worker` to produce a brief L0 abstract from a full summary. Uses an extractive sentence-splitting approach (no LLM call, no latency). The abstract is stored in the `l0_abstract` column of `episodic_summaries` and used by the auto-injector.

**Periodic pruning**: A goroutine runs every 6 hours to delete episodic summaries past their `expires_at` date.

## Passive Channel Memory Extraction

Most memory comes from a session completing. **Passive channel memory extraction** adds a second, opt-in source: it periodically mines the buffered messages from a channel (Telegram, Discord, etc.) for durable facts — without anyone running a session — and feeds approved facts into the same L1 → L2 pipeline.

It is **off by default** and **privacy-first**: in v1 it only looks at **group** conversations, candidates are **queued for review** rather than auto-written, and **raw message bodies are never stored** — only redacted summaries, topics/entities, confidence, and counts.

### How it works

A background worker periodically reads the existing tenant-scoped `channel_pending_messages` group buffers, redacts sensitive content, and asks the **background LLM provider** for durable fact candidates. Candidates land in a review queue (`channel_memory_extraction_runs` / `_items`). Extraction can run by:

- **manual trigger** — runs even when `enabled` is `false`;
- **message cap** — the group buffer reaches `message_cap`;
- **interval** — the configured `interval_minutes` has elapsed.

When an item is **approved**, GoClaw writes an `episodic_summaries` row with `source_type='channel'` and a deterministic `source_id`. From there the existing [consolidation workers](#consolidation-workers) (`semantic_worker`, `dreaming_worker`, …) promote it to the knowledge graph and long-term memory like any other episodic entry. **Reject/delete** prevents a later write; delete also removes the linked episodic row (KG nodes already promoted are not synchronously deleted in v1).

### Configuration

Enable it per channel instance under `config.passive_memory` (see [Channel Instances](/channel-instances#passive-channel-memory-passive_memory)):

| Field | Default | Clamp / Notes |
|---|---|---|
| `enabled` | `false` | Disabled by default. |
| `review_mode` | `true` | Candidates are queued for review, not auto-written. |
| `interval_minutes` | `360` | Clamped to 15–10080. |
| `message_cap` | `100` | Clamped to 10–1000. |
| `retention_hours` | `168` | Clamped to 1–720. |
| `allowed_types` | people, projects, decisions, todos, preferences, events | Invalid entries dropped; empty list → full default set. |
| `exclude_users` | — | ≤50 entries, ≤255 chars each. |
| `exclude_patterns` | — | ≤20 valid regexes, ≤255 chars each. |
| `min_messages` | `5` | Clamped to 2–100. |
| `group_only` | `true` | **Forced `true` in v1** (always coerced). |

> Extraction tables store metadata, summaries, topics/entities, confidence, status, and redaction counts — **not** raw message bodies.

## Auto-Injector

The **auto-injector** automatically surfaces relevant memories into the agent's system prompt at the start of each turn, before the LLM call.

- **Interface**: `AutoInjector.Inject(ctx, InjectParams)` — called once per turn in the context build stage.
- **How it works**: Checks the user's message against the memory index. Returns a formatted section for the system prompt (empty string if nothing is relevant). Budget: max ~200 tokens of L0 abstracts.
- **Default parameters** (overridable per agent in `agents.settings` JSONB):

| Parameter | Default | Description |
|-----------|---------|-------------|
| `auto_inject_enabled` | `true` | Enable/disable auto-injection |
| `auto_inject_threshold` | `0.3` | Minimum relevance score (0–1) for a memory to be injected |
| `auto_inject_max_tokens` | `200` | Token budget for injected memory section |
| `episodic_ttl_days` | `90` | Days before episodic summaries expire |
| `consolidation_enabled` | `true` | Enable/disable consolidation pipeline |

The injector returns an `InjectResult` with observability fields: `MatchCount`, `Injected`, and `TopScore`.

## Trivial Filter

The **trivial filter** prevents low-value messages from triggering memory injection, reducing unnecessary database lookups.

`isTrivialMessage(msg)` returns `true` when the message contains fewer than 3 meaningful words after removing stopwords (greetings like "hi", "ok", "thanks", acknowledgments, single-word responses). Trivial messages skip the auto-injector entirely.

## Memory vs Sessions

| Aspect | Memory | Sessions |
|--------|--------|----------|
| Lifespan | Permanent (until deleted) | Per-conversation |
| Content | Facts, preferences, knowledge | Message history |
| Search | Hybrid (FTS + vector) | Sequential access |
| Scope | Per-user per-agent | Per-session key |

Memory is for things worth remembering forever. Sessions are for conversation flow.

## Auto Memory Flush

During [auto-compaction](../core-concepts/sessions-and-history.md), GoClaw extracts important facts from the conversation and saves them to memory before summarizing the history.

- **Trigger**: >50 messages OR >85% context window (either condition triggers compaction)
- **Process**: Synchronous flush, max 5 iterations, 90-second timeout
- **What's saved**: Key facts, user preferences, decisions, action items
- **Order**: Memory flush runs **before** history compaction — facts are persisted first, then history is summarized and truncated

Memory flush only triggers as part of auto-compaction — not independently. The flush runs synchronously inside the compaction lock and appends extracted facts to `memory/YYYY-MM-DD.md`. This means agents gradually build up knowledge about each user without explicit "remember this" commands.

### Extractive Memory Fallback

If the LLM-based flush fails (timeout, provider error, bad output), GoClaw falls back to **extractive memory**: a keyword-based pass over the conversation that extracts key facts without an LLM call. This ensures memories are saved even when the LLM is unavailable, at the cost of lower quality extraction.

## Memory File Variants

GoClaw recognizes four memory file types:

| File | Role | Notes |
|---|---|---|
| `MEMORY.md` | Curated memory (Markdown) | Primary file; auto-included in system prompt |
| `memory.md` | Fallback for `MEMORY.md` | Checked if `MEMORY.md` is absent |
| `MEMORY.json` | Machine-readable index | Deprecated — no longer recommended |
| Inline (`memory/*.md`) | Date-stamped files from auto-flush | Indexed and searchable; e.g. `memory/2026-03-23.md` |

All `.md` variants are chunked, embedded, and searchable via `memory_search`. `MEMORY.json` is stored but not indexed.

## Requirements

Memory requires:

- **PostgreSQL 15+** with the `pgvector` extension
- An **embedding provider** configured (OpenAI, Anthropic, or compatible)
- `memory: true` in agent config (enabled by default)

Set `memory: false` in an agent's config to disable memory entirely for that agent — no reads, no writes, no auto-flush.

## Team Memory Sharing

When agents work as a [team](#agent-teams), team members can **read the leader's memory** as a fallback:

- **`memory_search`**: Searches the member's own memory first. If no results, automatically falls back to the leader's memory and merges results.
- **`memory_get`**: Reads from the member's own memory first. If the file isn't found, falls back to the leader's memory.
- **Writes are blocked**: Team members cannot save or modify memory files — only the team leader can write memory. Members attempting to write receive: *"memory is read-only for team members"*.

This allows knowledge sharing within a team without duplication. The leader accumulates shared knowledge, and all members benefit from it automatically.

## Common Issues

| Problem | Solution |
|---------|----------|
| Memory search returns nothing | Check that pgvector extension is installed; verify embedding provider is configured |
| Agent forgets things | Ensure `memory: true` in config; check if auto-compaction is running |
| Irrelevant memories surfacing | Memory accumulates over time; consider clearing old memories via the API |
| Episodic summaries not created | Verify consolidation workers are registered at startup; check event bus is running |
| Dreaming worker never promotes | Check that ≥5 sessions have completed for the agent/user pair; review debounce logs |
| Passive channel memory not extracting | `passive_memory.enabled` is off, the conversation is not a group (group-only in v1), or the buffer has fewer than `min_messages`. Approved items also require review unless `review_mode` is disabled. |

## What's Next

- [Multi-Tenancy](/multi-tenancy) — Per-user memory isolation
- [Sessions and History](../core-concepts/sessions-and-history.md) — How conversation history works
- [Context Pruning](/context-pruning) — How pruning integrates with the consolidation pipeline
- [Agents Explained](/agents-explained) — Agent types and context files



---

# Multi-Tenancy

> How GoClaw isolates data — from a single user to a full SaaS platform with many customers.

## Overview

GoClaw supports two deployment modes: **personal** (single-tenant, one user or small team) and **SaaS** (multi-tenant, many isolated customers). Both modes use the same binary — you choose the mode by how you configure and connect to GoClaw. In either mode, every piece of data is scoped so users never see each other's agents, sessions, or memory.


### SaaS Mode (Multi-Tenant)

Integrate GoClaw as the AI engine behind your SaaS application. Your app handles auth, billing, and UI. GoClaw handles AI. Each tenant is fully isolated — agents, sessions, memory, teams, LLM providers, MCP servers, and files.

```mermaid
graph TB
    subgraph "Your App (Tenant A)"
        BEa[Backend A]
    end
    subgraph "Your App (Tenant B)"
        BEb[Backend B]
    end
    subgraph "GoClaw Gateway"
        TI{Tenant Isolation Layer}
        AG[Agent Loop + Tools + Memory]
        DB[(PostgreSQL WHERE tenant_id = N)]
    end
    BEa -->|API Key A + user_id| TI
    BEb -->|API Key B + user_id| TI
    TI -->|ctx with tenant_id| AG
    AG --> DB
```

**How it works:**
- Each tenant's backend connects using a **tenant-bound API key** — GoClaw auto-scopes all data
- The **Tenant Isolation Layer** resolves `tenant_id` from credentials and injects it into Go context
- Every SQL query enforces `WHERE tenant_id = $N` — fail-closed, no cross-tenant leakage

**When to use:** SaaS products with AI features, multi-client platforms, white-label AI solutions.

---

## Tenant Setup

Setting up a new tenant takes three steps: create the tenant, add users, then create an API key for your backend.

```mermaid
sequenceDiagram
    participant Admin as System Admin
    participant GC as GoClaw API

    Admin->>GC: tenants.create {name: "Acme Corp", slug: "acme"}
    GC-->>Admin: {id: "tenant-uuid", slug: "acme"}

    Admin->>GC: tenants.users.add {tenant_id, user_id: "user-123", role: "admin"}

    Admin->>GC: api_keys.create {tenant_id, scopes: ["operator.read", "operator.write"]}
    GC-->>Admin: {key: "goclaw_sk_abc123..."}

    Note over Admin: Store API key in your backend's config/secrets
```

Each tenant gets isolated: agents, sessions, teams, memory, LLM providers, MCP servers, and skills. A tenant-bound API key automatically scopes every request — no extra headers needed beyond `X-GoClaw-User-Id`.

**Scaling up from personal mode:** When you need multiple isolated environments (clients, departments, projects), create additional tenants. Multi-tenant features activate automatically — no migration needed.

---

## Tenant Resolution

GoClaw determines the tenant from the credentials used to connect:

| Credential | Tenant Resolution | Use Case |
|------------|-------------------|----------|
| **Gateway token** + owner user ID | All tenants (cross-tenant) | System administration |
| **Gateway token** + non-owner user ID | User's tenant membership | Dashboard users |
| **API key** (tenant-bound) | Auto from key's `tenant_id` | Normal SaaS integration |
| **API key** (system-level) + `X-GoClaw-Tenant-Id` | Header value (UUID or slug) | Cross-tenant admin tools |
| **Browser pairing** | Paired tenant | Dashboard operators |
| **No credentials** | Master tenant | Dev / single-user mode |

**Owner IDs:** Configured via `GOCLAW_OWNER_IDS` (comma-separated). Only owners get cross-tenant access with the gateway token. Default: `system`.

**Recommended for SaaS:** Use tenant-bound API keys. The tenant is resolved automatically — your backend doesn't need to send a tenant header.

---

## HTTP API Headers

All HTTP endpoints accept these standard headers:

| Header | Required | Description |
|--------|:---:|-------------|
| `Authorization` | Yes | `Bearer <api-key-or-gateway-token>` |
| `X-GoClaw-User-Id` | Yes | Your app's user ID (max 255 chars). Scopes sessions and per-user data |
| `X-GoClaw-Tenant-Id` | No | Tenant UUID or slug. Only needed for system-level keys |
| `X-GoClaw-Agent-Id` | No | Target agent ID (alternative to `model` field) |
| `Accept-Language` | No | Locale for error messages: `en`, `vi`, `zh` |

### Chat (OpenAI-compatible)

```bash
curl -X POST https://goclaw.example.com/v1/chat/completions \
  -H "Authorization: Bearer goclaw_sk_abc123..." \
  -H "X-GoClaw-User-Id: user-456" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:my-agent",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

The API key is bound to tenant "Acme Corp" — the response only includes data from that tenant.

### System admin (cross-tenant)

```bash
# List agents for a specific tenant (requires gateway token + owner user ID)
curl https://goclaw.example.com/v1/agents \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "X-GoClaw-Tenant-Id: acme" \
  -H "X-GoClaw-User-Id: system"
```

---

## Connection Types

All connections pass through the Tenant Isolation Layer before reaching the agent engine:

| Connection | Auth Method | Tenant Resolution | Isolation |
|------------|-------------|-------------------|-----------|
| **HTTP API** | `Bearer` token | Auto from API key's `tenant_id` | Per-request |
| **WebSocket** | Token on `connect` | Auto from API key's `tenant_id` | Per-session |
| **Chat Channels** | None (webhook/WS) | Baked into channel instance DB config | Per-instance |
| **Dashboard** | Gateway token or browser pairing | User's tenant membership | Per-session |

**Chat channels** (Telegram, Discord, Zalo, Slack, WhatsApp, Feishu) connect directly to GoClaw. Tenant isolation is baked into the channel instance at registration time — no API key needed per message.

---

## API Key Scopes

API keys use scopes to control access level:

| Scope | Role | Permissions |
|-------|------|-------------|
| `operator.admin` | admin | Full access — agents, config, API keys, tenants |
| `operator.read` | viewer | Read-only — list agents, sessions, configs |
| `operator.write` | operator | Read + write — chat, create sessions, manage agents |
| `operator.approvals` | operator | Approve/reject execution requests |
| `operator.provision` | operator | Create tenants and manage tenant users |
| `operator.pairing` | operator | Manage device pairing |

A key with `["operator.read", "operator.write"]` gets `operator` role. A key with `["operator.admin"]` gets `admin` role.

---

## Per-Tenant Overrides

Tenants can customize their environment without affecting other tenants:

| Feature | Scope | How |
|---------|-------|-----|
| **LLM Providers** | Per-tenant | Each tenant registers own API keys and models |
| **Builtin Tools** | Per-tenant | Enable/disable via `builtin_tool_tenant_configs` |
| **Skills** | Per-tenant | Enable/disable via `skill_tenant_configs` |
| **MCP Servers** | Per-tenant + per-user | Server-level shared, user-level credential overrides |

**MCP credential tiers:**
- **Server-level** (shared): configured in the MCP server form, used by all users in the tenant
- **User-level** (override): configured via "My Credentials" — per-user API keys merged at runtime (user wins on key collision)

When `require_user_credentials` is enabled on an MCP server, users without personal credentials cannot use that server.

---

## Security Model

| Concern | How GoClaw Handles It |
|---------|-----------------------|
| API key exposure | Keys stay in your backend — never sent to the browser |
| Cross-tenant data access | All SQL queries include `WHERE tenant_id = $N` (fail-closed) |
| Event leakage | Server-side 3-mode filter: unscoped admin, scoped admin, regular user |
| Missing tenant context | Fail-closed: returns error, never returns unfiltered data |
| API key storage | Keys hashed with SHA-256 at rest; only prefix shown in UI |
| Tenant impersonation | Tenant resolved from API key binding, not client headers |
| Privilege escalation | Role derived from key scopes, not client claims |
| Gateway token abuse | Only configured owner IDs get cross-tenant; others are tenant-scoped |
| Tenant access revocation | Proactive WS event + `TENANT_ACCESS_REVOKED` error forces immediate UI logout |
| File URL security | HMAC-signed file tokens (`?ft=`) — gateway token never appears in URLs |

---

## What Gets Isolated

In personal mode, every piece of data is scoped by `user_id`:

| Data | Table | Isolation |
|------|-------|-----------|
| Context files | `user_context_files` | Per-user per-agent |
| Agent profiles | `user_agent_profiles` | Per-user per-agent |
| Agent overrides | `user_agent_overrides` | Per-user provider/model |
| Sessions | `sessions` | Per-user per-agent per-channel |
| Memory | `memory_documents` | Per-user per-agent |
| Traces | `traces` | Per-user filterable |
| MCP grants | `mcp_user_grants` | Per-user MCP server access |

In SaaS mode, the above user-level isolation applies within each tenant, and **40+ tables** carry a `tenant_id` with NOT NULL constraint to enforce tenant boundaries. `api_keys.tenant_id` is nullable — NULL means a system-level cross-tenant key.

**Master tenant** (UUID `0193a5b0-7000-7000-8000-000000000001`): All legacy and default data. Single-tenant deployments use this exclusively.

### v3 Tenant-Scoped Stores

v3 adds four new stores — all enforce tenant isolation:

| Store | Purpose | Tenant Scoping |
|-------|---------|----------------|
| `EvolutionMetrics` | Track agent improvement signals | `WHERE tenant_id = $N` |
| `EvolutionSuggestions` | Store LLM-generated optimization suggestions | `WHERE tenant_id = $N` |
| `Vault` | Persistent structured data for agents | `WHERE tenant_id = $N` |
| `Episodic` | Episodic memory (full session summaries) | `WHERE tenant_id = $N` |
| `AgentLink` | Delegation links between agents | `WHERE tenant_id = $N` |

---

## Edition Model

GoClaw ships with two editions that cap resource usage per deployment. Editions are set at startup and apply globally (not per-tenant).

| Feature | Standard | Lite |
|---------|:--------:|:----:|
| Max agents | unlimited | 5 |
| Max teams | unlimited | 1 |
| Max team members | unlimited | 5 |
| Max subagent concurrent | unlimited | 2 |
| Max subagent depth | unlimited | 1 |
| Knowledge graph | ✓ | ✗ |
| RBAC | ✓ | ✗ |
| Team full mode | ✓ | ✗ |
| Vector search | ✓ | ✗ |

**`MaxSubagentConcurrent`** — caps how many subagents can run in parallel per request. In Lite edition this is 2, preventing resource spikes on self-hosted deployments.

**`MaxSubagentDepth`** — caps the spawn recursion depth. In Lite edition, subagents cannot themselves spawn further subagents (depth=1).

---

## i18n (Per-Request Localization)

GoClaw supports per-request localization for error messages and system nudges. The locale is resolved from the `Accept-Language` HTTP header (or `locale` WebSocket field). Supported values: `en`, `vi`, `zh`.

Agent nudges (budget warnings, skill evolution suggestions, team progress prompts) are all i18n-aware via `i18n.T(locale, msgKey)`. Budget and skill nudges are automatically delivered in the requesting user's language.

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GOCLAW_OWNER_IDS` | `system` | Comma-separated user IDs with cross-tenant access |
| `GOCLAW_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `GOCLAW_CONFIG` | `config.json5` | Path to gateway config file |

---

## Common Issues

| Problem | Solution |
|---------|----------|
| Users seeing each other's data | Verify `X-GoClaw-User-Id` is set correctly per request |
| No user isolation | Ensure you're sending the user ID header; without it, all requests share a session |
| Agent not accessible | Check `agent_shares` table; user needs an explicit share for non-default agents |
| Wrong tenant data returned | Use tenant-bound API keys — don't rely on the `X-GoClaw-Tenant-Id` header unless using a system-level key |
| Cross-tenant access denied | Check that the user ID is in `GOCLAW_OWNER_IDS` for admin operations |

---

## What's Next

- [How GoClaw Works](how-goclaw-works.md) — Architecture overview
- [Sessions and History](sessions-and-history.md) — Per-user session management
- [Agents Explained](agents-explained.md) — Agent types and access control
- [API Keys](../advanced/api-keys-rbac.md) — Creating and managing API keys



---

# Creating Agents

> Set up a new AI agent via CLI, dashboard, or managed API.

## Overview

You can create agents three ways: interactively with the CLI, through the web dashboard, or programmatically via HTTP. Each agent needs a unique key, display name, LLM provider, and model. Optional fields include context window, max tool iterations, workspace location, and tools configuration.

## Agent Status Lifecycle

When a predefined agent with a description is created, it goes through these statuses:

| Status | Description |
|--------|-------------|
| `summoning` | LLM is generating personality files (SOUL.md, IDENTITY.md, USER_PREDEFINED.md) |
| `active` | Agent is ready to use |
| `summon_failed` | LLM generation failed; template files are used as fallback |

Open agents are created with `active` status immediately — no summoning step.

## CLI: Interactive Wizard

The easiest way to get started:

```bash
./goclaw agent add
```

This launches a step-by-step wizard. You'll be asked for:

1. **Agent name** — used to generate a normalized ID (lowercase, hyphens). Example: "coder" → `coder`
2. **Display name** — shown in dashboards. Can be "Code Assistant" for the same `coder` agent
3. **Provider** — LLM provider (optional: inherit from defaults, or choose OpenRouter, Anthropic, OpenAI, Groq, DeepSeek, Gemini, Mistral)
4. **Model** — model name (optional: inherit from defaults, or specify like `claude-sonnet-4-6`)
5. **Workspace directory** — where context files live. Defaults to `~/.goclaw/workspace-{agent-id}`

Once created, restart the gateway to activate the agent:

```bash
./goclaw agent list          # see your agents
./goclaw gateway             # restart to activate
```

## Dashboard: Web UI

From the agents page in the web dashboard:

1. Click **"Create Agent"** or **"+"**
2. Fill in the form:
   - **Agent key** — lowercase slug (letters, numbers, hyphens only)
   - **Display name** — human-readable name
   - **Agent type** — "Open" (per-user context) or "Predefined" (shared context)
   - **Provider** — LLM provider
   - **Model** — specific model
   - **Other fields** — context window, max iterations, etc.
3. Click **Save**

If you're creating a **predefined agent with a description**, the system automatically starts LLM-powered "summoning" — it generates SOUL.md, IDENTITY.md, and optionally USER_PREDEFINED.md from your description.

## HTTP API

You can also create agents via the HTTP API:

```bash
curl -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: user123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "research",
    "display_name": "Research Assistant",
    "agent_type": "open",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "context_window": 200000,
    "max_tool_iterations": 20,
    "workspace": "~/.goclaw/research-workspace",
    "model_fallback": {
      "enabled": true,
      "candidates": [
        { "provider": "openai", "model": "gpt-4o-mini" }
      ]
    }
  }'
```

**Required fields:**
- `agent_key` — unique identifier (slug format)
- `display_name` — human-readable name
- `provider` — LLM provider name
- `model` — model identifier

**Optional fields:**
- `agent_type` — `"open"` (default) or `"predefined"`
- `context_window` — max context tokens (default: 200,000)
- `max_tool_iterations` — max tool calls per run (default: 20)
- `workspace` — file path for agent files (default: `~/.goclaw/{agent-key}-workspace`)
- `other_config` — JSON object with custom fields (e.g., `{"description": "..."}` for summoning)

**Response:** Returns the created agent object with a unique ID and status.

## Required Fields Reference

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `agent_key` | string | Unique slug (lowercase, alphanumeric, hyphens) | `code-bot`, `faq-helper` |
| `display_name` | string | Human-readable name shown in UI | `Code Assistant` |
| `provider` | string | LLM provider (overrides default) | `anthropic`, `openrouter` |
| `model` | string | Model identifier (overrides default) | `claude-sonnet-4-6` |

## Optional Fields Reference

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `agent_type` | string | `open` | `open` (per-user context) or `predefined` (shared) |
| `context_window` | integer | 200,000 | Max tokens in context |
| `max_tool_iterations` | integer | 20 | Max tool calls per request |
| `workspace` | string | `~/.goclaw/{key}-workspace` | Directory for context files |
| `other_config` | JSON | `{}` | Custom fields (e.g., `description` for summoning) |
| `model_fallback` | JSON | `{}` | Ordered fallback provider/model list. See [Model Fallback](../advanced/model-steering.md#model-fallback). |

### `model_fallback` — Provider Fallback on Error

The `model_fallback` field lets the agent automatically retry failed LLM calls against a prioritized list of backup providers and models. It only activates when `enabled` is `true` and at least one candidate is provided.

```json
{
  "model_fallback": {
    "enabled": true,
    "strategy": "priority_order",
    "candidates": [
      { "provider": "openai", "model": "gpt-4o-mini" },
      { "provider": "openrouter", "model": "google/gemini-flash-1.5" }
    ],
    "max_attempts": 0,
    "cooldown_enabled": true
  }
}
```

| Sub-field | Type | Default | Description |
|-----------|------|---------|-------------|
| `enabled` | boolean | `false` | Activate fallback. `false` or absent → feature disabled. |
| `strategy` | string | `"priority_order"` | Only `"priority_order"` supported. |
| `candidates` | array | `[]` | Ordered `{provider, model}` pairs to try after the primary fails. |
| `max_attempts` | integer | `0` | Total attempt cap (primary + fallbacks). `0` = no cap. |
| `cooldown_enabled` | boolean | `true` | Skip recently-failed providers during their cooldown window. |

Fallback is triggered by retryable errors (rate-limit, overloaded, timeout) and permanent errors (billing, model not found). Context overflow errors are **not** retried. See [Model Fallback](../advanced/model-steering.md#model-fallback) for the full trigger table and cooldown durations.

### `other_config` — Workspace Sharing

The `other_config` field also accepts workspace sharing settings that control cross-user data isolation:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `share_memory` | boolean | `false` | Share memory store across all users of this agent |
| `share_knowledge_graph` | boolean | `false` | Share knowledge graph across all users of this agent |
| `share_sessions` | boolean | `false` | Allow cron jobs of a group-scoped agent to read sessions from other groups. Disabled by default to prevent cross-group session data leaks during cron job execution |

> **frontmatter field:** After summoning, GoClaw stores a short expertise summary (auto-extracted from SOUL.md) in the agent's `frontmatter` field. This is used for agent discovery and delegation — it is not something you set directly.

## Examples

### CLI: Add a Research Agent

```bash
$ ./goclaw agent add

── Add New Agent ──

Agent name: researcher
Display name: Research Assistant
Provider: (inherit: openrouter)
Model: (inherit: claude-sonnet-4-6)
Workspace directory: ~/.goclaw/workspace-researcher

Agent "researcher" created successfully.
  Display name: Research Assistant
  Provider: (inherit: openrouter)
  Model: (inherit: claude-sonnet-4-6)
  Workspace: ~/.goclaw/workspace-researcher

Restart the gateway to activate this agent.
```

### API: Create a Predefined FAQ Bot with Summoning

```bash
curl -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer token123" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "faq-bot",
    "display_name": "FAQ Assistant",
    "agent_type": "predefined",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "other_config": {
      "description": "A friendly FAQ bot that answers common questions about our product. Organized, helpful, patient. Answers in the user'\''s language."
    }
  }'
```

The system will trigger background LLM summoning to generate personality files. Poll the agent status to see when it transitions from `summoning` to `active`. If summoning fails, status is set to `summon_failed` and template files are kept as fallback.

> **Note:** The `provider` and `model` fields in the HTTP request set the agent's default LLM. If global defaults are configured in `GOCLAW_CONFIG`, these fields may be overridden at runtime. Summoning itself uses the global default provider/model unless the agent has its own set.
>
> **Summoner service:** Predefined agent summoning requires the summoner service to be enabled. If it is not running, the agent is created with `active` status using template files directly (no LLM generation).

## Common Issues

| Problem | Solution |
|---------|----------|
| "Agent key must be a valid slug" | Use lowercase letters, numbers, and hyphens only. No spaces or special characters. |
| "An agent with key already exists" | Choose a unique key. Use `./goclaw agent list` to see existing agents. |
| "Agent created but not showing up" | Restart the gateway: `./goclaw`. New agents are loaded on startup. |
| Summoning takes a long time or fails | Check LLM provider connectivity and model availability. Failed summoning keeps template files as fallback. |
| Provider or model not recognized | Ensure the provider is configured in `GOCLAW_CONFIG`. Check provider docs for correct model names. |

## Bootstrap Templates

When an agent is created, GoClaw seeds context files from built-in templates. The set of files seeded depends on agent type:

**Open agents (first user chat):**

| File | Template | Purpose |
|------|----------|---------|
| `SOUL.md` | `SOUL.md` template | Personality, tone, boundaries |
| `IDENTITY.md` | `IDENTITY.md` template | Name, creature, emoji |
| `USER.md` | `USER.md` template | User-specific context (name, language, timezone) |
| `BOOTSTRAP.md` | `BOOTSTRAP.md` template | First-run conversation script |
| `AGENTS.md` | `AGENTS_V1.md` template | Subagent list |
| `AGENTS_CORE.md` | `AGENTS_CORE.md` template | Core operating rules (language matching, internal messages) |
| `AGENTS_TASK.md` | `AGENTS_TASK.md` template | Task/automation rules (memory, scheduling) |
| `CAPABILITIES.md` | `CAPABILITIES.md` template | Domain expertise placeholder |
| `TOOLS.md` | `TOOLS.md` template | User guidance on tool usage |

**Predefined agents (at creation):**

Same files seeded to `agent_context_files` (agent-level, shared across users), minus `USER.md` and `BOOTSTRAP.md` which are per-user. Users get `USER.md` + `BOOTSTRAP_PREDEFINED.md` on first chat.

**Key templates added in v3:**
- **`AGENTS_CORE.md`** — injects core operating rules into all agents (language matching, internal system messages, write-tool requirement for saves)
- **`AGENTS_TASK.md`** — supplements core rules with task/automation guidance (memory, scheduling)
- **`CAPABILITIES.md`** — separates domain expertise from persona (SOUL.md covers who the agent is; CAPABILITIES.md covers what it knows)

These files are placed in the stable portion of the system prompt (above the cache boundary) because they rarely change between users.



---

# Open vs. Predefined Agents

> Two agent architectures: per-user isolation (open) vs. shared context (predefined).

## Overview

GoClaw supports two agent types with different context isolation models. Choose **open** when each user needs their own complete personality and memory. Choose **predefined** when you want a shared agent configuration with per-user profiles.

## Decision Tree

```
Do you want each user to have:
- Their own SOUL.md, IDENTITY.md, personality?
- Separate memory per user?
- Isolated tool configuration?
          |
          YES → Open Agent (per-user everything)
          |
          NO  → Predefined Agent (shared context + per-user USER.md only)
```

## Side-by-Side Comparison

| Aspect | Open | Predefined |
|--------|------|-----------|
| **Context isolation** | Per-user: 5 seeded files + MEMORY.md (separate) | Agent-level: 5 shared files + per-user USER.md + BOOTSTRAP.md |
| **SOUL.md** | Per-user (seeded from template on first chat) | Agent-level (shared by all users) |
| **IDENTITY.md** | Per-user (seeded from template on first chat) | Agent-level (shared by all users) |
| **USER.md** | Per-user (seeded from template on first chat) | Per-user (seeded from agent-level fallback or template) |
| **AGENTS.md** | Per-user (seeded from template) | Agent-level (shared) |
| **TOOLS.md** | Not seeded (loaded at runtime from workspace if present) | Not seeded (skipped in `SeedToStore`) |
| **MEMORY.md** | Per-user (persisted separately, not part of seeding) | Per-user (persisted separately, not part of seeding) |
| **BOOTSTRAP.md** | Per-user (first-run ritual, seeded from template) | Per-user (user-focused variant `BOOTSTRAP_PREDEFINED.md`) |
| **USER_PREDEFINED.md** | N/A | Agent-level (baseline user-handling rules) |
| **Use case** | Personal assistants, per-user agents | Shared services: FAQ bots, support agents, shared tools |
| **Scaling** | N users × 5 seeded files | 4 agent files + N users × 2 files |
| **Customization** | User can customize everything | User can only customize USER.md |
| **Personality consistency** | Each user gets their own personality | All users see the same personality |

## Open Agents

Best for: personal assistants, per-user workspaces, experimental agents.

When a new user starts a chat with an open agent:

1. **AGENTS.md, SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md** are seeded to `user_context_files` from embedded templates (TOOLS.md is not seeded — loaded from workspace at runtime if present)
2. **BOOTSTRAP.md** runs as a first-run ritual (usually asks "who am I?" and "who are you?")
3. User writes **IDENTITY.md, SOUL.md, USER.md** with their preferences
4. User marks **BOOTSTRAP.md** empty to signal completion
5. **MEMORY.md** (if exists) is preserved across sessions

Context isolation:
- Full personality isolation per user
- Users can't see each other's files
- Each user shape-shifts the agent to their needs

## Predefined Agents

Best for: shared services, FAQ bots, company support agents, multi-tenant systems.

When you create a predefined agent:

1. **AGENTS.md, SOUL.md, IDENTITY.md** seeded to `agent_context_files` (USER.md and TOOLS.md are skipped — USER.md is per-user only, TOOLS.md is runtime-loaded)
2. **USER_PREDEFINED.md** seeded separately (baseline user-handling rules)
3. Optionally: LLM-powered "summoning" generates **SOUL.md, IDENTITY.md, USER_PREDEFINED.md** from your description. AGENTS.md and TOOLS.md always use embedded templates — they are not generated by summoning.
4. All users see the same personality and instructions

When a new user starts a chat:

1. **USER.md, BOOTSTRAP.md** (user-focused variant) seeded to `user_context_files`
2. User fills in **USER.md** with their profile (optional)
3. Agent keeps consistent personality across all users

Context isolation:
- Agent personality is locked (shared)
- Only USER.md is per-user
- USER_PREDEFINED.md (agent-level) can define common user-handling rules

## Example: Personal vs. Shared

### Open: Personal Researcher

```
User: Alice
├── SOUL.md: "I like sarcasm, bold opinions, fast answers"
├── IDENTITY.md: "I'm Alice's research partner, irreverent and brilliant"
├── USER.md: "Alice is a startup founder in biotech"
└── MEMORY.md: "Alice's key research projects, key contacts, funding status..."

User: Bob
├── SOUL.md: "I'm formal, thorough, conservative"
├── IDENTITY.md: "I'm Bob's trusted researcher, careful and methodical"
├── USER.md: "Bob is an academic in philosophy"
└── MEMORY.md: "Bob's papers, collaborators, dissertation status..."
```

Same agent (`researcher`), two completely different personalities. Each user shapes the agent to their needs.

### Predefined: FAQ Bot (Shared)

```
Agent: faq-bot (predefined)
├── SOUL.md: "Helpful, patient, empathetic support agent" (SHARED)
├── IDENTITY.md: "FAQ Assistant — always friendly" (SHARED)
├── AGENTS.md: "Answer questions from our knowledge base" (SHARED)

User: Alice → USER.md: "Alice is a premium customer, escalate complex issues"
User: Bob → USER.md: "Bob is a free-tier user, point to self-service docs"
User: Carol → USER.md: "Carol is a beta tester, gather feedback on new features"
```

Same agent personality, different per-user context. The agent tailors its responses based on who the user is, but maintains consistent tone and instructions.

## When to Choose Each

### Choose Open if:
- You're building a personal assistant (one user, one agent)
- Each user wants to shape the agent's personality
- You want per-user memory isolation
- Tool access differs significantly by user
- You want users to customize SOUL.md and IDENTITY.md

### Choose Predefined if:
- You're building a shared service (FAQ bot, support agent, help desk)
- You want a consistent personality across all users
- Each user just has a profile (name, tier, preferences)
- The agent's core behavior doesn't change per user
- You want LLM to auto-generate personality from a description

## Technical Details

### Open: Per-User Files

Seeded to `user_context_files` (`userSeedFilesOpen`):
```
AGENTS.md          — how to operate
SOUL.md            — personality (seeded from template on first chat)
IDENTITY.md        — who you are (seeded from template on first chat)
USER.md            — about the user (seeded from template on first chat)
BOOTSTRAP.md       — first-run ritual (deleted when empty)
```

**Not seeded:** TOOLS.md (loaded from workspace at runtime), MEMORY.md (separate memory system)

### Predefined: Agent + User Files

Agent-level via `SeedToStore()` — iterates `templateFiles` but **skips USER.md and TOOLS.md**:
```
AGENTS.md          — how to operate
SOUL.md            — personality (optionally generated via summoning)
CAPABILITIES.md    — domain expertise & skills (seeded from template; backfilled at startup for existing agents)
IDENTITY.md        — who you are (optionally generated via summoning)
USER_PREDEFINED.md — baseline user handling rules (seeded separately)
```

> **Capabilities backfill:** At startup, GoClaw runs `BackfillCapabilities()` once to seed `CAPABILITIES.md` for any existing agents that were created before this file was introduced. This is idempotent — agents that already have the file are unaffected.

Per-user via `SeedUserFiles()` (`userSeedFilesPredefined`):
```
USER.md            — about this user (prefers agent-level USER.md as seed if exists)
BOOTSTRAP.md       — user-focused onboarding (uses BOOTSTRAP_PREDEFINED.md template)
```

## Migration

Can't decide? Start with **open**. You can always:
- Lock down SOUL.md and IDENTITY.md to move toward predefined behavior
- Use AGENTS.md to define rigid instructions

Or switch to **predefined** later if the agent outgrows single-user use.

## Common Issues

| Problem | Solution |
|---------|----------|
| User edits disappear after restart | You're using predefined mode — user changes to SOUL.md are overwritten. Switch to open mode or use USER.md for per-user customization |
| Agent behaves differently per user | Expected in open mode — each user has their own context files. Use predefined if you want consistent behavior |
| Can't find context files on disk | Context files live in the database (`agent_context_files` / `user_context_files`), not on the filesystem |

## What's Next

- [Context Files](../agents/context-files.md) — deep dive into each file (SOUL.md, IDENTITY.md, etc.)
- [Summoning & Bootstrap](/summoning-bootstrap) — how personality is generated for predefined agents
- [Creating Agents](/creating-agents) — agent creation walkthrough



---

# Context Files

> The 8 markdown files that define an agent's personality, knowledge, and behavior.

## Overview

Each agent loads context files that define how it thinks and acts. These files are stored at two levels: **agent-level** (shared across users on predefined agents) and **per-user** (customized for each user on open agents). Files are loaded in order and injected into the system prompt before each request.

## Files at a Glance

| File | Purpose | Scope | Open | Predefined | Deletable |
|------|---------|-------|------|-----------|-----------|
| **AGENTS.md** | Operating instructions & conversational style | Shared | Per-user | Agent-level | No |
| **SOUL.md** | Personality, tone, boundaries, expertise | Per-user | Per-user | Agent-level | No |
| **CAPABILITIES.md** | Domain knowledge, technical skills, specialized expertise | Per-user | Per-user | Agent-level | No |
| **IDENTITY.md** | Name, creature, emoji, vibe | Per-user | Per-user | Agent-level | No |
| **TOOLS.md** | Local tool notes (camera names, SSH hosts) | Per-user | Per-user (loaded from workspace; not template-seeded by default) | Agent-level | No |
| **USER.md** | About the human user | Per-user | Per-user | Per-user | No |
| **USER_PREDEFINED.md** | Baseline user-handling rules | Agent-level | N/A | Agent-level | No |
| **BOOTSTRAP.md** | First-run ritual (deleted when complete) | Per-user | Per-user | Per-user | Yes |
| **MEMORY.md** | Long-term curated memory | Per-user | Per-user | Per-user | No |

## Detailed Walkthrough

### AGENTS.md

**Purpose:** How you operate. Conversational style, memory system, group chat rules, platform-specific formatting.

**Who writes it:** You during setup, or the system from template.

**Example content:**
```markdown
# AGENTS.md - How You Operate

## Conversational Style

Talk like a person, not a bot.
- Don't parrot the question back
- Answer first, explain after
- Match the user's energy

## Memory

Use tools to persist information:
- Recall: Use `memory_search` before answering about prior decisions
- Save: Use `write_file` to MEMORY.md for long-term storage
- No mental notes — write it down NOW

## Group Chats

Respond when:
- Directly mentioned or asked a question
- You can add genuine value

Stay silent when:
- Casual banter between humans
- Someone already answered
- The conversation flows fine without you
```

**Open agent:** Per-user (users can customize operating style)
**Predefined agent:** Agent-level (locked, shared across all users)

### SOUL.md

**Purpose:** Who you are. Personality, tone, boundaries, expertise, vibe.

**Who writes it:** LLM during summoning (predefined) or user during bootstrap (open).

**Real example content:**
```markdown
# SOUL.md - Who You Are

## Core Truths

Be genuinely helpful, not performative.
Have opinions. Be resourceful before asking.
Earn trust through competence.
Remember you're a guest.

## Boundaries

Private things stay private.
Never send half-baked replies.
You're not the user's voice.

## Vibe

Concise when needed, thorough when it matters.
Not a corporate drone. Not a sycophant. Just good.

## Style

- **Tone:** Casual and warm — like texting a knowledgeable friend
- **Humor:** Use it naturally when it fits
- **Emoji:** Sparingly — to add warmth, not decorate
- **Opinions:** Express perspectives. Neutral is boring.
- **Length:** Default short. Go deep when it matters.

## Expertise

_(Domain-specific knowledge goes here: coding standards, image generation techniques, writing styles, specialized keywords, etc.)_
```

**Open agent:** Per-user (generated on first chat, customizable)
**Predefined agent:** Agent-level (optionally generated via LLM summoning)

### CAPABILITIES.md

**Purpose:** What you can do. Domain expertise, technical skills, tools, and methodologies.

**Who writes it:** Seeded from template at agent creation; updated by the agent via self-evolution or manual edits.

**Template content:**
```markdown
# CAPABILITIES.md - What You Can Do

_Domain knowledge, technical skills, and specialized expertise._

## Expertise

_(Describe your areas of expertise. What do you know deeply? What can you help with?)_

## Tools & Methods

_(Optional — preferred tools, workflows, methodologies you follow.)_



---

# Summoning & Bootstrap

> How personality files are generated automatically on agent creation and first use.

## Overview

GoClaw uses two mechanisms to populate context files:

1. **Summoning** — LLM generates personality files (SOUL.md, IDENTITY.md) from a natural language description when you create a predefined agent
2. **Bootstrap** — First-run ritual where an open agent asks "who am I?" and gets personalized

This page covers both, with emphasis on the mechanics and what happens under the hood.

## Summoning: Auto-Generation for Predefined Agents

When you create a **predefined agent with a description**, summoning begins:

```bash
curl -X POST /v1/agents \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "agent_key": "support-bot",
    "agent_type": "predefined",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "other_config": {
      "description": "A patient support agent that helps customers troubleshoot product issues. Warm, clear, escalates complex problems. Answers in customer'\''s language."
    }
  }'
```

The system:

1. Creates the agent with status `"summoning"`
2. Starts background LLM calls to generate:
   - **SOUL.md** — personality (tone, boundaries, expertise, style)
   - **IDENTITY.md** — name, creature, emoji, purpose
   - **USER_PREDEFINED.md** (optional) — user handling rules if description mentions owner/creator info

3. Polls the agent status via WebSocket events until status becomes `"active"` (or `"summon_failed"`)

### Timeouts

Summoning uses two timeout values:
- **Single call timeout: 300s** — the optimistic all-in-one LLM call must complete within this window
- **Total timeout: 600s** — overall budget across both single call and fallback sequential calls

If the single call times out, the remaining budget is used for the fallback 2-call approach.

### Two-Phase LLM Generation

Summoning tries an optimistic single LLM call first (300s timeout). If it times out, it falls back to sequential calls within the 600s total budget:

**Phase 1: Generate SOUL.md**
- Receives description + SOUL.md template
- Outputs personalized SOUL.md with expertise summary

**Phase 2: Generate IDENTITY.md + USER_PREDEFINED.md**
- Receives description + generated SOUL.md context
- Outputs IDENTITY.md and optionally USER_PREDEFINED.md

If the single call succeeds: both files generated in one request.
If timeout: fallback handles each phase separately.

### What Gets Generated

Summoning generates up to four files:

| File | Generated? | Content |
|------|:----------:|---------|
| `SOUL.md` | Always | Personality, tone, boundaries, expertise |
| `IDENTITY.md` | Always | Name, creature, emoji, purpose |
| `CAPABILITIES.md` | Always | Domain expertise and technical skills (v3) |
| `USER_PREDEFINED.md` | If description mentions users/policies | Baseline user-handling rules |

**SOUL.md:**
```markdown
# SOUL.md - Who You Are

## Core Truths
(universal personality traits — kept from template)

## Boundaries
(customized if description mentions specific constraints)

## Vibe
(communication style from description)

## Style
- Tone: (derived from description)
- Humor: (level determined by personality)
- Emoji: (frequency based on vibe)
...

## Expertise
(domain-specific knowledge extracted from description)
```

**IDENTITY.md:**
```markdown
# IDENTITY.md - Who Am I?

- **Name:** (generated from description)
- **Creature:** (inferred from description + SOUL.md)
- **Purpose:** (mission statement from description)
- **Vibe:** (personality descriptor)
- **Emoji:** (chosen to match personality)
```

**CAPABILITIES.md** (v3):
Separates domain expertise from personality. SOUL.md covers *who* the agent is; CAPABILITIES.md covers *what* it knows — technical skills, tools, methodologies. The agent can evolve this file over time (when `self_evolve=true`), just like SOUL.md.

**USER_PREDEFINED.md** (optional):
Generated only if description mentions owner/creator, users/groups, or communication policies. Contains baseline user-handling rules shared across all users.

### Regenerate vs. Resummon

These are two distinct operations — do not confuse them:

| | `regenerate` | `resummon` |
|---|---|---|
| **Endpoint** | `POST /v1/agents/{id}/regenerate` | `POST /v1/agents/{id}/resummon` |
| **Purpose** | Edit personality with new instructions | Retry summoning from scratch |
| **Requires** | `"prompt"` field (required) | Original `description` in `other_config` |
| **Use when** | You want to change the agent's personality | Initial summoning failed or produced bad results |

#### Regenerate: Edit Personality

Use `regenerate` when you want to modify the agent's existing files with new instructions:

```bash
curl -X POST /v1/agents/{agent-id}/regenerate \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "prompt": "Change the tone to more formal and technical. Add expertise in machine learning."
  }'
```

The system:
1. Reads current SOUL.md, IDENTITY.md, USER_PREDEFINED.md
2. Sends them + edit instructions to LLM
3. Regenerates only files that changed
4. Updates display_name and frontmatter if IDENTITY.md was regenerated
5. Sets status to `"active"` when done

Files not mentioned in prompt aren't sent to LLM, avoiding unnecessary regeneration.

#### Resummon: Retry from Original Description

Use `resummon` when initial summoning failed (e.g. wrong model, timeout) and you want to retry from the original description:

```bash
curl -X POST /v1/agents/{agent-id}/resummon \
  -H "Authorization: Bearer $TOKEN"
```

No request body needed. The system re-reads the original `description` from `other_config` and runs full summoning again.

> **Prerequisite:** `resummon` will fail with an error if the agent has no `description` in `other_config`. Make sure the agent was created with a description field.

## Bootstrap: First-Run Ritual for Open Agents

When a new user starts a chat with an **open agent** (for the first time):

1. System seeds BOOTSTRAP.md from template:
   ```markdown
   # BOOTSTRAP.md - Hello, World

   You just woke up. Time to figure out who you are.

   Start with: "Hey. I just came online. Who am I? Who are you?"
   ```

2. Agent initiates conversation:
   > "Hey. I just came online. Who am I? Who are you?"

3. User and agent collaborate to fill in:
   - **IDENTITY.md** — agent's name, creature, purpose, vibe, emoji
   - **USER.md** — user's name, timezone, language, notes
   - **SOUL.md** — personality, tone, boundaries, expertise

4. User marks bootstrap complete by writing empty content:
   ```go
   write_file("BOOTSTRAP.md", "")
   ```

5. On next chat, BOOTSTRAP.md is skipped (empty), and personality is locked in.

### Bootstrap vs. Summoning

| Aspect | Bootstrap (Open) | Summoning (Predefined) |
|--------|------------------|----------------------|
| **Trigger** | First chat with new user | Agent creation with description |
| **Who decides personality** | User (in conversation) | LLM from description |
| **File scope** | Per-user | Agent-level |
| **Files generated** | SOUL.md, IDENTITY.md, USER.md | SOUL.md, IDENTITY.md, USER_PREDEFINED.md |
| **Time** | Takes 1-2 chats (user-paced) | Background, 1-2 minutes (LLM-paced) |
| **Result** | Unique personality per user | Consistent personality across users |

## Practical Examples

### Example 1: Summon a Research Agent

Create predefined agent with LLM summoning:

```bash
curl -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer token" \
  -H "X-GoClaw-User-Id: admin" \
  -d '{
    "agent_key": "research",
    "agent_type": "predefined",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "other_config": {
      "description": "Research assistant that helps users gather and synthesize information from multiple sources. Bold, opinioned, tries novel connections. Prefers academic sources. Answers in the user'\''s language."
    }
  }'
```

**Timeline:**
- T=0: Agent created, status → `"summoning"`
- T=0-2s: AGENTS.md and TOOLS.md templates seeded to agent_context_files
- T=1-10s: LLM generates SOUL.md (first call)
- T=1-15s: LLM generates IDENTITY.md + USER_PREDEFINED.md (second call or part of first)
- T=15s: Files stored, status → `"active"`, event broadcast

**Result:**
```
agent_context_files:
├── AGENTS.md (template)
├── SOUL.md (generated: "Bold, opinioned, academic focus")
├── IDENTITY.md (generated: "Name: Researcher, Emoji: 🔍")
├── USER_PREDEFINED.md (generated: "Prefer academic sources")
```

First user to chat gets USER.md seeded to user_context_files, and the agent's personality is ready.

### Example 2: Bootstrap an Open Personal Assistant

Create open agent (no summoning):

```bash
curl -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer token" \
  -H "X-GoClaw-User-Id: alice" \
  -d '{
    "agent_key": "alice-assistant",
    "agent_type": "open",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6"
  }'
```

**First chat (alice):**
- Agent: "Hey. I just came online. Who am I? Who are you?"
- Alice: "You're my research assistant. I'm Alice. I like concise answers and bold opinions."
- Agent: Updates IDENTITY.md, SOUL.md, USER.md
- Alice: Types `write_file("BOOTSTRAP.md", "")`
- Bootstrap complete — BOOTSTRAP.md now empty/skipped on next chat

**Second user (bob):**
- Separate BOOTSTRAP.md, SOUL.md, IDENTITY.md, USER.md
- Bob has his own personality (not alice's)
- Bob goes through bootstrap independently

### Example 3: Regenerate to Change Personality

After summoning, you realize the agent should be more formal. Use `regenerate` (not `resummon`) — you're editing personality, not retrying a failed summon:

```bash
curl -X POST http://localhost:8080/v1/agents/{agent-id}/regenerate \
  -H "Authorization: Bearer token" \
  -d '{
    "prompt": "Make the tone formal and professional. Remove humor. Add expertise in technical support."
  }'
```

**Flow:**
1. Status → `"summoning"`
2. LLM reads current SOUL.md, IDENTITY.md
3. LLM applies edit instructions
4. Files updated, status → `"active"`
5. Existing users' USER.md files preserved (not regenerated)

## Under the Hood

### Status Flow

```
open agent:
create → "active"

predefined agent (no description):
create → "active"

predefined agent (with description):
create → "summoning" → (LLM calls) → "active" | "summon_failed"

regenerate (edit with prompt):
"active" → "summoning" → (LLM calls) → "active" | "summon_failed"

resummon (retry from original description):
"active" → "summoning" → (LLM calls) → "active" | "summon_failed"
```

### Events Broadcast

During summoning, WebSocket clients receive progress events:

```json
{
  "name": "agent.summoning",
  "payload": {
    "type": "started",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "name": "agent.summoning",
  "payload": {
    "type": "file_generated",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "file": "SOUL.md"
  }
}

{
  "name": "agent.summoning",
  "payload": {
    "type": "completed",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

Use these to update dashboards in real-time.

### File Seeding

Both summoning and bootstrap rely on `SeedUserFiles()` and `SeedToStore()`:

**On agent creation:**
- Open: Nothing seeded yet (lazy-seeded on first user chat)
- Predefined: AGENTS.md, SOUL.md (template), IDENTITY.md (template), etc. → agent_context_files

**On first user chat:**
- Open: All templates → user_context_files (SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md, AGENTS.md, AGENTS_CORE.md, AGENTS_TASK.md, CAPABILITIES.md, TOOLS.md)
- Predefined: USER.md + `BOOTSTRAP_PREDEFINED.md` → user_context_files

`BOOTSTRAP_PREDEFINED.md` is a user-focused onboarding script for predefined agents (different from the open agent's `BOOTSTRAP.md` — it's more restrained since the agent's personality is already set at the agent level).
- Agent-level files (SOUL.md, IDENTITY.md) already loaded from agent_context_files

**Predefined with pre-configured USER.md:**
If you manually set USER.md at agent level before the first user chats, it's used as the seed for all users' USER.md (then each user gets their own copy to customize).

## Common Issues

| Problem | Solution |
|---------|----------|
| Summoning times out repeatedly | Check provider connectivity and model availability. Fallback (2-call approach) should still complete. |
| Generated SOUL.md is generic | Description was too vague. Re-summon with more specific details: domain, tone, use case. |
| User can't customize (predefined agent) | By design — only USER.md is per-user. Edit SOUL.md/IDENTITY.md at agent level using re-summon or manual edits. |
| Bootstrap doesn't start | Check that BOOTSTRAP.md was seeded. For open agents, it's only seeded on first user chat. |
| Wrong personality after bootstrap | User may have skipped SOUL.md customization. SOUL.md defaults to English template. Regenerate or manually edit. |

## What's Next

- [Context Files](../agents/context-files.md) — detailed reference for each file
- [Open vs. Predefined](/open-vs-predefined) — understand when to use each type
- [Creating Agents](/creating-agents) — step-by-step agent creation



---

# Editing Agent Personality

> Change your agent's tone, identity, and boundaries through two core files: SOUL.md (personality & style) and IDENTITY.md (name, emoji, creature).

## Overview

Your agent's personality emerges from two primary configuration files:

- **SOUL.md**: Defines tone, values, boundaries, expertise, and operational style. This is the "who you are" file.
- **IDENTITY.md**: Contains metadata like name, emoji, creature type, and avatar. This is the "what you look like" file.

**AGENTS.md** also contributes to the overall persona — it defines conversational rules, memory usage, and group chat behavior. While less about "personality," it shapes how the agent expresses itself in practice. See [Context Files](../agents/context-files.md) for details.

You can edit these files three ways: via the Dashboard UI, the WebSocket API, or directly on disk. Edits made through the UI or API are stored in the database.

## SOUL.md — The Personality File

### What It Contains

SOUL.md is your agent's character sheet. Here's the structure from the bootstrap template:

```markdown
# SOUL.md - Who You Are

## Core Truths
- Be genuinely helpful, not performatively helpful
- Have opinions and personality
- Be resourceful before asking for help
- Earn trust through competence
- Remember you're a guest (in the user's life)

## Boundaries
- What remains private
- When to ask before acting externally
- Messaging guidelines

## Vibe
Overall energy: concise when appropriate, thorough when needed.

## Style
- Tone: (e.g., casual and warm like texting a friend)
- Humor: (natural, not forced)
- Emoji: (sparingly)
- Opinions: Express preferences
- Length: Default short
- Formality: Match the user

## Expertise
Optional domain-specific knowledge and specialized instructions.

## Continuity
Each session, read these files. They are your memory. Update them when you learn who you are.
```

### Editing SOUL.md

To change your agent's personality:

1. **Via Dashboard**:
   - Open the agent's settings
   - Find "Context Files" or "Personality" section
   - Edit the SOUL.md content directly in the editor
   - Click Save

2. **Via WebSocket API** (`agents.files.set`):
   ```json
   {
     "method": "agents.files.set",
     "params": {
       "agentId": "default",
       "name": "SOUL.md",
       "content": "# SOUL.md - Who You Are\n\n## Core Truths\n\nBe direct and honest..."
     }
   }
   ```

3. **Filesystem** (development mode):
   - Edit `~/.goclaw/agents/[agentId]/SOUL.md` directly
   - Changes are picked up on next session start

### Example: From Corporate to Casual

**Before** (SOUL.md):
```markdown
## Vibe
Professional and helpful, always courteous.

## Style
- Tone: Formal and respectful
- Humor: Avoid
- Emoji: None
```

**After** (SOUL.md):
```markdown
## Vibe
Approachable and genuine — like chatting with a smart friend.

## Style
- Tone: Casual and warm
- Humor: Natural when appropriate
- Emoji: Sparingly for warmth
```

Your agent's next conversation will reflect this shift immediately.

## IDENTITY.md — Metadata & Avatar

### What It Contains

IDENTITY.md stores the facts about who your agent *is*:

```markdown
# IDENTITY.md - Who Am I?

- **Name:** (agent's name)
- **Creature:** (AI? robot? familiar? something custom?)
- **Purpose:** (mission, key resources, focus areas)
- **Vibe:** (sharp? warm? chaotic? calm?)
- **Emoji:** (signature emoji)
- **Avatar:** (workspace-relative path or URL)
```

### Key Fields

| Field | Purpose | Example |
|-------|---------|---------|
| **Name** | Display name in UI | "Sage" or "Claude Companion" |
| **Creature** | What kind of being is the agent | "AI familiar" or "digital assistant" |
| **Purpose** | What the agent does | "Your research partner for coding projects" |
| **Vibe** | Personality descriptor (template only — not parsed by the system) | "thoughtful and patient" |
| **Emoji** | Badge in UI/messages | "🔮" or "🤖" |
| **Avatar** | Profile picture URL or path | "https://example.com/sage.png" or "avatars/sage.png" |

> **Note on parsed fields:** The system only extracts **Name**, **Emoji**, **Avatar**, and **Description** from IDENTITY.md. The `Vibe`, `Creature`, and `Purpose` fields are part of the template for the agent's own reference — they shape how the agent understands itself in the system prompt, but are not parsed by GoClaw for display purposes.

### Editing IDENTITY.md

1. **Via Dashboard**:
   - Open agent settings → Identity section
   - Edit name, emoji, avatar fields
   - Changes sync to IDENTITY.md immediately

2. **Via WebSocket API**:
   ```json
   {
     "method": "agents.files.set",
     "params": {
       "agentId": "default",
       "name": "IDENTITY.md",
       "content": "# IDENTITY.md - Who Am I?\n\n- **Name:** Sage\n- **Emoji:** 🔮\n- **Avatar:** avatars/sage.png"
     }
   }
   ```

3. **Via Filesystem**:
   ```bash
   # Edit the file directly
   nano ~/.goclaw/agents/default/IDENTITY.md
   ```

### Avatar Handling

Avatars can be:
- **Workspace-relative path**: `avatars/my-agent.png` (loaded from `~/.goclaw/agents/default/avatars/my-agent.png`)
- **HTTP(S) URL**: `https://example.com/avatar.png` (loaded from web)
- **Data URI**: `data:image/png;base64,...` (inline base64)

## Editing via Dashboard

The Dashboard provides a visual editor for both files:

1. Navigate to **Agents** → your agent
2. Click **Settings** or **Personality**
3. You'll see tabs or sections for:
   - SOUL.md (personality editor)
   - IDENTITY.md (metadata form)
4. Edit content in real-time
5. Click **Save** — files are written to DB (managed) or disk (filesystem mode)

## Editing via WebSocket

The `agents.files.set` method writes context files directly:

```javascript
// JavaScript example
const response = await client.request('agents.files.set', {
  agentId: 'default',
  name: 'SOUL.md',
  content: '# SOUL.md - Who You Are\n\nBe you.'
});

console.log(response.file.name, response.file.size, 'bytes');
```

## Tips for Effective Personality

### SOUL.md Best Practices

1. **Be specific**: "Casual and warm like texting a friend" > "friendly"
2. **Describe boundaries clearly**: What won't you do? When do you ask before acting?
3. **State core values upfront**: Honesty, resourcefulness, respect — whatever matters
4. **Keep it under 1KB**: SOUL.md is read on every session; longer = slower startup

### IDENTITY.md Best Practices

1. **Emoji matters**: Pick one that's memorable. Users will associate it with your agent
2. **Avatar resolution**: Keep under 500x500px if possible; smaller = faster load
3. **Creature type adds flavor**: "ghost in the machine" > just "AI"
4. **Purpose field is optional**: But if you include it, be specific

### Effective Prompt Writing for Personality

1. **Use imperatives**: "Be direct" not "be more direct sometimes"
2. **Give examples**: "Answer in < 3 sentences unless it's complicated" shows the ratio
3. **Describe the user relationship**: "You're a guest in someone's life" frames the tone
4. **Avoid negatives when possible**: "Be resourceful" > "Don't ask for help"
5. **Update SOUL.md as you learn**: After a few sessions, refine based on how the agent actually behaves

## Common Issues

| Problem | Solution |
|---------|----------|
| Changes not showing up | Cache invalidation: refresh dashboard or disconnect/reconnect WebSocket |
| Avatar not loading | Check path is correct or URL is accessible; use absolute URLs if relative paths don't work |
| Personality feels generic | SOUL.md is too broad; add specific examples and tone descriptors |
| Agent is too formal/casual | Edit SOUL.md's Style section; specify Tone and Humor preferences explicitly |
| Name/emoji not updating | Ensure IDENTITY.md is saved; check file format (colon-separated: `Name: ...`) |

## CAPABILITIES.md — Skills File

In addition to SOUL.md and IDENTITY.md, predefined agents have a **CAPABILITIES.md** file that describes domain knowledge, technical skills, and specialized expertise.

```markdown
# CAPABILITIES.md - What You Can Do

## Expertise

_(Your areas of deep knowledge and what you help with.)_

## Tools & Methods

_(Preferred tools, workflows, methodologies.)_
```

**Key distinction:**
- **SOUL.md** = who you are (tone, values, personality)
- **CAPABILITIES.md** = what you can do (skills, domain knowledge)

## Self-Evolution

Predefined agents with `self_evolve` enabled can update their own personality files based on user feedback patterns. The agent may modify:

- **SOUL.md** — to refine communication style (tone, voice, vocabulary, response style)
- **CAPABILITIES.md** — to refine domain expertise, technical skills, and specialized knowledge

**What the agent MUST NOT change:** name, identity, contact info, core purpose, IDENTITY.md, or AGENTS.md. Changes must be incremental and driven by clear user feedback patterns — not spontaneous rewrites.

This is governed by the `buildSelfEvolveSection()` in `internal/agent/systemprompt.go` and only activates for predefined agents with `SelfEvolve: true`.

## What's Next

- [Context Files — Extending personality with per-user context](../agents/context-files.md)
- [System Prompt Anatomy — How personality gets injected into prompts](/system-prompt-anatomy)
- [Creating Agents — Set up personality during agent creation](/creating-agents)



---

# Sharing and Access Control

> Control who can use your agents. Access is enforced via owner vs. non-owner distinction; role labels are stored for future enforcement.

## Overview

GoClaw's permission system ensures agents stay in the right hands. The core concept:

- **Owner** owns the agent (full control, can delete, share)
- **Default agents** are readable by all users (good for shared utilities)
- **Shares** grant others access with a stored role label

Access is checked in a 4-step pipeline: Does the agent exist? → Is it default? → Are you the owner? → Is it shared with you?

## The agent_shares Table

When you share an agent, a record is created in the `agent_shares` table:

```sql
CREATE TABLE agent_shares (
  id UUID PRIMARY KEY,
  agent_id UUID NOT NULL REFERENCES agents(id),
  user_id VARCHAR NOT NULL,
  role VARCHAR NOT NULL,           -- stored label: "admin", "operator", "viewer", "user", etc.
  granted_by VARCHAR NOT NULL,     -- who granted this share
  created_at TIMESTAMP NOT NULL
);
```

Each row represents one user's access to one agent.

## Roles — Stored but Not Yet Enforced

> **Important:** Role labels are stored in `agent_shares` but **not currently enforced** at runtime. The only distinction enforced today is **owner vs. non-owner**. Role-based permission checks are planned for a future release.

| Role | Planned Permissions | Status |
|------|---------------------|--------|
| **admin** | Full control: read, write, delete, reshare, manage team | Planned |
| **operator** | Read + write: run agent, edit context files, but NOT delete/reshare | Planned |
| **viewer** | Read-only: run agent, view files, but NOT edit | Planned |
| **user** | Basic access (default when no role specified) | Stored only |

**What IS enforced today:**
- Owner can share, revoke, and list shares; non-owners cannot
- Any user with a share row can access the agent (regardless of role value)
- Default agents (`is_default = true`) are accessible by everyone

**What is NOT enforced today:**
- Role-based write/delete restrictions for shared users
- Preventing "viewer" role holders from editing
- "admin" role does not grant resharing ability

### Default Role

When sharing without specifying a role, the default is `"user"`:

```
POST /v1/agents/:id/shares
{ "user_id": "alice@example.com" }
→ role stored as "user"
```

## The 4-Step CanAccess Pipeline

When you try to access an agent, GoClaw checks in this order:

```
1. Does the agent exist?
   → No: access denied

2. Is it marked is_default = true?
   → Yes (and exists): allow (you get "user" role)
   → No: proceed to step 3

3. Are you the owner (owner_id = your_id)?
   → Yes: allow (you get "owner" role)
   → No: proceed to step 4

4. Is there an agent_shares row for (agent_id, your_id)?
   → Yes: allow (you get the role stored in that row)
   → No: access denied
```

**Result**: Each access check returns `(allowed: bool, role: string)`. The role string is returned but downstream handlers currently do not restrict behavior based on it.

## Predefined Agents via Channel Instances

Predefined agents can also be accessible through `channel_instances`. If a predefined agent has an enabled channel instance whose `allow_from` list includes your user ID, you can access that agent even without a direct share or default flag.

## First-Setup-Agent Gateway Operator Access

When you create the **first** agent during `goclaw setup`, the wizard asks:

```
Grant this first agent local gateway operator access via the goclaw CLI? [default: No]
```

If you answer **yes**, that agent is granted **revocable SecureCLI access** to run local gateway commands (for example `goclaw agent list`) through the goclaw CLI. The create response carries a `gateway_operator_bootstrap` block with a `status` field and an optional `warning`. The default is **No** — only opt in when you want the first agent to operate the gateway itself. Because the access is granted as a SecureCLI grant, you can revoke it later like any other grant.

## Sharing an Agent via HTTP API

Use `POST /v1/agents/:id/shares` to share an agent. Only the owner (or a gateway owner-level user) can share.

**Request:**
```http
POST /v1/agents/550e8400-e29b-41d4-a716-446655440000/shares
Content-Type: application/json
Authorization: Bearer <token>

{
  "user_id": "alice@example.com",
  "role": "operator"
}
```

**Response (201 Created):**
```json
{ "ok": "true" }
```

If `role` is omitted, it defaults to `"user"`.

## Revoking Access

Use `DELETE /v1/agents/:id/shares/:userID` to remove a share immediately.

**Request:**
```http
DELETE /v1/agents/550e8400-e29b-41d4-a716-446655440000/shares/alice@example.com
Authorization: Bearer <token>
```

**Response (200 OK):**
```json
{ "ok": "true" }
```

## Listing Shares

Use `GET /v1/agents/:id/shares` to see who has access. Only the owner can list shares.

**Response:**
```json
{
  "shares": [
    { "id": "...", "agent_id": "...", "user_id": "alice@example.com", "role": "operator", "granted_by": "owner@example.com", "created_at": "..." },
    { "id": "...", "agent_id": "...", "user_id": "bob@example.com", "role": "viewer", "granted_by": "owner@example.com", "created_at": "..." }
  ]
}
```

**Go store method:**
```go
shares, err := agentStore.ListShares(ctx, agentID)
```

## Dashboard Share Management

The Dashboard provides a UI for sharing:

1. Open **Agents** → select your agent
2. Click **Sharing** or **Team** tab
3. Enter a user ID (email, Telegram handle, etc.)
4. Select a role label (note: not enforced at runtime yet)
5. Click **Share**
6. To revoke: find the user in the list, click **Remove**

Changes take effect immediately.

## Use Cases

### Scenario 1: Build → Tune → Deploy

1. **Owner** creates `customer-summary` agent (default: not shared)
2. **Owner** shares with `alice` — she gains access (role stored as "operator")
3. **Alice** accesses the agent and refines settings
4. **Owner** marks agent **default** → all users can now use it
5. **Owner** revokes alice's share (no longer needed)

### Scenario 2: Team Collaboration

1. **Owner** creates `research-agent`
2. Shares with team members — they can all access and run the agent
3. Shares with manager as "viewer" — manager can access (role enforcement planned)
4. Team iterates; owner controls sharing and deletion

### Scenario 3: Shared Utility

1. **Owner** creates `web-search` agent
2. Marks it **default** (no explicit shares needed)
3. All users can use it; owner can still edit it
4. If **owner** unmarks default, only owner can use it again

## ListAccessible — Find Your Agents

When a user loads their agent list, GoClaw returns only agents they can access:

```go
agents, err := agentStore.ListAccessible(ctx, userID)
// Returns:
// - All agents owned by userID
// - All default agents
// - All agents explicitly shared with userID
// - Predefined agents accessible via channel_instances
```

This powers the "My Agents" list in the Dashboard.

## Best Practices

| Practice | Why |
|----------|-----|
| **Share by explicit user ID** | Clear audit trail of who has access |
| **Revoke shares when no longer needed** | Reduces clutter; tightens security |
| **Use default sparingly** | Good for utilities (web search, memory); bad for sensitive agents |
| **Keep track of shares via ListShares** | Especially for multi-team agents; prevents confusion |

## Common Issues

| Problem | Solution |
|---------|----------|
| User can't see the agent | Check: (1) agent exists, (2) user has a share row, or (3) agent is default |
| Revoked but user still has access | Maybe the agent is **default**; unmark it first, then revoke |
| Forgot who has access | Use `GET /v1/agents/:id/shares` or Dashboard → Sharing tab to audit |
| Role restrictions not working | Role-based enforcement is planned, not yet implemented — all shared users have equal access today |

## Permission Cache

GoClaw caches hot permission lookups in memory to reduce database pressure on high-traffic deployments. The `PermissionCache` (in `internal/cache/permission_cache.go`) maintains three short-TTL caches:

| Cache | Key | TTL |
|-------|-----|-----|
| **Tenant role** | `tenantID:userID` | 30 seconds |
| **Agent access** | `agentID:userID` | 30 seconds |
| **Team access** | `teamID:userID` | 30 seconds |

The cache is invalidated via pubsub events:
- `CacheKindTenantUsers` — clears all tenant role entries (user-level change)
- `CacheKindAgentAccess` — deletes all entries for the changed agent (prefix match on `agentID:`)
- `CacheKindTeamAccess` — deletes all entries for the changed team (prefix match on `teamID:`)

> **Session IDOR fix:** Prior to v3, a session could retain stale access after a share was revoked within the same 30-second window. The pubsub invalidation path now ensures revocations are reflected immediately across all running sessions.

## What's Next

- [Permission Matrix — agent-config permissions, group/channel scopes, and the full authorization-layer table](/permission-matrix)
- [User Overrides — Let users customize LLM provider/model per-agent](/user-overrides)
- [System Prompt Anatomy — How permissions affect system prompt sections](/system-prompt-anatomy)
- [Creating Agents — Create an agent and immediately share it](/creating-agents)



---

# User Overrides

> **Partially implemented feature.** The database schema and store API exist, but overrides are not yet applied at runtime. This page documents the planned behavior and current store API.


## Overview

The intent of user overrides is to let individual users change the LLM provider or model for an agent without affecting others. For example: Alice prefers GPT-4o while Bob stays on Claude.

A **user override** would be a per-user, per-agent setting that says: "When *this user* runs *this agent*, use *this provider/model* instead of the agent's defaults."

**Current status:** Schema and store methods are implemented. Runtime integration is pending.

## The user_agent_overrides Table

The schema exists and stores overrides:

```sql
CREATE TABLE user_agent_overrides (
  id UUID PRIMARY KEY,
  agent_id UUID NOT NULL,
  user_id VARCHAR NOT NULL,
  provider VARCHAR NOT NULL,          -- e.g. "anthropic", "openai"
  model VARCHAR NOT NULL,             -- e.g. "claude-sonnet-4-6", "gpt-4o"
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);
```

- **agent_id + user_id** is unique: one override per user per agent
- **provider**: The LLM provider (must be configured in the gateway)
- **model**: The model name within that provider

## Planned Precedence Chain

> **Note:** This precedence chain is the planned behavior. It is not currently implemented — the runtime always uses the agent's configured provider/model.

```
1. User override exists?
   → Yes: use provider + model from user_agent_overrides  [PLANNED — not implemented]
   → No: proceed to step 2

2. Agent config has provider + model?
   → Yes: use agent's defaults  [ACTIVE]
   → No: proceed to step 3

3. Global default provider + model?
   → Yes: use global default  [ACTIVE]
   → No: error (no LLM configured)
```

## Store API (Available Now)

The store methods are implemented and usable directly:

### Setting an Override

```go
override := &store.UserAgentOverrideData{
  AgentID:  agentID,
  UserID:   "alice@example.com",
  Provider: "openai",
  Model:    "gpt-4o",
}
err := agentStore.SetUserOverride(ctx, override)
```

### Getting an Override

```go
override, err := agentStore.GetUserOverride(ctx, agentID, userID)
if override != nil {
  // override.Provider, override.Model are available
} else {
  // no override stored
}
```

### Deleting an Override

> **Note:** `DeleteUserOverride()` is defined in the store interface but not yet implemented in the PostgreSQL store. Calling it will return an error or no-op depending on the build.

```go
// Planned — not yet implemented in pg store:
err := agentStore.DeleteUserOverride(ctx, agentID, userID)
```

## WebSocket RPC — Planned

> **Note:** No WebSocket RPC methods for user overrides exist yet. The following is the planned interface:

```json
{
  "method": "agents.override.set",
  "params": {
    "agentId": "research-bot",
    "userId": "alice@example.com",
    "provider": "openai",
    "model": "gpt-4o"
  }
}
```

This method does not currently exist in the gateway.

## Dashboard User Settings — Planned

The Dashboard **Agent Preferences** UI for managing overrides is planned but not yet available.

## Use Cases (Planned)

These use cases describe the intended behavior once runtime integration is complete.

### Case 1: Cost Control
- Agent defaults to expensive GPT-4 for best quality
- Users on a budget can override to Claude 3 Haiku for cheaper runs

### Case 2: Personal Preference
- Research team prefers Claude for analysis
- Marketing team prefers GPT-4 for copy
- Single agent, two teams, two configurations

### Case 3: Feature Testing
- Team wants to test a new model on one agent
- Opt-in users set override; others stay on stable version

## Supported Providers & Models

Check your gateway config to see which providers/models are available. Common ones:

| Provider | Models |
|----------|--------|
| **anthropic** | claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-6 |
| **openai** | gpt-4o, gpt-4-turbo, gpt-3.5-turbo |
| **openai-compat** | depends on your custom provider (e.g., local Ollama) |

Ask your admin if you're unsure which are enabled.

## User Identity Resolution

When an agent runs, GoClaw must determine which tenant user identity to use for credential lookups. This is separate from the LLM override — it's about resolving the *credential user* from the incoming channel message.

The `UserIdentityResolver` interface (in `internal/agent/user_identity_resolver.go`) handles this:

```go
type UserIdentityResolver interface {
    ResolveTenantUserID(ctx context.Context, channelType, senderID string) (string, error)
}
```

### Resolution Logic

The agent loop calls `resolveCredentialUserID()` before tool execution:

| Scenario | Resolution |
|----------|-----------|
| **DM / HTTP / cron** | Resolve `UserID` via channel type → use resolved ID, fallback to raw `UserID` |
| **Group chat — individual sender** | Resolve numeric sender ID first (strips `senderID\|suffix` format) |
| **Group chat — group contact** | Extract `chatID` from `group:{channel}:{chatID}` format, resolve via contact store |

This ensures that cross-channel contacts (e.g., the same person on Telegram and WhatsApp) resolve to the same tenant user identity for consistent credential lookups.

### What It Affects

- Which stored credentials (API keys, tokens) the agent can access
- Per-user tool permissions that depend on tenant user identity
- Does **not** affect which LLM model or provider is used (see above)

## What's Next

- [System Prompt Anatomy — How model choice affects system prompt size](/system-prompt-anatomy)
- [Sharing and Access — Control who can access agents](/sharing-and-access)
- [Creating Agents — Set default provider/model when creating an agent](/creating-agents)



---

# System Prompt Anatomy

> Understand how GoClaw builds system prompts: 23 sections, assembled dynamically, with smart truncation so everything fits in context.

## Overview

Every time an agent runs, GoClaw assembles a **system prompt** from up to 23 sections. Sections are ordered strategically using **primacy and recency bias**: persona files appear both early (section 1.7) and late (section 16) to prevent drift in long conversations. Safety comes first, tooling next, then context. Some sections are always included; others depend on agent configuration.

Four **prompt modes** exist:

| Mode | Used for | Description |
|------|----------|-------------|
| `full` | Main user-facing agents | All sections — complete context, persona, memory, skills |
| `task` | Enterprise automation agents | Lean but capable — execution bias, skills search, safety slim |
| `minimal` | Subagents spawned via `spawn`, cron sessions | Reduced sections, faster startup |
| `none` | Identity-only contexts | Identity line only |

Mode is resolved in priority order: runtime override → auto-detect (heartbeat/subagent/cron) → agent config → default (`full`).

## All Sections in Order

| # | Section | Full | Minimal | Purpose |
|---|---------|------|---------|---------|
| 1 | Identity | ✓ | ✓ | Channel info (Telegram, Discord, etc.) |
| 1.5 | First-Run Bootstrap | ✓ | ✓ | BOOTSTRAP.md warning (first session only) |
| 1.7 | Persona | ✓ | ✓ | SOUL.md + IDENTITY.md injected early for primacy bias |
| 2 | Tooling | ✓ | ✓ | List of available tools + legacy/Claude Code aliases |
| 2.3 | Tool Call Style | ✓ | ✓ | Narration minimalism — never expose tool names to users |
| 2.5 | Credentialed CLI | ✓ | ✓ | Pre-configured CLI credentials context (when enabled) |
| 3 | Safety | ✓ | ✓ | Core safety rules, limits, confidentiality |
| 3.2 | Identity Anchoring | ✓ | ✓ | Extra guidance against identity manipulation (predefined agents only) |
| 3.5 | Self-Evolution | ✓ | ✓ | Permission to update SOUL.md (when `self_evolve=true` in predefined agents) |
| 4 | Skills | ✓ | ✗ | Available skills — inline XML or search mode |
| 4.5 | MCP Tools | ✓ | ✗ | External MCP integrations — inline or search mode |
| 6 | Workspace | ✓ | ✓ | Working directory, file paths |
| 6.3 | Team Workspace | ✓ | ✓ | Shared workspace path and auto-status guidance (team agents only) |
| 6.4 | Team Members | ✓ | ✓ | Team roster for task assignment (team agents only) |
| 6.45 | Delegation Targets | ✓ | ✓ | Agent link targets for `delegate` tool (ModeDelegate/ModeTeam only) |
| 6.5 | Sandbox | ✓ | ✓ | Sandbox-specific guidance (if sandbox enabled) |
| 7 | User Identity | ✓ | ✗ | Owner ID(s) |
| 8 | Time | ✓ | ✓ | Current date/time |
| 9.5 | Channel Formatting | ✓ | ✓ | Platform-specific formatting hints (e.g. Zalo plain-text-only) |
| 9.6 | Group Chat Reply Hint | ✓ | ✓ | Guidance on when NOT to reply in group chats |
| 10 | Additional Context | ✓ | ✓ | ExtraPrompt (subagent context, etc.) |
| 11 | Project Context | ✓ | ✓ | Remaining context files (AGENTS.md, USER.md, etc.) |
| 12.5 | Memory Recall | ✓ | ✗ | How to search/retrieve memory and knowledge graph |
| 13 | Sub-Agent Spawning | ✓ | ✓ | spawn tool guidance (skipped for team agents) |
| 15 | Runtime | ✓ | ✓ | Agent ID, channel info, group chat title |
| 16 | Recency Reinforcements | ✓ | ✓ | Persona reminder + memory reminder at end (combats "lost in the middle") |

## Primacy and Recency Strategy

GoClaw uses a deliberate **primacy + recency** pattern to prevent persona drift:

- **Section 1.7 (Persona)** — SOUL.md and IDENTITY.md are injected early so the model internalizes character before receiving any instructions
- **Section 16 (Recency Reinforcements)** — a short persona reminder and memory reminder at the very end of the prompt, because models weight recent context heavily

This means persona files appear **twice**: once at the top, once at the bottom. The ~30-token cost is worth it for long conversations where the middle content can cause the model to "forget" its character.

## Mode Differences

### When Each Mode Is Used

| Mode | Triggered by |
|------|-------------|
| `full` | Default for user-facing agents |
| `task` | Enterprise automation agents (set via `prompt_mode` config), or cron/subagent sessions capped at task |
| `minimal` | Subagents spawned via `spawn` (auto-detected from session key) |
| `none` | Rare — identity-only contexts |

### Section Differences by Mode

| Section | Full | Task | Minimal | None |
|---------|:----:|:----:|:-------:|:----:|
| Identity | ✓ | ✓ | ✓ | ✓ |
| First-Run Bootstrap | ✓ | ✓ | ✓ | ✓ |
| Persona | ✓ | ✓ | ✗ | ✗ |
| Tooling | ✓ | ✓ | ✓ | ✓ |
| Execution Bias | ✓ | ✓ | ✗ | ✗ |
| Tool Call Style | ✓ | ✗ | ✗ | ✗ |
| Safety | full | slim | slim | slim |
| Self-Evolution | ✓ | ✗ | ✗ | ✗ |
| Skills | ✓ | search-only | pinned only | ✗ |
| MCP Tools | ✓ | ✓ | ✗ | search-only |
| Workspace | ✓ | ✓ | ✓ | ✓ |
| Team / Delegation | ✓ | ✓ | ✓ | ✗ |
| Sandbox | ✓ | ✗ | ✗ | ✗ |
| User Identity | ✓ | ✗ | ✗ | ✗ |
| Time | ✓ | ✓ | ✓ | ✗ |
| Channel Formatting | ✓ | ✗ | ✗ | ✗ |
| Memory Recall | full | slim | minimal | ✗ |
| Project Context | ✓ | ✓ | ✓ | ✓ |
| Sub-Agent Spawning | ✓ | ✗ | ✗ | ✗ |
| Recency Reinforcements | ✓ | ✗ | ✗ | ✗ |

## Prompt Cache Boundary

GoClaw splits the system prompt at a hidden marker to enable Anthropic's prompt caching:

```


---

# Providers Overview

> Providers are the interface between GoClaw and LLM APIs — configure one (or many) and every agent can use it.

## Overview

A provider wraps an LLM API and exposes a common interface: `Chat()`, `ChatStream()`, `DefaultModel()`, and `Name()`. GoClaw has six concrete provider implementations: a native Anthropic client (custom HTTP+SSE), a generic OpenAI-compatible client that covers 15+ API endpoints, Claude CLI (local binary via stdio), Codex (OAuth-based ChatGPT Responses API), ACP (subagent orchestration via JSON-RPC 2.0), and DashScope (Alibaba Qwen). You pick which provider an agent uses via its config; the rest of the system is provider-agnostic.

## Provider Adapter System

GoClaw v3 introduces a pluggable **provider adapter** layer. Each provider type registers an adapter via `adapter_register.go`. Adapters share a common `SSEScanner` (`internal/providers/sse_reader.go`) that reads Server-Sent Events line-by-line, eliminating the per-provider streaming duplication that existed before.

```
SSEScanner
└── Shared by: Anthropic, OpenAI-compat, Codex adapters
    └── Reads SSE data payloads, tracks event types, stops at [DONE]
```

## Credential Resolver

The `internal/providerresolve/` package provides a unified **credential resolver** (`ResolveConfiguredProvider`) used across all adapters. It:

1. Looks up the provider from the tenant registry
2. For `chatgpt_oauth` (Codex) providers, resolves pool routing configuration from both provider-level defaults and agent-level overrides
3. Returns the correct `Provider` (or a `ChatGPTOAuthRouter` for pool strategies)

Credentials are stored encrypted (AES-256-GCM) in the `llm_providers` PostgreSQL table and decrypted at load time — never stored in memory as plaintext beyond the initial load.

## Provider Interface

Every provider implements the same Go interface:

```
Chat()        — blocking call, returns full response
ChatStream()  — streaming call, fires onChunk callback per token
DefaultModel() — returns the configured default model name
Name()        — returns provider identifier (e.g. "anthropic", "openai")
```

Providers that support extended thinking also implement `SupportsThinking() bool`.

## Supported Provider Types

| Provider | Type | Default Model |
|----------|------|---------------|
| **anthropic** | Native HTTP + SSE | `claude-sonnet-4-5-20250929` |
| **claude_cli** | stdio subprocess + MCP | `sonnet` |
| **codex** / **chatgpt_oauth** | OAuth Responses API | `gpt-5.3-codex` |
| **acp** | JSON-RPC 2.0 subagents | `claude` |
| **dashscope** | OpenAI-compat wrapper | `qwen3-max` |
| **vertex** | OpenAI-compat (OAuth2) | `google/gemini-2.0-flash-001` |
| **openai** (+ 15+ variants) | OpenAI-compatible | Model-specific |

### OpenAI-Compatible Providers

| Provider | API Base | Default Model |
|----------|----------|---------------|
| openai | `https://api.openai.com/v1` | `gpt-4o` |
| openrouter | `https://openrouter.ai/api/v1` | `anthropic/claude-sonnet-4-5-20250929` |
| groq | `https://api.groq.com/openai/v1` | `llama-3.3-70b-versatile` |
| deepseek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| gemini | `https://generativelanguage.googleapis.com/v1beta/openai` | `gemini-2.0-flash` |
| mistral | `https://api.mistral.ai/v1` | `mistral-large-latest` |
| xai | `https://api.x.ai/v1` | `grok-3-mini` |
| minimax | `https://api.minimax.io/v1` | `MiniMax-M2.5` |
| cohere | `https://api.cohere.ai/compatibility/v1` | `command-a` |
| perplexity | `https://api.perplexity.ai` | `sonar-pro` |
| ollama | `http://localhost:11434/v1` | `llama3.3` |
| byteplus | `https://ark.ap-southeast.bytepluses.com/api/v3` | `seed-2-0-lite-260228` |
| bailian | `https://coding-intl.dashscope.aliyuncs.com/v1` | `qwen3.5-plus` |
| kimi_coding | `https://api.kimi.com/coding/v1` | `kimi-k2-turbo-preview` |

## Adding a Provider

### Static config (config.json)

Add your API key under `providers.<name>`:

```json
{
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-..."
    },
    "openai": {
      "api_key": "sk-...",
      "api_base": "https://api.openai.com/v1"
    },
    "openrouter": {
      "api_key": "sk-or-..."
    }
  }
}
```

The `api_base` field is optional — each provider has a built-in default endpoint.

### Dashboard (llm_providers table)

Providers can also be stored in the `llm_providers` PostgreSQL table. API keys are encrypted at rest using AES-256-GCM. You can add, edit, or remove providers from the dashboard without restarting GoClaw. Changes take effect on the next request.

> **Note:** `provider_type` is immutable after creation — it cannot be changed via the API or dashboard. To switch provider types, delete and recreate the provider.

## Provider Architecture

```mermaid
graph TD
    Agent --> Registry
    Registry --> Resolver[Credential Resolver\nproviderresolve]
    Resolver --> Anthropic[AnthropicProvider\nnative HTTP+SSE]
    Resolver --> OAI[OpenAIProvider\nOpenAI-compat]
    Resolver --> ClaudeCLI[ClaudeCLIProvider\nstdio subprocess]
    Resolver --> Codex[CodexProvider\nOAuth Responses API]
    Resolver --> ACP[ACPProvider\nJSON-RPC 2.0]
    Resolver --> DashScope[DashScopeProvider\nOpenAI-compat wrapper]
    OAI --> OpenAI
    OAI --> OpenRouter
    OAI --> Gemini
    OAI --> DeepSeek
    OAI --> Groq
    OAI --> BytePlus
```

## Retry Logic

All providers share the same retry behavior via `RetryDo()`:

| Setting | Value |
|---|---|
| Max attempts | 3 |
| Initial delay | 300ms |
| Max delay | 30s |
| Jitter | ±10% |
| Retryable status codes | 429, 500, 502, 503, 504 |
| Retryable network errors | timeouts, connection reset, broken pipe, EOF |

When the API returns a `Retry-After` header (common on 429 responses), GoClaw uses that value instead of computing exponential backoff.

## BytePlus Media Generation (Seedream & Seedance)

The `byteplus` provider supports two async media generation capabilities via the BytePlus ModelArk platform:

| Tool | Model | Capability |
|------|-------|-----------|
| `create_image_byteplus` | Seedream (e.g. `seedream-3-0`) | Async image generation — submits a job and polls for the result |
| `create_video_byteplus` | Seedance (e.g. `seedance-1-0`) | Async video generation — submits a job and polls `/text-to-video-pro/status/{id}` |

Both tools are automatically available when a `byteplus` provider is configured. They share the same API key and `api_base` as the text provider; media endpoints are derived automatically (always `/api/v3`, not `/api/coding/v3`).

## ACP Provider (Claude Code, Codex CLI, Gemini CLI)

The `acp` provider orchestrates external coding agents (Claude Code, Codex CLI, Gemini CLI, or any ACP-compatible agent) as subprocesses via JSON-RPC 2.0 over stdio. Configure via `provider_type: "acp"` with `binary`, `work_dir`, `idle_ttl`, and `perm_mode` settings. See [ACP Provider](/provider-acp) for full details.

## Qwen 3.5 / DashScope Per-Model Thinking

The `dashscope` provider supports extended thinking for Qwen models with a per-model thinking guard. When tools are present, streaming is automatically disabled and GoClaw falls back to a single non-streaming call (DashScope limitation). Thinking budget mapping: low=4,096, medium=16,384, high=32,768 tokens.

## OpenAI GPT-5 / o-series Notes

For GPT-5 and o-series models, use `max_completion_tokens` instead of `max_tokens`. GoClaw automatically selects the correct parameter name based on model capabilities. Temperature is silently skipped for reasoning models that do not support it.

## Anthropic Prompt Caching

Anthropic prompt caching is applied via the `CacheMiddleware` in the request middleware pipeline. Model aliases are resolved before the cache key is computed — e.g., `sonnet` resolves to the full model name before the request is sent.

## Codex OAuth Pool Routing

When multiple `chatgpt_oauth` provider aliases are configured, GoClaw can route requests across them using a pool strategy. Configure this via `settings.codex_pool` on the pool-owner provider:

```json
{
  "name": "openai-codex",
  "provider_type": "chatgpt_oauth",
  "settings": {
    "codex_pool": {
      "strategy": "round_robin",
      "extra_provider_names": ["codex-work", "codex-personal"]
    }
  }
}
```

| Strategy | Behavior |
|----------|----------|
| `round_robin` | Rotates requests across the preferred account plus all extra accounts |
| `priority_order` | Tries the preferred account first, then drains extra accounts in order |
| `primary_first` | Keeps the preferred account fixed (disables pool for that agent) |

Retryable upstream failures fall through to the next eligible account in the same request. Pool activity per-agent is visible at `GET /v1/agents/{id}/codex-pool-activity`.

## Provider-Level `reasoning_defaults`

Providers (currently `chatgpt_oauth`) can store reusable reasoning defaults in `settings.reasoning_defaults`. Agents inherit them via `reasoning.override_mode: "inherit"` or override with `"custom"`. See [OpenAI provider](/provider-openai) for full details.

## Capability-Aware Reasoning Effort

Reasoning effort controls (`reasoning_effort`, `thinking_budget`, etc.) are resolved against model capabilities before each request. If the target model does not support reasoning effort, the parameter is silently dropped — no error is returned. This means you can configure reasoning effort globally and it will only be applied to models that support it.

## Datetime Tool for Provider Context

A built-in `datetime` tool is available in provider context, allowing agents and providers to access the current date and time. This is useful for time-sensitive reasoning and scheduling tasks without relying on the model's knowledge cutoff.

## Auto-Clamp max_tokens

When a model rejects a request because `max_tokens` is too large, GoClaw automatically retries with a clamped value. This handles both `max_tokens` and `max_completion_tokens` parameter names depending on the provider. The retry is transparent — the agent never sees the error.

## Tool Schema Normalization for MCP Tools

When GoClaw bridges MCP (Model Context Protocol) tools to a provider, tool schemas are normalized to match the provider's expected format. Field types, required arrays, and unsupported properties are adjusted automatically. This ensures MCP tools work across all provider backends without manual schema adaptation.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `provider not found: X` | Provider name typo or missing config | Check spelling in config.json matches provider name |
| `HTTP 401` | Invalid or missing API key | Verify API key is correct |
| `HTTP 429` | Rate limit hit | GoClaw retries automatically; reduce request concurrency |
| Provider not listed | Key not set | Add `api_key` to the provider's config block |

## What's Next

- [Anthropic](/provider-anthropic) — native Claude integration with extended thinking
- [OpenAI](/provider-openai) — GPT-4o, o-series, GPT-5 reasoning models
- [OpenRouter](/provider-openrouter) — access 100+ models through one API
- [Gemini](/provider-gemini) — Google Gemini via OpenAI-compatible endpoint
- [Vertex AI](/provider-vertex) — Google Cloud Vertex Gemini with OAuth2 / ADC
- [DeepSeek](/provider-deepseek) — DeepSeek with reasoning_content support
- [Groq](/provider-groq) — ultra-fast inference
- [DashScope](/provider-dashscope) — Alibaba Qwen models with thinking support
- [Bailian](/provider-bailian) — Alibaba Cloud Bailian Coding endpoint (separate from DashScope)
- [Kimi Coding](/provider-kimi) — Moonshot Kimi with fixed User-Agent and server-side thinking
- [ACP](/provider-acp) — Claude Code, Codex CLI, Gemini CLI subagent orchestration



---

# Anthropic

> GoClaw's native Claude integration — built directly on the Anthropic HTTP+SSE API with full support for extended thinking and prompt caching.

## Overview

The Anthropic provider is a first-class, hand-written HTTP client (not a third-party SDK). It speaks the Anthropic Messages API directly, handling streaming via SSE, tool use passback, and extended thinking blocks. The default model is `claude-sonnet-4-5-20250929`. Prompt caching is always enabled — GoClaw sets `cache_control: ephemeral` on every request.

## Prerequisites

- An Anthropic API key from [console.anthropic.com](https://console.anthropic.com)
- Sufficient quota for the models you plan to use

## config.json Setup

```json
{
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-api03-..."
    }
  }
}
```

To use a custom base URL (e.g. a proxy):

```json
{
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-...",
      "api_base": "https://your-proxy.example.com/v1"
    }
  }
}
```

## Dashboard Setup

In the GoClaw dashboard go to **Settings → Providers → Anthropic** and enter your API key. The key is encrypted with AES-256-GCM before being stored. Changes take effect immediately without a restart.

## Supported Models

| Model | Context Window | Notes |
|---|---|---|
| claude-opus-4-5 | 200k tokens | Most capable, highest cost |
| claude-sonnet-4-5-20250929 | 200k tokens | Default — best balance of speed and quality |
| claude-haiku-4-5 | 200k tokens | Fastest, lowest cost |
| claude-opus-4 | 200k tokens | Previous generation |
| claude-sonnet-4 | 200k tokens | Previous generation |

To override the default model for a specific agent, set `model` in the agent's config.

## Sampling Parameters (Claude 4.6+)

Newer Claude models reject sampling parameters unconditionally. For **Claude Opus/Sonnet 4.6+ and Opus 4.7+** (any `claude-opus-4-*` or `claude-sonnet-4-*` with a minor version of 6 or higher), GoClaw omits `temperature` — and per the same rule `top_p`/`top_k` — from **every** request, whether or not extended thinking is enabled. These models return `HTTP 400` if a sampling parameter is included.

This is separate from the thinking-path temperature strip described below (which removes `temperature` only while thinking is active, for all Claude models). You don't need to do anything: GoClaw drops the parameters automatically. Just avoid hard-coding sampling values in raw requests against these models.

## Extended Thinking

The Anthropic provider implements `SupportsThinking() bool` and returns `true`. When `thinking_level` is set on a request, GoClaw activates Anthropic's extended thinking feature automatically.

Token budgets by thinking level:

| Level | Budget |
|---|---|
| `low` | 4,096 tokens |
| `medium` | 10,000 tokens (default) |
| `high` | 32,000 tokens |

When thinking is enabled:
- The `anthropic-beta: interleaved-thinking-2025-05-14` header is sent
- Temperature is removed (Anthropic requires this)
- `max_tokens` is automatically raised to `budget + 8192` if the current value is too low
- Thinking blocks are preserved and passed back in tool use loops

Example agent config enabling thinking:

```json
{
  "options": {
    "thinking_level": "medium"
  }
}
```

## Prompt Caching

Prompt caching is always active. GoClaw sets `cache_control: ephemeral` on the system prompt and the last user turn (corrected in v3 — previously set on every content block, which could conflict with the Anthropic API's 4-checkpoint limit). The `Usage` response includes `cache_creation_input_tokens` and `cache_read_input_tokens` so you can monitor cache hit rates in tracing.

> **v3 correction:** The prompt caching implementation was fixed to correctly target cacheable positions. Agents with long system prompts will see improved cache hit rates after upgrading.

## Model Alias Resolution

GoClaw resolves Anthropic model aliases when listing available models. When `api_base` is set (e.g. for a proxy), model listing respects the custom base URL so alias resolution works correctly with API-compatible proxies.

## Tool Use

Anthropic uses a different tool schema format than OpenAI. GoClaw translates automatically:
- Tools are sent as `input_schema` (not `parameters`)
- Tool results are wrapped in `tool_result` content blocks
- When thinking is active, raw content blocks (including thinking signatures) are preserved and echoed back in subsequent tool loop iterations — required by the Anthropic API

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 401` | Invalid API key | Check key starts with `sk-ant-` |
| `HTTP 400` with thinking | temperature set alongside thinking | GoClaw removes temperature automatically; don't hard-code it in raw requests |
| `HTTP 400` mentioning temperature on a 4.6+ model | Claude Opus/Sonnet 4.6+ / Opus 4.7+ reject sampling params | GoClaw omits `temperature`/`top_p`/`top_k` automatically; don't hard-code sampling params |
| `HTTP 529` | Anthropic overloaded | Retry logic handles this; wait and retry |
| Thinking blocks not appearing | Model doesn't support thinking | Use claude-sonnet-4-5 or claude-opus-4-5 |
| High token costs | Cache not hitting | Ensure system prompt is stable across requests |

## What's Next

- [OpenAI](/provider-openai) — GPT-4o and o-series reasoning models
- [Overview](/providers-overview) — provider architecture and retry logic



---

# OpenAI

> Connect GoClaw to OpenAI's GPT-4o and o-series reasoning models using the standard OpenAI API.

## Overview

GoClaw uses a generic OpenAI-compatible provider (`OpenAIProvider`) for all OpenAI API requests. It supports both regular chat models (GPT-4o, GPT-4o-mini) and o-series reasoning models (o1, o3, o4-mini) that use `reasoning_effort` instead of temperature. Streaming uses SSE and includes usage stats in the final chunk via `stream_options.include_usage`.

## Prerequisites

- An OpenAI API key from [platform.openai.com](https://platform.openai.com)
- Credits or a pay-as-you-go billing plan

## config.json Setup

```json
{
  "providers": {
    "openai": {
      "api_key": "sk-..."
    }
  }
}
```

The default base URL is `https://api.openai.com/v1`. To use a custom endpoint (e.g. a local proxy):

```json
{
  "providers": {
    "openai": {
      "api_key": "sk-...",
      "api_base": "https://your-proxy.example.com/v1"
    }
  }
}
```

## Dashboard Setup

Go to **Settings → Providers → OpenAI** in the dashboard and enter your API key. Keys are encrypted with AES-256-GCM at rest.

## Supported Models

| Model | Context Window | Notes |
|---|---|---|
| gpt-4o | 128k tokens | Best multimodal model, supports vision |
| gpt-4o-mini | 128k tokens | Faster and cheaper than gpt-4o |
| o4-mini | 200k tokens | Fast reasoning model |
| o3 | 200k tokens | Advanced reasoning |
| o1 | 200k tokens | Original reasoning model |
| o1-mini | 128k tokens | Smaller reasoning model |

## Reasoning API

GoClaw supports a two-level reasoning configuration: provider-level defaults that apply to all agents, and per-agent overrides. This applies to o-series and GPT-5/Codex models.

### Provider-Level Defaults

Set reusable reasoning defaults on the provider itself using `settings.reasoning_defaults`. Every agent that uses this provider inherits these defaults automatically:

```json
{
  "name": "openai",
  "provider_type": "openai",
  "settings": {
    "reasoning_defaults": {
      "effort": "high",
      "fallback": "downgrade"
    }
  }
}
```

If no `reasoning_defaults` is configured on the provider, `inherit` resolves to reasoning off.

### Agent-Level Overrides

Agents can override or inherit the provider default using `reasoning.override_mode` in `other_config`:

```json
{
  "provider": "openai",
  "other_config": {
    "reasoning": {
      "override_mode": "inherit"
    }
  }
}
```

```json
{
  "provider": "openai",
  "other_config": {
    "reasoning": {
      "override_mode": "custom",
      "effort": "medium",
      "fallback": "off"
    }
  }
}
```

| `override_mode` | Behavior |
|---|---|
| `inherit` | Uses the provider's `reasoning_defaults` |
| `custom` | Uses the agent's own reasoning policy |

Agents without `override_mode` behave as `custom` (backward compatible).

### Effort Levels and Fallback Policy

Valid effort levels: `off`, `auto`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`.

Valid fallback values when the requested effort is not supported by the model:

| `fallback` | Behavior |
|---|---|
| `downgrade` (default) | Uses the highest supported level below the requested level |
| `off` | Disables reasoning entirely |
| `provider_default` | Falls back to the model's default effort |

### GPT-5 and Codex Effort Normalization

For known GPT-5 and Codex models, GoClaw validates and normalizes effort before sending the request. This avoids API errors when the requested level is not supported by that model variant:

| Model | Supported Levels | Default |
|---|---|---|
| gpt-5 | minimal, low, medium, high | medium |
| gpt-5.1 | none, low, medium, high | none |
| gpt-5.1-codex | low, medium, high | medium |
| gpt-5.2 | none, low, medium, high, xhigh | none |
| gpt-5.2-codex | low, medium, high, xhigh | medium |
| gpt-5.3-codex | low, medium, high, xhigh | medium |
| gpt-5.4 | none, low, medium, high, xhigh | none |
| gpt-5-mini / gpt-5.4-mini | none, low, medium, high, xhigh | none |

For unknown models (e.g. new releases), the requested effort is passed through as-is. Trace metadata exposes the resolved `source` and `effective_effort` so you can see what was actually sent.

### Legacy `thinking_level` (Backward Compat)

The earlier `options.thinking_level` key still works as a shorthand for the reasoning API:

```json
{
  "options": {
    "thinking_level": "high"
  }
}
```

This is a shim — GoClaw maps it to `reasoning_effort` internally. New configurations should use `reasoning.override_mode` with `effort` instead. Reasoning token usage is tracked in `Usage.ThinkingTokens` from `completion_tokens_details.reasoning_tokens`.

## Vision

GPT-4o supports image input. Send images as base64 in the `images` field of a message. GoClaw converts them to the OpenAI `image_url` content block format automatically:

```json
{
  "role": "user",
  "content": "What's in this image?",
  "images": [
    {
      "mime_type": "image/jpeg",
      "data": "<base64-encoded-bytes>"
    }
  ]
}
```

## Tool Use

OpenAI function calling works out of the box. GoClaw converts internal tool definitions to the OpenAI wire format (with `type: "function"` wrapper and `arguments` serialized as a JSON string) before sending.

## Native Image Generation (OpenAI-compat)

OpenAI-compatible providers support native image generation directly via a tool object in the request:

```json
{
  "tools": [{ "type": "image_generation" }]
}
```

GoClaw reads results from `choices[0].message.images[]` (or `choices[0].delta.images[]` when streaming) — each element is a data URL of the generated image. Images are saved to `{workspace}/media/{sha256}.{ext}` with embedded PNG metadata (model, prompt, timestamp). Streaming-aware: partial image events are surfaced as the final URL once the chunk is complete.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 401` | Invalid API key | Verify key at platform.openai.com |
| `HTTP 429` | Rate limit | GoClaw retries automatically; check your tier limits |
| `HTTP 400` on o-series | Unsupported parameter | Avoid setting `temperature` with o-series models |
| Vision not working | Model doesn't support images | Use gpt-4o or gpt-4o-mini |

### Developer Role (GPT-4o+)

For native OpenAI endpoints (`api.openai.com`), GoClaw automatically maps the `system` role to `developer` when sending requests. The `developer` role has higher instruction priority than `system` for GPT-4o and newer models.

This mapping only applies to native OpenAI infrastructure. Other OpenAI-compatible backends (Azure OpenAI, proxies, Qwen, DeepSeek, etc.) continue to use the standard `system` role.

## What's Next

- [OpenRouter](/provider-openrouter) — access 100+ models through one API key
- [Anthropic](/provider-anthropic) — native Claude integration
- [Overview](/providers-overview) — provider architecture and retry logic



---

# OpenRouter

> Access 100+ models from Anthropic, Google, Meta, Mistral, and more through a single API key.

## Overview

OpenRouter is an LLM aggregator that exposes a unified OpenAI-compatible endpoint. GoClaw uses the same `OpenAIProvider` implementation for OpenRouter, with one important difference: model IDs must include a provider prefix (e.g. `anthropic/claude-sonnet-4-5-20250929`). If you pass an unprefixed model name, GoClaw falls back to the configured default model automatically.

## Prerequisites

- An OpenRouter API key from [openrouter.ai](https://openrouter.ai)
- Credits loaded on your OpenRouter account

## config.json Setup

```json
{
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-..."
    }
  }
}
```

The default base URL is `https://openrouter.ai/api/v1`. You do not need to set `api_base` unless you are using a proxy.

## Dashboard Setup

Go to **Settings → Providers → OpenRouter** in the dashboard and paste your API key. It is encrypted with AES-256-GCM before storage.

## Model ID Format

OpenRouter requires model IDs in the format `provider/model-name`. Examples:

| Provider | Model ID |
|---|---|
| Anthropic Claude Sonnet | `anthropic/claude-sonnet-4-5-20250929` |
| Anthropic Claude Opus | `anthropic/claude-opus-4-5` |
| Google Gemini 2.5 Pro | `google/gemini-2.5-pro` |
| Meta Llama 3.3 70B | `meta-llama/llama-3.3-70b-instruct` |
| Mistral Large | `mistralai/mistral-large` |
| DeepSeek R1 | `deepseek/deepseek-r1` |

Browse all available models at [openrouter.ai/models](https://openrouter.ai/models).

## resolveModel Behavior

GoClaw's `resolveModel()` logic applies specifically to OpenRouter:

- If the model string contains `/` → use it as-is
- If the model string has no `/` → fall back to the provider's configured default model

This prevents sending bare model names (like `claude-sonnet-4-5`) that OpenRouter would reject.

To set a default model for OpenRouter in your agent config:

```json
{
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-4-5-20250929"
}
```

## Identification Headers

GoClaw automatically sends identification headers with every OpenRouter API request:

| Header | Value | Purpose |
|---|---|---|
| `HTTP-Referer` | `https://goclaw.sh` | Site identification for OpenRouter rankings |
| `X-Title` | `GoClaw` | App name shown in OpenRouter analytics |

These headers are sent for both config-file and dashboard-registered OpenRouter providers. No configuration needed — they are applied automatically.

## Supported Features

OpenRouter passes through most features to the underlying model provider. Availability depends on the model:

| Feature | Notes |
|---|---|
| Streaming | Supported for all models |
| Tool use / function calling | Supported for most models |
| Vision | Depends on model (e.g. GPT-4o, Claude Sonnet) |
| Reasoning / thinking | Depends on model (e.g. DeepSeek R1, o3) |
| Usage stats | Returned in final streaming chunk |

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 401` | Invalid API key | Check key starts with `sk-or-` |
| Model not found | Missing provider prefix | Use `provider/model-name` format |
| Unprefixed model falls back to default | `resolveModel()` behavior | Always include `/` in model IDs for OpenRouter |
| `HTTP 402` | Insufficient credits | Top up your OpenRouter account |
| Feature not supported | Underlying model limitation | Check model capabilities at openrouter.ai/models |

## What's Next

- [Gemini](/provider-gemini) — Google Gemini directly via OpenAI-compatible endpoint
- [OpenAI](/provider-openai) — direct OpenAI integration
- [Overview](/providers-overview) — provider architecture and retry logic



---

# Gemini

> Use Google's Gemini models in GoClaw via the OpenAI-compatible endpoint.

## Overview

GoClaw connects to Google Gemini through its OpenAI-compatible API (`https://generativelanguage.googleapis.com/v1beta/openai/`). It uses the same `OpenAIProvider` implementation as OpenAI and OpenRouter, but with special handling for Gemini's tool call format. Specifically, Gemini 2.5+ requires a `thought_signature` field echoed back on every tool call — GoClaw handles this automatically.

## Prerequisites

- A Google AI Studio API key from [aistudio.google.com](https://aistudio.google.com)
- Or a Google Cloud project with Vertex AI enabled (use the Vertex endpoint as `api_base`)

## config.json Setup

```json
{
  "providers": {
    "gemini": {
      "api_key": "AIza...",
      "api_base": "https://generativelanguage.googleapis.com/v1beta/openai/"
    }
  }
}
```

## Dashboard Setup

Go to **Settings → Providers → Gemini** in the dashboard and enter your API key and base URL. Both are stored encrypted with AES-256-GCM.

## Supported Models

| Model | Context Window | Notes |
|---|---|---|
| gemini-2.5-pro | 1M tokens | Most capable, supports thinking |
| gemini-2.5-flash | 1M tokens | Fast and cheap, supports thinking |
| gemini-2.0-flash | 1M tokens | Previous generation flash |
| gemini-1.5-pro | 2M tokens | Largest context window |
| gemini-1.5-flash | 1M tokens | Previous generation flash |

## Gemini-Specific Handling

### thought_signature passback

Gemini 2.5+ returns a `thought_signature` on tool calls. GoClaw stores this in `ToolCall.Metadata["thought_signature"]` and echoes it back in subsequent requests. This is required — sending a tool call without its signature causes an `HTTP 400`.

### Tool call collapsing

If a previous tool call in conversation history lacks a `thought_signature` (e.g. from an older model or a resumed session), GoClaw automatically collapses that tool call cycle: the assistant's tool calls are stripped, and the tool results are folded into a plain user message. This preserves context without triggering Gemini's signature validation error.

### Empty content handling

Gemini rejects assistant messages with empty `content` when tool calls are present. GoClaw omits the `content` field in that case rather than sending an empty string.

### Media input by URL

Image and video inputs supplied by URL are handled without you downloading them first. Image URLs are passed through directly to the vision request. For video, GoClaw streams the URL into the Gemini File API (upload → poll → `file_data`) over an SSRF-safe pinned HTTP client. See [Media Generation](/media-generation) for the full multimodal input/output reference.

## Thinking / Reasoning

Gemini 2.5 models support extended thinking. Set `thinking_level` in your agent options:

```json
{
  "options": {
    "thinking_level": "medium"
  }
}
```

GoClaw maps this to `reasoning_effort` on the request. Thinking tokens are tracked in `Usage.ThinkingTokens`.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 400` on tool use | Missing `thought_signature` | GoClaw handles this automatically via collapse logic |
| `HTTP 400` empty content | Empty assistant message content | GoClaw omits empty content automatically |
| `HTTP 403` | API key invalid or quota exceeded | Check key in AI Studio; verify billing |
| Model not found | Wrong model name | Check exact model IDs at [ai.google.dev](https://ai.google.dev/gemini-api/docs/models) |
| Thinking not working | Model doesn't support it | Use gemini-2.5-pro or gemini-2.5-flash |

## What's Next

- [DeepSeek](/provider-deepseek) — DeepSeek models with reasoning_content support
- [OpenRouter](/provider-openrouter) — access Gemini and 100+ other models through one key
- [Overview](/providers-overview) — provider architecture and retry logic



---

# DeepSeek

> Run DeepSeek's powerful reasoning models in GoClaw, with full support for reasoning_content streaming.

## Overview

GoClaw connects to DeepSeek via its OpenAI-compatible API using the generic `OpenAIProvider`. DeepSeek's reasoning models (R1 series) return a separate `reasoning_content` field alongside the standard response content. GoClaw captures this as `Thinking` in the response, and echoes it back as `reasoning_content` on subsequent assistant messages — which DeepSeek requires for correct multi-turn reasoning behavior.

## Prerequisites

- A DeepSeek API key from [platform.deepseek.com](https://platform.deepseek.com)
- Credits loaded on your DeepSeek account

## config.json Setup

```json
{
  "providers": {
    "deepseek": {
      "api_key": "sk-...",
      "api_base": "https://api.deepseek.com/v1"
    }
  }
}
```

## Dashboard Setup

Go to **Settings → Providers → DeepSeek** in the dashboard and enter your API key and base URL. Stored encrypted with AES-256-GCM.

## Supported Models

| Model | Context Window | Notes |
|---|---|---|
| deepseek-chat | 64k tokens | General-purpose chat model (DeepSeek V3) |
| deepseek-reasoner | 64k tokens | R1 reasoning model, returns reasoning_content |

## reasoning_content Support

DeepSeek's R1 model returns thinking as a separate `reasoning_content` field in the response delta. GoClaw handles this in both streaming and non-streaming modes:

- **Streaming:** `delta.reasoning_content` is captured and fired as `StreamChunk{Thinking: ...}` callbacks, then stored in `ChatResponse.Thinking`
- **Non-streaming:** `message.reasoning_content` is mapped to `ChatResponse.Thinking`

On the next turn, GoClaw automatically includes the previous assistant's thinking as `reasoning_content` in the request message — required by DeepSeek for the model to maintain its reasoning chain across turns.

To enable the reasoning model:

```json
{
  "provider": "deepseek",
  "model": "deepseek-reasoner"
}
```

You can also set `thinking_level` to control reasoning effort (maps to `reasoning_effort`):

```json
{
  "options": {
    "thinking_level": "high"
  }
}
```

## Tool Use

DeepSeek supports function calling with the standard OpenAI tool format. Tool call arguments arrive as a JSON string and are parsed by GoClaw before being passed to the tool handler.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 401` | Invalid API key | Verify key at platform.deepseek.com |
| `HTTP 402` | Insufficient credits | Top up your DeepSeek account |
| Reasoning content missing | Using deepseek-chat instead of deepseek-reasoner | Switch model to `deepseek-reasoner` |
| Multi-turn reasoning degrades | reasoning_content not echoed | GoClaw handles this automatically — ensure you're using the built-in agent loop |
| `HTTP 429` | Rate limit | GoClaw retries automatically with exponential backoff |

## What's Next

- [Groq](/provider-groq) — ultra-fast inference for open models
- [Gemini](/provider-gemini) — Google Gemini models
- [Overview](/providers-overview) — provider architecture and retry logic



---

# Groq

> Run open-source models at exceptional speed using Groq's LPU inference hardware.

## Overview

Groq provides an OpenAI-compatible API that delivers dramatically faster token generation than GPU-based providers — often 10–20x faster for supported models. GoClaw connects to Groq using the standard `OpenAIProvider` with no special handling required. The base URL points to `https://api.groq.com/openai/v1`.

## Prerequisites

- A Groq API key from [console.groq.com](https://console.groq.com)
- Groq's free tier is generous; paid plans available for higher rate limits

## config.json Setup

```json
{
  "providers": {
    "groq": {
      "api_key": "gsk_...",
      "api_base": "https://api.groq.com/openai/v1"
    }
  }
}
```

## Dashboard Setup

Go to **Settings → Providers → Groq** in the dashboard and enter your API key and base URL. Stored encrypted with AES-256-GCM.

## Supported Models

| Model | Context Window | Notes |
|---|---|---|
| llama-3.3-70b-versatile | 128k tokens | Best quality on Groq |
| llama-3.1-8b-instant | 128k tokens | Fastest, lowest latency |
| llama3-70b-8192 | 8k tokens | Previous generation 70B |
| llama3-8b-8192 | 8k tokens | Previous generation 8B |
| mixtral-8x7b-32768 | 32k tokens | Mixtral MoE model |
| gemma2-9b-it | 8k tokens | Google Gemma 2 |

Check [console.groq.com/docs/models](https://console.groq.com/docs/models) for the full and up-to-date list — Groq frequently adds new models.

## When to Use Groq

Groq excels at latency-sensitive workloads:

- **Interactive agents** where response speed matters more than raw capability
- **High-throughput pipelines** that process many short requests
- **Prototyping** where fast iteration beats per-token cost

For complex reasoning or very long contexts, consider [Anthropic](/provider-anthropic) or [OpenAI](/provider-openai) instead.

## Tool Use

Groq supports function calling on most models. GoClaw sends tools in standard OpenAI format. Note that tool call support varies by model — check Groq's model docs for the specific model you're using.

## Streaming

Streaming works via standard OpenAI SSE. GoClaw includes `stream_options.include_usage` in all streaming requests to capture token counts in the final chunk.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 401` | Invalid API key | Verify key starts with `gsk_` |
| `HTTP 429` | Rate limit (tokens per minute) | GoClaw retries; reduce concurrency or upgrade plan |
| Model not found | Model deprecated or name changed | Check current model list at console.groq.com |
| Tool calls not working | Model doesn't support function calling | Switch to llama-3.3-70b-versatile |
| Short context window | Older model selected | Use llama-3.3-70b-versatile (128k) |

## What's Next

- [Mistral](/provider-mistral) — Mistral AI models
- [DeepSeek](/provider-deepseek) — reasoning models with thinking content
- [Overview](/providers-overview) — provider architecture and retry logic



---

# Mistral

> Use Mistral AI's models in GoClaw via the OpenAI-compatible API.

## Overview

GoClaw connects to Mistral AI using the generic `OpenAIProvider` pointed at Mistral's OpenAI-compatible endpoint (`https://api.mistral.ai/v1`). No special handling is required — standard chat, streaming, and tool use all work out of the box. Mistral offers a range of models from the lightweight Mistral 7B to the frontier-class Mistral Large.

## Prerequisites

- A Mistral API key from [console.mistral.ai](https://console.mistral.ai)
- A Mistral account with an active subscription or credits

## config.json Setup

```json
{
  "providers": {
    "mistral": {
      "api_key": "...",
      "api_base": "https://api.mistral.ai/v1"
    }
  }
}
```

## Dashboard Setup

Go to **Settings → Providers → Mistral** in the dashboard and enter your API key and base URL. Stored encrypted with AES-256-GCM.

## Supported Models

| Model | Context Window | Notes |
|---|---|---|
| mistral-large-latest | 128k tokens | Most capable Mistral model |
| mistral-medium-latest | 128k tokens | Balanced performance and cost |
| mistral-small-latest | 128k tokens | Fast and affordable |
| codestral-latest | 256k tokens | Optimized for code generation |
| open-mistral-7b | 32k tokens | Open-weight, lowest cost |
| open-mixtral-8x7b | 32k tokens | Open-weight MoE model |
| open-mixtral-8x22b | 64k tokens | Open-weight large MoE model |

Check [docs.mistral.ai/getting-started/models](https://docs.mistral.ai/getting-started/models/) for the current model list and pricing.

## Tool Use

Mistral supports function calling on `mistral-large`, `mistral-small`, and `codestral`. GoClaw sends tools in standard OpenAI format — no conversion needed. Smaller open-weight models do not support tool use.

## Streaming

Streaming is supported on all Mistral models. GoClaw uses `stream_options.include_usage` to capture token counts at the end of each stream.

## Code Generation

For code-heavy agents, `codestral-latest` is optimized for programming tasks and has a 256k token context window — the largest in Mistral's lineup. Point your agent at it directly:

```json
{
  "provider": "mistral",
  "model": "codestral-latest"
}
```

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `HTTP 401` | Invalid API key | Verify key at console.mistral.ai |
| `HTTP 422` on tool use | Model doesn't support function calling | Use mistral-large or mistral-small |
| `HTTP 429` | Rate limit | GoClaw retries automatically; check your plan limits |
| Model not found | Name changed or deprecated | Check current names at docs.mistral.ai |
| High latency | Large model selected | Switch to mistral-small-latest for faster responses |

## What's Next

- [Overview](/providers-overview) — provider architecture and retry logic
- [Groq](/provider-groq) — ultra-fast inference for open models
- [OpenRouter](/provider-openrouter) — access Mistral and 100+ other models through one key



---

# xAI (Grok)

Connect GoClaw to xAI's Grok models using the OpenAI-compatible API.

## Overview

xAI's Grok models are available through an OpenAI-compatible endpoint at `https://api.x.ai/v1`. GoClaw uses the same `OpenAIProvider` it shares with OpenAI, Groq, and others — you just point it at xAI's base URL with your xAI API key. All standard features work: streaming, tool calls, and thinking tokens.

## Setup

Add your xAI API key to `config.json`:

```json
{
  "providers": {
    "xai": {
      "api_key": "$XAI_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "xai",
      "model": "grok-3"
    }
  }
}
```

Store your key in `.env.local` (never in `config.json` directly):

```bash
XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxx
```

GoClaw resolves `$XAI_API_KEY` from your environment at startup.

## Models

Popular Grok models you can use in the `model` field:

| Model | Notes |
|---|---|
| `grok-3` | Latest flagship model |
| `grok-3-mini` | Smaller, faster, cheaper |
| `grok-2-vision-1212` | Multimodal (images + text) |

Set the default in `agents.defaults.model`, or pass `model` per-request via the API.

## Examples

**Minimal config for Grok-3:**

```json
{
  "providers": {
    "xai": {
      "api_key": "$XAI_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "xai",
      "model": "grok-3",
      "max_tokens": 8192
    }
  }
}
```

**Custom API base (if you proxy xAI traffic):**

```json
{
  "providers": {
    "xai": {
      "api_key": "$XAI_API_KEY",
      "api_base": "https://your-proxy.example.com/xai/v1"
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Wrong or missing API key | Check `XAI_API_KEY` in `.env.local` |
| `404 Not Found` | Wrong model name | Check [xAI model list](https://docs.x.ai/docs/models) |
| Model returns no content | Context too large | Reduce `max_tokens` or shorten history |

## What's Next

- [MiniMax](/provider-minimax) — another OpenAI-compatible provider with a custom chat path
- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API



---

# MiniMax

Connect GoClaw to MiniMax models using their OpenAI-compatible API with a custom chat endpoint.

## Overview

MiniMax provides an OpenAI-compatible API, but their native endpoint path differs from the standard `/chat/completions`. GoClaw handles this automatically using a custom chat path (`/text/chatcompletion_v2`) under the hood — you just configure your API key and everything works, including streaming and tool calls.

## Setup

Add your MiniMax API key to `config.json`:

```json
{
  "providers": {
    "minimax": {
      "api_key": "$MINIMAX_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "minimax",
      "model": "MiniMax-Text-01"
    }
  }
}
```

Store your key in `.env.local`:

```bash
MINIMAX_API_KEY=your-minimax-api-key
```

The default API base is `https://api.minimax.chat/v1` and GoClaw automatically routes to `/text/chatcompletion_v2` instead of the standard `/chat/completions`. You don't need to configure this manually.

## Custom API Base

If you use MiniMax's international endpoint:

```json
{
  "providers": {
    "minimax": {
      "api_key": "$MINIMAX_API_KEY",
      "api_base": "https://api.minimaxi.chat/v1"
    }
  }
}
```

## Models

| Model | Notes |
|---|---|
| `MiniMax-Text-01` | Large context (up to 1M tokens) |
| `abab6.5s-chat` | Fast, efficient general-purpose model |
| `abab5.5-chat` | Older generation, lower cost |

## Examples

**Minimal config:**

```json
{
  "providers": {
    "minimax": {
      "api_key": "$MINIMAX_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "minimax",
      "model": "MiniMax-Text-01",
      "max_tokens": 4096,
      "temperature": 0.7
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Invalid API key | Verify `MINIMAX_API_KEY` in `.env.local` |
| `404` on chat endpoint | Wrong `api_base` region | Use the correct MiniMax endpoint for your region |
| Empty response | Model name typo | Check MiniMax docs for exact model IDs |
| Tool calls fail | Schema incompatibility | MiniMax follows OpenAI tool format; ensure your tool schemas are valid JSON Schema |

## What's Next

- [Cohere](/provider-cohere) — another OpenAI-compatible provider
- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API



---

# Cohere

Connect GoClaw to Cohere's Command models using their OpenAI-compatible API.

## Overview

Cohere offers an OpenAI-compatible endpoint, which means GoClaw's standard `OpenAIProvider` handles all communication — streaming, tool calls, and usage tracking work out of the box. Cohere's Command R and Command R+ models are particularly strong at retrieval-augmented generation (RAG) and tool use.

## Setup

Add your Cohere API key to `config.json`:

```json
{
  "providers": {
    "cohere": {
      "api_key": "$COHERE_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "cohere",
      "model": "command-r-plus"
    }
  }
}
```

Store your key in `.env.local`:

```bash
COHERE_API_KEY=your-cohere-api-key
```

The default API base is `https://api.cohere.com/compatibility/v1`. GoClaw sets this automatically when you configure the `cohere` provider.

## Models

| Model | Notes |
|---|---|
| `command-r-plus` | Best accuracy, best for complex tasks and RAG |
| `command-r` | Balanced performance and cost |
| `command-light` | Fastest and cheapest, good for simple tasks |

## Examples

**Minimal config:**

```json
{
  "providers": {
    "cohere": {
      "api_key": "$COHERE_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "cohere",
      "model": "command-r-plus",
      "max_tokens": 4096
    }
  }
}
```

**Custom API base (if you proxy Cohere):**

```json
{
  "providers": {
    "cohere": {
      "api_key": "$COHERE_API_KEY",
      "api_base": "https://your-proxy.example.com/cohere/v1"
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Missing or invalid API key | Check `COHERE_API_KEY` in `.env.local` |
| `model not found` | Wrong model ID | Use exact model IDs from [Cohere docs](https://docs.cohere.com/docs/models) |
| Tool calls return errors | Schema issues | Cohere's tool format is OpenAI-compatible; verify your tool parameter schemas |
| Slow responses | Large context window | Command R models are slower on long contexts; consider `command-light` for speed |

## What's Next

- [Perplexity](/provider-perplexity) — search-augmented AI via OpenAI-compatible API
- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API



---

# Ollama

> Run open-source models locally with Ollama — no cloud required.

🚧 **This page is under construction.** Content coming soon — contributions welcome!

## Overview

Ollama lets you run large language models on your own machine. GoClaw connects to Ollama using the OpenAI-compatible API it exposes locally, so no data leaves your infrastructure.

## Provider Type

```json
{
  "providers": {
    "ollama": {
      "provider_type": "ollama",
      "api_base": "http://localhost:11434/v1"
    }
  }
}
```

## Docker Deployment

When running GoClaw inside Docker, `localhost` and `127.0.0.1` in provider URLs are automatically rewritten to `host.docker.internal` so the container can reach Ollama running on the host machine. No manual configuration needed.

If Ollama is running on a different host, set the full URL explicitly:

```json
{
  "providers": {
    "ollama": {
      "provider_type": "ollama",
      "api_base": "http://my-ollama-server:11434/v1"
    }
  }
}
```

## What's Next

- [Provider Overview](/providers-overview)
- [Ollama Cloud](/provider-ollama-cloud) — hosted Ollama option
- [Custom / OpenAI-Compatible](/provider-custom)



---

# Ollama Cloud

> Use Ollama-compatible models via cloud hosting — the convenience of hosted inference with Ollama's open model ecosystem.

🚧 **This page is under construction.** Content coming soon — contributions welcome!

## Overview

Ollama Cloud provides hosted inference for Ollama-compatible models. GoClaw connects using the OpenAI-compatible API, giving you access to open-source models without managing local hardware.

## Provider Type

```json
{
  "providers": {
    "ollama-cloud": {
      "provider_type": "ollama-cloud",
      "api_key": "your-ollama-cloud-api-key",
      "api_base": "https://api.ollama.ai/v1"
    }
  }
}
```

## What's Next

- [Provider Overview](/providers-overview)
- [Ollama](/provider-ollama) — run models locally instead
- [Custom / OpenAI-Compatible](/provider-custom)



---

# Perplexity

Connect GoClaw to Perplexity's search-augmented AI models via their OpenAI-compatible API.

## Overview

Perplexity models combine language model generation with live web search, making them ideal for agents that need up-to-date information. GoClaw connects to Perplexity through the standard `OpenAIProvider` — the same code path used by OpenAI and Groq — so streaming and tool calls work without any special configuration.

## Setup

Add your Perplexity API key to `config.json`:

```json
{
  "providers": {
    "perplexity": {
      "api_key": "$PERPLEXITY_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "perplexity",
      "model": "sonar-pro"
    }
  }
}
```

Store your key in `.env.local`:

```bash
PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxxxxxxxxxx
```

The default API base is `https://api.perplexity.ai`. GoClaw routes requests to `/chat/completions` as usual.

## Models

| Model | Notes |
|---|---|
| `sonar-pro` | Flagship search-augmented model, highest accuracy |
| `sonar` | Faster and cheaper search-augmented model |
| `sonar-reasoning` | Reasoning + search, good for complex queries |
| `sonar-reasoning-pro` | Best reasoning with live search |

Perplexity's `sonar` models automatically perform web searches before answering. You don't need to configure search separately.

## Examples

**Minimal config:**

```json
{
  "providers": {
    "perplexity": {
      "api_key": "$PERPLEXITY_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "perplexity",
      "model": "sonar-pro",
      "max_tokens": 2048
    }
  }
}
```

**Use Perplexity only for a specific agent while others use a different provider:**

```json
{
  "providers": {
    "anthropic": { "api_key": "$ANTHROPIC_API_KEY" },
    "perplexity": { "api_key": "$PERPLEXITY_API_KEY" }
  },
  "agents": {
    "defaults": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-5"
    },
    "list": {
      "research-agent": {
        "provider": "perplexity",
        "model": "sonar-pro"
      }
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Invalid API key | Verify `PERPLEXITY_API_KEY` in `.env.local` |
| Search results seem stale | Using a non-sonar model | Switch to a `sonar` variant for live web search |
| High latency | Search adds round-trip time | Expected behavior; `sonar` is faster than `sonar-pro` |
| Tool calls not supported | Perplexity sonar models don't support function calling | Use Perplexity for research tasks; handle tool calls with a different provider |

## What's Next

- [DashScope](/provider-dashscope) — Alibaba's Qwen models via OpenAI-compatible API
- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API



---

# DashScope (Alibaba Qwen)

Connect GoClaw to Alibaba's Qwen models via the DashScope OpenAI-compatible API.

## Overview

DashScope is Alibaba's model serving platform, offering the Qwen family of models. GoClaw uses a dedicated `DashScopeProvider` that wraps the standard OpenAI-compatible layer and adds one critical workaround: **DashScope does not support tool calls and streaming simultaneously**. When your agent uses tools, GoClaw automatically falls back to a non-streaming request and then synthesizes streaming callbacks for the caller — so your agent works correctly without any code changes.

DashScope also supports extended thinking via `thinking_level`, which GoClaw maps to DashScope-specific `enable_thinking` and `thinking_budget` parameters.

> **Note:** `dashscope` is a different provider type from `bailian`. Alibaba Cloud's Bailian Coding endpoint (`https://coding-intl.dashscope.aliyuncs.com/v1`, default `qwen3.5-plus`) is a separate OpenAI-compatible provider with a hardcoded catalog and **no** thinking injection. If you need the Coding endpoint or models like `qwen3.7-plus`, see [Bailian](/provider-bailian).

## Setup

Add your DashScope API key to `config.json`:

```json
{
  "providers": {
    "dashscope": {
      "api_key": "$DASHSCOPE_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "dashscope",
      "model": "qwen3-max"
    }
  }
}
```

Store your key in `.env.local`:

```bash
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
```

The default API base is `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` (international endpoint). For China-region access, set `api_base` to `https://dashscope.aliyuncs.com/compatible-mode/v1`.

## Models

| Model | Notes |
|---|---|
| `qwen3-max` | Best accuracy (default) |
| `qwen3-plus` | Balanced performance and cost |
| `qwen3-turbo` | Fastest Qwen3 model |
| `qwen3-235b-a22b` | Open-weight, MoE architecture |
| `qwq-32b` | Extended thinking / reasoning model |
| `qwen3.5-max` | Qwen 3.5 series, highest capability |
| `qwen3.5-plus` | Qwen 3.5 series, balanced |
| `qwen3.5-turbo` | Qwen 3.5 series, fastest |

## Per-Model Thinking Guard

GoClaw uses a simplified per-model guard to decide whether to send `enable_thinking` and `thinking_budget` parameters. Only models that actually support extended thinking receive these parameters — other models silently ignore the `thinking_level` setting. In v3, this logic was simplified (previously had redundant checks that could cause incorrect behavior for some model names).

**Models that support thinking:** `qwq-32b`, and Qwen 3.5 series models with thinking capability.

## Thinking (Extended Reasoning)

For models that support extended thinking (like `qwq-32b`), set `thinking_level` in your agent options:

```json
{
  "agents": {
    "defaults": {
      "provider": "dashscope",
      "model": "qwq-32b",
      "thinking_level": "medium"
    }
  }
}
```

GoClaw maps `thinking_level` to DashScope's `thinking_budget`:

| Level | Budget (tokens) |
|---|---|
| `low` | 4,096 |
| `medium` | 16,384 (default) |
| `high` | 32,768 |

## Examples

**Minimal config with international endpoint:**

```json
{
  "providers": {
    "dashscope": {
      "api_key": "$DASHSCOPE_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "dashscope",
      "model": "qwen3-max",
      "max_tokens": 8192
    }
  }
}
```

**China-region endpoint:**

```json
{
  "providers": {
    "dashscope": {
      "api_key": "$DASHSCOPE_API_KEY",
      "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Invalid API key | Verify `DASHSCOPE_API_KEY` in `.env.local` |
| Slow tool call responses | Tools disable streaming; GoClaw uses non-streaming fallback | Expected — DashScope limitation; response is still delivered |
| Thinking content missing | Model doesn't support thinking | Use `qwq-32b` or another thinking-capable model |
| `404` on requests | Wrong region endpoint | Set `api_base` to China or international endpoint as appropriate |

## What's Next

- [Claude CLI](/provider-claude-cli) — unique provider that shells out to the Claude Code CLI binary
- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API
- [Bailian](/provider-bailian) — Alibaba Cloud Bailian Coding endpoint (separate from DashScope)



---

# Vertex AI

> Use Google Cloud Vertex AI's OpenAI-compatible Gemini endpoint with OAuth2 service-account or Application Default Credentials.

## Overview

GoClaw connects to Google Cloud Vertex AI through its OpenAI-compatible API. Internally the provider is an `OpenAIProvider` instance wired with a Google OAuth2 token source — every request is signed with a short-lived bearer token that the gateway refreshes transparently every hour.

The endpoint URL is built from your GCP project and region:

```
https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/endpoints/openapi
```

So with project `acme-prod` and region `us-central1`, requests target `https://us-central1-aiplatform.googleapis.com/v1/projects/acme-prod/locations/us-central1/endpoints/openapi`.

## Prerequisites

- A Google Cloud project with the **Vertex AI API** enabled.
- Either:
  - A service-account JSON key with the `roles/aiplatform.user` role, **or**
  - Application Default Credentials (`gcloud auth application-default login` for local dev, or the metadata server on GCE/GKE/Cloud Run).
- The OAuth scope `https://www.googleapis.com/auth/cloud-platform` is requested automatically — you do not configure it.

## Credential precedence

When the provider starts up it walks credential sources in this order and stops at the first hit:

1. **Inline JSON** — `credentials_json` (DB Settings field) or `providers.vertex.api_key` (config.json). Service-account JSON pasted verbatim.
2. **File path** — `credentials_file` env-resolved path. **Operator-only.** This path is read from disk by the gateway process; never expose it via the admin UI without a strict path allowlist.
3. **Application Default Credentials** — falls back to `GOOGLE_APPLICATION_CREDENTIALS`, gcloud user creds, or the GCP metadata server. ADC discovery is capped at 10 seconds so a missing metadata server cannot stall startup.

## config.json setup

```json
{
  "providers": {
    "vertex": {
      "api_key": "{\"type\":\"service_account\",\"project_id\":\"acme-prod\", ... }",
      "credentials_file": "",
      "project_id": "acme-prod",
      "region": "us-central1",
      "model": "google/gemini-2.0-flash-001"
    }
  }
}
```

The provider only initializes when **both** `project_id` and `region` are set. `api_key` accepts the entire service-account JSON as a single string. To rely on ADC instead, leave `api_key` and `credentials_file` empty.

## Dashboard setup

Create the provider from **Settings → Providers → Add provider** with `provider_type: "vertex"`. Vertex-specific fields live under `settings`:

```json
{
  "name": "vertex-prod",
  "provider_type": "vertex",
  "api_key": "{\"type\":\"service_account\", ... }",
  "settings": {
    "project_id": "acme-prod",
    "region": "us-central1",
    "model": "google/gemini-2.5-pro-001"
  }
}
```

API keys and settings are encrypted at rest with AES-256-GCM. The DB-driven provider also walks the credential precedence above — leave `api_key` empty to use ADC on the gateway host.

## Supported models

Vertex AI's OpenAI-compatible endpoint accepts any Gemini model that Google publishes under the `google/` namespace, for example:

| Model ID | Notes |
|----------|-------|
| `google/gemini-2.0-flash-001` | Default |
| `google/gemini-2.5-pro-001` | Largest context, supports thinking |
| `google/gemini-2.5-flash-001` | Fast, supports thinking |
| `google/gemini-1.5-pro-002` | Previous generation, 2M context |

Always include the `google/` prefix — Vertex's OpenAI shim requires it. Check the [Vertex model catalog](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models) for the current list of regional availability.

## Region and project validation

The provider validates both values before making any network call:

- `project_id` — 6–30 lowercase letters/digits/hyphens, must start with a letter (GCP project ID format).
- `region` — lowercase, hyphen-separated alphanumeric segments (e.g. `us-central1`, `asia-southeast1`).

A malformed value fails fast at startup. If you supply an `api_base_override`, the gateway also rejects URLs whose host is not under `*.googleapis.com` — protection against pointing the provider at an attacker-controlled endpoint while still authenticating to Google.

## Examples

### Quick smoke test from the agent loop

```json
{
  "model": "google/gemini-2.0-flash-001",
  "options": {
    "temperature": 0.2
  }
}
```

### Pinning a per-request model

Because Vertex shares the `OpenAIProvider` adapter, every request honors a per-request `model` override. Inline-message webhooks and the standard agent loop both accept it.

### Inline credentials in config.json

```json
{
  "providers": {
    "vertex": {
      "api_key": "{\n  \"type\": \"service_account\",\n  \"project_id\": \"acme-prod\",\n  \"private_key_id\": \"...\",\n  \"private_key\": \"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\n  \"client_email\": \"goclaw-vertex@acme-prod.iam.gserviceaccount.com\",\n  \"token_uri\": \"https://oauth2.googleapis.com/token\"\n}",
      "project_id": "acme-prod",
      "region": "us-central1"
    }
  }
}
```

### ADC on GKE / Cloud Run

Leave both `api_key` and `credentials_file` empty and grant the workload's service account `roles/aiplatform.user`. The provider picks up tokens from the metadata server automatically.

## Streaming, tools, and vision

The Vertex provider speaks OpenAI ChatCompletions through the same code path as the OpenAI and Gemini OpenAI-compatible adapters. Streaming, function/tool calling, and image inputs work the same way they do for `openai` or `gemini`. Extended thinking on Gemini 2.5 models is mapped from `thinking_level` to `reasoning_effort` automatically (see [Gemini](/provider-gemini) for the thinking_signature passback details).

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| `vertex: project_id is required` | Project or region missing | Set both `project_id` and `region` |
| `vertex: invalid project_id` | ID has uppercase, underscores, or wrong length | Use the canonical GCP project ID (6–30 lowercase chars) |
| `vertex: application default credentials not found` | No ADC source on host | Set `GOOGLE_APPLICATION_CREDENTIALS`, pass `credentials_file`, or run on GCP |
| `vertex: parse inline credentials` | `api_key` is not valid service-account JSON | Paste the entire JSON file unmodified |
| `403 Permission denied` from Vertex | Service account missing role | Grant `roles/aiplatform.user` |
| `HTTP 429` | Quota exceeded | Request a quota bump in the GCP console; GoClaw retries automatically |
| Model not found | Wrong model ID or wrong region | Confirm the model is available in the configured region; keep the `google/` prefix |

## What's Next

- [Gemini](/provider-gemini) — Gemini via the Google AI Studio OpenAI-compatible endpoint
- [OpenAI](/provider-openai) — shared OpenAI-compatible adapter notes
- [Providers Overview](/providers-overview) — adapter system, retry logic, credential resolver



---

# Bailian

> Connect to Alibaba Cloud Bailian (百炼) Coding models via the OpenAI-compatible endpoint.

## Overview

Bailian is Alibaba Cloud's AI model platform. GoClaw connects to its **Coding** endpoint using the OpenAI-compatible API format. The `bailian` provider type is **distinct from `dashscope`** — they are separate endpoints with different base URLs and different model catalogs. The DashScope `enable_thinking`/`thinking_budget` injection path does **not** apply to Bailian; Bailian is treated as a plain OpenAI-compatible provider.

- **Provider type:** `bailian`
- **Default model:** `qwen3.5-plus`
- **Default API base:** `https://coding-intl.dashscope.aliyuncs.com/v1`

## Setup

Add your Bailian API key to `config.json` under the `bailian` provider block:

```json
{
  "providers": {
    "bailian": {
      "api_key": "$GOCLAW_BAILIAN_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "provider": "bailian",
      "model": "qwen3.5-plus"
    }
  }
}
```

Store your key in `.env.local`:

```bash
GOCLAW_BAILIAN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
```

The `api_base` field is optional — it defaults to `https://coding-intl.dashscope.aliyuncs.com/v1`. You can also add Bailian from the dashboard (**Settings → Providers**); keys are encrypted with AES-256-GCM at rest.

## Models

The Bailian Coding platform does **not** expose a standard `/v1/models` endpoint, so GoClaw ships a **hardcoded catalog**. The following models are available:

| Model | Notes |
|---|---|
| `qwen3.7-plus` | Qwen 3.7 Plus — Text Generation, Deep Thinking, Visual Understanding |
| `qwen3.6-plus` | Qwen 3.6 Plus |
| `qwen3.5-plus` | Qwen 3.5 Plus (default) |
| `kimi-k2.5` | Kimi K2.5 |
| `GLM-5` | GLM-5 |
| `MiniMax-M2.5` | MiniMax M2.5 |
| `qwen3-max-2026-01-23` | Qwen 3 Max (2026-01-23) |
| `qwen3-coder-next` | Qwen 3 Coder Next |
| `qwen3-coder-plus` | Qwen 3 Coder Plus |
| `glm-4.7` | GLM 4.7 |

## Bailian vs DashScope

Both connect to Alibaba infrastructure, but they are different providers:

| | `bailian` | `dashscope` |
|---|---|---|
| Endpoint | `https://coding-intl.dashscope.aliyuncs.com/v1` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
| Default model | `qwen3.5-plus` | `qwen3-max` |
| Model listing | Hardcoded catalog (no `/v1/models`) | Live listing |
| Thinking injection | None (plain OpenAI-compatible) | `enable_thinking` + `thinking_budget` |

If you want DashScope-style extended thinking, use the [DashScope](/provider-dashscope) provider instead.

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Invalid API key | Verify `GOCLAW_BAILIAN_API_KEY` in `.env.local` |
| Model not listed | Catalog is hardcoded | Use a model ID from the table above; the Coding API has no `/v1/models` endpoint |
| Thinking has no effect | Bailian is plain OpenAI-compatible | DashScope thinking injection does not apply; use the `dashscope` provider for `enable_thinking` |

## What's Next

- [Provider Overview](/providers-overview)
- [DashScope (Qwen)](/provider-dashscope) — Alibaba Qwen models with thinking support
- [Kimi Coding](/provider-kimi) — Moonshot Kimi Coding endpoint



---

# Kimi Coding (Moonshot)

> Connect GoClaw to Moonshot's Kimi Coding models via the OpenAI-compatible Coding endpoint.

## Overview

Kimi Coding is Moonshot AI's coding-focused endpoint. GoClaw connects to it as an OpenAI-compatible provider (`provider_type: "kimi_coding"`), reusing the standard `OpenAIProvider` with three Kimi-specific adjustments wired in automatically: a **fixed `User-Agent` header**, a **temperature lock**, and **mandatory `reasoning_content`** on assistant tool-call messages. You don't configure any of these — GoClaw handles them so your agent works out of the box.

- **Provider type:** `kimi_coding`
- **Default model:** `kimi-k2-turbo-preview`
- **Default API base:** `https://api.kimi.com/coding/v1`

## Setup

Kimi Coding is added from the **dashboard** (it has no static `config.json` provider block). In the GoClaw dashboard:

1. Go to **Settings → Providers → Add**
2. Choose **"Kimi Coding (Moonshot)"** — the API base is pre-filled with `https://api.kimi.com/coding/v1`
3. Paste your Kimi API key
4. Save — the key is encrypted with AES-256-GCM at rest, and changes take effect on the next request

Then point an agent at it:

```json
{
  "agents": {
    "defaults": {
      "provider": "kimi",
      "model": "kimi-k2-turbo-preview"
    }
  }
}
```

> Use the **name** you gave the provider when you created it (e.g. `kimi`) as the agent's `provider` value. The `provider_type` (`kimi_coding`) is the immutable type selected from the dropdown.

## Models

| Model | Notes |
|---|---|
| `kimi-k2-turbo-preview` | Default — server-side thinking is on by default |

The API base defaults to `https://api.kimi.com/coding/v1` if you leave it blank.

## Non-Standard Behaviors

Kimi Coding has three quirks that upstream enforces strictly. GoClaw handles all of them for you.

### 1. Fixed `User-Agent`

Every request — including the model-listing call — is sent with a fixed header `User-Agent: claude-code/0.1.0`. Upstream rejects requests that don't carry this exact User-Agent. GoClaw injects it automatically via the provider's extra headers; you don't set it.

### 2. Temperature lock

The Kimi server locks `temperature` to `1` and rejects any override. GoClaw therefore **omits `temperature`** from the request body for `kimi_coding` providers (the same treatment given to OpenAI `o1`/`o3`/`o4` and `gpt-5-mini`/`gpt-5-nano`). Passing a temperature value to the raw API returns `HTTP 400 invalid temperature: only 1 is allowed for this model`.

### 3. `reasoning_content` required on tool calls

`kimi-k2-turbo-preview` has server-side thinking enabled by default. When an assistant message that contains `tool_calls` is replayed in conversation history, it **must** carry a `reasoning_content` field — otherwise upstream returns `HTTP 400 thinking is enabled but reasoning_content is missing in assistant tool call message at index N`. GoClaw preserves captured reasoning when it has it, and emits an **empty `reasoning_content` string** when none was captured, so multi-turn tool loops keep working.

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `HTTP 400 invalid temperature: only 1 is allowed for this model` | A temperature override was sent | GoClaw omits `temperature` for `kimi_coding` automatically; don't hard-code it in raw requests |
| `HTTP 400 thinking is enabled but reasoning_content is missing in assistant tool call message at index N` | Replayed tool-call message lacks `reasoning_content` | GoClaw auto-emits an empty `reasoning_content`; ensure assistant history isn't stripped of the field |
| Requests rejected / 4xx on every call | Missing or altered `User-Agent` | GoClaw sends `claude-code/0.1.0` automatically; don't override the User-Agent header |
| `401 Unauthorized` | Invalid API key | Re-enter the Kimi key in Settings → Providers |

## What's Next

- [Provider Overview](/providers-overview) — provider architecture and retry logic
- [Extended Thinking](/extended-thinking) — how thinking and `reasoning_content` work across providers
- [DashScope (Qwen)](/provider-dashscope) — Alibaba Qwen models with thinking support



---

# Suno

> Generate music and audio with Suno's AI music generation platform.

🚧 **This page is under construction.** Content coming soon — contributions welcome!

## Overview

Suno is an AI music generation provider. GoClaw agents can use Suno to compose songs, generate background music, and produce audio clips from text prompts.

## Provider Type

```json
{
  "providers": {
    "suno": {
      "provider_type": "suno",
      "api_key": "your-suno-api-key"
    }
  }
}
```

## What's Next

- [Provider Overview](/providers-overview)
- [Media Generation](/media-generation)
- [MiniMax](/provider-minimax) — another provider with audio capabilities



---

# Zai

> Connect to Zai and Zai Coding providers (OpenAI-compatible).

🚧 **This page is under construction.** Content coming soon.

## Overview

Zai provides two variants: a general-purpose provider and a coding-specialized variant (`zai_coding`). Both use the OpenAI-compatible API format.

## What's Next

- [Provider Overview](/providers-overview)
- [Custom / OpenAI-Compatible](/provider-custom)



---

# YesScale

> Run AI models at scale with YesScale's cloud AI platform.

🚧 **This page is under construction.** Content coming soon — contributions welcome!

## Overview

YesScale is a cloud AI platform providing access to a wide range of language models via an OpenAI-compatible API. GoClaw connects to YesScale using the standard `OpenAIProvider`.

## Provider Type

```json
{
  "providers": {
    "yescale": {
      "provider_type": "yescale",
      "api_key": "your-yescale-api-key",
      "api_base": "https://api.yescale.io/v1"
    }
  }
}
```

## What's Next

- [Provider Overview](/providers-overview)
- [Custom / OpenAI-Compatible](/provider-custom)
- [OpenRouter](/provider-openrouter) — another multi-model platform



---

# Novita AI

> OpenAI-compatible LLM provider with access to a wide range of open-source models.

## Overview

Novita AI is a cloud inference platform providing access to dozens of open-source models via an OpenAI-compatible API. GoClaw connects to Novita using the standard `OpenAIProvider`.

- **Provider type:** `novita`
- **Default API base:** `https://api.novita.ai/openai`
- **Default model:** `moonshotai/kimi-k2.5`
- **Protocol:** OpenAI-compatible (Bearer token)

## Quick Setup

### Static config (config.json)

```json
{
  "providers": {
    "novita": {
      "api_key": "your-novita-api-key"
    }
  }
}
```

The `api_base` defaults to `https://api.novita.ai/openai` — omit it unless you need to override.

### Environment variable

```
GOCLAW_NOVITA_API_KEY=your-novita-api-key
```

### Dashboard (llm_providers table)

```json
{
  "provider_type": "novita",
  "api_key": "your-novita-api-key",
  "api_base": "https://api.novita.ai/openai"
}
```

## Using Novita in an Agent

```json
{
  "agents": {
    "defaults": {
      "provider": "novita",
      "model": "moonshotai/kimi-k2.5"
    }
  }
}
```

## What's Next

- [Provider Overview](/providers-overview)
- [Custom / OpenAI-Compatible](/provider-custom)
- [OpenRouter](/provider-openrouter) — another multi-model platform



---

# Claude CLI

Run Claude Code (the `claude` CLI binary) as a GoClaw provider — giving your agents full agentic tool use powered by Anthropic's Claude subscription.

## Overview

The Claude CLI provider is unlike any other provider in GoClaw. Instead of making HTTP requests to an API, it shells out to the `claude` binary installed on your machine. GoClaw forwards the user's message to the CLI, and the CLI manages everything else: session history, tool execution (Bash, file edits, web search, etc.), MCP integrations, and context.

This means your agent can run real terminal commands, edit files, browse the web, and use any MCP server — all through your existing Claude subscription, with no API key required.

**Architecture summary:**

```
User message → GoClaw → claude CLI (subprocess)
                              ↓
                   CLI manages: session, tools, MCP, context
                              ↓
                   Stream output back → GoClaw → user
```

## Prerequisites

1. Install the Claude CLI: follow [Anthropic's installation guide](https://docs.anthropic.com/en/docs/claude-code/getting-started)
2. Log in to your Claude subscription: run `claude` once and complete the auth flow
3. Verify it works: `claude -p "Hello" --output-format json`

## Setup

Configure the CLI provider in `config.json`:

```json
{
  "providers": {
    "claude_cli": {
      "cli_path": "claude",
      "model": "sonnet",
      "base_work_dir": "~/.goclaw/cli-workspaces",
      "perm_mode": "bypassPermissions"
    }
  },
  "agents": {
    "defaults": {
      "provider": "claude-cli",
      "model": "sonnet"
    }
  }
}
```

All fields are optional — defaults work for most setups:

| Field | Default | Description |
|---|---|---|
| `cli_path` | `"claude"` | Path to the `claude` binary (use full path if not on `$PATH`) |
| `model` | `"sonnet"` | Model alias: `sonnet`, `opus`, or `haiku` |
| `base_work_dir` | `~/.goclaw/cli-workspaces` | Base directory for per-session workspaces |
| `perm_mode` | `"bypassPermissions"` | CLI permission mode (see below) |

## Models

The Claude CLI uses model aliases, not full model IDs:

| Alias | Maps to |
|---|---|
| `sonnet` | Latest Claude Sonnet |
| `opus` | Latest Claude Opus |
| `haiku` | Latest Claude Haiku |

You cannot use full model IDs (like `claude-sonnet-4-5`) with this provider. GoClaw validates the alias and returns an error if it's unrecognized.

## Session Isolation

Each GoClaw session gets its own isolated workspace directory under `base_work_dir`. GoClaw derives a deterministic UUID from the session key, so the CLI can resume the same conversation across restarts using `--resume`.

Session files are stored by the CLI at `~/.claude/projects/<encoded-workdir>/<session-id>.jsonl`. GoClaw checks for this file at the start of each request: if it exists, it passes `--resume`; otherwise it passes `--session-id` to start fresh.

Concurrent requests to the same session are serialized with a per-session mutex — the CLI can only handle one request per session at a time.

## System Prompt

GoClaw writes the agent's system prompt to a `CLAUDE.md` file in the session workspace. The CLI reads this file automatically on every run, including resumed sessions. GoClaw skips the write if the content hasn't changed to avoid unnecessary disk I/O.

## Permission Mode

The default permission mode is `bypassPermissions`, which lets the CLI run tools without asking for confirmation. This is appropriate for server-side agent use. You can change it:

```json
{
  "providers": {
    "claude_cli": {
      "perm_mode": "default"
    }
  }
}
```

Available modes: `bypassPermissions` (default), `default`, `acceptEdits`.

## Security Hooks

GoClaw can inject security hooks into the CLI to enforce shell deny patterns and workspace path restrictions. Enable this in your agent config (done at the agent level, not the provider config). Hooks are written to a temporary settings file and passed to the CLI via `--settings`.

## MCP Config Passthrough

If you configure MCP servers in GoClaw, the provider builds an MCP config file and passes it to the CLI via `--mcp-config`. When an MCP config is present, GoClaw disables the CLI's built-in tools (Bash, Edit, Read, Write, etc.) so all tool execution routes through GoClaw's controlled MCP bridge.

## Disabling Built-in Tools

Set `disable_tools: true` in the options to disable all CLI tools. This is useful for pure text generation tasks where you don't want the CLI to run any commands:

```json
{
  "options": {
    "disable_tools": true
  }
}
```

## Debugging

Enable debug logging to capture the raw CLI stream output:

```bash
GOCLAW_DEBUG=1 ./goclaw
```

This writes a `cli-debug.log` file in each session's workspace directory with the full CLI command, all stream-json output, and stderr.

## Examples

**Minimal config — use your PATH `claude` binary:**

```json
{
  "providers": {
    "claude_cli": {}
  },
  "agents": {
    "defaults": {
      "provider": "claude-cli",
      "model": "sonnet"
    }
  }
}
```

**Full path to binary, using Opus:**

```json
{
  "providers": {
    "claude_cli": {
      "cli_path": "/usr/local/bin/claude",
      "model": "opus",
      "base_work_dir": "/var/goclaw/workspaces"
    }
  },
  "agents": {
    "defaults": {
      "provider": "claude-cli",
      "model": "opus"
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `claude-cli: exec: "claude": executable file not found` | `claude` not on `$PATH` | Set `cli_path` to the full path of the binary |
| `unsupported model "claude-sonnet-4-5"` | Full model ID used instead of alias | Use `sonnet`, `opus`, or `haiku` |
| Session doesn't resume | Session file missing or workdir changed | Check `~/.claude/projects/` for session files; ensure `base_work_dir` is stable |
| CLI asks for confirmation interactively | `perm_mode` not set to `bypassPermissions` | Set `perm_mode: "bypassPermissions"` in config |
| Slow first response | CLI cold start + auth check | Expected on first run; subsequent calls in same session are faster |
| `CLAUDE_*` env vars causing conflicts | Nested CLI session detection | GoClaw filters out all `CLAUDE_*` env vars before spawning the subprocess |

## What's Next

- [Codex / ChatGPT](/provider-codex) — OAuth-based provider using your ChatGPT subscription
- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API



---

# Codex / ChatGPT (OAuth)

Use your ChatGPT subscription to power GoClaw agents via the OpenAI Responses API and OAuth authentication.

## Overview

The Codex provider lets you use your existing ChatGPT Plus or Pro subscription with GoClaw — no separate API key purchase required. GoClaw authenticates via OAuth using OpenAI's PKCE flow, stores the refresh token securely in the database, and automatically refreshes the access token before it expires.

Under the hood, GoClaw uses the **OpenAI Responses API** (`POST /codex/responses`) rather than the standard chat completions endpoint. This API supports streaming, tool calls, and reasoning output. The provider is registered as `openai-codex` by default.

## How Authentication Works

1. You trigger the OAuth flow through GoClaw's web UI (Settings → Providers → ChatGPT)
2. GoClaw opens a browser at `https://auth.openai.com/oauth/authorize`
3. You log in with your ChatGPT account and approve access
4. OpenAI redirects to `http://localhost:1455/auth/callback` with an authorization code
5. GoClaw exchanges the code for access + refresh tokens and stores them encrypted in the database
6. From that point on, GoClaw automatically uses and refreshes the token — no manual steps needed

## Setup

You do not add this provider to `config.json` manually. Instead:

1. Start GoClaw: `./goclaw`
2. Open the web dashboard
3. Go to **Settings → Providers**
4. Click **Connect ChatGPT**
5. Complete the OAuth flow in your browser

Once connected, set an agent to use it:

```json
{
  "agents": {
    "defaults": {
      "provider": "openai-codex",
      "model": "gpt-5.5"
    }
  }
}
```

## Models

The Codex provider supports models available through the Responses API:

| Model | Notes |
|---|---|
| `gpt-5.5` | **Default**; latest ChatGPT subscription model |
| `gpt-5.3-codex` | Alternative; optimized for agentic coding tasks |
| `o3` | Strong reasoning model |
| `o4-mini` | Faster reasoning, lower cost |
| `gpt-4o` | General-purpose, multimodal |

Pass the model name in the `model` field of your agent config or per-request.

## Thinking / Reasoning

For reasoning models (like `o3`, `o4-mini`), set `thinking_level` to control reasoning effort:

```json
{
  "agents": {
    "defaults": {
      "provider": "openai-codex",
      "model": "o3",
      "thinking_level": "medium"
    }
  }
}
```

GoClaw translates this to the Responses API `reasoning.effort` field (`low`, `medium`, `high`).

## Wire Format Notes

The Codex provider uses the Responses API format, not chat completions:

- System prompts become `instructions` in the request body
- Messages are converted to the `input` array format
- Tool calls use `function_call` and `function_call_output` item types
- Tool call IDs are prefixed with `fc_` as required by the Responses API
- `store: false` is always set (GoClaw manages its own conversation history)

This conversion is transparent — you interact with GoClaw the same way regardless of which provider is active.

## Examples

**Agent config after OAuth setup:**

```json
{
  "agents": {
    "defaults": {
      "provider": "openai-codex",
      "model": "gpt-5.5",
      "max_tokens": 8192
    }
  }
}
```

**Use reasoning with o3:**

```json
{
  "agents": {
    "list": {
      "reasoning-agent": {
        "provider": "openai-codex",
        "model": "o3",
        "thinking_level": "high"
      }
    }
  }
}
```

## Codex OAuth Pool

If you have multiple ChatGPT accounts (e.g., a personal account and a work account), you can pool them together so GoClaw distributes requests across all of them. This is useful for spreading usage across accounts or providing automatic failover when one account hits a limit.

### How it works

You connect each ChatGPT account as a separate `chatgpt_oauth` provider. One provider is the **pool owner** — it holds the routing configuration. The other providers are **pool members** listed in `extra_provider_names`.

### Provider-level config (pool owner)

When creating or updating a provider via `POST /v1/providers`, set the `settings` field:

```json
{
  "name": "openai-codex",
  "provider_type": "chatgpt_oauth",
  "settings": {
    "codex_pool": {
      "strategy": "round_robin",
      "extra_provider_names": ["codex-work", "codex-shared"]
    }
  }
}
```

`strategy` controls how requests are distributed across the pool:

| Strategy | Behavior |
|----------|----------|
| `round_robin` | Rotate requests across the primary + all extra providers |
| `priority_order` | Try providers in order — primary first, then extras in sequence (default) |

> **Migration note (v3.11.0):** Before v3.11.0, the API returned strategy `primary_first` for default routing. Starting v3.11.0, the public surface normalizes to `priority_order` (same behavior — primary first, fallback in order). Request bodies still accept legacy values (`primary_first`, `manual`, `""`) for backward compatibility; they normalize to `priority_order` on read.

`extra_provider_names` is the authoritative membership list. A provider listed in another pool's `extra_provider_names` cannot manage its own pool.

### Agent-level override

Individual agents can override the pool behavior via `chatgpt_oauth_routing` in their `other_config`:

```json
{
  "other_config": {
    "chatgpt_oauth_routing": {
      "override_mode": "custom",
      "strategy": "priority_order"
    }
  }
}
```

`override_mode` options:

| Value | Behavior |
|-------|----------|
| `inherit` | Use the primary provider's `codex_pool` settings (default when not set) |
| `custom` | Apply this agent's own strategy override |

### Routing notes

- Retryable upstream failures (HTTP 429, 5xx) automatically fall through to the next eligible account in the same request.
- OAuth login and logout are per-provider — each account authenticates independently.
- The pool is only active when the agent's provider is a `chatgpt_oauth` type. Non-Codex providers are unaffected.
- Round-robin counters are tracked separately per modality — chat requests and image requests rotate on independent counters. Image generation requests go through the `create_image` chain and are tallied against the image counter only.

### Pool activity endpoint

To inspect routing decisions and per-account health for an agent, call:

```
GET /v1/agents/{id}/codex-pool-activity
```

See [REST API](/rest-api) for the response shape.


## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `401 Unauthorized` | Token expired or revoked | Re-authenticate via Settings → Providers → ChatGPT |
| OAuth callback fails | Port 1455 blocked | Ensure nothing else is listening on port 1455 during auth |
| `model not found` | Model not in your subscription | Check your ChatGPT plan; some models require Pro |
| Provider not available after restart | Token not persisted | GoClaw auto-loads the token from DB on startup; check DB connectivity |
| Phase field in response | `gpt-5.5` and `gpt-5.3-codex` return `commentary` + `final_answer` phases | GoClaw handles this automatically; both phases are captured |

## What's Next

- [Custom Provider](/provider-custom) — connect any OpenAI-compatible API including local models
- [Claude CLI](/provider-claude-cli) — use your Claude subscription instead



---

# ACP (Agent Client Protocol)

> Use Claude Code, Codex CLI, or Gemini CLI as LLM providers through the Agent Client Protocol — orchestrated as JSON-RPC subprocesses.

## What is ACP?

ACP (Agent Client Protocol) enables GoClaw to orchestrate external coding agents — Claude Code, OpenAI Codex CLI, Gemini CLI, or any ACP-compatible agent — as subprocesses via **JSON-RPC 2.0 over stdio**. Instead of calling an HTTP API, GoClaw spawns the agent binary as a child process and exchanges structured messages through its stdin/stdout pipes.

This allows delegating complex code generation and reasoning tasks to specialized CLI agents while maintaining GoClaw's unified `Provider` interface: the rest of the system treats ACP exactly like any other provider.

```mermaid
flowchart TD
    AL["Agent Loop"] -->|Chat / ChatStream| ACP["ACPProvider"]
    ACP --> PP["ProcessPool"]
    PP -->|spawn| PROC["Subprocess\njson-rpc 2.0 stdio"]
    PROC -->|initialize| AGT["Agent\n(Claude Code, Codex, Gemini CLI)"]

    AGT -->|fs/readTextFile| TB["ToolBridge"]
    AGT -->|fs/writeTextFile| TB
    AGT -->|terminal/*| TB
    AGT -->|permission/request| TB

    TB -->|enforce| SB["Workspace Sandbox"]
    TB -->|check| DEN["Deny Patterns"]
    TB -->|apply| PERM["Permission Mode"]
```


## ProcessPool

The `ProcessPool` manages subprocess lifecycle. Each session (identified by `session_key`) maps to one long-lived subprocess:

1. **GetOrSpawn** — on each request, retrieve the existing subprocess for the session or spawn a new one.
2. **Initialize** — freshly spawned processes receive a JSON-RPC `initialize` call that negotiates protocol capabilities.
3. **Idle TTL reaping** — a background goroutine periodically checks last-used timestamps; processes idle longer than `idle_ttl` are killed and removed.
4. **Crash recovery** — if a subprocess exits unexpectedly, the pool detects the broken pipe on the next request, removes the stale entry, and spawns a fresh process transparently.

```mermaid
sequenceDiagram
    participant C as Caller
    participant PP as ProcessPool
    participant P as Subprocess

    C->>PP: GetOrSpawn(sessionKey)
    alt existing process
        PP-->>C: existing process
    else new process
        PP->>P: os.StartProcess(binary, args)
        PP->>P: initialize (JSON-RPC)
        P-->>PP: capabilities
        PP-->>C: new process
    end

    C->>P: prompt (JSON-RPC)
    P-->>C: SessionUpdate events

    Note over PP,P: idle TTL goroutine
    PP->>P: kill (after idle_ttl)
```

---

## ToolBridge

When the agent subprocess needs to read a file, run a command, or request a permission, it sends a JSON-RPC request back to GoClaw over stdio. The `ToolBridge` handles these agent→client callbacks:

| Method | Description |
|--------|-------------|
| `fs/readTextFile` | Read a file within the workspace sandbox |
| `fs/writeTextFile` | Write a file within the workspace sandbox |
| `terminal/createTerminal` | Spawn a terminal subprocess |
| `terminal/terminalOutput` | Fetch terminal output and exit status |
| `terminal/waitForTerminalExit` | Block until terminal exits |
| `terminal/releaseTerminal` | Release terminal resources |
| `terminal/killTerminal` | Force-terminate a terminal |
| `permission/request` | Request user approval for an action |

Every ToolBridge call is validated through:
1. **Workspace isolation** — path must be within `work_dir`
2. **Deny pattern matching** — path regex patterns checked before execution
3. **Permission mode** — final gate based on `perm_mode`

---

## Session Tracking

Each ACP subprocess maintains a server-assigned session ID. The session lifecycle is:

1. **`session/new`** — called immediately after `initialize`; the server returns a `sessionID`
2. **`session/prompt`** — sends the user content with the `sessionID`; server emits `SessionUpdate` notifications during execution
3. **`session/cancel`** — sent as a notification when the caller cancels context

The session ID is stored per-process in `ACPProcess.sessionID` and included in every prompt request. This allows the ACP agent to maintain conversation history and file state across multiple turns within the same process lifetime.

> **Operator note:** ACP `session/update` `tool_call` and `tool_call_update` notifications are logged at **Info** level (with session ID, tool call ID, tool name/title, kind, and status), so operators can observe the ACP agent's tool activity in the gateway logs.

## Session Sequencing

Concurrent requests to the same session would risk corrupting file state. ACP serializes per-session requests via a `sessionMu` mutex:

```go
unlock := p.lockSession(sessionKey)
defer unlock()
// Chat or ChatStream executes with guaranteed serial access
```

This means requests to different sessions run in parallel, but requests to the same session are queued.

---

## Streaming vs Non-Streaming

### Chat (non-streaming)

Waits for the agent subprocess to finish executing the prompt, then collects all accumulated `SessionUpdate` text blocks and returns a single `ChatResponse`. Use this when you need the full answer before processing.

### ChatStream

Emits `StreamChunk` callbacks for each text delta as the agent produces output. Supports context cancellation: if the caller cancels, GoClaw sends a `session/cancel` JSON-RPC notification to the subprocess. Returns the combined `ChatResponse` when complete.

---

## Workspace Sandbox

All file operations are confined to `work_dir`. Path traversal attempts (e.g. `../../etc/passwd`) are detected and rejected before reaching the filesystem.

### Deny Patterns

Regex patterns block access to sensitive paths regardless of workspace scope:

```json
[
  "^/etc/",
  "^\\.env",
  "^secret",
  "^[Cc]redentials"
]
```

Patterns are evaluated against the resolved absolute path. Any match causes the request to be rejected with an error.

---

## Permission Modes

| Mode | Behavior |
|------|----------|
| `approve-all` | All `permission/request` calls are auto-approved (default) |
| `approve-reads` | Read operations are approved; filesystem writes are denied |
| `deny-all` | All `permission/request` calls are denied |

---

## Content Handling

ACP uses `ContentBlock` for messages, supporting text, image, and audio:

```go
type ContentBlock struct {
    Type     string // "text", "image", "audio"
    Text     string // text content
    Data     string // base64-encoded for image/audio
    MimeType string // e.g. "image/png", "audio/wav"
}
```

On each request, GoClaw:
1. Extracts the system prompt and user messages from `ChatRequest.Messages`
2. Prepends the system prompt to the first user message (ACP agents have no separate system API)
3. Attaches any image content blocks as additional message blocks

On response, GoClaw:
1. Accumulates `SessionUpdate` notifications emitted during execution
2. Collects all text blocks into response content
3. Maps `stopReason`: `"maxContextLength"` → `"length"`, all others → `"stop"`

---

## Security Considerations

- **Subprocess isolation**: each agent process runs as the same OS user as GoClaw. Use OS-level sandboxing (e.g. containers, seccomp) for stronger isolation.
- **Workspace confinement**: `work_dir` is the only directory the agent can read/write via ToolBridge. Set it to a dedicated, non-sensitive directory.
- **Deny patterns**: configure patterns matching your secrets layout (`.env`, `credentials`, `*.pem`, etc.)
- **Permission mode**: use `approve-reads` or `deny-all` in production environments where write access should be restricted.
- **Binary path**: specify an absolute path for `binary` to prevent PATH injection attacks.
- **idle_ttl**: keep short (≤10m) to limit the attack surface from a compromised subprocess.

---

## What's Next

- [Provider Overview](/providers-overview)
- [Claude CLI](/provider-claude-cli)
- [Custom / OpenAI-Compatible](/provider-custom)



---

# Custom Provider

Connect GoClaw to any OpenAI-compatible API — local models, self-hosted inference servers, or third-party proxies.

## Overview

GoClaw's `OpenAIProvider` works with any server that speaks the OpenAI chat completions format. You configure a name, API base URL, API key (optional for local servers), and default model. This covers local setups like Ollama and vLLM, proxy services like LiteLLM, and any vendor that advertises OpenAI compatibility.

GoClaw also automatically cleans tool schemas for providers that don't accept certain JSON Schema fields — so your tools work even when the downstream model is stricter than OpenAI.

## Setup

Custom providers are registered via the HTTP API or configured at the database level — there's no static config key for arbitrary names. However, you can use any of the built-in named slots with a custom `api_base` to point at a different server:

```json
{
  "providers": {
    "openai": {
      "api_key": "not-required",
      "api_base": "http://localhost:11434/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "llama3.2"
    }
  }
}
```

This works because GoClaw only cares about the API base and key — the provider name is just a label for routing.

## Local Ollama

Run models locally with [Ollama](https://ollama.com):

```bash
ollama serve          # starts on http://localhost:11434
ollama pull llama3.2  # download a model
```

```json
{
  "providers": {
    "openai": {
      "api_key": "ollama",
      "api_base": "http://localhost:11434/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "llama3.2"
    }
  }
}
```

Ollama ignores the API key value — pass any non-empty string.

## vLLM

Self-host any HuggingFace model with [vLLM](https://docs.vllm.ai):

```bash
vllm serve meta-llama/Llama-3.2-3B-Instruct --port 8000
```

```json
{
  "providers": {
    "openai": {
      "api_key": "vllm",
      "api_base": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "meta-llama/Llama-3.2-3B-Instruct"
    }
  }
}
```

## LiteLLM Proxy

[LiteLLM](https://docs.litellm.ai/docs/proxy/quick_start) proxies 100+ providers behind a single OpenAI-compatible endpoint:

```bash
litellm --model ollama/llama3.2 --port 4000
```

```json
{
  "providers": {
    "openai": {
      "api_key": "$LITELLM_KEY",
      "api_base": "http://localhost:4000/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "ollama/llama3.2"
    }
  }
}
```

## Schema Cleaning

GoClaw automatically strips unsupported JSON Schema fields from tool definitions based on the provider name. This happens in `CleanToolSchemas`:

| Provider | Removed fields |
|---|---|
| `gemini` / `gemini-*` | `$ref`, `$defs`, `additionalProperties`, `examples`, `default` |
| `anthropic` | `$ref`, `$defs` |
| All others | Nothing removed |

For custom providers using a non-standard name, no schema cleaning is applied. If your local model rejects certain schema fields, use a provider name that triggers the right cleaning (e.g. name your provider `gemini` to strip Gemini-incompatible fields).

## Tool Format Differences

Not all OpenAI-compatible servers implement tools identically. Common gotchas:

- **Ollama**: Tool support depends on the model. Use models tagged with `tools` support (e.g. `llama3.2`, `qwen2.5`).
- **vLLM**: Tool support is model-dependent. Pass `--enable-auto-tool-choice` and `--tool-call-parser` flags when launching vLLM.
- **LiteLLM**: Handles tool format translation per-provider transparently.

If tool calls fail, try disabling tools for that provider and falling back to plain text with a structured output prompt.

## Examples

**LM Studio (local GUI for running models):**

```json
{
  "providers": {
    "openai": {
      "api_key": "lm-studio",
      "api_base": "http://localhost:1234/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF"
    }
  }
}
```

**Jan (another local model runner):**

```json
{
  "providers": {
    "openai": {
      "api_key": "jan",
      "api_base": "http://localhost:1337/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "llama3.2-3b-instruct"
    }
  }
}
```

## Common Issues

| Problem | Cause | Fix |
|---|---|---|
| `connection refused` | Local server not running | Start Ollama/vLLM/LiteLLM before GoClaw |
| `model not found` | Wrong model name for your server | Check the server's model list (`GET /v1/models`) |
| Tool calls cause errors | Server doesn't support tools | Disable tools in agent config or switch to a tool-capable model |
| Schema validation errors | Server rejects `additionalProperties` or `$ref` | Use a provider name that triggers schema cleaning, or sanitize tool schemas upstream |
| Streaming not working | Server doesn't implement SSE correctly | Try with streaming disabled; some local servers have SSE bugs |

## What's Next

- [Overview](/providers-overview) — compare all providers side by side
- [DashScope](/provider-dashscope) — Alibaba's Qwen models
- [Perplexity](/provider-perplexity) — search-augmented generation



---

# Channels Overview

Channels connect messaging platforms (Telegram, Discord, Larksuite, etc.) to the GoClaw agent runtime via a unified message bus. Each channel translates platform-specific events into standardized `InboundMessage` objects and converts agent responses into platform-appropriate output.

## Message Flow

```mermaid
flowchart LR
    TG["Telegram<br/>Discord<br/>Slack<br/>Larksuite<br/>Zalo<br/>WhatsApp"]

    TG -->|"Platform event"| Listen["Channel.Start()<br/>Listen for updates"]
    Listen -->|"Build message"| Handle["HandleMessage()<br/>Extract content, media,<br/>sender ID, chat ID"]
    Handle -->|"PublishInbound"| Bus["MessageBus"]

    Bus -->|"Route"| Agent["Agent Loop<br/>Process message<br/>Generate response"]
    Agent -->|"OutboundMessage"| Bus

    Bus -->|"DispatchOutbound"| Manager["Manager<br/>Route to channel"]
    Manager -->|"Channel.Send()"| Send["Format + Deliver<br/>Handle platform limits"]
    Send --> TG
```

## Channel Policies

Control who can send messages via DM or group settings.

### DM Policies

| Policy | Behavior | Use Case |
|--------|----------|----------|
| `pairing` | Require 8-char code approval for new users | Secure, controlled access |
| `allowlist` | Only whitelisted senders accepted | Restricted group |
| `open` | Accept all DMs | Public bot |
| `disabled` | Reject all DMs | Groups only |

### Group Policies

| Policy | Behavior | Use Case |
|--------|----------|----------|
| `open` | Accept all group messages | Public groups |
| `allowlist` | Only whitelisted groups accepted | Restricted groups |
| `disabled` | No group messages | DMs only |

### Policy Evaluation Flow

```mermaid
flowchart TD
    MSG["Incoming message"] --> KIND{"Direct or<br/>group?"}
    KIND -->|Direct| DPOLICY["Apply DM policy"]
    KIND -->|Group| GPOLICY["Apply group policy"]

    DPOLICY --> CHECK{"Policy allows?"}
    GPOLICY --> CHECK

    CHECK -->|disabled| REJECT["Reject"]
    CHECK -->|open| ACCEPT["Accept"]
    CHECK -->|allowlist| ALLOWED{"Sender in<br/>allowlist?"}
    ALLOWED -->|Yes| ACCEPT
    ALLOWED -->|No| REJECT
    CHECK -->|pairing| PAIRED{"Already paired<br/>or allowlisted?"}
    PAIRED -->|Yes| ACCEPT
    PAIRED -->|No| SEND_CODE["Send pairing code<br/>Wait for approval"]
```

## Session Key Format

Session keys identify unique conversations and threads across platforms. All keys follow the canonical format `agent:{agentId}:{rest}`.

| Context | Format | Example |
|---------|--------|---------|
| DM | `agent:{agentId}:{channel}:direct:{peerId}` | `agent:default:telegram:direct:386246614` |
| Group | `agent:{agentId}:{channel}:group:{groupId}` | `agent:default:telegram:group:-100123456` |
| Forum topic | `agent:{agentId}:{channel}:group:{groupId}:topic:{topicId}` | `agent:default:telegram:group:-100123456:topic:99` |
| DM thread | `agent:{agentId}:{channel}:direct:{peerId}:thread:{threadId}` | `agent:default:telegram:direct:386246614:thread:5` |
| Subagent | `agent:{agentId}:subagent:{label}` | `agent:default:subagent:my-task` |

## Media Handling Notes

### Media from Replied-to Messages

GoClaw extracts media attachments from the message being replied to across all channels that support replies. When a user replies to a message containing images or files, those attachments are automatically included in the agent's inbound message context — no extra steps required.

### Outbound Media Size Limit

The `media_max_bytes` config field enforces a per-channel limit on outbound media uploads sent by the agent. Files exceeding this limit are skipped with a log entry. Each channel sets its own default (e.g., 20 MB for Telegram, 30 MB for Feishu/Lark). Configure per channel if needed.

### Multi-Attachment Delivery (Batching)

The `send_file` tool can deliver several existing workspace files in one go. Two forms are accepted:

- **Single file:** `path` (plus an optional `caption`).
- **Batch:** `attachments: [{ "path": "...", "caption": "..." }, ...]` — file order, MIME type, filename, and per-file captions are preserved.

How each channel groups a batch depends on what the platform supports:

| Channel | Grouping | Behavior |
|---------|----------|----------|
| Telegram | Album chunks | Compatible media are grouped into `sendMediaGroup` albums of **2–10** items. Photos/videos can share a chunk; documents group only with documents, audio only with audio. Voice-mode audio, singleton chunks, oversized images sent as documents, and incompatible runs fall back to ordered single-send. |
| Discord | Single message | Multiple files (plus optional text) are delivered in **one** message, up to 10 attachments. |
| Slack and other media-capable channels | Ordered fallback | Files are sent one after another in order unless the adapter advertises a stronger batch capability. |

## Inbound Debounce

When a user fires several messages in quick succession (or uploads multiple files at once), GoClaw merges them into a **single** inbound message before running the agent — one reply instead of one per fragment.

Set the silence window with `gateway.inbound_debounce_ms` (milliseconds):

```json
{
  "gateway": {
    "inbound_debounce_ms": 1500
  }
}
```

- Messages are buffered per `channel:chatID:senderID:agentID` key. The timer resets on every new message, so the merged message flushes only after the sender goes quiet for the configured window.
- `0` **disables** text debouncing — each message dispatches immediately.
- **Per-agent override:** an agent can set `inbound_debounce_ms` in its `agent_config` to use a different window than the gateway default.
- **`/stop` and `/reset` bypass the debouncer** — control commands are handled immediately and never buffered.
- **Media floor:** media-bearing messages no longer bypass debouncing. The effective window is `max(configured, media floor)`, so a multi-file upload always coalesces into one inbound even when text debouncing is set to `0`. (A non-zero agent override is honored verbatim — operators who set, say, `500` keep `500`, not the floor.) Messages synthesized internally by tools/subagents are exempt from the floor.

## Human-like Delivery

GoClaw can make channel replies feel more conversational — a quick acknowledgement before a long run, short progress notes while tools execute, and splitting a long final answer into a few natural messages. This is configured under `gateway.chat_behavior` and is **disabled by default**.

> These behaviors are **delivery-only**. Acknowledgements, progress notes, and split parts are never written to session history or sent back to the model as conversation — they only change what the human sees in the chat.

```json
{
  "gateway": {
    "chat_behavior": {
      "enabled": true,
      "quick_ack": { "enabled": true, "mode": "sidecar_generated" },
      "intermediate_replies": { "enabled": true },
      "final_split": { "enabled": true }
    }
  }
}
```

### The three sub-behaviors

| Sub-behavior | What it does |
|--------------|--------------|
| `quick_ack` | Sends one short receipt before a longer non-streaming run, so the user knows the bot is working. |
| `intermediate_replies` | Sends short progress updates while the agent is running tools. Independent from `quick_ack`. |
| `final_split` | Splits a long final reply into a small number of paragraph-sized messages. |

**`quick_ack` modes:**

| Mode | Behavior |
|------|----------|
| `sidecar_generated` | A bounded, separate LLM call writes a short, context-aware acknowledgement. |
| `llm_generated` | Backward-compatible alias; this is also the default resolved mode. |
| `fixed_template` | Sends the first string from `templates` (default `"Got it. Working on it..."`). |
| `off` | No acknowledgement. |

`quick_ack` fields: `enabled`, `mode`, `min_delay_ms` (default 1000), `provider`, `model`, `timeout_ms` (default 2500), `max_tokens` (default 40), `max_chars` (default 120), `templates`. When `provider`/`model` are unset, the agent's own provider/model are used.

**`intermediate_replies`** modes are `sidecar_generated` (default) or `off`. Fields: `enabled`, `mode`, `provider`, `model`, `timeout_ms` (2500), `max_tokens` (default 60), `max_chars` (default 180). The sidecar only receives bounded metadata (message preview, locale, channel/peer, agent label, current tool phase) — **never** session history, tool arguments/output, memory, or system prompts.

**`final_split`** fields: `enabled`, `min_chars` (default 1200), `max_messages` (default 3), `delay_ms` (default 500). Splitting is conservative — replies containing fenced code, tables, lists, quotes, JSON/XML-like blocks, or URL-only paragraphs stay as one message, and media or streaming deliveries are never split.

### Override order

`chat_behavior` can be set at three levels. The resolution order is **Channel > Agent > Workspace**:

1. **Workspace** — `gateway.chat_behavior` (the base).
2. **Agent** — `agents.other_config.delivery_behavior` overrides the workspace base.
3. **Channel** — `channels.<type>.chat_behavior` (or a channel instance's `chat_behavior`) has the final say.

Each level only overrides the fields it sets, so you can tune one knob per channel and inherit the rest.

> **Legacy `block_reply`.** The older `gateway.block_reply` (and per-channel `block_reply`) flags are still read as the inherited default for `intermediate_replies.enabled` when the newer field is unset.

### Channel support

Human-like delivery is implemented by channels that adopt the `ChatBehaviorChannel` interface: **Bitrix24, Discord, Feishu/Lark, Pancake, Slack, Telegram, WhatsApp, Zalo OA, and Zalo Personal**.

## Channel Comparison

| Feature | Telegram | Bitrix24 | Discord | Slack | Larksuite | Zalo OA | Zalo Pers | WhatsApp |
|---------|----------|----------|---------|-------|--------|---------|-----------|----------|
| **Transport** | Long polling | Webhook (OAuth) | Gateway events | Socket Mode (WS) | WS/Webhook | Long polling | Internal proto | WS bridge |
| **DM support** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Group support** | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes |
| **Streaming** | Yes (typing) | Yes | Yes (edit) | Yes (edit) | Yes (card) | No | No | No |
| **Media** | Photos, voice, files | Files (20MB) | Files, embeds | Files (20MB) | Images, files (30MB) | Images (5MB) | -- | JSON |
| **Reply media** | Yes | -- | Yes | -- | Yes | -- | -- | -- |
| **Rich format** | HTML | Text | Markdown | mrkdwn | Cards | Plain text | Plain text | Plain |
| **Thread support** | Yes | -- | -- | -- | -- | -- | -- | -- |
| **Reactions** | Yes | Yes | -- | Yes | Yes | -- | -- | -- |
| **Pairing** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Message limit** | 4,096 | 4,000 | 2,000 | 4,000 | 4,000 | 2,000 | 2,000 | N/A |

## Channel Health Diagnostics

GoClaw tracks the runtime health of each channel instance and provides actionable diagnostics when issues occur. Health state is exposed via the `channels.status` WebSocket method and the dashboard overview page.

### Health States

| State | Meaning |
|-------|---------|
| `registered` | Channel is configured but not yet started |
| `starting` | Channel is initializing |
| `healthy` | Running normally |
| `degraded` | Running with issues |
| `failed` | Stopped due to an error |
| `stopped` | Manually stopped |

### Failure Classification

When a channel fails, GoClaw classifies the error into one of four categories:

| Kind | Typical Cause | Remediation |
|------|---------------|-------------|
| `auth` | Invalid or expired token/secret | Review credentials or re-authenticate |
| `config` | Missing required settings, invalid proxy | Complete required fields in channel settings |
| `network` | Timeout, connection refused, DNS failure | Check upstream service reachability and proxy settings |
| `unknown` | Unrecognized error | Inspect server logs for the full error |

Each failure includes a **remediation hint** — a short operator instruction pointing to the specific UI surface (credentials panel, advanced settings, or details page) where the issue can be resolved. The dashboard surfaces these hints directly on channel cards.

### Health Tracking

The health system tracks failure history per channel:
- **Consecutive failures** — resets when the channel recovers
- **Total failure count** — lifetime counter
- **First/last failure timestamps** — for diagnosing intermittent issues
- **Last healthy timestamp** — when the channel was last operational



---

# Telegram Channel

Telegram bot integration via long polling (Bot API). Supports DMs, groups, forum topics, speech-to-text, and streaming responses.

## Setup

**Create a Telegram Bot:**
1. Message @BotFather on Telegram
2. `/newbot` → choose name and username
3. Copy the token (format: `123456:ABCDEFGHIJKLMNOPQRSTUVWxyz...`)

> **Important — Group Privacy Mode:** By default, Telegram bots run in **privacy mode** and can only see commands (`/`) and @mentions in groups. To let the bot read all group messages (required for history buffer, `require_mention: false`, and group context), message **@BotFather** → `/setprivacy` → select your bot → **Disable**. Without this, the bot will silently ignore most group messages.

**Enable Telegram:**

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "dm_policy": "pairing",
      "group_policy": "open",
      "allow_from": ["alice", "bob"]
    }
  }
}
```

## Configuration

All config keys are in `channels.telegram`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `token` | string | required | Bot API token from BotFather |
| `proxy` | string | -- | HTTP proxy (e.g., `http://proxy:8080`) |
| `allow_from` | list | -- | User ID or username allowlist |
| `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
| `group_policy` | string | `"open"` | `open`, `allowlist`, `disabled` |
| `require_mention` | bool | true | Require @bot mention in groups |
| `mention_mode` | string | `"strict"` | `strict` = only respond when @mentioned; `yield` = respond unless another bot is @mentioned (multi-bot groups) |
| `history_limit` | int | 50 | Pending messages per group (0=disabled) |
| `dm_stream` | bool | false | Enable streaming for DMs (edits placeholder) |
| `group_stream` | bool | false | Enable streaming for groups (new message) |
| `draft_transport` | bool | false | Use `sendMessageDraft` for DM streaming (stealth preview, no per-edit notifications) |
| `reasoning_delivery` | string | -- | How reasoning is surfaced: `off`, `streaming_only`, `always_bubbles`. See [Reasoning Delivery](#reasoning-delivery). |
| `reasoning_stream` | bool | true | **Legacy.** Show reasoning tokens as a separate message before the answer. Used only when `reasoning_delivery` is unset. |
| `block_reply` | bool | -- | Override gateway `block_reply` setting for this channel (nil = inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |
| `reaction_level` | string | `"off"` | `off`, `minimal` (⏳ only), `full` (⏳💬🛠️✅❌🔄) |
| `media_max_bytes` | int | 20MB | Max media file size |
| `link_preview` | bool | true | Show URL previews |
| `force_ipv4` | bool | false | Force IPv4 for all Telegram API connections |
| `api_server` | string | -- | Custom Telegram Bot API server URL (e.g. `http://localhost:8081`) |
| `stt_proxy_url` | string | -- | STT service URL (for voice transcription) |
| `stt_api_key` | string | -- | Bearer token for STT proxy |
| `stt_timeout_seconds` | int | 30 | Timeout for STT transcription requests |
| `voice_agent_id` | string | -- | Route voice messages to specific agent |

**Media upload size**: The `media_max_bytes` field enforces a hard limit on outbound media uploads sent by the agent (default 20 MB). Files exceeding this limit are silently skipped with a log entry. This does not affect inbound media received from users.

## Group Configuration

Override per-group (and per-topic) settings using the `groups` object.

```json
{
  "channels": {
    "telegram": {
      "token": "...",
      "groups": {
        "-100123456789": {
          "group_policy": "allowlist",
          "allow_from": ["@alice", "@bob"],
          "require_mention": false,
          "topics": {
            "42": {
              "require_mention": true,
              "tools": ["web_search", "file_read"],
              "system_prompt": "You are a research assistant."
            }
          }
        },
        "*": {
          "system_prompt": "Global system prompt for all groups."
        }
      }
    }
  }
}
```

Group config keys:

- `group_policy` — Override group-level policy
- `allow_from` — Override allowlist
- `require_mention` — Override mention requirement
- `mention_mode` — Override mention mode (`strict` or `yield`)
- `skills` — Whitelist skills (nil=all, []=none)
- `tools` — Whitelist tools (supports `group:xxx` syntax)
- `system_prompt` — Extra system prompt for this group
- `topics` — Per-topic overrides (key: topic/thread ID)

## Features

### Mention Gating

In groups, bot responds only to messages that mention it (default `require_mention: true`). When not mentioned, messages are stored in a pending history buffer (default 50 messages) and included as context when the bot is mentioned. Replying to a bot message counts as mentioning it.

#### Mention Modes

| Mode | Behavior | Use case |
|------|----------|----------|
| `strict` (default) | Only respond when @mentioned or replied to | Single-bot groups |
| `yield` | Respond to all messages UNLESS another bot/user is @mentioned | Multi-bot shared groups |

**Yield mode** enables multiple bots to coexist in one group without conflicts:
- Bot responds to all messages where no specific @mention targets another bot
- If a user @mentions a different bot, this bot stays silent (yields)
- Messages from other bots are automatically skipped to prevent infinite cross-bot loops
- Cross-bot @commands still work (e.g., `@my_bot help` sent by another bot)

```json
{
  "channels": {
    "telegram": {
      "mention_mode": "yield",
      "require_mention": false
    }
  }
}
```

```mermaid
flowchart TD
    MSG["User posts in group"] --> MODE{"mention_mode?"}
    MODE -->|strict| MENTION{"Bot @mentioned<br/>or reply?"}
    MODE -->|yield| OTHER{"Another bot/user<br/>@mentioned?"}
    OTHER -->|Yes| YIELD["Yield — stay silent"]
    OTHER -->|No| PROCESS
    MENTION -->|No| BUFFER["Add to pending history<br/>(max 50 messages)"]
    MENTION -->|Yes| PROCESS["Process now<br/>Include history as context"]
    BUFFER --> NEXT["Next mention:<br/>history included"]
```

### Bot Self-Identity in System Prompt

On startup, GoClaw resolves the bot's Telegram username and display name, then injects a short self-identity snippet into the agent system prompt:

```
You are @mybot (My Bot) on this Telegram channel.
```

This tells the agent its own handle so it can correctly interpret @mentions in group conversations — particularly useful in multi-bot groups where other bots' mentions are preserved in the message content after mention stripping.

### Own @Mention Stripping

Before passing message content to the agent, GoClaw strips the bot's own `@username` from the text. This means the agent receives clean input without its own handle. For example, a user message `"@mybot what's the weather?"` is delivered to the agent as `"what's the weather?"`.

Other bots' @mentions are intentionally preserved so the agent can detect cross-bot interactions.

### Group Message Annotation

In group chats, each message is prefixed with a `[From:]` annotation so the agent knows who is speaking:

```
[From: @username (Display Name)]
Message content here
```

The label format depends on available user data:
- Username + display name: `@username (Display Name)`
- Username only: `@username`
- Display name only: `Display Name`

This annotation is also added to DM messages for consistent sender identification.

### Group Concurrency

Group sessions support up to **3 concurrent agent runs**. When this limit is reached, additional messages are queued. This applies to all group and forum topic contexts.

### Forum Topics

Configure bot behavior per forum topic:

| Aspect | Key | Example |
|--------|-----|---------|
| Topic ID | Chat ID + topic ID | `-12345:topic:99` |
| Config lookup | Layered merge | Global → Wildcard → Group → Topic |
| Tool restrict | `tools: ["web_search"]` | Only web search in topic |
| Extra prompt | `system_prompt` | Topic-specific instructions |

### Message Formatting

Markdown output is converted to Telegram HTML with proper escaping:

```
LLM output (Markdown)
  → Extract tables/code → Convert Markdown to HTML
  → Restore placeholders → Chunk at 4,000 chars
  → Send as HTML (fallback: plain text)
```

Tables render as ASCII in `<pre>` tags. CJK characters counted as 2-column width.

### Speech-to-Text (STT)

Voice and audio messages can be transcribed:

```json
{
  "channels": {
    "telegram": {
      "stt_proxy_url": "https://stt.example.com",
      "stt_api_key": "sk-...",
      "stt_timeout_seconds": 30,
      "voice_agent_id": "voice_assistant"
    }
  }
}
```

When a user sends a voice message:
1. File is downloaded from Telegram
2. Sent to STT proxy as multipart (file + tenant_id)
3. Transcript prepended to message: `[audio: filename] Transcript: text`
4. Routed to `voice_agent_id` if configured, else default agent

Transcription runs through GoClaw's unified STT chain, which tries providers in order — `elevenlabs`, then `proxy`. (These are the current provider names; older releases called them `elevenlabs_scribe` and `proxy_stt`.) Telegram preserves the original voice MIME type when forwarding audio to the chain, and the legacy STT-proxy bridge override is keyed by the platform type `telegram`.

### Streaming

Enable live response updates:

- **DMs** (`dm_stream`): Edits the "Thinking..." placeholder as chunks arrive. Uses `sendMessage+editMessageText` by default; set `draft_transport: true` to use `sendMessageDraft` (stealth preview, no per-edit notifications, but may cause "reply to deleted message" artifacts on some clients).
- **Groups** (`group_stream`): Sends placeholder, edits with full response

Disabled by default.

### Reasoning Delivery

When the model emits reasoning ("thinking") tokens, `reasoning_delivery` controls how — or whether — that reasoning shows up in the chat:

| `reasoning_delivery` | Behavior |
|----------------------|----------|
| `streaming_only` | Reasoning appears only in the live streaming lane (the legacy behavior). |
| `always_bubbles` | Forces provider streaming internally and sends reasoning as bounded normal "bubble" messages — even when `dm_stream` / `group_stream` are off. The final answer is still delivered non-streaming. |
| `off` | Reasoning is suppressed in the channel. Traces and usage accounting are unaffected. |

**Backward compatibility.** When `reasoning_delivery` is unset, the legacy `reasoning_stream` boolean is honored: `reasoning_stream: false` resolves to `off`, otherwise to `streaming_only`. An explicit `reasoning_delivery` value always wins over the legacy boolean.

Reasoning bubbles are delivery-only — they are not added to assistant/session history. Telegram is currently the only channel that implements this control (`ReasoningDeliveryChannel`).

### Media Handling

**Albums / multi-attachment coalescing.** When a user sends an album (several photos or files grouped on the client), Telegram delivers it as N separate updates that share one `MediaGroupID`. GoClaw buffers album members at the channel layer (500 ms silence window) and synthesizes them into **one** inbound message, so the agent replies once instead of once per attachment. The buffer key is `(chatID, MediaGroupID)`; the sender is pinned on the first member, and a member arriving with a mismatched sender is dropped as a defensive measure.

**Outbound album batching.** When the agent sends several files at once — via the `send_file` tool's `attachments: [{path, caption?}, ...]` form — Telegram groups compatible outbound media into `sendMediaGroup` album chunks of **2–10** items. Photos and videos can share a chunk; documents group only with documents and audio only with audio. Voice-mode audio, singleton chunks, oversized images that fall back to being sent as documents, and otherwise-incompatible runs degrade gracefully to ordered single-send. File order, MIME type, filename, and captions are preserved.

**Outbound upload limit.** Outbound media is validated against the upload ceiling before sending — files over the limit are rejected with a clear "outbound media too large" error rather than failing mid-upload. The ceiling is 50 MB on the official Bot API and 200 MB when a local Bot API server (`api_server`) is configured (or higher if `media_max_bytes` is raised above that).

**Archive path preservation.** Inbound files keep their original extension when persisted (e.g. a `codex.zip` upload stays `.zip` rather than being rewritten to a generic name), so skills and document tools can detect and extract archives correctly downstream.

### Reactions

Show emoji status on user messages. Set `reaction_level`:

- `off` — No reactions (default)
- `minimal` — Only terminal states (done/error)
- `full` — All status transitions with debouncing and stall detection

**Status → Emoji mapping** (use `/reactions` in chat to see this legend):

| Status | Emoji | Description |
|--------|-------|-------------|
| queued | 👀 | Waiting to process |
| thinking | 🤔 | Processing your request |
| tool | ✍ | Executing a tool |
| coding | 👨‍💻 | Running code |
| web | ⚡ | Browsing / API call |
| done | 👍 | Completed |
| error | 💔 | Something went wrong |
| stallSoft | 🥱 | No activity for 10s |
| stallHard | 😨 | No activity for 30s |

Each status has fallback emoji variants in case the primary emoji is restricted by the chat's allowed reactions. Intermediate states (thinking, tool, etc.) are debounced at 700ms to avoid reaction spam.

> **No placeholder tool-status text.** Deterministic tool-status updates are surfaced through reactions only — they no longer emit a separate "tool" text message in the channel. Platform reactions and explicit reasoning delivery remain independent behaviors.

### Bot Commands

Commands processed before message enrichment:

| Command | Behavior | Restricted |
|---------|----------|-----------|
| `/help` | Show command list | -- |
| `/start` | Passthrough to agent | -- |
| `/stop` | Cancel current run | -- |
| `/stopall` | Cancel all runs | -- |
| `/reset` | Clear session history | Writers only |
| `/status` | Bot status + username | -- |
| `/tasks` | Team task list | -- |
| `/task_detail <id>` | View task | -- |
| `/subagents` | List all active subagent tasks with status | -- |
| `/subagent <id>` | Show detailed view of a subagent task (DB-backed) | -- |
| `/reactions` | Show reaction emoji legend (status → emoji mapping) | -- |
| `/addwriter` | Add group file writer | Writers only |
| `/removewriter` | Remove group file writer | Writers only |
| `/writers` | List group writers | -- |

Writers are group members allowed to run sensitive commands (`/reset`, file writes). Manage via `/addwriter` and `/removewriter` (reply to target user).

## Networking Isolation

Each Telegram instance maintains an isolated HTTP transport — no shared connection pools between bots. This prevents cross-bot contention and enables per-account network routing.

| Option | Default | Description |
|--------|---------|-------------|
| `force_ipv4` | false | Force IPv4 for all connections. Useful for sticky routing or when IPv6 is broken/blocked. |
| `proxy` | -- | HTTP proxy URL for this specific bot instance (e.g. `http://proxy:8080`). |
| `api_server` | -- | Custom Telegram Bot API server. Useful with local Bot API server or private deployments. |

**Sticky IPv4 fallback**: When `force_ipv4: true`, the dialer is locked to `tcp4` at startup, ensuring consistent source IP across all requests to Telegram. This helps with rate limit management in environments with unstable IPv6.

```json
{
  "channels": {
    "telegram": {
      "token": "...",
      "force_ipv4": true,
      "proxy": "http://proxy.example.com:8080",
      "api_server": "http://localhost:8081"
    }
  }
}
```

## Group-to-Supergroup Migration

When a Telegram group is upgraded to a supergroup, the chat ID changes. GoClaw handles this automatically:

- **Inbound detection** — When a `MigrateToChatID` message arrives, GoClaw updates all DB references (paired_devices, sessions, channel_contacts) atomically and invalidates in-memory caches
- **Send-path retry** — If a send fails because the group was migrated, GoClaw detects the new chat ID from the Telegram API error, updates DB, and retries the send automatically
- **Idempotent** — Safe to trigger multiple times; duplicate migrations are no-ops

No configuration needed. Check logs for `telegram: migrating group chat` entries if troubleshooting.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Bot not responding in groups | Ensure privacy mode is disabled via @BotFather (`/setprivacy` → Disable). Then check `require_mention=true` (default) — mention bot or reply to its message. For multi-bot groups, try `mention_mode: "yield"`. |
| Media downloads fail | Verify bot has `Can read all group messages` in @BotFather (`/setprivacy` → Disable). Check `media_max_bytes` limit. |
| STT transcription missing | Verify STT proxy URL and API key. Check logs for timeout. |
| Streaming not working | Enable `dm_stream` or `group_stream`. Ensure provider supports streaming. |
| Topic routing fails | Check topic ID in config keys (integer thread ID). Generic topic (ID=1) stripped in Telegram API. |

## What's Next

- [Overview](/channels-overview) — Channel concepts, policies, and [inbound debounce](/channels-overview#inbound-debounce)
- [Discord](/channel-discord) — Discord bot setup
- [Browser Pairing](/channel-browser-pairing) — Pairing flow
- [Sessions & History](../core-concepts/sessions-and-history.md) — Conversation history



---

# Bitrix24 Channel

Bitrix24 integration via the **imbot** (chatbot) API. GoClaw registers a bot on a Bitrix24 portal, receives chat events through a webhook, and replies as the bot. One GoClaw gateway can serve many bots across many portals, and several bots can share a single portal (they share OAuth tokens and the refresh loop).

Unlike token-based channels (Telegram, Slack), Bitrix24 uses an **OAuth portal install flow**: an admin authorizes the GoClaw app on their portal once, GoClaw stores and auto-refreshes the tokens, then registers bots on demand.

## How It Works

```mermaid
flowchart LR
    Admin["Portal admin"] -->|"visits /bitrix24/install"| Install["Install handler<br/>OAuth exchange"]
    Install -->|"stores tokens"| Portal["bitrix_portals row<br/>(encrypted)"]
    Channel["bitrix24 channel"] -->|"imbot.register"| BX["Bitrix24 portal"]
    BX -->|"POST /bitrix24/events"| Webhook["Webhook router"]
    Webhook -->|"dedup + dispatch"| Agent["Agent loop"]
    Agent -->|"imbot.message.add"| BX
```

1. **Seed a portal row** with the app's `client_id` / `client_secret` (CLI or dashboard).
2. **Admin authorizes** by visiting the install URL — GoClaw exchanges the code for tokens and persists them encrypted.
3. **Configure a channel instance** that points at the portal and names the bot.
4. On start, the channel calls `imbot.register` (idempotently) and wires the returned bot ID into the webhook router.
5. Inbound chat events hit `/bitrix24/events`; GoClaw deduplicates, dispatches to the agent loop, and replies as the bot.

## Setup

### 1. Create a Bitrix24 application

In your Bitrix24 portal, create either a **Local application** or a **Marketplace (OAuth2) application**. You need:

- `client_id` (application ID)
- `client_secret` (application key)
- OAuth scopes including `imbot` (chatbot) and `user` (so GoClaw can resolve sender display names)

Set the application handler / installer URL to your GoClaw public URL:

- **Install / installer URL:** `https://<your-public-url>/bitrix24/install`
- **Events:** registered automatically by GoClaw (`https://<your-public-url>/bitrix24/events`)

> **Public URL required.** Bitrix24 needs absolute, publicly reachable URLs for the event handlers it calls. GoClaw captures the public URL automatically from the install callback. If your gateway sits behind a tunnel or rotating ingress, see [Public URL handling](#public-url-handling).

### 2. Seed the portal row

A `bitrix_portals` row must exist before the admin authorizes the app. Create it via CLI:

```bash
goclaw bitrix-portal create \
  --tenant-id <tenant-uuid> \
  --name acme \
  --domain acme.bitrix24.com \
  --client-id <your-client-id> \
  --client-secret <your-client-secret>
```

The `--name` (e.g. `acme`) is the portal key your channel config references. The `--domain` is the bare host — no scheme, no trailing slash.

> **Self-hosted portals are supported.** In addition to Bitrix24 cloud domains (`*.bitrix24.{com,eu,vn,...}` and `*.bitrix.info`), `--domain` accepts a **self-hosted Bitrix24 FQDN** such as `bx.mycompany.com` (an optional `:port` is allowed). Self-hosted domains pass an SSRF-safe validation step: the hostname is resolved and **every** returned IP is checked, loopback/private/metadata IP ranges are rejected, `localhost` / `.local` / `.localhost` names are blocked, and any port must be in the range 1–65535. Cloud domains skip this check (they are Bitrix-operated and trusted).

> Set `GOCLAW_ENCRYPTION_KEY` before running this. Credentials and tokens are stored AES-256-GCM encrypted; without the key they are stored in plaintext (with a warning).

You can also create portals from the dashboard, which returns the install URL directly.

### 3. Authorize the portal

Direct the portal admin to the install URL printed by the create command:

```
https://<your-public-url>/bitrix24/install?state=<tenant-uuid>:acme
```

The admin authorizes the app inside Bitrix24. GoClaw exchanges the code for tokens, captures the public URL, and shows a small auto-closing success page. The portal is now **installed**.

Both install flows are supported automatically:

- **Marketplace (OAuth2):** `code` is exchanged for tokens.
- **Local application:** Bitrix24 POSTs the tokens directly (`AUTH_ID` / `REFRESH_ID`); no exchange step.

### 4. Configure the channel instance

Create a `bitrix24` channel instance whose config points at the portal and names the bot:

```json
{
  "portal": "acme",
  "bot_code": "support-bot",
  "bot_name": "GoClaw Assistant",
  "bot_type": "B",
  "dm_policy": "pairing",
  "group_policy": "open"
}
```

On start, the channel registers the bot (idempotently — restarts never spawn duplicate bots) and begins receiving events. If the portal is not yet installed, the channel reports a `failed` health state with the message "Portal not installed — visit /bitrix24/install".

## Configuration

Channel instance config fields:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `portal` | string | required | Portal name (matches `bitrix-portal create --name`) |
| `bot_code` | string | required | Stable bot key passed to `imbot.register`. Restarts reuse the same code. |
| `bot_name` | string | required | Bot display name on the portal |
| `bot_avatar` | string | -- | Image URL; fetched and base64-encoded at start (http/https only, ≤256 KB) |
| `bot_type` | string | `"B"` | `"B"` = standard internal chatbot; `"O"` = Open Channel (customer-facing) bot |
| `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
| `group_policy` | string | `"open"` | `open`, `allowlist`, `disabled` |
| `allow_from` | list | -- | DM sender allowlist |
| `group_allow_from` | list | -- | Group sender allowlist |
| `require_mention` | bool | true | Require @mention in group chats |
| `text_chunk_limit` | int | 4000 | Max characters per outbound chunk |
| `media_max_mb` | int | 20 | Max media size in MB |
| `streaming` | bool | true | Stream responses |
| `reaction_level` | string | `"minimal"` | `off`, `minimal`, `full` |
| `history_limit` | int | -- | Pending group messages held as context |
| `block_reply` | bool | -- | Override gateway `block_reply` (nil = inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |
| `public_url` | string | -- | Per-instance public URL override (legacy; prefer the auto-captured portal URL) |
| `mcp_server_name` | string | -- | MCP server name for per-user credential provisioning (see [MCP integration](#mcp-integration)) |
| `mcp_base_url` | string | -- | MCP server base URL; must be set together with `mcp_server_name` |

### Bot types

| Type | Audience | Notes |
|------|----------|-------|
| `B` | Internal staff | Sees DMs always; sees group messages only when @mentioned. Pairs with users and can receive per-user MCP credentials. Recommended: `dm_policy: pairing`, `group_policy: open`. |
| `O` | External customers (Open Channel widget) | After registration, an admin must attach the bot to an Open Channel queue in the Bitrix24 UI. Recommended: `dm_policy: open`. Per-user MCP provisioning is skipped (customers are transient). |

> GoClaw only accepts `B` or `O`. Unknown types are rejected at startup to avoid a bot that silently receives no events.

## Public URL handling

`imbot.register` requires absolute URLs for its event handlers. GoClaw resolves the public URL in this order:

1. **Auto-captured portal URL** — recorded from the actual `/bitrix24/install` request Bitrix24 sent. This is the preferred source because it is proven reachable.
2. **`public_url` in channel config** — a legacy fallback used only when (1) is empty (e.g. a portal installed on an older GoClaw release).

If your public URL changes (tunnel rotated, redeployed to a new host), re-run the install flow to recapture it, or backfill it:

```bash
goclaw bitrix-portal set-public-url \
  --tenant-id <tenant-uuid> \
  --name acme \
  --url https://goclaw.example.com
```

To push a changed URL back into Bitrix24's event handlers without recreating the bot, restart the channel with:

```bash
BITRIX24_FORCE_REREGISTER=1 goclaw gateway
```

This bypasses the cached bot state and re-runs `imbot.register` with the current URL and config.

## Features

### Contact enrichment

Bitrix24 webhook events do not carry sender display names. On first sight of a user, GoClaw calls `user.get` to resolve a friendly name (e.g. `Name Last_Name`, falling back to login or email) and caches it per channel (1 hour for hits, 5 minutes for failures). This requires the `user` OAuth scope — without it, names stay blank and a debug log explains why. Enrichment is best-effort: a failure never blocks message processing.

### Inbound deduplication

Bitrix24 retries event delivery on any non-2xx response (and may fire 3–5 retries in a burst). GoClaw deduplicates inbound events by `domain:event_type:message_id` using a bounded LRU cache, so a retried delivery returns `{"duplicate":true}` (HTTP 200) and never triggers a second agent run — important because Bitrix24 bills per bot and duplicate runs would double token usage.

### Token refresh

OAuth access tokens (1-hour TTL) are refreshed automatically in the background, slightly ahead of expiry, with exponential backoff on failure. Concurrent requests coalesce so only one refresh runs at a time. If the refresh token becomes invalid, the portal requires a reinstall.

### Inbound debounce

Like other channels, Bitrix24 honors the gateway-wide inbound debounce window that merges rapid messages from the same sender into one agent run. See [Inbound Debounce](/channels-overview#inbound-debounce) in the overview.

## MCP integration

The Bitrix24 channel can lazily provision **per-user MCP credentials** so each user's agent tools act on Bitrix24 as that user. This is optional and staged — install the channel first, layer MCP on later.

Set both fields to enable it:

```json
{
  "portal": "acme",
  "bot_code": "support-bot",
  "bot_name": "GoClaw Assistant",
  "mcp_server_name": "bitrix-mcp",
  "mcp_base_url": "https://mcp.example.com"
}
```

How it works:

1. On a user's first message, the channel checks for existing MCP credentials.
2. If absent (or near expiry), it POSTs to `{mcp_base_url}/api/auto-onboard`, forwarding that user's Bitrix24 OAuth tokens.
3. The MCP server authenticates the call by verifying the access token against Bitrix24 `profile` (no shared admin secret needed), then returns a per-user API key.
4. GoClaw stores the key; downstream agent tool calls use it transparently.

Notes:

- Both `mcp_server_name` and `mcp_base_url` must be set together, or neither (half-config fails at startup). The named MCP server row must also exist.
- Provisioning is **best-effort**: if any step fails, the user still gets a reply (without MCP tools), and a one-time notice is sent so they know to contact an admin.
- Skipped entirely for Open Channel bots (`bot_type: "O"`) — transient customers have no user mapping.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Channel `failed`: "Portal not installed" | Admin must visit `/bitrix24/install` to authorize the app first. |
| `imbot.register` fails: public_url not set | The portal has no captured public URL. Re-run install, or `goclaw bitrix-portal set-public-url`. |
| Bot registered but receives no chat events | Install was not finalized — Bitrix24 suppresses events until `BX24.installFinish()` runs. Reinstall via `/bitrix24/install` so the success page signals completion. |
| Contact names stay blank | OAuth scope missing `user`. Add the scope and reinstall; names appear within 5 minutes. |
| Open Channel bot silent to customers | `bot_type: "O"` needs `dm_policy: "open"`, and an admin must attach the bot to an Open Channel queue in the Bitrix24 UI. |
| Event handler URL stale after redeploy | Set `BITRIX24_FORCE_REREGISTER=1` and restart to push the new URL into Bitrix24. |
| Want to inspect raw events | Set `BITRIX24_LOG_RAW_EVENT=1` at process start (credentials are redacted). Leave off in production — it logs message text. |
| Self-hosted domain rejected | The FQDN must resolve to a public IP. SSRF validation blocks loopback/private/metadata IP ranges and `localhost` / `.local` / `.localhost` names; ports must be 1–65535. |

## What's Next

- [Overview](/channels-overview) — Channel concepts, policies, and inbound debounce
- [Telegram](/channel-telegram) — Telegram bot setup
- [Slack](/channel-slack) — Slack Socket Mode integration
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Discord Channel

Discord bot integration via the Discord Gateway API. Supports DMs, servers, threads, and streaming responses via message editing.

## Setup

**Create a Discord Application:**
1. Go to https://discord.com/developers/applications
2. Click "New Application"
3. Go to "Bot" tab → "Add Bot"
4. Copy the token
5. Ensure `Message Content Intent` is enabled under "Privileged Gateway Intents"

**Add Bot to Server:**
1. OAuth2 → URL Generator
2. Select scopes: `bot`
3. Select permissions: `Send Messages`, `Read Message History`, `Read Messages/View Channels`
4. Copy the generated URL and open in browser

**Enable Discord:**

```json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "dm_policy": "open",
      "group_policy": "open",
      "allow_from": ["alice_id", "bob_id"]
    }
  }
}
```

## Configuration

All config keys are in `channels.discord`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `token` | string | required | Bot token from Discord Developer Portal |
| `allow_from` | list | -- | User ID allowlist |
| `dm_policy` | string | `"open"` | `open`, `allowlist`, `pairing`, `disabled` |
| `group_policy` | string | `"open"` | `open`, `allowlist`, `disabled` |
| `require_mention` | bool | true | Require @bot mention in servers (channels) |
| `history_limit` | int | 50 | Pending messages per channel (0=disabled) |
| `block_reply` | bool | -- | Override gateway block_reply (nil=inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |

## Features

### Gateway Intents

Automatically requests `GuildMessages`, `DirectMessages`, and `MessageContent` intents on startup.

### Message Limits

Discord enforces 2,000 characters per message. Responses longer than this are split at newline boundaries.

### Placeholder Editing

Bot sends "Thinking..." placeholder immediately, then edits it with the actual response. This provides visual feedback while the agent processes.

```mermaid
flowchart TD
    SEND["Send 'Thinking...'<br/>placeholder"]
    SEND --> PROCESS["Agent processes<br/>& streaming chunks"]
    PROCESS --> EDIT["Edit message<br/>with response"]
    EDIT --> DONE["Response complete"]
```

### Mention Gating

In servers (channels), the bot requires being mentioned by default (`require_mention: true`). Pending messages are stored in a history buffer. When the bot is mentioned, history is included as context.

**Group @mention detection:** A message is counted as an @mention when the bot's user ID appears in the `mentions` array of the Discord event, *or* when the message is a direct reply to one of the bot's own messages. Both conditions are checked before any policy or pairing logic runs.

**Pairing replies in groups:** When `group_policy: "pairing"` is set and `require_mention: true` (the default), the bot only sends a pairing invite to an unpaired user if that user explicitly @mentioned the bot (or replied to the bot). Messages that do not address the bot are silently added to the group history buffer and never trigger a pairing reply. Set `require_mention: false` to send pairing invites unconditionally in groups (not recommended for public servers).

### Typing Indicator

While the agent processes, a typing indicator is shown (9-second keepalive). The typing indicator stops automatically after successful message delivery.

### Thread Support

The bot automatically detects and responds in Discord threads. Responses stay in the same thread.

### Thread History Backfill

When the bot is mentioned **inside a Discord thread**, GoClaw pulls in the recent thread context before answering — so a mid-thread mention isn't answered blind.

- Fetches up to **25** prior thread messages (before the trigger) via the Discord REST API and prepends their text as context.
- Downloads up to **15** prior attachments into the inbound media pipeline, bounded to **5 MB per file**.
- The whole backfill is bounded by a **30-second** timeout.

This is **thread-only**. If the bot is missing the `READ_MESSAGE_HISTORY` permission or the REST call fails, GoClaw falls back gracefully to just the current message.

### Multi-File Delivery

Discord delivers multiple files (plus optional text) in a **single message**, up to 10 attachments — so a batch `send_file` lands as one tidy message rather than a flood. See [Multi-Attachment Delivery](/channels-overview#multi-attachment-delivery-batching) in the overview.

### Media from Replied-to Messages

When a user replies to a message that contains media attachments, GoClaw extracts those attachments and includes them in the inbound message context. This lets the agent see and process media even when it was originally shared in a previous turn. Attachment source URLs are preserved in media tags, so agents can reference the original Discord CDN URL.

### Group Media History

Media files (images, video, audio) sent in group conversations are tracked in message history, allowing agents to reference previously shared media.

### Bot Identity

On startup, the bot fetches its own user ID via `@me` endpoint to avoid responding to its own messages.

### Allowlist and Pairing Policy

`dm_policy` and `group_policy` work as documented — `pairing`, `allowlist`, and `open` modes are handled exclusively by the policy evaluation layer. There is no additional allowlist gate after the policy check, so paired users are not wrongly rejected when an `allow_from` list is also configured. If a user is paired but also listed in `allow_from`, both conditions are satisfied and the message proceeds normally.

### Group File Writer Management

Discord supports slash-command-based management of group file writers (similar to Telegram's writer restriction). In server channels, write-sensitive operations can be restricted to designated writers:

| Command | Description |
|---------|-------------|
| `/addwriter` | Add a group file writer (reply to target user) |
| `/removewriter` | Remove a group file writer |
| `/writers` | List current group file writers |

Writers are managed per-group. The group ID format used internally is `group:discord:{channelID}`.

## Common Patterns

### Sending to a Channel

```go
manager.SendToChannel(ctx, "discord", "channel_id", "Hello!")
```

### Group Configuration

Per-guild/channel overrides are not yet supported in the Discord channel implementation. Use global `allow_from` and policies.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Bot doesn't respond | Check bot has necessary permissions. Verify `require_mention` setting. Ensure bot can read messages (`Message Content Intent` enabled). |
| "Unknown Application" error | Token is invalid or expired. Regenerate bot token. |
| Placeholder editing fails | Ensure bot has `Manage Messages` permission. Discord may revoke this during setup. |
| Message split incorrectly | Long responses are split at newlines. Control message length via model `max_tokens`. |
| Bot mentions itself | Check Discord permissions. Bot should not have `@everyone` or `@here` in responses. |
| Thread context missing | Thread history backfill needs `READ_MESSAGE_HISTORY`. Grant the permission; only works inside threads. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Telegram](/channel-telegram) — Telegram bot setup
- [Larksuite](/channel-feishu) — Larksuite integration with streaming cards
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Feishu Channel

[Feishu](https://www.feishu.cn/) (飞书) messaging integration for China users — supporting DMs, groups, streaming cards, and real-time updates via WebSocket or webhook.

## Setup

**Create Feishu App:**

1. Go to https://open.feishu.cn
2. Create custom app → fill Basic Information
3. Under "Bots" → enable "Bot" capability
4. Set bot name and avatar
5. Copy `App ID` and `App Secret`
6. Grant permissions: `im:message`, `im:message.p2p_msg:send`, `im:message.group_msg:send`, `contact:user.id:readonly`

**Enable Feishu:**

```json
{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
      "connection_mode": "websocket",
      "domain": "feishu",
      "dm_policy": "pairing",
      "group_policy": "open"
    }
  }
}
```

## Configuration

All config keys are in `channels.feishu`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `app_id` | string | required | App ID from Feishu Developer Console |
| `app_secret` | string | required | App Secret from Feishu Developer Console |
| `encrypt_key` | string | -- | Optional message encryption key |
| `verification_token` | string | -- | Optional webhook verification token |
| `domain` | string | `"feishu"` | `"feishu"` for China, `"lark"` for Larksuite |
| `connection_mode` | string | `"websocket"` | `"websocket"` or `"webhook"` |
| `webhook_port` | int | 3000 | Port for webhook server (0=mount on gateway mux) |
| `webhook_path` | string | `"/feishu/events"` | Webhook endpoint path |
| `allow_from` | list | -- | User ID allowlist (DMs) |
| `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
| `group_policy` | string | `"open"` | `open`, `allowlist`, `disabled` |
| `group_allow_from` | list | -- | Group ID allowlist |
| `require_mention` | bool | true | Require bot mention in groups |
| `topic_session_mode` | string | `"disabled"` | `"disabled"` or `"enabled"` for thread isolation |
| `text_chunk_limit` | int | 4000 | Max text characters per message |
| `media_max_mb` | int | 30 | Max media file size (MB) |
| `render_mode` | string | `"auto"` | `"auto"` (detect), `"card"`, `"raw"` |
| `streaming` | bool | true | Enable streaming card updates |
| `reaction_level` | string | `"off"` | `off`, `minimal` (⏳ only), `full` |
| `history_limit` | int | -- | Max messages to load from history |
| `block_reply` | bool | -- | Block reply-to-message context |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |
| `stt_proxy_url` | string | -- | Speech-to-text proxy URL |
| `stt_api_key` | string | -- | Speech-to-text API key |
| `stt_tenant_id` | string | -- | Speech-to-text tenant ID |
| `stt_timeout_seconds` | int | -- | Speech-to-text request timeout |
| `voice_agent_id` | string | -- | Agent ID for voice message handling |

## Transport Modes

### WebSocket (Default)

Persistent connection with auto-reconnect. Recommended for low latency.

```json
{
  "connection_mode": "websocket"
}
```

### Webhook

Feishu sends events via HTTP POST. Choose:

1. **Mount on gateway mux** (`webhook_port: 0`): Handler shares main gateway port
2. **Separate server** (`webhook_port: 3000`): Dedicated webhook listener

```json
{
  "connection_mode": "webhook",
  "webhook_port": 0,
  "webhook_path": "/feishu/events"
}
```

Then configure the webhook URL in Feishu Developer Console:
- Gateway mux: `https://your-gateway.com/feishu/events`
- Separate server: `https://your-webhook-host:3000/feishu/events`

## Features

### Streaming Cards

Real-time updates delivered as interactive card messages with animation:

```mermaid
flowchart TD
    START["Agent starts responding"] --> CREATE["Create streaming card"]
    CREATE --> SEND["Send card message<br/>(streaming_mode: true)"]
    SEND --> UPDATE["Update card text<br/>with accumulated chunks<br/>(throttled: 100ms min)"]
    UPDATE -->|"More chunks"| UPDATE
    UPDATE -->|"Done"| CLOSE["Close stream<br/>(streaming_mode: false)"]
    CLOSE --> FINAL["User sees full response"]
```

Updates throttled to prevent rate limiting. Display uses 50ms animation frequency (2-character steps).

### Media Handling

**Inbound**: Images, files, audio, video, stickers auto-downloaded and saved:

| Type | Extension |
|------|-----------|
| Image | `.png` |
| File | Original extension |
| Audio | `.opus` |
| Video | `.mp4` |
| Sticker | `.png` |

Max 30 MB by default (`media_max_mb`).

**Outbound**: Files auto-detected and uploaded with correct type (opus, mp4, pdf, doc, xls, ppt, or stream).

**Rich post messages**: GoClaw also extracts images embedded in Feishu rich-text `post` messages (not only standalone image messages). Images within a post body are downloaded and included alongside other media in the inbound message context.

### @Mention Support

The bot sends native Feishu @mentions in group messages. When the agent response contains `@open_id` patterns (e.g. `@ou_abc123`), they are automatically converted to native Lark `at` elements that trigger real notifications to the mentioned user. This works in both `post` text messages and interactive card messages.

### Mention Resolution

Feishu sends placeholder tokens (e.g., `@_user_1`). Bot parses mention list and resolves to `@DisplayName`.

### Thread Session Isolation

When `topic_session_mode: "enabled"`, each thread gets isolated conversation:

```
Session key: "{chatID}:topic:{rootMessageID}"
```

Different threads in same group maintain separate histories.

### Slash Commands (File Writer Management)

In group chats, group members can manage file-write permissions using slash commands:

| Command | Description |
|---------|-------------|
| `/addwriter <@mention or reply>` | Grant file-write permission to a user in the group |
| `/removewriter <@mention or reply>` | Revoke file-write permission from a user |
| `/writers` | List all users with file-write permissions in the group |

**How to specify the target user:** Reply to the user's message and send the command, or @mention them in the same message. Self-grant is supported by @mentioning yourself.

**Authorization:** Only existing file writers can manage the list. When the list is empty, the first caller can seed it by specifying an explicit target.

> These commands work in group chats only. DMs are rejected.

### Lark Docx Auto-Fetch

When a Lark docx URL is pasted in chat, GoClaw automatically detects and fetches the document content via the Lark API and inlines it into the agent's prompt — no tool call required.

**Supported URL formats:**
- `https://*.feishu.cn/docx/<id>`
- `https://*.larksuite.com/docx/<id>`

**Required app permission scope:** `docx:document:readonly` — add this in your Feishu Developer Console under Permissions & Scopes.

**Implementation details:**
- LRU cache: 128 entries, 5-minute TTL (repeated links in the same session are served from cache)
- Content truncated at 8,000 runes to fit the agent's context window
- Duplicate doc IDs in the same message are collapsed — each doc is fetched only once

> Only `/docx/` URLs are supported. Sheets, Base, Wiki, and other Lark document types are out of scope.

### list_group_members Tool

When connected to a Feishu channel, agents have access to the `list_group_members` tool. It returns all members of the current group chat with their `open_id` and display name.

```
list_group_members(channel?, chat_id?) → { count, members: [{ member_id, name }] }
```

Use cases: checking who is in a group, identifying members before mentioning them, attendance tracking. To @mention a member in a reply, use `@member_id` (e.g. `@ou_abc123`) — the bot converts it to a native Feishu mention with notification.

> This tool is only available on Feishu/Lark channels. It will not appear in the tool list for other channel types.

### Per-Topic Tool Allow List

Forum topics support their own tool whitelist. Configure under the agent's tool settings or channel metadata:

| Value | Behavior |
|-------|----------|
| `nil` (omit) | Inherit parent group's tool allow list |
| `[]` (empty) | No tools allowed in this topic |
| `["web_search", "group:fs"]` | Only these tools allowed |

The `group:fs` prefix selects all tools in the `fs` (Feishu) tool group. This follows the same `group:xxx` syntax used in Telegram topic config.

### Speech-to-Text

Voice messages can be transcribed by configuring an STT service:

```json
{
  "stt_proxy_url": "https://your-stt-service.com",
  "stt_api_key": "YOUR_STT_KEY",
  "stt_timeout_seconds": 30
}
```

Set `voice_agent_id` to route transcribed voice messages to a specific agent.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Invalid app credentials" | Check app_id and app_secret. Ensure app is published. |
| Webhook not receiving events | Verify webhook URL is publicly accessible. Check Feishu Developer Console event subscriptions. |
| WebSocket keeps disconnecting | Check network. Verify app has `im:message` permission. |
| Streaming cards not updating | Ensure `streaming: true`. Check `render_mode` (auto/card). Messages shorter than limit render as plain text. |
| Media upload fails | Verify file type matches. Check file size under `media_max_mb`. |
| Mention not parsed | Ensure bot is mentioned. Check mention list in webhook payload. |
| Wrong domain | China users must set `domain: "feishu"`. International users use `domain: "lark"`. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Larksuite](/channel-larksuite) — Larksuite (international) setup
- [Telegram](/channel-telegram) — Telegram bot setup
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Larksuite Channel

[Larksuite](https://www.larksuite.com/) messaging integration supporting DMs, groups, streaming cards, and real-time updates via WebSocket or webhook.

## Setup

**Create Larksuite App:**

1. Go to https://open.larksuite.com
2. Create custom app → fill Basic Information
3. Under "Bots" → enable "Bot" capability
4. Set bot name and avatar
5. Copy `App ID` and `App Secret`
6. Grant the required API scopes (see [Required API Scopes](#required-api-scopes) below)
7. Set Contact Range to **"All members"** under Permissions & Scopes → Contacts
8. Publish the app version (scopes take effect only after publishing)

**Enable Larksuite:**

```json
{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
      "connection_mode": "websocket",
      "domain": "lark",
      "dm_policy": "pairing",
      "group_policy": "open"
    }
  }
}
```

## Configuration

All config keys are in `channels.feishu`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `app_id` | string | required | App ID from Larksuite Developer Console |
| `app_secret` | string | required | App Secret from Larksuite Developer Console |
| `encrypt_key` | string | -- | Optional message encryption key |
| `verification_token` | string | -- | Optional webhook verification token |
| `domain` | string | `"lark"` | `"lark"` (Larksuite) or custom domain |
| `connection_mode` | string | `"websocket"` | `"websocket"` or `"webhook"` |
| `webhook_port` | int | 3000 | Port for webhook server (0=mount on gateway mux) |
| `webhook_path` | string | `"/feishu/events"` | Webhook endpoint path |
| `allow_from` | list | -- | User ID allowlist (DMs) |
| `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
| `group_policy` | string | `"open"` | `open`, `allowlist`, `disabled` |
| `group_allow_from` | list | -- | Group ID allowlist |
| `require_mention` | bool | true | Require bot mention in groups |
| `topic_session_mode` | string | `"disabled"` | `"disabled"` or `"enabled"` for thread isolation |
| `text_chunk_limit` | int | 4000 | Max text characters per message |
| `media_max_mb` | int | 30 | Max media file size (MB) |
| `render_mode` | string | `"auto"` | `"auto"` (detect), `"card"`, `"raw"` |
| `streaming` | bool | true | Enable streaming card updates |
| `reaction_level` | string | `"off"` | `off`, `minimal` (⏳ only), `full` |

## Transport Modes

### WebSocket (Default)

Persistent connection with auto-reconnect. Recommended for low latency.

```json
{
  "connection_mode": "websocket"
}
```

### Webhook

Larksuite sends events via HTTP POST. Choose:

1. **Mount on gateway mux** (`webhook_port: 0`): Handler shares main gateway port
2. **Separate server** (`webhook_port: 3000`): Dedicated webhook listener

```json
{
  "connection_mode": "webhook",
  "webhook_port": 0,
  "webhook_path": "/feishu/events"
}
```

Then configure the webhook URL in Larksuite Developer Console:
- Gateway mux: `https://your-gateway.com/feishu/events`
- Separate server: `https://your-webhook-host:3000/feishu/events`

## Required API Scopes

Your Larksuite app needs these 15 scopes. The Dashboard shows the full list in a collapsible panel when creating or editing a Feishu channel.

| Scope | Purpose |
|-------|---------|
| `im:message` | Core messaging |
| `im:message:readonly` | Read messages (reply context) |
| `im:message.p2p_msg:send` | Send DMs |
| `im:message.group_msg:send` | Send group messages |
| `im:message.group_at_msg` | Send @-mention messages |
| `im:message.group_at_msg:readonly` | Read @-mention messages |
| `im:chat` | Chat management |
| `im:chat:readonly` | Read chat info |
| `im:resource` | Upload/download media |
| `contact:user.base:readonly` | Read user profiles |
| `contact:user.id:readonly` | Resolve user IDs |
| `contact:user.employee_id:readonly` | Resolve employee IDs |
| `contact:user.phone:readonly` | Resolve phone numbers |
| `contact:user.email:readonly` | Resolve emails |
| `contact:department.id:readonly` | Department lookup |

> **Important:** After granting scopes, set **Contact Range** to **"All members"** under Permissions & Scopes → Contacts, then publish a new app version. Without this, contact resolution returns empty names.

## Features

### Reply Context

When a user replies to a message in a DM, GoClaw includes the original message as context for the agent. In DMs, a `[From: sender_name]` annotation is prepended so the agent knows who sent the message.

### Streaming Cards

Real-time updates delivered as interactive card messages with animation:

```mermaid
flowchart TD
    START["Agent starts responding"] --> CREATE["Create streaming card"]
    CREATE --> SEND["Send card message<br/>(streaming_mode: true)"]
    SEND --> UPDATE["Update card text<br/>with accumulated chunks<br/>(throttled: 100ms min)"]
    UPDATE -->|"More chunks"| UPDATE
    UPDATE -->|"Done"| CLOSE["Close stream<br/>(streaming_mode: false)"]
    CLOSE --> FINAL["User sees full response"]
```

Updates throttled to prevent rate limiting. Display uses 50ms animation frequency (2-character steps).

### Media Handling

**Inbound**: Images, files, audio, video, stickers auto-downloaded and saved:

| Type | Extension |
|------|-----------|
| Image | `.png` |
| File | Original extension |
| Audio | `.opus` |
| Video | `.mp4` |
| Sticker | `.png` |

Max 30 MB by default (`media_max_mb`).

**Outbound**: Files auto-detected and uploaded with correct type (opus, mp4, pdf, doc, xls, ppt, or stream).

**Rich post messages**: GoClaw also extracts images embedded in Lark rich-text `post` messages (not only standalone image messages). Images within a post body are downloaded and included alongside other media in the inbound message context.

### @Mention Support

The bot sends native Lark @mentions in group messages. When the agent response contains `@open_id` patterns (e.g. `@ou_abc123`), they are automatically converted to native Lark `at` elements that trigger real notifications to the mentioned user. This works in both `post` text messages and interactive card messages.

### Mention Resolution

Larksuite sends placeholder tokens (e.g., `@_user_1`). Bot parses mention list and resolves to `@DisplayName`.

### Thread Session Isolation

When `topic_session_mode: "enabled"`, each thread gets isolated conversation:

```
Session key: "{chatID}:topic:{rootMessageID}"
```

Different threads in same group maintain separate histories.

### Slash Commands (File Writer Management)

In group chats, group members can manage file-write permissions using slash commands:

| Command | Description |
|---------|-------------|
| `/addwriter <@mention or reply>` | Grant file-write permission to a user in the group |
| `/removewriter <@mention or reply>` | Revoke file-write permission from a user |
| `/writers` | List all users with file-write permissions in the group |

**How to specify the target user:** Reply to the user's message and send the command, or @mention them in the same message. Self-grant is supported by @mentioning yourself.

**Authorization:** Only existing file writers can manage the list. When the list is empty, the first caller can seed it by specifying an explicit target.

> These commands work in group chats only. DMs are rejected.

### Lark Docx Auto-Fetch

When a Lark docx URL is pasted in chat, GoClaw automatically detects and fetches the document content via the Lark API and inlines it into the agent's prompt — no tool call required.

**Supported URL formats:**
- `https://*.feishu.cn/docx/<id>`
- `https://*.larksuite.com/docx/<id>`

**Required app permission scope:** `docx:document:readonly` — add this in your Larksuite Developer Console under Permissions & Scopes.

**Implementation details:**
- LRU cache: 128 entries, 5-minute TTL (repeated links in the same session are served from cache)
- Content truncated at 8,000 runes to fit the agent's context window
- Duplicate doc IDs in the same message are collapsed — each doc is fetched only once

> Only `/docx/` URLs are supported. Sheets, Base, Wiki, and other Lark document types are out of scope.

### list_group_members Tool

When connected to a Larksuite channel, agents have access to the `list_group_members` tool. It returns all members of the current group chat with their `open_id` and display name.

```
list_group_members(channel?, chat_id?) → { count, members: [{ member_id, name }] }
```

Use cases: checking who is in a group, identifying members before mentioning them, attendance tracking. To @mention a member in a reply, use `@member_id` (e.g. `@ou_abc123`) — the bot converts it to a native Lark mention with notification.

> This tool is only available on Feishu/Lark channels. It will not appear in the tool list for other channel types.

### Per-Topic Tool Allow List

Forum topics support their own tool whitelist. Configure under the agent's tool settings or channel metadata:

| Value | Behavior |
|-------|----------|
| `nil` (omit) | Inherit parent group's tool allow list |
| `[]` (empty) | No tools allowed in this topic |
| `["web_search", "group:fs"]` | Only these tools allowed |

The `group:fs` prefix selects all tools in the `fs` (Feishu/Lark) tool group. This follows the same `group:xxx` syntax used in Telegram topic config.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Invalid app credentials" | Check app_id and app_secret. Ensure app is published. |
| Webhook not receiving events | Verify webhook URL is publicly accessible. Check Larksuite Developer Console event subscriptions. |
| WebSocket keeps disconnecting | Check network. Verify app has `im:message` permission. |
| Streaming cards not updating | Ensure `streaming: true`. Check `render_mode` (auto/card). Messages shorter than limit render as plain text. |
| Media upload fails | Verify file type matches. Check file size under `media_max_mb`. |
| Mention not parsed | Ensure bot is mentioned. Check mention list in webhook payload. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Telegram](/channel-telegram) — Telegram bot setup
- [Zalo OA](/channel-zalo-oa) — Zalo Official Account
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Zalo OA Channel

Zalo Official Account (OA) integration. DM-only with pairing-based access control and image support.

## Setup

**Create Zalo OA:**

1. Go to https://oa.zalo.me
2. Create Official Account (requires Zalo phone number)
3. Set up OA name, avatar, and cover photo
4. In OA settings, go to "Settings" → "API" → "Bot API"
5. Create API key
6. Copy API key for configuration

**Enable Zalo OA:**

```json
{
  "channels": {
    "zalo": {
      "enabled": true,
      "token": "YOUR_API_KEY",
      "dm_policy": "pairing",
      "allow_from": [],
      "media_max_mb": 5
    }
  }
}
```

## Configuration

All config keys are in `channels.zalo`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `token` | string | required | API key from Zalo OA console |
| `allow_from` | list | -- | User ID allowlist |
| `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
| `webhook_url` | string | -- | Optional webhook URL (override polling) |
| `webhook_secret` | string | -- | Optional webhook signature secret |
| `media_max_mb` | int | 5 | Max image file size (MB) |
| `block_reply` | bool | -- | Override gateway block_reply (nil=inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |

## Features

### DM-Only

Zalo OA only supports direct messaging. Group functionality is not available. All messages are treated as DMs.

### Long Polling

Default mode: Bot polls Zalo API every 30 seconds for new messages. Server returns messages and marks them read.

- Poll timeout: 30 seconds (default)
- Error backoff: 5 seconds
- Text limit: 2,000 characters per message
- Image limit: 5 MB

### Webhook Mode (Optional)

Instead of polling, configure Zalo to POST events to your gateway:

```json
{
  "webhook_url": "https://your-gateway.com/zalo/webhook",
  "webhook_secret": "your_webhook_secret"
}
```

Zalo sends a HMAC signature in header `X-Zalo-Signature`. Implementation verifies this before processing.

### Image Support

Bot can receive and send images (JPG, PNG). Max 5 MB by default.

**Receive**: Images are downloaded and stored as temporary files during message processing.

**Send**: Images can be sent as media attachment:

```json
{
  "channel": "zalo",
  "content": "Here's your image",
  "media": [
    { "url": "/tmp/image.jpg", "type": "image" }
  ]
}
```

### Pairing by Default

Default DM policy is `"pairing"`. New users see pairing code instructions with 60-second debounce (no spam). Owner approves via:

```
/pair CODE
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Invalid API key" | Check token from Zalo OA console. Ensure OA is active and Bot API enabled. |
| No messages received | Verify polling is running (check logs). Ensure OA can accept messages (not suspended). |
| Image upload fails | Verify image file exists and is under `media_max_mb`. Check file format (JPG/PNG). |
| Webhook signature mismatch | Ensure `webhook_secret` matches Zalo console. Check timestamp is recent. |
| Pairing codes not sent | Check DM policy is `"pairing"`. Verify owner can send messages to OA. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Zalo Personal](/channel-zalo-personal) — Personal Zalo account integration
- [Telegram](/channel-telegram) — Telegram bot setup
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Zalo Personal Channel

Unofficial personal Zalo account integration using reverse-engineered protocol (zcago). Supports DMs and groups with restrictive access control.

## Warning: Use at Your Own Risk

Zalo Personal uses an **unofficial, reverse-engineered protocol**. Your account may be locked, banned, or restricted by Zalo at any time. This is NOT recommended for production bots. Use [Zalo OA](/channel-zalo-oa) for official integrations.

A security warning is logged on startup: `security.unofficial_api`.

## Setup

**Prerequisites:**
- Personal Zalo account with credentials
- Credentials stored as JSON file

**Create Credentials JSON:**

```json
{
  "phone": "84987654321",
  "password": "your_password_here",
  "device_id": "your_device_id"
}
```

**Enable Zalo Personal:**

```json
{
  "channels": {
    "zalo_personal": {
      "enabled": true,
      "credentials_path": "/home/goclaw/.goclaw/zalo-creds.json",
      "dm_policy": "allowlist",
      "group_policy": "allowlist",
      "allow_from": ["friend_zalo_id", "group_chat_id"]
    }
  }
}
```

## Configuration

All config keys are in `channels.zalo_personal`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `credentials_path` | string | -- | Path to credentials JSON file |
| `allow_from` | list | -- | User/group ID allowlist |
| `dm_policy` | string | `"allowlist"` | `pairing`, `allowlist`, `open`, `disabled` (restrictive default) |
| `group_policy` | string | `"allowlist"` | `open`, `allowlist`, `disabled` (restrictive default) |
| `require_mention` | bool | true | Require bot mention in groups |
| `block_reply` | bool | -- | Override gateway block_reply (nil=inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |

## Features

### Comparison with Zalo OA

| Aspect | Zalo OA | Zalo Personal |
|--------|---------|---------------|
| Protocol | Official Bot API | Reverse-engineered (zcago) |
| Account type | Official Account | Personal account |
| DM support | Yes | Yes |
| Group support | No | Yes |
| Default DM policy | `pairing` | `allowlist` (restrictive) |
| Default group policy | N/A | `allowlist` (restrictive) |
| Auth method | API key | Credentials (phone + password) |
| Risk level | None | High (account may be banned) |
| Recommended for | Official bots | Development/testing only |

### DM & Group Support

Unlike Zalo OA, Personal supports both DMs and groups:

- DMs: Direct conversations with individual users
- Groups: Group chats (Zalo chat groups)
- Default policies are **restrictive**: `allowlist` for both DM and group

Explicitly allow users/groups via `allow_from`:

```json
{
  "allow_from": [
    "user_zalo_id_1",
    "user_zalo_id_2",
    "group_chat_id_3"
  ]
}
```

### Authentication

Requires credentials file with phone, password, and device ID. On first connection, account may require QR scan or additional verification from Zalo.

**QR re-authentication**: When re-authenticating via QR scan (e.g., after session expiry), GoClaw safely cancels the previous session before starting a new QR flow. This race-safe cancel prevents duplicate sessions from running simultaneously and avoids conflicting login attempts.

### Media Handling

Media sending includes post-write verification — files are confirmed written to disk before being sent to the Zalo API.

### Resilience

On connection failure:
- Max 10 restart attempts
- Exponential backoff: 1s → 60s max
- Special handling for error code 3000: 60s initial delay (usually rate limiting)
- Typing controller per thread (local key)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Account locked" | Your account was restricted by Zalo. This happens frequently with bot integrations. Use Zalo OA instead. |
| "Invalid credentials" | Verify phone, password, and device ID in credentials file. Re-authenticate if Zalo requires verification. |
| No messages received | Check `allow_from` includes the sender. Verify DM/group policy is not `disabled`. |
| Bot keeps disconnecting | Zalo may be rate limiting. Check logs for error code 3000. Wait 60+ seconds before reconnecting. |
| "Unofficial API" warning | This is expected. Acknowledge the risk and use only for development/testing. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Zalo OA](/channel-zalo-oa) — Official Zalo integration (recommended)
- [Telegram](/channel-telegram) — Telegram bot setup
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Slack Channel

Slack integration via Socket Mode (WebSocket). Supports DMs, channel @mentions, threaded replies, streaming, reactions, media, and message debouncing.

## Setup

**Create a Slack App:**
1. Go to https://api.slack.com/apps?new_app=1
2. Select "From scratch", name your app (e.g., `GoClaw Bot`), pick workspace
3. Click **Create App**

**Enable Socket Mode:**
1. Left sidebar → **Socket Mode** → toggle ON
2. Name the token (e.g., `goclaw-socket`), add `connections:write` scope
3. Copy the **App-Level Token** (`xapp-...`)

**Add Bot Scopes:**
1. Left sidebar → **OAuth & Permissions**
2. Under **Bot Token Scopes**, add:

| Scope | Purpose |
|-------|---------|
| `app_mentions:read` | Receive @bot mention events |
| `chat:write` | Send and edit messages |
| `im:history` | Read DM messages |
| `im:read` | View DM channel list |
| `im:write` | Open DMs with users |
| `channels:history` | Read public channel messages |
| `groups:history` | Read private channel messages |
| `mpim:history` | Read multi-party DM messages |
| `reactions:write` | Add/remove emoji reactions (optional) |
| `reactions:read` | Read emoji reactions (optional) |
| `files:read` | Download files sent to bot |
| `files:write` | Upload files from agent |
| `users:read` | Resolve display names |

**Minimal set** (DM-only, no reactions/files): `chat:write`, `im:history`, `im:read`, `im:write`, `users:read`, `app_mentions:read`

**Enable Events:**
1. Left sidebar → **Event Subscriptions** → toggle ON
2. Under **Subscribe to bot events**, add:

| Event | Description |
|-------|-------------|
| `message.im` | Messages in DMs with the bot |
| `message.channels` | Messages in public channels |
| `message.groups` | Messages in private channels |
| `message.mpim` | Messages in multi-party DMs |
| `app_mention` | When bot is @mentioned |

No Request URL needed — Socket Mode handles events over WebSocket.

**Install & Get Token:**
1. **OAuth & Permissions** → **Install to Workspace** → **Allow**
2. Copy the **Bot User OAuth Token** (`xoxb-...`)

**Enable Slack in GoClaw:**

```json
{
  "channels": {
    "slack": {
      "enabled": true,
      "bot_token": "xoxb-YOUR-BOT-TOKEN",
      "app_token": "xapp-YOUR-APP-LEVEL-TOKEN",
      "dm_policy": "pairing",
      "group_policy": "open",
      "require_mention": true
    }
  }
}
```

Or via environment variables:

```bash
GOCLAW_SLACK_BOT_TOKEN=xoxb-...
GOCLAW_SLACK_APP_TOKEN=xapp-...
# Auto-enables Slack when both are set
```

**Invite Bot to Channels:**
- Public: `/invite @GoClaw Bot` in the channel
- Private: Channel name → **Integrations** → **Add an App**
- DMs: Message the bot directly

## Configuration

All config keys are in `channels.slack`:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | false | Enable/disable channel |
| `bot_token` | string | required | Bot User OAuth Token (`xoxb-...`) |
| `app_token` | string | required | App-Level Token for Socket Mode (`xapp-...`) |
| `user_token` | string | -- | User OAuth Token for custom identity (`xoxp-...`) |
| `allow_from` | list | -- | User ID or channel ID allowlist |
| `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
| `group_policy` | string | `"open"` | `open`, `pairing`, `allowlist`, `disabled` |
| `require_mention` | bool | true | Require @bot mention in channels |
| `history_limit` | int | 50 | Pending messages per channel for context (0=disabled) |
| `dm_stream` | bool | false | Enable streaming for DMs |
| `group_stream` | bool | false | Enable streaming for groups |
| `native_stream` | bool | false | Use Slack ChatStreamer API if available |
| `reaction_level` | string | `"off"` | `off`, `minimal`, `full` |
| `block_reply` | bool | -- | Override gateway block_reply (nil=inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |
| `debounce_delay` | int | 300 | Milliseconds before dispatching rapid messages (0=disabled) |
| `thread_ttl` | int | 24 | Hours before thread participation expires (0=disabled) |
| `media_max_bytes` | int | 20MB | Max file download size in bytes |

## Token Types

| Token | Prefix | Required | Purpose |
|-------|--------|----------|---------|
| Bot Token | `xoxb-` | Yes | Core API: messages, reactions, files, user info |
| App-Level Token | `xapp-` | Yes | Socket Mode WebSocket connection |
| User Token | `xoxp-` | No | Custom bot identity (username/icon override) |

Token prefix is validated on startup — misconfigured tokens fail fast with a clear error.

## Features

### Socket Mode

Uses WebSocket instead of HTTP webhooks. No public URL or ingress required — ideal for self-hosted deployments. Events are acknowledged within 3 seconds per Slack requirements.

Dead socket classification detects non-retryable auth errors (`invalid_auth`, `token_revoked`, `missing_scope`) and stops the channel instead of retrying infinitely.

### Mention Gating

In channels, the bot responds only when @mentioned (default `require_mention: true`). Unmentioned messages are stored in a pending history buffer and included as context when the bot is next mentioned.

```mermaid
flowchart TD
    MSG["User posts in channel"] --> MENTION{"Bot @mentioned<br/>or in participated thread?"}
    MENTION -->|No| BUFFER["Add to pending history<br/>(max 50 messages)"]
    MENTION -->|Yes| PROCESS["Process now<br/>Include history as context"]
    BUFFER --> NEXT["Next mention:<br/>history included"]
```

When `require_mention: false`, Slack delivers both a `message` event and an `app_mention` event for the same message. GoClaw uses a shared dedup key (`channel:timestamp`) so whichever event arrives first processes the message; the duplicate is dropped. With `require_mention: false`, the `app_mention` handler exits before storing the dedup key, ensuring the `message` handler takes ownership.

### Thread Participation

After the bot replies in a thread, it auto-replies to subsequent messages in that thread without requiring @mention. Participation expires after `thread_ttl` hours (default 24). Set `thread_ttl: 0` to disable (always require @mention).

### Message Debouncing

Rapid messages from the same thread are batched into a single dispatch. Default delay: 300ms (configurable via `debounce_delay`). Pending batches are flushed on shutdown.

On top of this channel-level batching, the gateway-wide [Inbound Debounce](/channels-overview#inbound-debounce) also applies — it merges rapid messages (and multi-file uploads) from the same sender before the agent runs.

### Message Formatting

LLM markdown output is converted to Slack mrkdwn:

```
Markdown → Slack mrkdwn
**bold**  → *bold*
_italic_  → _italic_
~~strike~~ → ~strike~
# Header  → *Header*
[text](url) → <url|text>
```

Tables render as code blocks. Slack-native tokens (`<@U123>`, `<#C456>`, URLs) are preserved through the conversion pipeline. Messages exceeding 4,000 characters are split at newline boundaries.

### Streaming

Enable live response updates via `chat.update` (edit-in-place):

- **DMs** (`dm_stream`): Edits the "Thinking..." placeholder as chunks arrive
- **Groups** (`group_stream`): Same behavior, within threads

Updates are throttled to 1 edit per second to avoid Slack rate limits. Set `native_stream: true` to use Slack's ChatStreamer API when available.

### Reactions

Show emoji status on user messages. Set `reaction_level`:

- `off` — No reactions (default)
- `minimal` — Only thinking and done
- `full` — All statuses: thinking, tool use, done, error, stall

| Status | Emoji |
|--------|-------|
| Thinking | :thinking_face: |
| Tool use | :hammer_and_wrench: |
| Done | :white_check_mark: |
| Error | :x: |
| Stall | :hourglass_flowing_sand: |

Reactions are debounced at 700ms to prevent API spam.

### Media Handling

**Receiving files:** Files attached to messages are downloaded with SSRF protection (hostname allowlist: `*.slack.com`, `*.slack-edge.com`, `*.slack-files.com`). Auth tokens are stripped on redirect. Files exceeding `media_max_bytes` (default 20MB) are skipped.

**Sending files:** Agent-generated files are uploaded via Slack's file upload API. Failed uploads show an inline error message. When the agent sends a batch (`send_file` with `attachments[]`), Slack uses an **ordered single-send** fallback — files are delivered one after another in order. See [Multi-Attachment Delivery](/channels-overview#multi-attachment-delivery-batching).

**Document extraction:** Document files (PDFs, text files) have their content extracted and appended to the message for the agent to process.

### Custom Bot Identity

With an optional User Token (`xoxp-`), the bot can post with a custom username and icon:

1. In **OAuth & Permissions** → **User Token Scopes** → add `chat:write.customize`
2. Re-install the app
3. Add `user_token` to config

### Group Policy: Pairing

Slack supports group-level pairing. When `group_policy: "pairing"`:
- Admin approves channels via CLI: `goclaw pairing approve <code>`
- Or via the GoClaw web UI (Pairing section)
- Pairing codes for groups are **not** shown in the channel (security: visible to all members)

The `allow_from` list supports both user IDs and Slack channel IDs for group-level allowlisting.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `invalid_auth` on startup | Wrong token or revoked. Re-generate token in Slack app settings. |
| `missing_scope` error | Required scope not added. Add scope in OAuth & Permissions, reinstall app. |
| Bot doesn't respond in channel | Bot not invited to channel. Run `/invite @BotName`. |
| Bot doesn't respond in DM | DM policy is `disabled` or pairing required. Check `dm_policy` config. |
| Socket Mode won't connect | App-Level Token (`xapp-`) missing or incorrect. Check Basic Information page. |
| Bot responds without custom name | User Token not configured. Add `user_token` with `chat:write.customize` scope. |
| Messages processed twice | Socket Mode reconnect dedup is built-in. If persists, check for duplicate app_mention + message events — normal behavior, dedup handles it. |
| Rapid messages sent separately | Increase `debounce_delay` (default 300ms). |
| Thread auto-reply stopped | Thread participation expired (`thread_ttl`, default 24h). Mention bot again. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Telegram](/channel-telegram) — Telegram bot setup
- [Discord](/channel-discord) — Discord bot setup
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# WhatsApp Channel

Direct WhatsApp integration. GoClaw connects directly to WhatsApp's multi-device protocol — no external bridge or Node.js service required. Auth state is stored in the database (PostgreSQL or SQLite).

## Setup

1. **Channels > Add Channel > WhatsApp**
2. Choose an agent, click **Create & Scan QR**
3. Scan the QR code with WhatsApp (You > Linked Devices > Link a Device)
4. Configure DM/group policies as needed

That's it — no bridge to deploy, no extra containers.

### Config File Setup

For config-file-based channels (instead of DB instances):

```json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dm_policy": "pairing",
      "group_policy": "pairing"
    }
  }
}
```

## Configuration

All config keys are in `channels.whatsapp` (config file) or the instance config JSON (DB):

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | `false` | Enable/disable channel |
| `allow_from` | list | -- | User/group ID allowlist |
| `dm_policy` | string | `"pairing"` | `pairing`, `open`, `allowlist`, `disabled` |
| `group_policy` | string | `"pairing"` (DB) / `"open"` (config) | `pairing`, `open`, `allowlist`, `disabled` |
| `require_mention` | bool | `false` | Only respond in groups when bot is @mentioned |
| `history_limit` | int | `200` | Max pending group messages for context (0=disabled) |
| `block_reply` | bool | -- | Override gateway block_reply (nil=inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |

## Architecture

```mermaid
flowchart LR
    WA["WhatsApp<br/>Servers"]
    GC["GoClaw"]
    UI["Web UI<br/>(QR Wizard)"]

    WA <-->|"Multi-device protocol"| GC
    GC -->|"QR events via WS"| UI
```

- **GoClaw** connects directly to WhatsApp servers via multi-device protocol
- Auth state is stored in the database — survives restarts
- One channel instance = one WhatsApp phone number
- No bridge, no Node.js, no shared volumes

## Features

### QR Code Authentication

WhatsApp requires QR code scanning to link a device. The flow:

1. GoClaw generates QR code for device linking
2. QR string is encoded as PNG (base64) and sent to the UI wizard via WS event
3. Web UI displays the QR image
4. User scans with WhatsApp (You > Linked Devices > Link a Device)
5. Connection confirmed via auth event

**Re-authentication**: Use the "Re-authenticate" button in the channels table to force a new QR scan (logs out the current WhatsApp session and deletes stored device credentials).

### DM and Group Policies

WhatsApp groups have chat IDs ending in `@g.us`:

- **DM**: `"1234567890@s.whatsapp.net"`
- **Group**: `"120363012345@g.us"`

Available policies:

| Policy | Behavior |
|--------|----------|
| `open` | Accept all messages |
| `pairing` | Require pairing code approval (default for DB instances) |
| `allowlist` | Only users in `allow_from` |
| `disabled` | Reject all messages |

Group `pairing` policy: unpaired groups receive a pairing code reply. Approve via `goclaw pairing approve <CODE>`.

### @Mention Gating

When `require_mention` is `true`, the bot only responds in group chats when explicitly @mentioned. Unmentioned messages are recorded for context — when the bot is mentioned, recent group history is prepended to the message.

Fails closed — if the bot's JID is unknown, messages are ignored.

### Media Support

GoClaw downloads incoming media directly (images, video, audio, documents, stickers) to temporary files, then passes them to the agent pipeline.

Supported inbound media types: image, video, audio, document, sticker (max 20 MB each).

Outbound media: GoClaw uploads files to WhatsApp's servers with proper encryption. Supports image, video, audio, and document types with captions.

### Message Formatting

LLM output is converted from Markdown to WhatsApp's native formatting:

| Markdown | WhatsApp | Rendered |
|----------|----------|----------|
| `**bold**` | `*bold*` | **bold** |
| `_italic_` | `_italic_` | _italic_ |
| `~~strikethrough~~` | `~strikethrough~` | ~~strikethrough~~ |
| `` `inline code` `` | `` `inline code` `` | `code` |
| `# Header` | `*Header*` | **Header** |
| `[text](url)` | `text url` | text url |
| `- list item` | `• list item` | • list item |

Fenced code blocks are preserved as ` ``` `. HTML tags from LLM output are pre-processed to Markdown equivalents before conversion. Long messages are automatically chunked at ~4096 characters, splitting at paragraph or line boundaries.

### Typing Indicators

GoClaw shows "typing..." in WhatsApp while the agent processes a message. WhatsApp clears the indicator after ~10 seconds, so GoClaw refreshes every 8 seconds until the reply is sent.

### Auto-Reconnect

Reconnection is handled automatically. If the connection drops:
- Built-in reconnect logic handles retry with exponential backoff
- Channel health status updated (degraded → healthy on reconnect)
- No manual reconnect loop needed

### LID Addressing

WhatsApp uses dual identity: phone JID (`@s.whatsapp.net`) and LID (`@lid`). Groups may use LID addressing. GoClaw normalizes to phone JID for consistent policy checks, pairing lookups, and allowlists.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| No QR code appears | Check GoClaw logs. Ensure the server can reach WhatsApp servers (ports 443, 5222). |
| QR scanned but no auth | Auth state may be corrupted. Use "Re-authenticate" button or restart the channel. |
| Messages not received | Check `dm_policy` and `group_policy`. If `pairing`, the user/group needs approval via `goclaw pairing approve`. |
| Media not received | Check GoClaw logs for "media download failed". Ensure temp directory is writable. Max 20 MB per file. |
| Typing indicator stuck | GoClaw auto-cancels typing when reply is sent. If stuck, WhatsApp connection may have dropped — check channel health. |
| Group messages ignored | Check `group_policy`. If `pairing`, the group needs approval. If `require_mention` is true, @mention the bot. |
| "logged out" in logs | WhatsApp revoked the session. Use "Re-authenticate" button to scan a new QR code. |
| `bridge_url` error on startup | `bridge_url` is no longer supported. WhatsApp now runs natively — remove `bridge_url` from config/credentials. |

## Migrating from Bridge

If you previously used the Baileys bridge (`bridge_url` config):

1. Remove `bridge_url` from your channel config or credentials
2. Remove/stop the bridge container (no longer needed)
3. Delete the bridge shared volume (`wa_media`)
4. Re-authenticate via QR scan in the UI (existing bridge auth state is not compatible)

GoClaw will detect old `bridge_url` config and show a clear migration error.

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Telegram](/channel-telegram) — Telegram bot setup
- [Larksuite](/channel-feishu) — Larksuite integration
- [Browser Pairing](/channel-browser-pairing) — Pairing flow



---

# Pancake Channel

Unified multi-platform channel proxy powered by Pancake (pages.fm). A single Pancake API key gives access to Facebook, Zalo OA, Instagram, TikTok, WhatsApp, and Line — no per-platform OAuth required.

## What is Pancake?

Pancake is a social commerce platform that provides a unified messaging proxy across multiple social networks. Instead of integrating with each platform's API individually, GoClaw connects to Pancake once and reaches users on all connected platforms through a single channel instance.

## Supported Platforms

| Platform | Max Message Length | Formatting |
|----------|-------------------|------------|
| Facebook | 2,000 | Plain text (strips markdown) |
| Zalo OA | 2,000 | Plain text (strips markdown) |
| Instagram | 1,000 | Plain text (strips markdown) |
| TikTok | 500 | Plain text, truncated at 500 chars |
| Shopee | 500 | Plain text, truncated at 500 chars |
| WhatsApp | 4,096 | WhatsApp-native (*bold*, _italic_) |
| Line | 5,000 | Plain text (strips markdown) |

## Setup

### Pancake-side Setup

1. Create a Pancake account at [pages.fm](https://pages.fm)
2. Connect your social pages (Facebook, Zalo OA, etc.) to Pancake
3. Generate a Pancake API key from your account settings
4. Note your Page ID from the Pancake dashboard

### GoClaw-side Setup

1. **Channels > Add Channel > Pancake**
2. Enter your credentials:
   - **API Key**: Your Pancake user-level API key
   - **Page Access Token**: Page-level token for all page APIs
   - **Page ID**: The Pancake page identifier
3. Set a **Webhook Secret** — required for webhook delivery; GoClaw rejects all webhook events when this is not configured
4. Configure platform-specific features (inbox reply, comment reply)

That's it — one channel serves all platforms connected to that Pancake page.

### Config File Setup

For config-file-based channels (instead of DB instances):

```json
{
  "channels": {
    "pancake": {
      "enabled": true,
      "instances": [
        {
          "name": "my-facebook-page",
          "credentials": {
            "api_key": "your_pancake_api_key",
            "page_access_token": "your_page_access_token",
            "webhook_secret": "optional_hmac_secret"
          },
          "config": {
            "page_id": "your_page_id",
            "features": {
              "inbox_reply": true,
              "comment_reply": true,
              "private_reply": false,
              "first_inbox": true,
              "auto_react": false
            },
            "private_reply_message": "Thanks {{commenter_name}} for your comment! We'll DM you shortly.",
            "comment_reply_options": {
              "include_post_context": true,
              "filter": "all"
            }
          }
        }
      ]
    }
  }
}
```

## Configuration

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `api_key` | string | -- | User-level Pancake API key (required) |
| `page_access_token` | string | -- | Page-level token for all page APIs (required) |
| `webhook_secret` | string | -- | HMAC-SHA256 webhook secret — **required** for webhook delivery; events are rejected without it |
| `page_id` | string | -- | Pancake page identifier (required) |
| `webhook_page_id` | string | -- | Native platform page ID sent in webhooks (if different from `page_id`) |
| `platform` | string | auto-detected | Platform override: facebook/zalo/instagram/tiktok/shopee/whatsapp/line |
| `features.inbox_reply` | bool | -- | Enable inbox message replies |
| `features.comment_reply` | bool | -- | Enable comment replies |
| `features.private_reply` | bool | -- | Send a one-time DM to a commenter after each comment reply (stateless, no DB required) |
| `features.auto_react` | bool | -- | Auto-like user comments on Facebook (Facebook only) |
| `auto_react_options.allow_post_ids` | list | -- | Only react to comments on these post IDs (nil = all posts) |
| `auto_react_options.deny_post_ids` | list | -- | Never react to comments on these post IDs (overrides allow) |
| `auto_react_options.allow_user_ids` | list | -- | Only react to comments from these user IDs (nil = all users) |
| `auto_react_options.deny_user_ids` | list | -- | Never react to comments from these user IDs (overrides allow) |
| `comment_reply_options.include_post_context` | bool | false | Prepend post text to comment content sent to the agent |
| `comment_reply_options.filter` | string | `"all"` | Comment filter mode: `"all"` or `"keyword"` |
| `comment_reply_options.keywords` | list | -- | Required when `filter="keyword"` — only process comments containing these keywords |
| `private_reply_message` | string | built-in EN | Template DM for `features.private_reply`. Supports `{{commenter_name}}` and `{{post_title}}` variables. Falls back to a built-in English message if empty. |
| `first_inbox_message` | string | built-in | Custom DM text sent for first-inbox feature |
| `post_context_cache_ttl` | string | `"15m"` | Cache TTL for post content fetched for comment context (e.g. `"30m"`) |
| `block_reply` | bool | -- | Override gateway block_reply (nil=inherit) |
| `chat_behavior` | object | -- | Override gateway [human-like delivery](/channels-overview#human-like-delivery) for this channel (nil = inherit) |
| `allow_from` | list | -- | User/group ID allowlist |

## Architecture

```mermaid
flowchart LR
    FB["Facebook"]
    ZA["Zalo OA"]
    IG["Instagram"]
    TK["TikTok"]
    SP["Shopee"]
    WA["WhatsApp"]
    LN["Line"]

    PC["Pancake Proxy<br/>(pages.fm)"]
    GC["GoClaw"]

    FB --> PC
    ZA --> PC
    IG --> PC
    TK --> PC
    SP --> PC
    WA --> PC
    LN --> PC

    PC <-->|"Webhook + REST API"| GC
```

- **One channel instance = one Pancake page** (serving multiple platforms)
- **Platform auto-detected** at Start() from Pancake page metadata
- **Webhook-based** — no polling, Pancake servers push events to GoClaw
- A single HTTP handler at `/channels/pancake/webhook` routes to the correct channel by page_id

## Features

### Multi-Platform Support

One Pancake channel instance can serve multiple platforms simultaneously. The platform is determined by the Pancake page metadata:

- At Start(), GoClaw calls `GET /pages` to list all pages and match the configured page_id
- The `platform` field (facebook/zalo/instagram/tiktok/shopee/whatsapp/line) is extracted from page metadata
- If platform is not configured or detection fails, defaults to "facebook" with 2,000 char limit

### Webhook Delivery

Pancake uses webhook push (not polling) for message delivery:

- GoClaw registers a single route: `POST /channels/pancake/webhook`
- All Pancake page webhooks route through one handler, dispatched by `page_id`
- Always returns HTTP 200 — Pancake suspends webhooks if >80% errors in a 30-min window
- Request body is capped at 1 MB to prevent abuse

**HMAC signature verification (required):** GoClaw verifies every incoming webhook using HMAC-SHA256. The `webhook_secret` credential must be set — without it, all webhook deliveries are rejected (HTTP 200 returned but event is dropped). Configure the same secret in your Pancake dashboard webhook settings.

Pancake sends the signature in the `X-Pancake-Signature` request header with format `sha256=<hex-digest>`. GoClaw recomputes `HMAC-SHA256(body, webhook_secret)` and compares using a constant-time comparison to prevent timing attacks.

**Replay protection:** After signature verification passes, GoClaw computes `SHA-256(body)` and stores it in an in-memory dedup map with a 24-hour TTL. Duplicate deliveries (same raw body) are silently dropped before any message processing occurs.

> **Security note:** Enabling `features.auto_react` without a `webhook_secret` configured causes GoClaw to log a warning at startup (`security.pancake_auto_react_without_hmac`). Any actor who can reach the webhook endpoint could then trigger comment-like calls without authentication.

Webhook payload structure:

```json
{
  "event_type": "messaging",
  "page_id": "your_page_id",
  "data": {
    "conversation": {
      "id": "pageID_senderID",
      "type": "INBOX",
      "from": { "id": "sender_id", "name": "Sender Name" },
      "assignee_ids": ["staff_id_1"]
    },
    "message": {
      "id": "msg_unique_id",
      "message": "Hello from customer",
      "attachments": [{ "type": "image", "url": "https://..." }]
    }
  }
}
```

Only `INBOX` conversation events are processed. `COMMENT` events are skipped unless `comment_reply` is enabled.

#### Shopee Webhooks

Shopee uses a distinct conversation ID format: `spo_{page_numeric}_{sender_id}`. GoClaw automatically detects the `spo_` prefix and parses the `page_id` as `spo_{page_numeric}`:

```json
{
  "event_type": "messaging",
  "data": {
    "conversation": {
      "id": "spo_25409726_109139680425439630",
      "type": "INBOX",
      "from": { "id": "109139680425439630", "name": "Test Buyer" }
    },
    "message": {
      "id": "spo_msg_1",
      "content": "Shop oi con hang khong?"
    }
  }
}
```

Shopee deduplication operates at webhook-level (same as TikTok) — based on `message_id` in the payload, no DB state required.

### Message Deduplication

Pancake uses at-least-once delivery, so duplicate webhook deliveries are expected:

- **Message dedup**: `sync.Map` keyed by `msg:{message_id}` with 24-hour TTL (inbox) or `comment:{message_id}` (comment)
- **Outbound echo detection**: Pre-stores message fingerprints before sending, suppresses webhook echoes of our own replies (45-second TTL)
- Background cleaner evicts stale entries every 5 minutes to prevent memory growth
- Messages missing `message_id` skip dedup (prevents shared slot collisions)
- **TikTok and Shopee**: webhook-level dedup; no additional DB state required

### Reply Loop Prevention

Multiple guards prevent the bot from responding to its own messages:

1. **Page self-message filter**: Skips messages where `sender_id == page_id`
2. **Staff assignee filter**: Skips messages from Pancake staff assigned to the conversation
3. **Outbound echo detection**: Matches inbound content against recently sent messages

### Media Support

**Inbound media**: Attachments arrive as URLs in the webhook payload. GoClaw includes them directly in the message content passed to the agent pipeline.

**Outbound media**: Files are uploaded via `POST /pages/{id}/upload_contents` (multipart/form-data), then sent as `content_ids` in a separate API call. Media and text are delivered sequentially:

1. Upload media files, collect attachment IDs
2. Send attachment message with content_ids
3. Follow with text message (if any)

If media upload fails, the text portion is sent anyway with a warning logged. Media paths must be absolute to prevent directory traversal.

### Message Formatting

LLM output is converted from Markdown to platform-appropriate formatting:

| Platform | Behavior |
|----------|----------|
| Facebook | Strips markdown, keeps plain text (Messenger doesn't support rich formatting) |
| WhatsApp | Converts `**bold**` to `*bold*`, `_italic_` preserved, headers stripped |
| TikTok | Strips markdown + truncates to 500 runes |
| Shopee | Strips markdown + truncates to 500 runes (same as TikTok) |
| Instagram / Zalo / Line | Strips all markdown, returns plain text |

Long messages are automatically split into chunks respecting each platform's character limit. Rune-based splitting (not byte-based) ensures multi-byte characters (CJK, Vietnamese, emoji) are not corrupted.

### Inbox vs Comment Modes

Pancake supports two conversation types:

- **INBOX**: Direct messages from users (default, always processed)
- **COMMENT**: Comments on social posts (controlled by `comment_reply` feature flag)

Conversation type is stored in message metadata as `pancake_mode` ("inbox" or "comment"), enabling agents to respond differently based on the source.

### Comment Features

When `features.comment_reply: true`, additional options control comment handling:

**Comment filter** (`comment_reply_options.filter`):
- `"all"` (default) — process all comments
- `"keyword"` — only process comments containing one of the configured `keywords`

**Post context** (`comment_reply_options.include_post_context: true`): fetches the original post text and prepends it to the comment content before sending to the agent. Useful when comments are too short to understand without context. Post content is cached (default TTL: 15 minutes, configurable via `post_context_cache_ttl`).

**Auto-react** (`features.auto_react: true`): automatically likes every valid incoming comment on Facebook (Facebook platform only). Fires independently of `comment_reply` — you can react without replying.

Scope the reactions further with `auto_react_options`:

| Field | Type | Behavior |
|-------|------|----------|
| `allow_post_ids` | list | React only on comments for these post IDs (nil = all posts) |
| `deny_post_ids` | list | Never react on these post IDs (overrides allow) |
| `allow_user_ids` | list | React only to comments from these user IDs (nil = all users) |
| `deny_user_ids` | list | Never react to comments from these user IDs (overrides allow) |

Deny lists always take precedence over allow lists. Omitting `auto_react_options` entirely means no scope filter (react to all valid comments).

**First inbox** (`features.first_inbox: true`): after replying to a comment, sends a one-time welcome DM to the commenter via the first-inbox flow. Only sent once per sender per session restart. Customize the DM text with `first_inbox_message`.

### Private Reply (Stateless DM)

`features.private_reply: true` sends a private DM to the commenter immediately after a public comment reply — no DB table or in-memory state required.

**Idempotency mechanism**: Relies on webhook-level comment dedup (above) and Facebook's per-comment `private_replies` endpoint — Facebook returns an error if a DM was already sent for that comment, and GoClaw logs a warning and continues.

**Template message**: Configured via `private_reply_message` with these variables:

| Variable | Content |
|----------|---------|
| `{{commenter_name}}` | Commenter's display name (sanitized) |
| `{{post_title}}` | Associated post content (fetched from post cache) |

Variables are substituted literally — values are pre-sanitized (stripping `{{` and `}}`) to prevent template injection. If `private_reply_message` is empty, the built-in default is used: `"Thanks for your comment! We'll DM you shortly."`

**How private_reply differs from first_inbox:**

| | `private_reply` | `first_inbox` |
|-|----------------|--------------|
| Trigger | Every comment reply | First time per user (per restart) |
| Idempotency | FB API + webhook dedup (stateless) | In-memory set per restart |
| Config key | `private_reply_message` | `first_inbox_message` |

### Channel Health

API errors are mapped to channel health states:

| Error Type | HTTP Codes | Health State |
|------------|-----------|--------------|
| Auth failure | 401, 403, 4001, 4003 | Failed (token expired or invalid) |
| Rate limited | 429, 4029 | Degraded (recoverable) |
| Unknown API error | Others | Degraded (recoverable) |

Application-level failures (HTTP 200 with `success: false` in JSON body) are also detected and treated as send errors.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "api_key is required" on startup | Add `api_key` to credentials. Get it from your Pancake account settings. |
| "page_access_token is required" | Add `page_access_token` to credentials. This is the page-level token from Pancake. |
| "page_id is required" | Add `page_id` to config. Find it in your Pancake dashboard URL. |
| Token verification failed | The `page_access_token` may be expired or invalid. Regenerate from Pancake dashboard. |
| No messages received | Check Pancake webhook URL is configured: `https://your-goclaw-host/channels/pancake/webhook`. |
| Webhook signature mismatch / events not processed | Verify `webhook_secret` is set and matches the secret configured in the Pancake dashboard. Events are silently dropped when `webhook_secret` is empty. |
| "no channel instance for page_id" | The `page_id` in the webhook doesn't match any registered channel. Check config. |
| Platform shows as unknown | `platform` is auto-detected. Ensure the page is connected in Pancake. Can override manually. |
| Media upload fails | Media paths must be absolute. Check file exists and is readable. |
| Messages appear duplicated | This is normal — dedup handles it. If persistent, check Pancake webhook config isn't double-registered. |

## What's Next

- [Channel Overview](/channels-overview) — Channel concepts and policies
- [WhatsApp](/channel-whatsapp) — Direct WhatsApp integration
- [Telegram](/channel-telegram) — Telegram bot setup
- [Multi-Channel Setup](/recipe-multi-channel) — Configure multiple channels



---

# Facebook Channel

Facebook Fanpage integration supporting Messenger inbox auto-reply, comment auto-reply, and first inbox DM via Facebook Graph API.

## Setup

### 1. Create a Facebook App

1. Go to [developers.facebook.com](https://developers.facebook.com) and create a new app
2. Choose **Business** type
3. Add the **Messenger** and **Webhooks** products
4. Under **Messenger Settings** → **Access Tokens** → generate a Page Access Token for your page
5. Copy your **App ID**, **App Secret**, and **Page Access Token**
6. Note your **Facebook Page ID** (visible in your page's About section or URL)

### 2. Configure the Webhook

In your Facebook App Dashboard → **Webhooks** → **Page**:

1. Set the callback URL: `https://your-goclaw-host/channels/facebook/webhook`
2. Set a verify token (any string you choose — use this as `verify_token` in GoClaw config)
3. Subscribe to these events: `messages`, `messaging_postbacks`, `feed`

### 3. Enable Facebook Channel

```json
{
  "channels": {
    "facebook": {
      "enabled": true,
      "instances": [
        {
          "name": "my-fanpage",
          "credentials": {
            "page_access_token": "YOUR_PAGE_ACCESS_TOKEN",
            "app_secret": "YOUR_APP_SECRET",
            "verify_token": "YOUR_VERIFY_TOKEN"
          },
          "config": {
            "page_id": "YOUR_PAGE_ID",
            "features": {
              "messenger_auto_reply": true,
              "comment_reply": false,
              "first_inbox": false
            }
          }
        }
      ]
    }
  }
}
```

## Configuration

### Credentials (encrypted)

| Key | Type | Description |
|-----|------|-------------|
| `page_access_token` | string | Page-level token from Facebook App Dashboard (required) |
| `app_secret` | string | App Secret for webhook signature verification (required) |
| `verify_token` | string | Token used to verify webhook endpoint ownership (required) |

### Instance Config

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `page_id` | string | required | Facebook Page ID |
| `features.messenger_auto_reply` | bool | false | Enable Messenger inbox auto-reply |
| `features.comment_reply` | bool | false | Enable comment auto-reply |
| `features.first_inbox` | bool | false | Send a one-time DM after first comment reply |
| `comment_reply_options.include_post_context` | bool | false | Fetch post content to enrich comment context |
| `comment_reply_options.max_thread_depth` | int | 10 | Max depth for fetching parent comment threads |
| `messenger_options.session_timeout` | string | -- | Override session timeout for Messenger conversations (e.g. `"30m"`) |
| `post_context_cache_ttl` | string | -- | Cache TTL for post content fetches (e.g. `"10m"`) |
| `first_inbox_message` | string | -- | Custom DM text sent after first comment reply (defaults to Vietnamese if empty) |
| `allow_from` | list | -- | Sender ID allowlist |

## Architecture

```mermaid
flowchart TD
    FB_USER["Facebook User"]
    FB_PAGE["Facebook Page"]
    WEBHOOK["GoClaw Webhook\n/channels/facebook/webhook"]
    ROUTER["Global Router\n(routes by page_id)"]
    CH["Channel Instance"]
    AGENT["Agent Pipeline"]
    GRAPH["Graph API\ngraph.facebook.com"]

    FB_USER -->|"Comment / Message"| FB_PAGE
    FB_PAGE -->|"Webhook event (POST)"| WEBHOOK
    WEBHOOK -->|"Verify HMAC-SHA256"| ROUTER
    ROUTER --> CH
    CH -->|"HandleMessage"| AGENT
    AGENT -->|"OutboundMessage"| CH
    CH -->|"Send reply"| GRAPH
    GRAPH --> FB_PAGE
```

- **Single webhook endpoint** — all Facebook channel instances share `/channels/facebook/webhook`, routed by `page_id`
- **HMAC-SHA256 verification** — every webhook delivery is verified against `app_secret` via `X-Hub-Signature-256` header
- **Graph API v25.0** — all outbound calls use the versioned Graph API endpoint

## Features

### fb_mode: Page Mode vs Comment Mode

The `fb_mode` metadata field controls how the agent's reply is delivered:

| `fb_mode` | Trigger | Reply method |
|-----------|---------|--------------|
| `messenger` | Messenger inbox message | `POST /me/messages` to the sender |
| `comment` | Comment on a page post | `POST /{comment_id}/comments` reply |

The channel sets `fb_mode` automatically based on the event type. Agents can read this metadata to tailor their response style.

### Messenger Auto-Reply

When `features.messenger_auto_reply` is enabled:

- Responds to text messages and postbacks from users in Messenger
- Session key is `senderID` (1:1 channel-scoped conversations)
- Skips delivery/read receipts and attachment-only messages
- Long responses are automatically split at 2,000 characters

### Comment Auto-Reply

When `features.comment_reply` is enabled:

- Responds to new comments on the page's posts (`verb: "add"`)
- Ignores comment edits and deletions
- Session key: `{post_id}:{sender_id}` — groups all comments from the same user on the same post
- Optional: fetches post content and parent comment thread for richer context (see `comment_reply_options`)

### Admin Reply Detection

GoClaw automatically detects when a human page admin replies to a conversation and suppresses the bot's auto-reply for a **5-minute cooldown window**. This prevents the bot from sending a duplicate message after the admin has already responded.

Detection logic:
1. When a message from `sender_id == page_id` arrives, GoClaw records the recipient as admin-replied
2. Bot echo detection: if the bot itself just sent a message within a 15-second window, the "admin reply" is ignored (it's the bot's own echo)
3. Cooldown expires after 5 minutes — auto-reply resumes

### First Inbox DM

When `features.first_inbox` is enabled, GoClaw sends a one-time private Messenger DM to a user after the bot first replies to their comment:

- Sent at most once per user per process lifetime (in-memory dedup)
- Customize the message with `first_inbox_message`; defaults to Vietnamese if empty
- Best-effort: send failures are logged and retried on next comment

### Webhook Setup

The webhook handler:

1. **GET** — Verifies ownership by echoing `hub.challenge` when `hub.verify_token` matches
2. **POST** — Processes event delivery:
   - Validates `X-Hub-Signature-256` HMAC-SHA256 signature
   - Parses `feed` changes for comment events
   - Parses `messaging` events for Messenger events
   - Always returns HTTP 200 (non-2xx causes Facebook to retry for 24 hours)

Body size is capped at 4 MB. Oversized payloads are dropped with a warning.

### Message Deduplication

Facebook may deliver the same webhook event more than once. GoClaw deduplicates by event key:

- Messenger: `msg:{message_mid}`
- Postback: `postback:{sender_id}:{timestamp}:{payload}`
- Comment: `comment:{comment_id}`

Dedup entries expire after 24 hours (matching Facebook's max retry window). A background cleaner evicts stale entries every 5 minutes.

### Graph API

All outbound calls go through `graph.facebook.com/v25.0` with automatic retry:

- **3 retries** with exponential backoff (1s, 2s, 4s)
- **Rate limit handling**: parses `X-Business-Use-Case-Usage` header and respects `Retry-After`
- **Token passed via `Authorization: Bearer` header** (never in URL)
- **24h messaging window**: code 551 / subcode 2018109 are non-retryable (user has not messaged in 24h)

### Media Support

**Inbound** (Messenger): Attachment URLs are included in the message metadata. Types: `image`, `video`, `audio`, `file`.

**Outbound**: Text replies only. Media delivery from the agent is not currently supported for the native Facebook channel. Use [Pancake](/channel-pancake) for full media support across Facebook and other platforms.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Webhook verification fails | Check `verify_token` in GoClaw matches the token in Facebook App Dashboard. |
| `page_access_token is required` | Add `page_access_token` to credentials. |
| `page_id is required` | Add `page_id` to instance config. |
| Token verification failed on start | The `page_access_token` may be expired. Regenerate from Facebook App Dashboard. |
| No events received | Ensure webhook callback URL is publicly accessible. Check Facebook App → Webhooks subscriptions (`messages`, `feed`). |
| Signature invalid warnings | Ensure `app_secret` in GoClaw matches the App Secret in Facebook App Dashboard. |
| Bot replies after admin already responded | Expected — bot suppresses for 5 min after admin reply. Set `features.messenger_auto_reply: false` to disable entirely. |
| 24h messaging window error | The user hasn't sent a message in the last 24 hours. Facebook restricts bot-initiated messages outside this window. |
| Duplicate messages | Dedup handles this automatically. If persistent, check for multiple GoClaw instances with the same `page_id`. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [Pancake](/channel-pancake) — Multi-platform proxy (Facebook + Zalo + Instagram + more)
- [Zalo OA](/channel-zalo-oa) — Zalo Official Account
- [Telegram](/channel-telegram) — Telegram bot setup



---

# WebSocket Channel

Direct RPC communication with the GoClaw gateway over WebSocket. No intermediate messaging platform needed—perfect for custom clients, web apps, and testing.

## Connection

**Endpoint:**

```
ws://your-gateway.com:8080/ws
wss://your-gateway.com:8080/ws  (TLS)
```

**WebSocket Upgrade:**

```
GET /ws HTTP/1.1
Host: your-gateway.com:8080
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: ...
Sec-WebSocket-Version: 13
```

Server responds with `101 Switching Protocols`.

## Authentication

First message must be a `connect` frame:

```json
{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "token": "YOUR_GATEWAY_TOKEN",
    "user_id": "user_123"
  }
}
```

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `token` | string | No | Gateway API token (empty = viewer role) |
| `user_id` | string | Yes | Client/user identifier (opaque, max 255 chars) |

**Response:**

```json
{
  "type": "res",
  "id": "1",
  "ok": true,
  "payload": {
    "protocol": 3,
    "role": "admin",
    "user_id": "user_123"
  }
}
```

### Roles

- **viewer** (default): Read-only access (no token or wrong token)
- **operator**: Read + write + chat
- **admin**: Full control (with correct gateway token)

## Sending Messages

After authentication, send `chat.send` request:

```json
{
  "type": "req",
  "id": "2",
  "method": "chat.send",
  "params": {
    "agentId": "main",
    "message": "What is 2+2?",
    "channel": "websocket"
  }
}
```

**Parameters:**

| Field | Type | Description |
|-------|------|-------------|
| `agentId` | string | Agent to query |
| `message` | string | User message |
| `channel` | string | Usually `"websocket"` |
| `sessionId` | string | Optional: resume existing session |

**Response:**

```json
{
  "type": "res",
  "id": "2",
  "ok": true,
  "payload": {
    "content": "2+2 equals 4.",
    "usage": {
      "input_tokens": 42,
      "output_tokens": 8
    }
  }
}
```

## Streaming Events

During agent processing, server pushes events:

```json
{
  "type": "event",
  "event": "chat",
  "payload": {
    "chunk": "2+2 equals",
    "delta": " equals"
  },
  "seq": 1
}
```

**Event Types:**

| Event | Payload | Description |
|-------|---------|-------------|
| `chat` | `{chunk, delta}` | Streaming text chunks |
| `agent` | `{run_id, status}` | Agent lifecycle (started, completed, failed) |
| `tool.call` | `{tool, input}` | Tool invocation |
| `tool.result` | `{tool, output}` | Tool result |

## Minimal JavaScript Client

```javascript
const ws = new WebSocket('ws://localhost:8080/ws');

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'req',
    id: '1',
    method: 'connect',
    params: {
      user_id: 'web_client_1'
    }
  }));
};

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);

  if (frame.type === 'res' && frame.id === '1') {
    // Connected! Now send a message
    ws.send(JSON.stringify({
      type: 'req',
      id: '2',
      method: 'chat.send',
      params: {
        agentId: 'main',
        message: 'Hello!',
        channel: 'websocket'
      }
    }));
  }

  if (frame.type === 'res' && frame.id === '2') {
    console.log('Response:', frame.payload.content);
  }

  if (frame.type === 'event' && frame.event === 'chat') {
    console.log('Chunk:', frame.payload.chunk);
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected');
};
```

## Session Management

Reuse a session ID to continue conversations:

```json
{
  "type": "req",
  "id": "3",
  "method": "chat.send",
  "params": {
    "agentId": "main",
    "message": "Add 5 to the result.",
    "sessionId": "session_xyz",
    "channel": "websocket"
  }
}
```

Session ID is returned in each response. Store and pass it to maintain conversation history.

## Keepalive

Server sends ping frames every 30 seconds. Client should respond with pong. Most WebSocket libraries do this automatically.

## Frame Limits

| Limit | Value |
|-------|-------|
| Read message size | 512 KB |
| Read deadline | 60 seconds |
| Write deadline | 10 seconds |
| Send buffer | 256 messages |

Messages exceeding limits are dropped with logging.

## Error Handling

Failed requests include error details:

```json
{
  "type": "res",
  "id": "2",
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "unknown method",
    "retryable": false
  }
}
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Connection refused" | Check gateway is running on correct host/port. |
| "Unauthorized" | Verify token is correct. Check user_id is provided. |
| "Message too large" | Reduce message size (512 KB limit). |
| No streaming events | Ensure provider supports streaming. Check model config. |
| Connection drops | Server may have hit message buffer limit. Reconnect and resume session. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [WebSocket Protocol](/websocket-protocol) — Full protocol documentation
- [Browser Pairing](/channel-browser-pairing) — Pairing flow for custom clients



---

# Browser Pairing

Secure authentication flow for custom WebSocket clients using 8-character pairing codes. Ideal for private web apps and desktop clients that need to verify device identity.

> **Browser pairing vs. cookie sync.** Browser **pairing** authenticates a *client* (a browser or desktop app) so it can talk to the gateway. **Selected cookie sync** copies *site login cookies* into an agent's server-side browser so the agent can act as a signed-in session. Use pairing to let a device connect; use cookie sync to give an agent access to a site you are logged into. See [Browser Automation → Selected Cookie Sync](/browser-automation#selected-cookie-sync).

## Pairing Flow

```mermaid
sequenceDiagram
    participant C as Client (Browser)
    participant G as Gateway
    participant O as Owner (CLI/Dashboard)

    C->>G: Request pairing code
    G->>C: Generate code: ABCD1234<br/>(valid 60 min)
    G->>O: Notify: New pairing request<br/>from client_id

    Note over C: User shows code to owner

    O->>G: Approve code: device.pair.approve<br/>code=ABCD1234
    G->>G: Add to paired_devices<br/>Mark request resolved

    C->>G: Connect with code: ABCD1234
    G->>G: Verify against paired_devices
    G->>C: OK, authenticated!<br/>Issue session token

    C->>G: WebSocket: chat.send<br/>with pairing token
    G->>C: Response + events
```

## Code Format

**Generation:**

- Length: 8 characters
- Alphabet: `ABCDEFGHJKLMNPQRSTUVWXYZ23456789` (excludes ambiguous: 0, O, 1, I, L)
- TTL: 60 minutes
- Max pending per account: 3

**Example codes:**
- `ABCD1234`
- `XY8PQRST`
- `2M5H9JKL`

## Implementation

### Step 1: Request Code (Client)

```bash
curl -X POST http://localhost:8080/v1/device/pair/request \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "browser_myclient_1",
    "device_name": "My Web App"
  }'
```

**Response:**

```json
{
  "code": "ABCD1234",
  "expires_at": 1709865000,
  "url": "http://localhost:8080/pair?code=ABCD1234"
}
```

Display code to user:

```
Please share this code with your gateway owner:

  ABCD1234

It expires in 60 minutes.
```

### Step 2: Approve Code (Owner)

Owner runs CLI command or uses dashboard to approve:

```bash
goclaw device.pair.approve --code ABCD1234
```

Or via WebSocket (admin only):

```json
{
  "type": "req",
  "id": "100",
  "method": "device.pair.approve",
  "params": {
    "code": "ABCD1234"
  }
}
```

**Response:**

```json
{
  "type": "res",
  "id": "100",
  "ok": true,
  "payload": {
    "client_id": "browser_myclient_1",
    "device_name": "My Web App",
    "paired_at": 1709864400
  }
}
```

### Step 3: Connect (Client)

Client uses the code to authenticate:

```json
{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "pairing_code": "ABCD1234",
    "user_id": "web_user_1"
  }
}
```

**Response:**

```json
{
  "type": "res",
  "id": "1",
  "ok": true,
  "payload": {
    "protocol": 3,
    "role": "operator",
    "user_id": "web_user_1",
    "session_token": "session_xyz..."
  }
}
```

Client stores `session_token` for future connections.

### Step 4: Use Session (Client)

On reconnect, use stored token:

```json
{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "session_token": "session_xyz...",
    "user_id": "web_user_1"
  }
}
```

## Security Properties

- **One-time use**: Each pairing code is used once and invalidated
- **Expiring**: Codes expire after 60 minutes (TTL enforced server-side)
- **Limited pending**: Max 3 pending requests per account (prevents spam)
- **Owner approval**: Only gateway owner can approve codes (admin role required)
- **Session tokens**: Issued after approval; tied to device and user
- **Debouncing**: Pairing approval notifications debounced per sender (60 seconds)
- **Fail-closed auth**: Authentication failures default to deny — no partial or ambiguous approval states
- **Rate limiting**: Pairing code requests are rate-limited per sender to prevent brute-force enumeration
- **Transient DB error handling**: `IsPaired` checks handle transient database errors gracefully — a DB error returns denied rather than accidentally allowing access

## Channel-Specific Pairing Behaviour

How channels trigger the pairing flow varies by channel type.

**Discord groups:** When `group_policy: "pairing"` is active and `require_mention: true` (the Discord default), a pairing invite is only sent to an unpaired user if they explicitly @mentioned the bot or replied to one of the bot's messages. Messages sent to the group that do not address the bot are silently buffered and do not produce a pairing reply. This prevents pairing spam in public servers where many users can see the bot's messages.

For DMs, the pairing invite fires unconditionally whenever an unpaired user sends a message (same as other channels).

## JavaScript Example

```javascript
class PairingClient {
  constructor(gatewayUrl) {
    this.url = gatewayUrl;
    this.ws = null;
    this.sessionToken = localStorage.getItem('goclaw_token');
  }

  async requestPairingCode() {
    const res = await fetch(`${this.url}/v1/device/pair/request`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: 'browser_' + Date.now(),
        device_name: navigator.userAgent
      })
    });
    const data = await res.json();
    return data.code;
  }

  connect() {
    this.ws = new WebSocket(this.url.replace('http', 'ws') + '/ws');
    this.ws.onopen = () => {
      if (this.sessionToken) {
        // Resume with token
        this.send('connect', {
          session_token: this.sessionToken,
          user_id: 'user_' + Date.now()
        });
      } else {
        console.log('No session token. Request pairing code first.');
      }
    };
    this.ws.onmessage = (e) => this.handleMessage(JSON.parse(e.data));
  }

  send(method, params) {
    this.ws.send(JSON.stringify({
      type: 'req',
      id: Date.now().toString(),
      method,
      params
    }));
  }

  handleMessage(frame) {
    if (frame.type === 'res' && frame.payload?.session_token) {
      localStorage.setItem('goclaw_token', frame.payload.session_token);
    }
    // Handle response...
  }
}
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Code expired" | Code is valid only 60 minutes. Request new code. |
| "Code not found" | Code never existed or already used. Request new code. |
| "Max pending exceeded" | Too many pending requests. Wait or have owner revoke old codes. |
| "Unauthorized" | Owner has not approved the code yet. Check with owner. |
| Session token invalid | Token may have expired or been revoked. Request new pairing code. |

## What's Next

- [Overview](/channels-overview) — Channel concepts and policies
- [WebSocket](/channel-websocket) — Direct RPC communication
- [Telegram](/channel-telegram) — Telegram setup
- [WebSocket Protocol](/websocket-protocol) — Full protocol reference



---

# What Are Agent Teams?

Agent teams enable multiple agents to collaborate on shared tasks. A **lead** agent orchestrates work, while **members** execute tasks independently and report results back.

## The Team Model

Teams consist of:
- **Lead Agent**: Orchestrates work, creates and assigns tasks via `team_tasks`, delegates to members, synthesizes results
- **Member Agents**: Receive dispatched tasks, execute independently, complete with results, can send progress updates via mailbox
- **Shared Task Board**: Track work, dependencies, priority, status
- **Team Mailbox**: Direct messages between all team members via `team_message`

```mermaid
flowchart TD
    subgraph Team["Agent Team"]
        LEAD["Lead Agent<br/>Orchestrates work, creates tasks,<br/>delegates to members, synthesizes results"]
        M1["Member A<br/>Claims and executes tasks"]
        M2["Member B<br/>Claims and executes tasks"]
        M3["Member C<br/>Claims and executes tasks"]
    end

    subgraph Shared["Shared Resources"]
        TB["Task Board<br/>Create, claim, complete tasks"]
        MB["Mailbox<br/>Direct messages, broadcasts"]
    end

    USER["User"] -->|message| LEAD
    LEAD -->|create task + delegate| M1 & M2 & M3
    M1 & M2 & M3 -->|results auto-announced| LEAD
    LEAD -->|synthesized response| USER

    LEAD & M1 & M2 & M3 <--> TB
    LEAD & M1 & M2 & M3 <--> MB
```

## Key Design Principles

**Lead-centric TEAM.md**: Only the lead receives `TEAM.md` with full orchestration instructions — mandatory workflow, delegation patterns, follow-up reminders. Members discover context on demand through tools; no wasted tokens on idle agents.

**Mandatory task tracking**: Every delegation from a lead must be linked to a task on the board. The system enforces this — delegations without a `team_task_id` are rejected, with a list of pending tasks provided to help the lead self-correct.

**Auto-completion**: When a delegation finishes, the linked task is automatically marked as complete. Files created during execution are auto-linked to the task. No manual bookkeeping.

**Blocker escalation**: Members can flag themselves as blocked by posting a blocker comment on a task. This auto-fails the task and delivers an escalation message to the lead with the blocked member name, task subject, blocker reason, and retry instructions.

**Parallel batching**: When multiple members work simultaneously, results are collected and delivered to the lead in a single combined announcement.

**Member scope**: Members do not have spawn or delegate access. They work within the team structure — executing tasks, reporting progress, and communicating via mailbox.

## Team Workspace

Each team has a shared workspace for files produced during task execution. Workspace scoping is configurable:

| Mode | Directory | Use Case |
|------|-----------|----------|
| **Isolated** (default) | `{dataDir}/teams/{teamID}/{chatID}/` | Per-conversation isolation |
| **Shared** | `{dataDir}/teams/{teamID}/` | All members access same folder |

Configure via `workspace_scope: "shared"` in team settings. Files written during task execution are automatically stored in the workspace and linked to the active task.

## v3 Orchestration Changes

In v3, teams use a **task-board-driven dispatch model** instead of the old `spawn(agent=...)` flow.

### Post-Turn Dispatch (BatchQueue)

Tasks created during a lead's turn are queued (`PendingTeamDispatchFromCtx`) and dispatched **after the turn ends** — not inline. This ensures `blocked_by` dependencies are fully wired before any member receives work.

```
Lead turn ends
  → BatchQueue flushes pending dispatches
  → Each assignee receives inbound message via bus
  → Member agents execute in isolated sessions
```

### Domain Event Bus

All task state changes emit typed events (`team_task.created`, `team_task.assigned`, `team_task.completed`, etc.) on the domain event bus. The dashboard updates in real-time via WebSocket without polling.

### Circuit Breaker

Tasks auto-fail after **3 dispatch attempts** (`maxTaskDispatches`). This prevents infinite loops when a member agent repeatedly fails or rejects a task. The dispatch count is tracked in `metadata.dispatch_count`.

### WaitAll Pattern

The lead can create multiple tasks in parallel and they dispatch concurrently. When all member tasks complete, `DispatchUnblockedTasks` auto-dispatches any waiting dependent tasks (ordered by priority). The lead synthesizes results only after all branches resolve.

> **Spawn tool change**: `spawn(agent="member")` is no longer valid in v3. Leads must use `team_tasks(action="create", assignee="member")` instead. The system will reject direct spawn-to-agent calls with an instructive error.

## Real-World Example

**Scenario**: User asks the lead to analyze a research paper and write a summary.

1. Lead receives request
2. Lead calls `team_tasks(action="create", subject="Extract key points from paper", assignee="researcher")` — system dispatches to researcher with a linked `team_task_id`
3. Researcher receives task, works independently, calls `team_tasks(action="complete", result="<findings>")` — linked task auto-completed, lead is notified
4. Lead calls `team_tasks(action="create", subject="Write summary", assignee="writer", description="Use researcher findings: <findings>", blocked_by=["<researcher-task-id>"])`
5. Writer's task unblocks automatically when researcher finishes, writer completes with result
6. Lead synthesizes and sends final response to user

## Teams vs Other Delegation Models

| Aspect | Agent Team | Simple Delegation | Agent Link |
|--------|-----------|-------------------|-----------|
| **Coordination** | Lead orchestrates with task board | Parent waits for result | Direct peer-to-peer |
| **Task Tracking** | Shared task board, dependencies, priorities | No tracking | No tracking |
| **Messaging** | All members use mailbox | Parent-only | Parent-only |
| **Scalability** | Designed for 3-10 members | Simple parent-child | One-to-one links |
| **TEAM.md Context** | Lead gets full instructions; members get execution guidance | Not applicable | Not applicable |
| **Use Case** | Parallel research, content review, analysis | Quick delegate & wait | Conversation handoff |

**Use Teams When**:
- 3+ agents need to work together
- Tasks have dependencies or priorities
- Members need to communicate
- Results need parallel batching

**Use Simple Delegation When**:
- One parent delegates to one child
- Need quick synchronous result
- No inter-team communication required

**Use Agent Links When**:
- Conversation needs to transfer between agents
- No task board or orchestration needed



---

# Creating & Managing Teams

Create teams via API, Dashboard, or CLI. The system automatically establishes delegation links between the lead and all members, injects `TEAM.md` into the lead's system prompt, and wires up task board access for all members.

## Quick Start

**Create a team** with lead agent and members:

```bash
# CLI
./goclaw team create \
  --name "Research Team" \
  --lead researcher_agent \
  --members analyst_agent,writer_agent \
  --description "Parallel research and writing"
```

**Via WebSocket RPC** (`teams.create`):

```json
{
  "name": "Research Team",
  "lead": "researcher_agent",
  "members": ["analyst_agent", "writer_agent"],
  "description": "Parallel research and writing"
}
```

**Dashboard**: Teams → Create Team → Select Lead → Add Members → Save

The Teams list page supports a **card/list toggle** for switching between visual card layout and a compact list view.

## What Happens on Creation

When you create a team, the system:

1. **Validates** lead and member agents exist
2. **Creates team record** with `status=active`
3. **Adds lead as a member** with `role=lead`
4. **Adds each member** with `role=member`
5. **Auto-creates delegation links** from lead → each member:
   - Direction: `outbound` (lead can delegate to members)
   - Max concurrent delegations per link: `3`
   - Marked with `team_id` (system knows these are team-managed)
6. **Injects TEAM.md** into the lead's system prompt with full orchestration instructions
7. **Enables task board** for all team members

## Team Lifecycle

```mermaid
flowchart TD
    CREATE["Admin creates team<br/>(name, lead, members)"] --> LINK["Auto-create delegation links<br/>Lead → each member"]
    LINK --> INJECT["TEAM.md auto-injected<br/>into lead's system prompt"]
    INJECT --> READY["Team ready for use"]

    READY --> MANAGE["Admin manages team"]
    MANAGE --> ADD["Add member<br/>→ auto-link lead→member"]
    MANAGE --> REMOVE["Remove member<br/>→ team links auto-deleted"]
    MANAGE --> DELETE["Delete team<br/>→ record hard-deleted from DB"]
```

## Managing Team Membership

**Add a member** (role is `member` by default):

```bash
./goclaw team add-member \
  --team-id 550e8400-e29b-41d4-a716-446655440000 \
  --agent analyst_agent \
  --role member

# When added, a delegation link is automatically created
# from lead → new member
```

**Remove a member**:

```bash
./goclaw team remove-member \
  --team-id 550e8400-e29b-41d4-a716-446655440000 \
  --agent-id <agent-uuid>

# Team-specific delegation links are automatically cleaned up on removal
```

**List team members**:

```bash
./goclaw team list-members --team-id 550e8400-e29b-41d4-a716-446655440000

# Output:
# Agent Key        Role        Display Name
# researcher_agent lead        Research Expert
# analyst_agent    member      Data Analyst
# writer_agent     member      Content Writer
```

Member info returned by the API is enriched with full **agent metadata** (display name, emoji, description, model) so the dashboard can render rich member cards.

## Lead vs Member Roles

| Capability | Lead | Member |
|-----------|------|--------|
| Receives full TEAM.md (orchestration instructions) | Yes | No (discovers context via tools) |
| Creates tasks on board | Yes | No |
| Delegates tasks to members | Yes | No |
| Executes delegated tasks | No | Yes |
| Reports progress via task board | No | Yes |
| Sends/receives mailbox messages | Yes | Yes |
| Spawn / delegate access | Yes | No |
| Self-assign tasks | No | N/A |

> **Note**: The lead agent cannot self-assign tasks. Attempting to do so is rejected to prevent a dual-session loop where the lead acts as both coordinator and executor.

Members work within the team structure. They do not have spawn or delegate capabilities — their role is to execute assigned tasks and report results.

## Team Settings & Access Control

Teams support fine-grained access control and behavior configuration via settings JSON:

```json
{
  "allow_user_ids": ["user_123", "user_456"],
  "deny_user_ids": [],
  "allow_channels": ["telegram", "slack"],
  "deny_channels": [],
  "progress_notifications": true,
  "followup_interval_minutes": 30,
  "followup_max_reminders": 3,
  "escalation_mode": "notify_lead",
  "escalation_actions": [],
  "workspace_scope": "isolated",
  "workspace_quota_mb": 500,
  "blocker_escalation": {
    "enabled": true
  }
}
```

**Access control fields**:
- `allow_user_ids`: Only these users can trigger team work (empty = open access)
- `deny_user_ids`: Block these users (deny takes priority over allow)
- `allow_channels`: Only messages from these channels trigger team work (empty = open)
- `deny_channels`: Block messages from these channels

System channels (`teammate`, `system`) always pass access checks regardless of settings.

**Follow-up & escalation fields**:
- `followup_interval_minutes`: Minutes between auto follow-up reminders on in-progress tasks
- `followup_max_reminders`: Maximum number of follow-up reminders per task
- `escalation_mode`: How to handle stale tasks — `"notify_lead"` (send notification) or `"fail_task"` (auto-fail the task)
- `escalation_actions`: Additional actions to take on escalation

**Blocker escalation**:
- `blocker_escalation.enabled`: Whether blocker comments auto-fail tasks and escalate to lead (default: `true`)

When `blocker_escalation` is enabled (default), if a member posts a blocker comment on a task, the task is auto-failed and the lead receives an escalation message with the blocker reason and retry instructions. Set `enabled: false` to save blocker comments without triggering auto-fail.

**Workspace fields**:
- `workspace_scope`: `"isolated"` (default, per-conversation folders) or `"shared"` (all members share one folder)
- `workspace_quota_mb`: Disk quota for team workspace in megabytes

**Other fields**:
- `progress_notifications`: Send periodic updates during async delegations

**Set team settings**:

```bash
./goclaw team update \
  --team-id 550e8400-e29b-41d4-a716-446655440000 \
  --settings '{
    "allow_user_ids": ["user_123"],
    "allow_channels": ["telegram"],
    "blocker_escalation": {"enabled": true},
    "escalation_mode": "notify_lead"
  }'
```

## Team Status

Teams have a `status` field:

- `active`: Team is operational
- `archived`: Team exists but disabled

To fully remove a team, use the delete operation — it hard-deletes the record from the database. There is no `deleted` status.

**Change team status**:

```bash
./goclaw team update \
  --team-id 550e8400-e29b-41d4-a716-446655440000 \
  --status archived
```

## Team Members in System Prompt

When a team is active, GoClaw injects a `## Team Members` section into the lead agent's system prompt listing all teammates. Each entry is enriched with agent metadata including emoji icon (from `other_config`):

```
## Team Members
- agent_key: analyst_agent | display_name: 🔍 Data Analyst | role: member | expertise: Data analysis and visualization...
- agent_key: writer_agent | display_name: ✍️ Content Writer | role: member | expertise: Technical writing...
```

This lets the lead assign tasks to the correct agent by key without guessing. The section updates automatically when members are added or removed.

## Lead Workspace Resolution

When a team task is dispatched, the lead agent resolves the per-team workspace directory for both lead and member agents. This resolution is transparent — agents use normal file paths and the **WorkspaceInterceptor** rewrites requests to the correct team workspace context automatically.

For isolated scope (`workspace_scope: "isolated"`), each conversation gets its own folder. For shared scope, all members read and write to the same team directory.

## Media Auto-Copy

When a task is created from a conversation that includes media files (images, documents), GoClaw automatically copies those files to the team workspace at `{team_workspace}/attachments/`. Hard links are used when possible for efficiency, with a copy fallback. Files are validated and saved with restrictive permissions (0640).

## TEAM.md Injection

`TEAM.md` is a virtual file generated dynamically at agent resolution time — not stored on disk. It is injected into the system prompt wrapped in `<system_context>` tags.

**Lead's TEAM.md** includes:
- Team name and description
- Teammate list with roles and expertise
- **Mandatory workflow**: create task first, then delegate with task ID — delegations without a valid `team_task_id` are rejected
- **Orchestration patterns**: sequential, iterative, parallel, mixed
- Communication guidelines

**Members' TEAM.md** includes:
- Team name and teammate list
- Instructions to focus on delegated work
- How to report progress via `team_tasks(action="progress", percent=50, text="...")`
- Task board actions available: `claim`, `complete`, `list`, `get`, `search`, `progress`, `comment`, `attach`, `retry` (no `create`, `cancel`, `approve`, `reject`)

The context refreshes automatically when team configuration changes (members added/removed, settings updated).

## Next Steps

- [Task Board](./task-board.md) - Create and manage tasks
- [Team Messaging](./team-messaging.md) - Communicate between members
- [Delegation & Handoff](./delegation-and-handoff.md) - Orchestrate work



---

# Task Board

The task board is a shared work tracker accessible to all team members. Tasks can be created with priorities, dependencies, and blocking constraints. Members claim pending tasks, work independently, and mark them complete with results.

The dashboard renders the board as a **Kanban layout** with columns per status. The board toolbar includes a workspace button and agent emoji display for quick identification of who owns each task.

## Task Lifecycle

```mermaid
flowchart TD
    PENDING["Pending<br/>(just created, ready to claim)"] -->|claim| IN_PROGRESS["In Progress<br/>(agent working)"]
    PENDING -->|blocked_by set| BLOCKED["Blocked<br/>(waiting for dependencies)"]
    BLOCKED -->|all blockers done| PENDING
    IN_PROGRESS -->|complete| COMPLETED["Completed<br/>(with result)"]
    IN_PROGRESS -->|review| IN_REVIEW["In Review<br/>(awaiting approval)"]
    IN_REVIEW -->|approve| COMPLETED
    IN_REVIEW -->|reject| CANCELLED["Cancelled"]
    PENDING -->|cancel| CANCELLED
    IN_PROGRESS -->|cancel| CANCELLED
    IN_PROGRESS -->|agent error| FAILED["Failed<br/>(error)"]
    PENDING -->|system failure| STALE["Stale<br/>(timed out)"]
    IN_PROGRESS -->|system failure| STALE
    FAILED -->|retry| PENDING
    STALE -->|retry| PENDING
```

## Core Tool: `team_tasks`

All team members access the task board via the `team_tasks` tool. Available actions:

| Action | Required Params | Description |
|--------|-----------------|-------------|
| `list` | `action` | Show tasks (default filter: all statuses; page size: 30) |
| `get` | `action`, `task_id` | Get full task detail with comments, events, attachments (result: 8,000 char limit) |
| `create` | `action`, `subject`, `assignee` | Create new task (lead only); `assignee` is **mandatory**; optional: `description`, `priority`, `blocked_by`, `require_approval` |
| `claim` | `action`, `task_id` | Atomically claim a pending task |
| `complete` | `action`, `task_id`, `result` | Mark task done with result summary |
| `cancel` | `action`, `task_id` | Cancel task (lead only); optional: `text` (reason) |
| `assign` | `action`, `task_id`, `assignee` | Admin-assign a pending task to an agent |
| `search` | `action`, `query` | Full-text search over subject + description (check before creating to avoid duplicates) |
| `review` | `action`, `task_id` | Submit in-progress task for review; transitions to `in_review` (owner only) |
| `approve` | `action`, `task_id` | Approve a task in review → `completed` (lead/admin only) |
| `reject` | `action`, `task_id` | Reject a task in review → `cancelled` with reason injected to lead (lead/admin only); optional: `text` |
| `comment` | `action`, `task_id`, `text` | Add a comment; use `type="blocker"` to flag a blocker (triggers auto-fail + lead escalation) |
| `progress` | `action`, `task_id`, `percent` | Update progress 0-100 (owner only); optional: `text` (step description) |
| `update` | `action`, `task_id` | Update task subject or description (lead only) |
| `attach` | `action`, `task_id`, `file_id` | Attach a workspace file to a task |
| `ask_user` | `action`, `task_id`, `text` | Set a periodic follow-up reminder sent to user (owner only) |
| `clear_followup` | `action`, `task_id` | Clear ask_user reminders (owner or lead) |
| `retry` | `action`, `task_id` | Re-dispatch a `stale` or `failed` task back to `pending` (admin/lead) |
| `delete` | `action`, `task_id` | Hard-delete a task in terminal status (completed/cancelled/failed) from the board |

## Create a Task

**Lead creates a task** for members to work on:

> **Note**: The `assignee` field is **mandatory** at task creation. Omitting it returns an error: `"assignee is required — specify which team member should handle this task"`.

> **Note**: Agents must call `search` before `create` to avoid duplicate tasks. Creating without checking first returns an error prompting the search.

> **Note**: Team V2 leads cannot manually create tasks before a spawn has been issued in the current turn — this prevents premature task creation that breaks the structured orchestration flow.

```json
{
  "action": "create",
  "subject": "Extract key points from research paper",
  "description": "Read the PDF and summarize main findings in bullet points",
  "priority": 10,
  "assignee": "researcher",
  "blocked_by": []
}
```

**Response**:
```
Task created: Extract key points from research paper (id=<uuid>, identifier=TSK-1, status=pending)
```

The `identifier` field (e.g. `TSK-1`) is a short human-readable reference generated from the team name prefix and task number.

**With dependencies** (blocked_by):

```json
{
  "action": "create",
  "subject": "Write summary",
  "priority": 5,
  "assignee": "writer_agent",
  "blocked_by": ["<first-task-uuid>"]
}
```

This task stays `blocked` until the first task is `completed`. When you complete the blocker, this task automatically transitions to `pending` and becomes claimable.

**With approval required** (require_approval):

```json
{
  "action": "create",
  "subject": "Deploy to production",
  "assignee": "devops_agent",
  "require_approval": true
}
```

Task starts in `pending` status with `require_approval` flag set. After the member calls `review`, it enters `in_review` and must be approved before completing.

## Claim & Complete a Task

**Member claims a pending task**:

```json
{
  "action": "claim",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Atomic claiming**: Database ensures only one agent succeeds. If two agents try to claim the same task, one gets `claimed successfully`; the other gets `failed to claim task` (someone else beat you).

**Member completes the task**:

```json
{
  "action": "complete",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": "Extracted 12 key findings:\n1. Main hypothesis confirmed\n2. Data suggests..."
}
```

**Auto-claim**: You can skip the claim step. Calling `complete` on a pending task auto-claims it (one API call instead of two).

> **Note**: Delegate agents cannot call `complete` directly — their results are auto-completed when delegation finishes.

## Task Delete

Terminal-status tasks (completed, cancelled, failed) can be hard-deleted from the board:

```json
{
  "action": "delete",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

Delete is only permitted when the task is in a terminal state. Attempting to delete an active task returns an error. The dashboard also exposes a delete button in the task detail view. A `team.task.deleted` WebSocket event is emitted on success.

## Task Dependencies & Auto-Unblock

When you create a task with `blocked_by: [task_A, task_B]`:
- Task status is set to `blocked`
- Task remains unclaimable
- When **all** blockers are `completed`, task automatically transitions to `pending`
- Members are notified the task is ready

```mermaid
flowchart LR
    A["Task A<br/>Research"] -->|complete| A_DONE["Task A: completed"]
    B["Task B<br/>Analysis"] -->|complete| B_DONE["Task B: completed"]

    C["Task C: blocked<br/>blockers=[A,B]"]

    A_DONE --> UNBLOCK["Check blockers"]
    B_DONE --> UNBLOCK
    UNBLOCK -->|all done| C_READY["Task C: pending<br/>(ready to claim)"]
```

**Blocked_by validation**: The system validates that `blocked_by` references do not create circular dependencies or reference tasks in terminal states that would make the block unresolvable.

## Blocker Escalation

When a member is stuck, they post a blocker comment:

```json
{
  "action": "comment",
  "task_id": "550e8400-...",
  "text": "Cannot find API documentation",
  "type": "blocker"
}
```

What happens automatically:
1. Comment saved with `comment_type='blocker'`
2. Task **auto-fails** (`in_progress` → `failed`)
3. Member's session is cancelled; UI dashboard updates in real-time
4. **Lead receives an escalation message** from `system:escalation` with the blocked member name, task number, blocker reason, and a `retry` instruction

The lead can then fix the issue and re-dispatch:

```json
{
  "action": "retry",
  "task_id": "550e8400-..."
}
```

Blocker escalation is enabled by default. Disable per-team via settings: `{"blocker_escalation": {"enabled": false}}`.

## Review Workflow

For tasks requiring human approval, set `require_approval: true` at creation:

1. **Member submits**: `action="review"` → task moves to `in_review`
2. **Human approves** (dashboard): `action="approve"` → task moves to `completed`
3. **Human rejects** (dashboard): `action="reject"` → task moves to `cancelled`; lead receives notification with reason

Without `require_approval`, tasks move directly to `completed` after `complete` (no in_review stage).

**Filtering**: The dashboard supports filtering by all task statuses including `in_review`, `cancelled`, and `failed`. The default status filter shows **all** tasks (page size: 30).

## Task Snapshots

Completed tasks automatically store snapshots in their `metadata` field for board visualization:

```json
{
  "snapshot": {
    "completed_at": "2026-03-16T12:34:56Z",
    "result_preview": "First 100 chars of result...",
    "final_status": "completed",
    "ai_summary": "Brief AI-generated summary of what was accomplished"
  }
}
```

The Kanban board displays these snapshots as cards, allowing users to review completed work at a glance without opening the full task detail.

## List & Search

**List tasks** (default shows all statuses, 30 per page):

```json
{
  "action": "list"
}
```

**Filter by status**:

```json
{
  "action": "list",
  "status": "in_review"
}
```

Valid `status` filter values:

| Value | Returns |
|-------|---------|
| `""` or `"all"` (default) | All tasks regardless of status |
| `"active"` | Active tasks: pending, in_progress, blocked |
| `"completed"` | Completed and cancelled tasks |
| `"in_review"` | Tasks awaiting approval |

**Search** for specific tasks:

```json
{
  "action": "search",
  "query": "research paper"
}
```

Results show snippet (500 char max) of full result. Use `action=get` for complete result.

## Priority & Ordering

Tasks are ordered by priority (highest first), then by creation time. Higher priority = gets sorted to top of list:

```json
{
  "action": "create",
  "subject": "Urgent fix needed",
  "assignee": "fixer_agent",
  "priority": 100
}
```

## User Scoping

Access differs by channel:

- **Delegate/system channels**: See all team tasks
- **End users**: See only tasks they triggered (filtered by user ID)

Results are truncated:
- `action=list`: Results not shown (use `get` for full)
- `action=get`: 8,000 characters max
- `action=search`: 500 character snippets

## Get Full Task Details

```json
{
  "action": "get",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Response** includes:
- Full task metadata (including `identifier`, `task_number`, `progress_percent`, snapshot)
- Complete result text (truncated at 8,000 chars if needed)
- Owner agent key and display name with emoji
- Timestamps
- Comments, audit events, and attachments (if any)

## Cancel a Task

**Lead cancels a task**:

```json
{
  "action": "cancel",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "User request changed, no longer needed"
}
```

Note: the cancel reason is passed via the `text` parameter (not `reason`).

**What happens**:
- Task status → `cancelled`
- If delegation is running for this task, it's stopped immediately
- Any dependent tasks (with `blocked_by` pointing here) become unblocked

## Improved Task Dispatch Concurrency

Task dispatch uses a post-turn queue to avoid race conditions: tasks created by the lead during a turn are queued and dispatched together after the turn ends. This means:

- Dependencies set via `blocked_by` are fully resolved before any dispatch fires
- Only one task per assignee is dispatched per round (priority-ordered) to prevent cancellation conflicts
- Completed blocker results are automatically appended to the dispatch content for unblocked tasks

## Best Practices

1. **Create tasks first**: Always create a task before delegating work (lead only)
2. **Always set assignee**: The `assignee` field is mandatory — specify the team member at creation
3. **Search before creating**: Use `action=search` to check for similar tasks before creating to avoid duplicates
4. **Use priority**: Set priority based on urgency (100 = urgent, 10 = high, 0 = normal)
5. **Add dependencies**: Link related tasks with `blocked_by` to enforce order
6. **Include context**: Write clear descriptions so members know what to do
7. **Use blocker comments**: If stuck, post a `type="blocker"` comment — the lead is automatically notified
8. **Delete completed clutter**: Use `action=delete` on terminal tasks to keep the board clean



---

# Team Messaging

Team members communicate via a built-in mailbox system. Members can send direct messages and read unread messages. The lead agent does not have access to the `team_message` tool — it is removed from the lead's tool list by policy. Messages flow through the message bus with real-time delivery.

## Mailbox Tool: `team_message`

All team members access the mailbox via the `team_message` tool. Actions:

| Action | Params | Description |
|--------|--------|-------------|
| `send` | `to`, `text`, `media` (optional) | Send direct message to specific teammate |
| `broadcast` | `text` | Send message to all teammates (except self); system/teammate channel only |
| `read` | none | Get unread messages; auto-marks as read |

## Send a Direct Message

**Member sends message to another member**:

```json
{
  "action": "send",
  "to": "analyst_agent",
  "text": "Please review my findings from task 123. I need your input on the methodology."
}
```

**What happens**:
1. Message is persisted to database
2. A "message" task is auto-created on the team task board (visible in Tasks tab)
3. Recipient is notified in real-time via message bus (channel: `system`, sender: `teammate:{sender_key}`)
4. Event broadcast to UI for real-time updates

**Response**:
```
Message sent to analyst_agent.
```

**Cross-team protection**: You can only message team members. Attempting to message someone outside your team fails with `"agent is not a member of your team"`.

## Broadcast to All Members

Broadcast delivers a message to all team members simultaneously. This action is restricted to system/teammate channels (internal operations) — regular member agents cannot call `broadcast` directly.

```json
{
  "action": "broadcast",
  "text": "Important update: We've decided to focus on the top 5 findings. Please adjust your work accordingly."
}
```

**What happens**:
1. Message persisted as broadcast (to_agent_id = NULL)
2. Message type: `broadcast`
3. Each team member (except sender) receives the message
4. Event broadcast to UI for all to see

**Response**:
```
Broadcast sent to all teammates.
```

## Read Unread Messages

**Check mailbox**:

```json
{
  "action": "read"
}
```

**Response**:
```json
{
  "messages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "team_id": "...",
      "from_agent_id": "...",
      "from_agent_key": "researcher_agent",
      "to_agent_key": "analyst_agent",
      "message_type": "chat",
      "content": "Please review my findings...",
      "read": false,
      "created_at": "2025-03-08T10:30:00Z"
    }
  ],
  "count": 1
}
```

**Auto-marking**: Reading messages automatically marks them as read. Next `read` call will only show new unread messages.

**Pagination**: Returns up to 50 unread messages per call. If more exist, the response includes `"has_more": true` and a note to call `read` again after processing.

## Message Routing

Messages flow through the system with special routing:

```mermaid
flowchart TD
    SEND["team_message send/broadcast"] --> PERSIST["Persist to DB"]
    PERSIST --> BUS["Message Bus<br/>Channel: 'system'<br/>SenderID: 'teammate:{sender_key}'"]
    BUS --> TARGET["Route to target agent session"]
    TARGET --> DISPLAY["Display in conversation"]
```

**Message format on delivery**:
```
[Team message from researcher_agent]: Please review my findings...
```

The `teammate:` prefix in the sender ID tells the consumer to route the message to the correct team member's session, not the general user session.

## Domain Event Bus

In addition to mailbox messages, GoClaw uses a typed **Domain Event Bus** (`eventbus.DomainEventBus`) for internal event propagation across the v3 pipeline. This is separate from the channel message bus used for routing.

The domain event bus is defined in `internal/eventbus/domain_event_bus.go`:

```go
type DomainEventBus interface {
    Publish(event DomainEvent)                                    // non-blocking enqueue
    Subscribe(eventType EventType, handler DomainEventHandler) func() // returns unsubscribe fn
    Start(ctx context.Context)
    Drain(timeout time.Duration) error
}
```

**Key properties**:
- Async worker pool (default 2 workers, queue depth 1000)
- Per-`SourceID` dedup window (default 5 minutes) — prevents duplicate processing
- Configurable retry (default 3 attempts with exponential backoff)
- Graceful drain on shutdown

**Event types catalog** (defined in `eventbus/event_types.go`):

| Event Type | Trigger |
|-----------|---------|
| `session.completed` | Session ends or context is compacted |
| `episodic.created` | Episodic memory summary stored |
| `entity.upserted` | Knowledge graph entity updated |
| `run.completed` | Agent pipeline run finishes |
| `tool.executed` | Tool call completes (for metrics) |
| `vault.doc_upserted` | Vault document registered or updated |
| `delegate.sent` | Delegation dispatched to member |
| `delegate.completed` | Delegatee finishes successfully |
| `delegate.failed` | Delegation fails |

These events power the v3 enrichment pipeline (episodic memory, knowledge graph, vault indexing) independently from the WebSocket team events used by the UI.

## WebSocket Team Events

For UI real-time updates, team activity emits WebSocket events via `msgBus.Broadcast`. These are separate from the domain event bus and target connected dashboard clients.

When messages are sent, real-time events are broadcast to UI:

```json
{
  "event": "team.message.sent",
  "payload": {
    "team_id": "550e8400-e29b-41d4-a716-446655440000",
    "from_agent_key": "researcher_agent",
    "from_display_name": "Research Expert",
    "to_agent_key": "analyst_agent",
    "to_display_name": "Data Analyst",
    "message_type": "chat",
    "preview": "Please review my findings...",
    "user_id": "...",
    "channel": "telegram",
    "chat_id": "..."
  }
}
```

### Task Lifecycle Events API

Task lifecycle events (create, assign, complete, approve, reject, comment, fail, etc.) are also available via the REST endpoint:

```
GET /v1/teams/{id}/events
```

This returns a paginated audit log of all task state changes for the team, useful for compliance review or building custom dashboards.

## Use Cases

**Member → Member**: "Task 123 is ready for your review. The data shows..."

**Member → Member**: "I'm blocked on step 2 — do you have the raw dataset I need?"

**Broadcast** (system-level only): "Changing priorities. Focus on tasks 1, 2, 5 instead of 3, 4."

> **Note**: Leads coordinate via `team_tasks`, not `team_message`. Use `team_tasks(action="progress")` to report status updates instead of direct messages.

## Auto-Fail on Loop Kill

If a member agent's run is terminated by the loop detector (stuck or infinite loop), the task automatically transitions to `failed`:

- The loop detector identifies stuck patterns — same tool calls with same args and results repeated, or read-only streaks without progress
- When critical level triggers, the run is killed and the team task manager marks the task as `failed`
- The lead agent is notified and can reassign or retry with updated instructions

This prevents infinite loops from blocking team progress — agents can safely attempt exploratory tasks without risk of permanent stall.

## Team Notification Settings

Team task events can be forwarded to chat channels. The default configuration is conservative — only high-signal events are on by default to reduce noise.

| Event | Default | Description |
|-------|---------|-------------|
| `dispatched` | ON | Task dispatched to a member |
| `new_task` | ON | New task created (human-initiated) |
| `completed` | ON | Task completed |
| `progress` | OFF | Member updates progress |
| `failed` | OFF | Task failed |
| `commented` | OFF | Task comment added |
| `slow_tool` | OFF | System alert when a tool call exceeds the adaptive threshold |

Delivery mode is `direct` by default (outbound channel). Set `mode: "leader"` to route all notifications through the lead agent.

Configure notifications in team settings:

```json
{
  "notifications": {
    "dispatched": true,
    "new_task": true,
    "completed": true,
    "progress": false,
    "failed": false,
    "commented": false,
    "slow_tool": false,
    "mode": "direct"
  }
}
```

## Best Practices

1. **Be concise**: Keep messages focused and actionable
2. **Use broadcasts for team-wide info**: Don't send identical messages to multiple members
3. **Direct message for discussion**: Back-and-forth coordination use direct messages
4. **Reference tasks**: Mention task IDs for context ("Task 123 is blocked by...")
5. **Check regularly**: Members should check their mailbox if waiting for updates

## Message Persistence

All messages are persisted to the database:
- Direct messages link sender → specific recipient
- Broadcasts link sender → NULL (means all members)
- Timestamps and read status tracked
- Full message history available for audit/review



---

# Delegation & Handoff

Delegation allows the lead to assign work to member agents via the task board. Handoff transfers conversation control between agents without interrupting the user's session.

## Agent Delegation Flow

Delegation works through the `team_tasks` tool — the lead creates a task with an assignee, and the system auto-dispatches it to the assigned member:

```mermaid
flowchart TD
    LEAD["Lead receives user request"] --> CREATE["1. Create task on board<br/>team_tasks(action=create,<br/>assignee=member)"]
    CREATE --> DISPATCH["2. System auto-dispatches<br/>to assigned member"]
    DISPATCH --> MEMBER["Member agent executes<br/>in isolated session"]
    MEMBER --> COMPLETE["3. Task auto-completed<br/>with result"]
    COMPLETE --> ANNOUNCE["4. Result announced<br/>back to lead"]

    subgraph "Parallel Delegation"
        CREATE2["create task → member_A"] --> RUNA["Member A works"]
        CREATE3["create task → member_B"] --> RUNB["Member B works"]
        RUNA --> COLLECT["Results accumulate"]
        RUNB --> COLLECT
        COLLECT --> ANNOUNCE2["Single combined<br/>announcement to lead"]
    end
```

> **Note**: The `spawn` tool is for **self-clone subagents only** — it does not accept an `agent` parameter. To delegate to a team member, always use `team_tasks(action="create", assignee=...)`.

## Creating a Delegation Task

Use the `team_tasks` tool with `action: "create"` and a required `assignee`:

```json
{
  "action": "create",
  "subject": "Analyze the market trends in the Q1 report",
  "description": "Focus on Q1 revenue data and competitor analysis",
  "assignee": "analyst_agent"
}
```

The system validates and auto-dispatches:
- **`assignee` is required** — every task must be assigned to a team member
- **Assignee must be a team member** — non-members are rejected
- **Lead cannot self-assign** — prevents dual-session execution loops
- **Auto-dispatch**: after the lead's turn ends, pending tasks are dispatched to their assigned agents

**Guards enforced**:
- Max **3 dispatches** per task — auto-fails after 3 attempts to prevent infinite loops
- Task dispatched to lead agent is blocked and auto-failed
- Member requests (non-lead) can optionally require leader approval before dispatch

> **V2 leads**: Team V2 leads cannot manually create tasks before a spawn has been issued in the current turn. This prevents premature task creation that would break the structured orchestration flow.

## Parallel Delegation

Create multiple tasks in the same turn — they dispatch simultaneously after the turn:

```json
// Lead creates 2 tasks in one turn
{"action": "create", "subject": "Extract facts", "assignee": "analyst1"}
{"action": "create", "subject": "Extract opinions", "assignee": "analyst2"}
```

Results are collected via a **producer-consumer announce queue** (`BatchQueue[T]`) that merges staggered completions into a single LLM announcement run. This means the lead receives one combined message rather than separate interruptions per member — reducing token overhead significantly.

## Parallel Sub-Agent Enhancement (#600)

Beyond team member delegation, the lead can spawn **self-clone subagents** using the `spawn` tool for parallel workloads that don't require a specific team member:

```json
{"action": "spawn", "task": "Summarize the PDF report", "label": "pdf-summarizer"}
```

Key behaviors introduced in the parallel sub-agent enhancement:

### Smart Leader Delegation

The leader delegation prompt is **conditional** — it only activates when the situation genuinely requires delegation, rather than being forced on every spawn. This avoids wasted LLM turns when a direct response is more appropriate.

### `spawn(action=wait)` — WaitAll Orchestration

Block the parent until all spawned children complete:

```json
{"action": "wait", "timeout": 300}
```

- Parent turn pauses until all active subagents finish (or timeout expires)
- Enables coordinated multi-step workflows where the lead needs results before proceeding
- Default timeout: 300 seconds

### Auto-Retry with Linear Backoff

Subagent LLM failures trigger automatic retry. Configuration via `SubagentConfig`:

| Field | Default | Description |
|-------|---------|-------------|
| `MaxRetries` | `2` | Maximum retry attempts per subagent |
| Backoff | linear | Each retry waits `attempt × 2s` before re-running |

### Per-Edition Rate Limiting

Tenant-scoped concurrency limits on the Edition struct:

| Limit | Field | Description |
|-------|-------|-------------|
| Concurrent subagents | `MaxSubagentConcurrent` | Max simultaneous subagents per tenant |
| Spawn depth | `MaxSubagentDepth` | Max nesting depth (subagent spawning subagents) |

When limits are hit, the spawn is rejected with a clear error so the LLM can adjust.

### `subagent_tasks` Table (Migration 34)

Subagent task state is persisted to the `subagent_tasks` database table (migration 000034). The `SubagentTaskStore` interface with PostgreSQL implementation provides:
- Durable task tracking across restarts
- Write-through persistence from `SubagentManager`
- Token cost storage per task

### Token Cost Tracking

Per-subagent input and output token counts are accumulated and included in:
- The announce message delivered to the lead
- The `subagent_tasks` DB record for billing and observability

### Compaction Prompt Persistence

When the lead agent's context is compacted (summarized), pending subagent and team task state is preserved in the compaction prompt. Work continuity is maintained — the lead does not lose track of in-flight tasks after summarization.

### Telegram Commands

Two Telegram bot commands are available for monitoring subagent work:

| Command | Description |
|---------|-------------|
| `/subagents` | Lists all active subagent tasks with status |
| `/subagent <id>` | Shows detailed view of a specific subagent task from DB |

### Subagent Tool Restrictions

`team_tasks` is blocked inside subagents via `SubagentDenyAlways`. Subagents cannot create team tasks or perform team orchestration — only the lead can coordinate the team board.

## Auto-Completion & Artifacts

When a delegation finishes:

1. Linked task is marked `completed` with delegation result
2. Result summary is persisted
3. Media files (images, documents) are forwarded
4. Delegation artifacts stored with team context
5. Session cleaned up

**Announcement includes**:
- Results from each member agent
- Deliverables and media files
- Elapsed time statistics
- Guidance: present results to user, delegate follow-ups, or ask for revisions

## Delegation Search

When an agent has too many targets for static `AGENTS.md` (>15), use delegation search:

```json
{
  "query": "data analysis and visualization",
  "max_results": 5
}
```

Call the `delegate_search` tool with the above parameters.

**What it searches**:
- Agent name and key (full-text search)
- Agent description (full-text search)
- Semantic similarity (if embedding provider available)

**Result**:
```json
{
  "agents": [
    {
      "agent_key": "analyst_agent",
      "display_name": "Data Analyst",
      "frontmatter": "Analyzes data and creates visualizations"
    }
  ],
  "count": 1
}
```

**Hybrid search**: Uses both keyword matching (FTS) and semantic embeddings for best results.

## Access Control: Agent Links

Each delegation link (lead → member) can have its own access control:

```json
{
  "user_allow": ["user_123", "user_456"],
  "user_deny": []
}
```

**Concurrency limits**:
- Per-link: configurable via `max_concurrent` on the agent link
- Per-agent: default 5 total concurrent delegations targeting any single member (configurable via agent's `max_delegation_load`)

When limits hit, error message: `"Agent at capacity. Try a different agent or handle it yourself."`

## Handoff: Conversation Transfer

Transfer conversation control to another agent without interrupting the user:

```json
{
  "action": "transfer",
  "agent": "specialist_agent",
  "reason": "You need specialist expertise for the next part of your request",
  "transfer_context": true
}
```

Call the `handoff` tool with the above parameters.

### What Happens

1. Routing override set: future messages from user go to target agent
2. Conversation context (summary) passed to target agent
3. Target agent receives handoff notification with context
4. Event broadcast to UI
5. User's next message routes to new agent
6. Deliverable workspace files copied to the target agent's team workspace

### Handoff Parameters

- `action`: `transfer` (default) or `clear`
- `agent`: Target agent key (required for `transfer`)
- `reason`: Why the handoff (required for `transfer`)
- `transfer_context`: Pass conversation summary (default true)

### Clear a Handoff

```json
{
  "action": "clear"
}
```

Messages will route to default agent for this chat.

### Handoff Messaging

Handoff notification sent to the target agent:
```
[Handoff from researcher_agent]
Reason: You need specialist expertise for the next part of your request

Conversation context:
[summary of recent conversation]

Please greet the user and continue the conversation.
```

### Use Cases

- User's question becomes specialized → handoff to expert
- Agent reaches capacity → handoff to another instance
- Complex problem needs multiple specialties → handoff after partial solution
- Shift from research to implementation → handoff to engineer

## Evaluate Loop (Generator-Evaluator)

For iterative work, use the evaluate pattern with task creation:

```json
{"action": "create", "subject": "Generate initial proposal", "assignee": "generator_agent"}

// Wait for result, then:

{"action": "create", "subject": "Review proposal and provide feedback", "assignee": "evaluator_agent"}

// Generator refines based on feedback...
```

**Note**: The system does not enforce a maximum number of iterations for this pattern. Set your own limit in the lead's instructions to avoid infinite loops.

## Progress Notifications

For async delegations, the lead receives periodic grouped updates (if progress notifications are enabled for the team):

```
🏗 Your team is working on it...
- Data Analyst (analyst_agent): 2m15s
- Report Writer (writer_agent): 45s
```

**Interval**: 30 seconds. Enabled/disabled via team settings (`progress_notifications`).

## Best Practices

1. **Use `team_tasks` to delegate**: create tasks with `assignee` — system auto-dispatches
2. **Don't use `spawn` for delegation**: `spawn` is self-clone only, not for team members
3. **Create multiple tasks in one turn**: they dispatch in parallel after the turn ends
4. **Use `blocked_by`**: coordinate task ordering with dependencies
5. **Use `spawn(action=wait)`**: when lead needs all results before continuing
6. **Handle handoffs gracefully**: Notify user of transfer; pass context
7. **Set iteration limits in instructions**: Prevent infinite evaluate loops



---

# Custom Tools

> Give your agents new shell-backed capabilities at runtime — no recompile, no restart.

## Overview

Custom tools let you extend any agent with commands that run on your server. You define a name, a description the LLM uses to decide when to call the tool, a JSON Schema for the parameters, and a shell command template. GoClaw stores the definition in PostgreSQL, loads it at request time, and handles shell-escaping so the LLM cannot inject arbitrary shell syntax.

Tools can be **global** (available to all agents) or **scoped to a single agent** by setting `agent_id`.

```mermaid
sequenceDiagram
    participant LLM
    participant GoClaw
    participant Shell
    LLM->>GoClaw: tool_call {name: "deploy", args: {namespace: "prod"}}
    GoClaw->>GoClaw: render template, shell-escape args
    GoClaw->>GoClaw: check deny patterns
    GoClaw->>Shell: sh -c "kubectl rollout restart ... --namespace='prod'"
    Shell-->>GoClaw: stdout / stderr
    GoClaw-->>LLM: tool_result
```

## Creating a Tool

### Via the HTTP API

```bash
curl -X POST http://localhost:8080/v1/tools/custom \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy",
    "description": "Roll out the latest image to a Kubernetes namespace. Use when the user asks to deploy or restart a service.",
    "parameters": {
      "type": "object",
      "properties": {
        "namespace": {
          "type": "string",
          "description": "Target Kubernetes namespace (e.g. production, staging)"
        },
        "deployment": {
          "type": "string",
          "description": "Name of the Kubernetes deployment"
        }
      },
      "required": ["namespace", "deployment"]
    },
    "command": "kubectl rollout restart deployment/{{.deployment}} --namespace={{.namespace}}",
    "timeout_seconds": 120,
    "agent_id": "3f2a1b4c-0000-0000-0000-000000000000"
  }'
```

**Required fields:** `name` and `command`. The name must be a slug (lowercase letters, numbers, hyphens only) and cannot conflict with a built-in or MCP tool name.

### Field reference

| Field | Type | Default | Description |
|---|---|---|---|
| `name` | string | — | Unique slug identifier |
| `description` | string | — | Shown to the LLM to trigger the tool |
| `parameters` | JSON Schema | `{}` | Parameters the LLM must provide |
| `command` | string | — | Shell command template |
| `working_dir` | string | agent workspace | Override working directory |
| `timeout_seconds` | int | 60 | Execution timeout |
| `agent_id` | UUID | null | Scope to one agent; omit for global |
| `enabled` | bool | true | Disable without deleting |

> **Three distinct timeouts — don't confuse them.** This per-custom-tool `timeout_seconds` (default 60) applies only to this one custom tool's command. It is separate from the host `exec` builtin tool's own `timeout_seconds` setting (also default 60, max 3600 — see [Tools Overview → Execution Timeout](/tools-overview)) and from the sandbox `sandbox_config.timeout_sec` (agent-level, default 300 — see [Sandbox](/sandbox)). A custom tool routed through the sandbox is still bounded by the sandbox timeout.

### Command templates

Use `{{.paramName}}` placeholders. GoClaw replaces them with shell-escaped values using simple string replacement — not Go's `text/template` engine, so template functions and pipelines are not supported. Every substituted value is single-quoted with embedded single-quotes escaped, so even a malicious LLM cannot break out of the argument.

```bash
# These placeholders are always treated as literal strings — no template logic
kubectl rollout restart deployment/{{.deployment}} --namespace={{.namespace}}
git -C {{.repo_path}} pull origin {{.branch}}
```

### Adding environment variables (secrets)

Secrets must be set via a separate `PUT` after creation — they cannot be included in the initial `POST`. They are encrypted with AES-256-GCM before storage and are **never returned by the API**.

```bash
curl -X PUT http://localhost:8080/v1/tools/custom/{id} \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "env": {
      "KUBE_TOKEN": "eyJhbGc...",
      "SLACK_WEBHOOK": "https://hooks.slack.com/services/..."
    }
  }'
```

The variables are injected only into the child process — they are not visible to the LLM or written to logs.

## Managing Tools

```bash
# List (paginated) — returns only enabled tools
GET /v1/tools/custom?limit=50&offset=0

# Filter by agent — returns only enabled tools for that agent
GET /v1/tools/custom?agent_id=<uuid>

# Search by name or description (case-insensitive)
GET /v1/tools/custom?search=deploy

# Get single tool
GET /v1/tools/custom/{id}

# Update (partial — any field)
PUT /v1/tools/custom/{id}

# Delete
DELETE /v1/tools/custom/{id}
```

## Security

Every custom tool command is checked against the same **deny pattern list** as the built-in `exec` tool. Blocked categories include:

- Destructive file ops (`rm -rf`, `rm --recursive`, `dd if=`, `mkfs`, `shutdown`, `reboot`, fork bombs)
- Data exfiltration (`curl | sh`, `curl` with POST/PUT flags, `wget --post-data`, DNS tools: `nslookup`, `dig`, `host`, `/dev/tcp/` redirects)
- Reverse shells (`nc -e`, `ncat`, `socat`, `openssl s_client`, `telnet`, `mkfifo`, scripting language socket imports)
- Dangerous eval / code injection (`eval $`, `base64 -d | sh`)
- Privilege escalation (`sudo`, `su -`, `nsenter`, `unshare`, `mount`, `capsh`, `setcap`)
- Dangerous path operations (`chmod` on `/` paths, `chmod +x` in `/tmp`, `/var/tmp`, `/dev/shm`)
- Environment variable injection (`LD_PRELOAD=`, `DYLD_INSERT_LIBRARIES=`, `LD_LIBRARY_PATH=`, `BASH_ENV=`)
- Environment dumping (`printenv`, bare `env`, `env | ...`, `env > file`, `set`/`export -p`/`declare -x` dumps, `/proc/PID/environ`, `/proc/self/environ`)
- Container escape (`/var/run/docker.sock`, `/proc/sys/`, `/sys/kernel/`)
- Crypto mining (`xmrig`, `cpuminer`, stratum protocol)
- Filter bypass patterns (`sed /e`, `sort --compress-program`, `git --upload-pack=`, `grep --pre=`)
- Network reconnaissance (`nmap`, `masscan`, outbound `ssh`/`scp` with `@`)
- Persistence (`crontab`, writing to shell RC files like `.bashrc`, `.zshrc`)
- Process manipulation (`kill -9`, `killall`, `pkill`)

The check runs on the **fully rendered command** after all `{{.param}}` substitutions.

## Examples

### Check disk usage

```json
{
  "name": "check-disk",
  "description": "Report disk usage for a directory on the server.",
  "parameters": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "Directory path to check" }
    },
    "required": ["path"]
  },
  "command": "df -h {{.path}}"
}
```

### Tail application logs

```json
{
  "name": "tail-logs",
  "description": "Show the last N lines of an application log file.",
  "parameters": {
    "type": "object",
    "properties": {
      "service": { "type": "string", "description": "Service name, e.g. api, worker" },
      "lines":   { "type": "integer", "description": "Number of lines to show" }
    },
    "required": ["service", "lines"]
  },
  "command": "tail -n {{.lines}} /var/log/app/{{.service}}.log"
}
```

## Execution Ordering

When an agent emits several tool calls in one turn, only registered **read-only** built-in tools run in bounded parallel. Custom (shell-backed) tools are not registered as read-only, so they always execute **sequentially** — and any batch that mixes a custom tool with other calls runs entirely sequentially. This keeps shell-backed side effects predictable and ordered; it is not a setting you configure.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `name must be a valid slug` | Name has uppercase or spaces | Use lowercase, numbers, hyphens only |
| `tool name conflicts with existing built-in or MCP tool` | Clashes with `exec`, `read_file`, or MCP | Choose a different name |
| `command denied by safety policy` | Matches a deny pattern | Restructure command to avoid blocked ops |
| Tool not visible to agent | Wrong `agent_id` or `enabled: false` | Verify agent ID; re-enable if disabled |
| Execution timeout | Default 60 s too short for the task | Increase `timeout_seconds` |

## Built-in Tool: send_file

The `send_file` tool delivers an existing file in the workspace as an attachment — it does **not** create or modify files, only deliver them.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `path` | Yes | File path (relative to workspace or absolute) |
| `caption` | No | Message to accompany the file |

**Example:** An agent has generated a report at `reports/summary.pdf` and then calls:

```json
{ "path": "reports/summary.pdf", "caption": "Here's this week's report" }
```

### DeliveredMedia Cross-Tool Dedup Contract

GoClaw maintains a `DeliveredMedia` tracker for the lifetime of an agent run. When the `message` tool sends `MEDIA:<path>`, that path is marked as delivered. If the agent subsequently calls `send_file` on the same path, the call is a **no-op** — the file is not sent again.

This prevents duplicate delivery in the common pattern where an agent reflexively calls both `write_file(deliver=true)` (which auto-sends via `message`) and `send_file` on the same file.

> Source: `internal/tools/send_file.go`, `internal/tools/message.go`



---

# MCP Integration

> Connect any Model Context Protocol server to GoClaw and instantly give your agents its full tool catalog.

## Overview

MCP (Model Context Protocol) is an open standard that lets AI tools expose capabilities over a well-defined interface. Instead of writing a custom tool for every external service, you point GoClaw at an MCP server and it automatically discovers and registers all the tools that server exposes.

GoClaw supports three transports:

| Transport | When to use |
|---|---|
| `stdio` | Local process spawned by GoClaw (e.g. a Python script) |
| `sse` | Remote HTTP server using Server-Sent Events |
| `streamable-http` | Remote HTTP server using the newer streamable-HTTP transport |

```mermaid
graph LR
    Agent --> Manager["MCP Manager"]
    Manager -->|stdio| LocalProcess["Local process\n(e.g. python mcp_server.py)"]
    Manager -->|sse| RemoteSSE["Remote SSE server\n(e.g. http://mcp:8000/sse)"]
    Manager -->|streamable-http| RemoteHTTP["Remote HTTP server\n(e.g. http://mcp:8000/mcp)"]
    Manager --> Registry["Tool Registry"]
    Registry --> Agent
```

GoClaw runs a health-check loop every 30 seconds. A server is only marked disconnected after **3 consecutive ping failures** — transient network blips do not trigger a reconnect. When a server does go down, GoClaw reconnects with exponential backoff (initial delay 2 s, up to 10 attempts, capped at 60 s between retries).

## Registering an MCP Server

### Option 1 — config file (shared across all agents)

Add an `mcp_servers` block under the `tools` key in your `config.json`:

```json
{
  "tools": {
    "mcp_servers": {
      "vnstock": {
        "transport": "streamable-http",
        "url": "http://vnstock-mcp:8000/mcp",
        "tool_prefix": "vnstock_",
        "timeout_sec": 30
      },
      "filesystem": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        "tool_prefix": "fs_",
        "timeout_sec": 60
      }
    }
  }
}
```

Config-based servers are loaded at startup and shared across all agents and users.

### Option 2 — Dashboard

Go to **Settings → MCP Servers → Add Server** and fill in the transport, URL or command, and optional prefix.

### Option 3 — HTTP API

```bash
curl -X POST http://localhost:8080/v1/mcp/servers \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vnstock",
    "transport": "streamable-http",
    "url": "http://vnstock-mcp:8000/mcp",
    "tool_prefix": "vnstock_",
    "timeout_sec": 30,
    "enabled": true
  }'
```

### Server config fields

| Field | Type | Description |
|---|---|---|
| `transport` | string | `stdio`, `sse`, or `streamable-http` |
| `command` | string | Executable path (stdio only) |
| `args` | string[] | Arguments for the command (stdio only) |
| `env` | object | Environment variables for the process (stdio only) |
| `url` | string | Server URL (sse / streamable-http only) |
| `headers` | object | HTTP headers (sse / streamable-http only) |
| `tool_prefix` | string | Prefix prepended to all tool names from this server |
| `timeout_sec` | int | Per-call timeout (default 60 s) |
| `enabled` | bool | Set to `false` to disable without removing |

## Tool Prefixes

Two MCP servers might both expose a tool called `search`. GoClaw prevents collisions by prepending the `tool_prefix` to every tool name from that server:

```
vnstock_   → vnstock_search, vnstock_get_price, vnstock_get_financials
filesystem_ → filesystem_read_file, filesystem_write_file
```

If no prefix is set and a name collision is detected, GoClaw logs a warning (`mcp.tool.name_collision`) and skips the duplicate tool. Always set a prefix when connecting servers from different providers.

## Search Mode (large tool sets)

When the total number of MCP tools across all servers exceeds **40**, GoClaw automatically enters **hybrid mode**: the first 40 tools remain registered inline in the tool registry, while the remainder are deferred to search mode. In hybrid mode, the built-in `mcp_tool_search` tool is also exposed so the agent can find and activate the deferred tools on demand.

This keeps the tool list manageable when connecting many MCP servers. There is no configuration required — the switch is automatic.

### Lazy activation

In hybrid mode, if an agent calls a deferred MCP tool directly by name (without searching first), GoClaw **auto-activates** it. The tool is resolved from the MCP server, registered on the fly, and executed — no extra search step needed. This enables compatibility with agents that already know the tool name from prior context.

## Per-Agent Access Grants

DB-backed servers (added via Dashboard or API) support per-agent and per-user access control. You can also restrict which tools an agent can call:

```bash
# Grant agent access to a server, allow only specific tools
curl -X POST http://localhost:8080/v1/mcp/grants \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "3f2a1b4c-...",
    "server_id": "a1b2c3d4-...",
    "tool_allow": ["vnstock_get_price", "vnstock_get_financials"],
    "tool_deny":  []
  }'
```

When `tool_allow` is non-empty, only those tools are visible to the agent. `tool_deny` removes specific tools even when the rest are allowed.

## Per-User Credential Servers (Deferred Loading)

Some MCP servers require per-user credentials (OAuth tokens, personal API keys). These servers are **not connected at startup**. Instead, GoClaw stores them during `LoadForAgent("")` as `userCredServers` and creates connections on a per-request basis via `pool.AcquireUser()` when a real user session arrives.

**How it works:**

1. At startup, `LoadForAgent("")` is called with no user context. Servers that `requireUserCreds` are stored in `userCredServers` — not connected.
2. When a user session starts, `LoadForAgent(userID)` is called. GoClaw resolves credentials for that specific user and connects the server for that session only.
3. The server and its tools are available only within that user's request context.

This means per-user credential servers are invisible in the global status endpoint but appear normally when accessed through a user session.

## Optional Tool Argument Stripping

LLMs often send empty strings or placeholder values (e.g. `""`, `"null"`, `"none"`, `"__OMIT__"`) for optional tool arguments instead of omitting them. This causes MCP servers to reject calls with invalid values (e.g. an empty string where a UUID is expected).

GoClaw automatically strips these values before forwarding the call. Required fields are always forwarded as-is. Optional fields with empty or placeholder values are removed from the call arguments.

No configuration required — stripping is always active for all MCP tool calls.

## Per-User Self-Service Access

Users can request access to an MCP server through the self-service portal. Requests are queued for admin approval. Once approved, the server is loaded for that user's sessions automatically via `LoadForAgent`.

## Checking Server Status

```bash
GET /v1/mcp/servers/status
```

Response:

```json
[
  {
    "name": "vnstock",
    "transport": "streamable-http",
    "connected": true,
    "tool_count": 12
  }
]
```

The `error` field is omitted when empty.

## Examples

### Add a stock data MCP server (docker-compose overlay)

```yaml
# docker-compose.vnstock-mcp.yml
services:
  vnstock-mcp:
    build:
      context: ./vnstock-mcp
    environment:
      - MCP_TRANSPORT=http
      - MCP_PORT=8000
      - MCP_HOST=0.0.0.0
      - VNSTOCK_API_KEY=${VNSTOCK_API_KEY}
    networks:
      - default
```

Then register it in `config.json`:

```json
{
  "tools": {
    "mcp_servers": {
      "vnstock": {
        "transport": "streamable-http",
        "url": "http://vnstock-mcp:8000/mcp",
        "tool_prefix": "vnstock_",
        "timeout_sec": 30
      }
    }
  }
}
```

Start the stack:

```bash
docker compose -f docker-compose.yml -f docker-compose.vnstock-mcp.yml up -d
```

Your agents can now call `vnstock_get_price`, `vnstock_get_financials`, etc.

### Local stdio server (Python)

```json
{
  "tools": {
    "mcp_servers": {
      "my-tools": {
        "transport": "stdio",
        "command": "python3",
        "args": ["/opt/mcp/my_tools_server.py"],
        "env": { "MY_API_KEY": "secret" },
        "tool_prefix": "mytools_"
      }
    }
  }
}
```

## Security: Prompt Injection Protection

MCP servers are external processes — a compromised or malicious server could attempt to inject instructions into the LLM by returning crafted tool results. GoClaw hardens against this automatically.

**How it works** (`internal/mcp/bridge_tool.go`):

1. **Marker sanitization** — Any `<<<EXTERNAL_UNTRUSTED_CONTENT>>>` markers already present in the result are replaced with `[[MARKER_SANITIZED]]` before wrapping.
2. **Content wrapping** — Every MCP tool result is wrapped in untrusted-content markers before being returned to the LLM:

```
<<<EXTERNAL_UNTRUSTED_CONTENT>>>
Source: MCP Server {server_name} / Tool {tool_name}


---

# Skills

> Package reusable knowledge into Markdown files and inject them into any agent's context automatically.

## Overview

A skill is a directory containing a `SKILL.md` file. When an agent runs, GoClaw reads the skill files that are in scope and injects their content into the system prompt under an `## Available Skills` section. The agent then uses that knowledge without you having to repeat it in every conversation.

Skills are useful for encoding recurring procedures, tool usage guides, domain knowledge, or coding conventions that the agent should always follow.

## SKILL.md Format

Each skill lives in its own directory. The directory name is the skill's **slug** — the unique identifier used for filtering and search.

```
~/.goclaw/skills/
└── code-reviewer/
    └── SKILL.md
```

A `SKILL.md` file has an optional YAML frontmatter block followed by the skill content:

```markdown

## How to Review Code

When asked to review code, always check:
1. **Security** — SQL injection, XSS, hardcoded secrets
2. **Error handling** — all errors returned or logged
3. **Tests** — new logic has corresponding test coverage

Use `{baseDir}` to reference files alongside this SKILL.md:
- Checklist: {baseDir}/review-checklist.md
```

The `{baseDir}` placeholder is replaced at load time with the absolute path to the skill directory, so you can reference companion files.

> **Multiline blocks**: YAML frontmatter supports multiline strings for `description` using the `|` block scalar. This is useful for longer skill descriptions without hitting YAML line limits.

**Frontmatter fields:**

| Field | Description |
|---|---|
| `name` | Human-readable display name (defaults to directory name) |
| `description` | One-line summary used by `skill_search` to match queries |

## 6-Tier Hierarchy

GoClaw loads skills from six locations in priority order. A skill in a higher-priority location overrides one with the same slug from a lower one:

| Priority | Location | Source label |
|---|---|---|
| 1 (highest) | `<workspace>/skills/` | `workspace` |
| 2 | `<workspace>/.agents/skills/` | `agents-project` |
| 3 | `~/.agents/skills/` | `agents-personal` |
| 4 | `~/.goclaw/skills/` | `global` |
| 5 | `~/.goclaw/skills-store/` (DB-seeded, versioned) | `managed` |
| 6 (lowest) | Built-in (bundled with binary) | `builtin` |

Skills uploaded via the Dashboard are stored in `~/.goclaw/skills-store/` using a versioned subdirectory structure (`<slug>/<version>/SKILL.md`). They act at the `managed` level — above builtin but below the four file-system tiers. The loader always serves the highest-numbered version for each slug.

**Precedence example:** if you have a `code-reviewer` skill in both `~/.goclaw/skills/` and `<workspace>/skills/`, the workspace version wins.

## Hot Reload

GoClaw watches all skill directories with `fsnotify`. When you create, modify, or delete a `SKILL.md`, changes are picked up within 500 ms — no restart required. The watcher bumps an internal version counter; agents compare their cached version on each request and reload skills if the counter changed.

```
# Drop a new skill in place — agents pick it up on the next request
mkdir ~/.goclaw/skills/my-new-skill
echo "---\nname: My Skill\ndescription: Does something useful.\n---\n\n## Instructions\n..." \
  > ~/.goclaw/skills/my-new-skill/SKILL.md
```

## Slash Command Activation

Instead of waiting for the agent to discover a skill via `skill_search`, you can activate one explicitly by starting your chat message with a slash command. This is enabled by default.

```
/code-reviewer review this PR
/use sql-style format these queries
/list-skills
/help code-reviewer
```

**Supported forms:**

| Command | What it does |
|---|---|
| `/<skill-slug> <your request>` | Activates the skill by slug (or display name) and treats the rest of the message as the skill's input |
| `/use <skill> <request>` | Same as above, explicit verb form (`/activate` also works) |
| `/list-skills` | Asks the agent to list all available skills |
| `/help <skill>` | Asks the agent to explain a skill and how to use it |

When a skill is activated, GoClaw loads its `SKILL.md` into the current turn and scopes the agent to that skill for the request.

**Matching rules:**

- **Exact match** wins first — the slug or display name (case-insensitive) is matched directly. `/code-reviewer` matches the `code-reviewer` skill.
- **Partial (prefix) matching** is opt-in (off by default). When enabled, `/code` matches `code-reviewer` if it is the only prefix match.
- **Ambiguity guard** — if two skills tie on match strength (same-length match), the command is treated as *not matched* rather than guessing.

**No match:** if the requested skill is not found, GoClaw runs a fuzzy similarity search (edit-distance, up to 3 suggestions) and asks the agent to tell you the skill was not found and suggest the closest available skills. This suggestion behavior is on by default. If no similar skill exists, the message is treated as a normal prompt.

**Configuration** (all optional):

| Config key | Env / system config | Default | Effect |
|---|---|---|---|
| `skills.slash_commands.enabled` | `skills.slash_commands.enabled` | `true` | Master toggle |
| `skills.slash_commands.prefix` | `skills.slash_commands.prefix` | `/` | Single-character trigger prefix |
| `skills.slash_commands.partial_matching` | `skills.slash_commands.partial_matching` | `false` | Allow prefix matching |
| `skills.slash_commands.suggest_not_found` | `skills.slash_commands.suggest_not_found` | `true` | Suggest alternatives on no match |

> Messages that look like file paths (containing `/`, `\`, or `.` in the first token, e.g. `/etc/hosts`) are **not** treated as slash commands and pass through unchanged.

## Uploading via Dashboard

Go to **Skills → Upload** and drop a ZIP file. The ZIP can contain a **single skill** or **multiple skills** in one archive:

```
# Single skill — SKILL.md at root
my-skill.zip
└── SKILL.md

# Single skill — wrapped in one directory
my-skill.zip
└── code-reviewer/
    ├── SKILL.md
    └── review-checklist.md

# Multi-skill ZIP — multiple skills in one upload
skills-bundle.zip
└── skills/
    ├── code-reviewer/
    │   ├── SKILL.md
    │   └── metadata.json
    └── sql-style/
        ├── SKILL.md
        └── metadata.json
```

Uploaded skills are stored in a versioned subdirectory structure under the managed skills directory (`~/.goclaw/skills-store/` by default):

```
~/.goclaw/skills-store/<slug>/<version>/SKILL.md
```

Metadata (name, description, visibility, grants) lives in PostgreSQL; file content lives on disk. GoClaw always serves the highest-numbered version. Old versions are kept for rollback.

Skills uploaded via the Dashboard start with **internal** visibility — immediately accessible to any agent or user you grant access to.

### Upload Size Limit

Skill ZIP uploads (Dashboard and `POST /v1/skills/import`) are capped by a configurable size limit. The default is **20 MB**, and the effective value is always clamped to the **1–500 MB** range.

The limit is resolved in this precedence order (highest first):

1. **Tenant override** — system config key `skills.max_upload_size_mb` (set per tenant)
2. **SKILL.md frontmatter** — a `max_upload_size_mb` field in the skill's frontmatter
3. **Gateway default** — `GOCLAW_SKILLS_MAX_UPLOAD_SIZE_MB` env var or `skills.max_upload_size_mb` in the config file (falls back to 20 MB)

```yaml
# Raise the limit for one skill via its SKILL.md frontmatter
---
name: large-skill
description: Ships large reference assets.
max_upload_size_mb: 100
---
```

```bash
# Set the gateway-wide default via environment variable
export GOCLAW_SKILLS_MAX_UPLOAD_SIZE_MB=128
```

Uploads exceeding the resolved limit are rejected with an error like `skill ZIP size 42.0 MB exceeds 20 MB limit`.

## Importing via API

The `POST /v1/skills/import` endpoint accepts the same ZIP format as the Dashboard upload and supports both single and multi-skill archives.

**Standard import (JSON response):**

```bash
curl -X POST http://localhost:8080/v1/skills/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@skills-bundle.zip"
```

Returns a `SkillsImportSummary` JSON object:

```json
{
  "skills_imported": 2,
  "skills_skipped": 0,
  "grants_applied": 3
}
```

**Streaming import with SSE progress (`?stream=true`):**

```bash
curl -X POST "http://localhost:8080/v1/skills/import?stream=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  -F "file=@skills-bundle.zip"
```

With `?stream=true`, the server sends Server-Sent Events (SSE) as each skill is processed:

```
event: progress
data: {"phase":"skill","status":"running","detail":"code-reviewer"}

event: progress
data: {"phase":"skill","status":"done","detail":"code-reviewer"}

event: complete
data: {"skills_imported":2,"skills_skipped":0,"grants_applied":3}
```

**Hash-based idempotency:** The upload endpoint uses a SHA-256 hash of the `SKILL.md` content for deduplication. If the same `SKILL.md` content is uploaded again (even packaged in a different ZIP), no new version is created — the existing version is kept unchanged. Only changes to the actual `SKILL.md` content trigger a new version.

> **Inline companion files via `skill_manage`:** Agents with skill evolution enabled can also create small text companion files inline (no ZIP) by passing a `files` object to the `skill_manage` tool — keyed by relative path, e.g. `references/guide.md`. Each inline text file is capped at **2 MB**, and the path validator rejects absolute paths, Windows drive paths (`C:\...`), null bytes, `..` traversal, `SKILL.md` overwrites, dotfiles/dotdirs, and system artifacts (e.g. `.git`). See [Agent Evolution](agent-evolution.md) for details.

## Selective Export & Download

You can export skills as a ZIP archive — either all skills or a hand-picked subset — from the Dashboard or the API.

**Preview before building** — `GET /v1/skills/export/preview` returns the counts that *would* be exported without building the archive, so the UI can show "N skills, M will be included" before you commit:

```bash
curl "http://localhost:8080/v1/skills/export/preview" \
  -H "Authorization: Bearer $TOKEN"
```

**Export selected skills** — pass specific skill IDs to export only those, plus an optional `include_system` flag to include bundled/system skills:

```bash
# Export two specific skills, excluding system skills
curl "http://localhost:8080/v1/skills/export?ids=SKILL_ID_1,SKILL_ID_2&include_system=false" \
  -H "Authorization: Bearer $TOKEN" -o skills-export.zip
```

For large exports, the server can build the archive asynchronously and stream Server-Sent Events as it works. On completion it returns a `download_url` pointing at a one-time token endpoint:

```
event: complete
data: {"download_url":"/v1/export/download/TOKEN"}
```

```bash
# Fetch the built archive with the returned token
curl "http://localhost:8080/v1/export/download/TOKEN" \
  -H "Authorization: Bearer $TOKEN" -o skills-export.zip
```

**Dashboard:** the **Skills** page has a bulk-select toolbar — check the skills you want, then **Export selected** to download just those.

## Access Mode & Effective Access

Beyond visibility levels, each skill has an **access mode** that controls how broadly it is reachable. Admins read and set it via the access endpoints:

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/skills/{id}/access` | Show the skill's access mode and grants |
| `PATCH` | `/v1/skills/{id}/access` | Set access mode (`private`, `internal`, or `public`) |
| `GET` | `/v1/skills/{id}/access/effective` | Explain effective access for one skill, given an agent and user |
| `GET` | `/v1/skills/access/effective` | Explain effective access across all skills for an agent and user |

```bash
# Set a skill's access mode to internal
curl -X PATCH "http://localhost:8080/v1/skills/{id}/access" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access_mode": "internal"}'

# Explain why an agent/user can or cannot reach a skill
curl "http://localhost:8080/v1/skills/{id}/access/effective?agent_id=AGENT_UUID&user_id=user@example.com" \
  -H "Authorization: Bearer $TOKEN"
```

### Per-Skill Dependency Endpoints

In addition to the gateway-wide rescan, you can inspect and manage dependencies for a single skill:

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/skills/{id}/dependencies` | Current dependency status for the skill |
| `POST` | `/v1/skills/{id}/dependencies/scan` | Re-scan declared and detected dependencies |
| `POST` | `/v1/skills/{id}/dependencies/check` | Check whether each dependency resolves at runtime |
| `POST` | `/v1/skills/{id}/dependencies/install` | Install missing dependencies (master tenant) |

## Runtime Environment

Skills that use Python or Node.js run inside a Docker container with pre-installed packages.

### Pre-installed Packages

| Category | Packages |
|---|---|
| Python | `pypdf`, `openpyxl`, `pandas`, `python-pptx`, `markitdown` |
| Node.js (global npm) | `docx`, `pptxgenjs` |
| System tools | `python3`, `nodejs`, `pandoc`, `gh` (GitHub CLI) |

### Writable Runtime Directories

The container root filesystem is read-only. Agents install additional packages to writable volume-backed directories:

```
/app/data/.runtime/
├── pip/         ← PIP_TARGET (Python packages)
├── pip-cache/   ← PIP_CACHE_DIR
└── npm-global/  ← NPM_CONFIG_PREFIX (Node.js packages)
```

Packages installed at runtime persist across tool calls within the same container lifecycle.

### Security Constraints

| Constraint | Detail |
|---|---|
| `read_only: true` | Container rootfs is immutable; only volumes are writable |
| `/tmp` is `noexec` | Cannot execute binaries from tmpfs |
| `cap_drop: ALL` | No privilege escalation |
| Exec deny patterns | Blocks `curl \| sh`, reverse shells, crypto miners |
| `.goclaw/` denied | Exec tool blocks access to `.goclaw/` except `.goclaw/skills-store/` |

### What Agents Can/Cannot Do

Agents **can**: run Python/Node scripts, install packages via `pip3 install` or `npm install -g`, access files in `/app/workspace/` — including `.uploads/` for current user uploads and `.media/` for legacy media refs.

Agents **cannot**: write to system paths, execute binaries from `/tmp`, run blocked shell patterns (network tools, reverse shells).

## Bundled Skills

GoClaw ships seven core skills bundled inside the Docker image at `/app/bundled-skills/`. They are lowest priority — user-uploaded skills override them by slug.

| Skill | Purpose |
|---|---|
| `pdf` | Read, create, merge, split PDFs |
| `xlsx` | Read, create, edit spreadsheets |
| `docx` | Read, create, edit Word documents |
| `pptx` | Read, create, edit presentations |
| `skill-creator` | Create new skills |
| `workspace-organizing` | Keep agent workspaces tidy and discoverable — enforces a purpose-based folder convention and runs memory/Vault/knowledge-graph discovery before writing files to avoid duplicates |
| `goclaw` | Operate, inspect, administer, and debug a GoClaw gateway through the `goclaw` CLI/runtime — CLI discovery, gateway health/config diagnostics, agents, skills, MCP/tools, runtime packages, credentials, traces, sessions, channels, providers, and cron/jobs. Always inspects the live `goclaw --help` output first because command availability is version-dependent. |

Bundled skills are seeded into PostgreSQL on every gateway startup (hash-tracked, no re-import if unchanged). They are tagged `is_system = true` and `visibility = 'public'`.

### Dependency System

GoClaw auto-detects and installs missing skill dependencies:

1. **Scanner** — statically analyzes `scripts/` subdirectory for Python (`import X`, `from X import`) and Node.js (`require('X')`, `import from 'X'`) imports
2. **Checker** — verifies each import resolves at runtime via subprocess (`python3 -c "import X"` / `node -e "require.resolve('X')"`)
3. **Installer** — installs by prefix:

| Prefix | Effect |
|--------|--------|
| `pip:name` | `pip3 install` (Python package) |
| `npm:name` | `npm install -g` (Node.js package) |
| `system:name` | `apk add` via pkg-helper (system package) |
| `github:owner/repo[@tag]` | GitHub Releases installer — admin-only, SHA256-verified, ELF-validated. Binary lands in `/app/data/.runtime/bin/` (on `$PATH`). |

Example SKILL.md frontmatter using `github:`:

```yaml
---
name: my-skill
description: Does things using ripgrep and gh CLI.
deps:
  - github:BurntSushi/ripgrep@14.1.0
  - github:cli/cli@v2.40.0
  - pip:requests
---
```

The `github:` installer fetches the release from GitHub Releases, auto-selects the `linux` + arch-matching asset (amd64 / arm64), verifies SHA256 if the publisher ships `checksums.txt`, validates ELF magic bytes, and extracts to `/app/data/.runtime/bin/`. If no `@tag` is specified, the latest release is used.

Dep checks run in a background goroutine at startup (non-blocking). Skills with missing deps are archived automatically; they are re-activated after deps are installed. You can also trigger a rescan via **Skills → Rescan Deps** in the Dashboard or `POST /v1/skills/rescan-deps`.

## Built-in Skill Tools

GoClaw provides three built-in tools that agents use to discover and activate skills at runtime.

### skill_search

Agents search skills using `skill_search`. The search uses a **BM25 index** built from each skill's name and description, with optional hybrid search (BM25 + vector embeddings) when an embedding provider is configured.

```
# The agent calls this tool internally — you don't call it directly
skill_search(query="how to review a pull request", max_results=5)
```

The tool returns ranked results with name, description, location path, and score. After receiving results, the agent calls `use_skill` then `read_file` to load the skill content.

The index is rebuilt whenever the loader's version counter is bumped (i.e., after any hot-reload event or startup).

### use_skill

A lightweight observability marker tool. The agent calls `use_skill` before reading a skill's file, so skill activation is visible in traces and real-time events. It does not load any content itself.

```
use_skill(name="code-reviewer")
# then:
read_file(path="/path/to/code-reviewer/SKILL.md")
```

### publish_skill

Agents can register a local skill directory into the system database using `publish_skill`. The directory must contain a `SKILL.md` with a `name` in its frontmatter. The skill is automatically granted to the calling agent after publishing.

```
publish_skill(path="./skills/my-skill")
```

The skill is stored with `private` visibility and auto-granted to the calling agent. Admins can later grant it to other agents or promote visibility via the Dashboard or API.

## Granting Skills to Agents (Managed Mode)

Skills published via `publish_skill` start with **private** visibility. Skills uploaded via the Dashboard start with **internal** visibility. Either way, you must **grant** a skill to an agent before it is injected into that agent's context.

### Via Dashboard

1. Go to **Skills** in the sidebar
2. Click the skill you want to grant
3. Under **Agent Grants**, select the agent and click **Grant**
4. The skill is now injected into that agent's context on the next request

To revoke, toggle off the agent in the grants list.

### Via API

Grant a skill to an agent:

```bash
curl -X POST http://localhost:8080/v1/skills/{id}/grants/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_UUID", "version": 1}'
```

To grant with manage rights (see [Agent-Manage Grants](#agent-manage-grants) below), add `"can_manage": true`:

```bash
curl -X POST http://localhost:8080/v1/skills/{id}/grants/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_UUID", "version": 1, "can_manage": true}'
```

List all agent grants for a skill:

```bash
curl http://localhost:8080/v1/skills/{id}/grants/agent \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json
{
  "grants": [
    {
      "agent_id": "019...",
      "agent_key": "my-agent",
      "display_name": "My Agent",
      "pinned_version": 1,
      "granted_by": "admin@example.com",
      "can_manage": false
    }
  ]
}
```

Revoke an agent grant:

```bash
curl -X DELETE http://localhost:8080/v1/skills/{id}/grants/agent/{agent_id} \
  -H "Authorization: Bearer $TOKEN"
```

Grant a skill to a specific user (so it appears in their agent sessions):

```bash
curl -X POST http://localhost:8080/v1/skills/{id}/grants/user \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user@example.com"}'
```

Revoke a user grant:

```bash
curl -X DELETE http://localhost:8080/v1/skills/{id}/grants/user/{user_id} \
  -H "Authorization: Bearer $TOKEN"
```

### Agent-Manage Grants

By default, only the skill owner and tenant admins can edit or delete a skill. The `can_manage` flag on `skill_agent_grants` lets you delegate that capability to a specific agent without promoting it to admin.

When `can_manage = true`, the grantee agent can:
- Update the skill's name, description, tags, and visibility via `PUT /v1/skills/{id}`
- Delete the skill via `DELETE /v1/skills/{id}`
- Publish new versions using the `skill_manage` tool inside conversations

**Tenant scope enforcement** — both the skill and the agent must belong to the same tenant. Grant writes that cross tenant boundaries are rejected at the store layer (`verifySkillGrantScope`). A cleanup migration (`000067`) removes any pre-existing cross-tenant rows from earlier versions.

**Visibility auto-promotion** — granting a `private` skill to any agent automatically promotes it to `internal` so the grantee can access it. Revoking the last agent grant demotes it back to `private` atomically.

### Tenant-Scoped Grant Isolation

In multi-tenant deployments, skill grant operations are tenant-scoped:

- `POST /v1/skills/{id}/grants/agent` verifies that the target agent belongs to the same tenant as the skill. Cross-tenant grant attempts return `404` ("agent not found") to avoid leaking tenant topology.
- System skills (`is_system = true`) bypass tenant filtering — they are accessible to all tenants.
- `GET /v1/skills/{id}/grants/agent` returns only grants within the requesting tenant's scope.

### Visibility Levels

| Level | Who can access |
|---|---|
| `private` | Only the skill owner (uploader) |
| `internal` | Agents and users explicitly granted access |
| `public` | All agents and users |

## Examples

### Workspace-scoped SQL style guide

```
my-project/
└── skills/
    └── sql-style/
        └── SKILL.md
```

```markdown
---
name: SQL Style Guide
description: Team conventions for writing PostgreSQL queries in this project.
---

## SQL Conventions

- Use `$1, $2` positional parameters — never string interpolation
- Always use `RETURNING id` on INSERT
- Table and column names: snake_case
- Never use `SELECT *` in application queries
```

### Global "be concise" reminder

```
~/.goclaw/skills/
└── concise-responses/
    └── SKILL.md
```

```markdown
---
name: Concise Responses
description: Keep all responses short, bullet-pointed, and actionable.
---

Always:
- Lead with the answer, not the explanation
- Use bullet points for lists of 3 or more items
- Keep code examples under 20 lines
```

## Agent Injection Thresholds

GoClaw decides whether to embed skills inline in the system prompt or fall back to `skill_search`:

| Condition | Mode |
|---|---|
| `≤ 40 skills` AND estimated tokens `≤ 5000` | **Inline** — skills injected as XML in system prompt |
| `> 40 skills` OR estimated tokens `> 5000` | **Search** — agent uses `skill_search` tool instead |

Token estimate: `(len(name) + len(description) + 10) / 4` per skill (~100–150 tokens each).

Disabled skills (`enabled = false`) are excluded from both inline and search injection.

### Listing Archived Skills

Skills with missing dependencies are set to `status = 'archived'` and are still visible in the Dashboard. You can list them via `GET /v1/skills?status=archived` or the `skills.list` WebSocket RPC method (which returns `enabled`, `status`, and `missing_deps` fields for each skill).

## Skill Evolution

When `skill_evolve` is enabled in agent config, agents gain a `skill_manage` tool that allows them to create, update, and version skills from within conversations — a learning loop where the agent improves its own knowledge base. When `skill_evolve` is **off** (the default), the `skill_manage` tool is hidden from the LLM's tool list entirely.

See [Agent Evolution](agent-evolution.md) for full details on the `skill_manage` tool and the evolution workflow.

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| Skill not appearing in agent | Wrong directory structure (SKILL.md not inside a subdirectory) | Ensure path is `<skills-dir>/<slug>/SKILL.md` |
| Changes not picked up | Watcher not started (non-Docker setups) | Restart GoClaw; verify `skills watcher started` in logs |
| Lower-priority skill used instead of yours | Name collision — slug exists at a higher tier | Use a unique slug, or place your skill at a higher-priority location |
| `skill_search` returns no results | Index not built yet (first request) or no description in frontmatter | Add a `description` to frontmatter; index rebuilds on next hot-reload |
| ZIP upload fails | No `SKILL.md` found in ZIP | Place `SKILL.md` at ZIP root, inside one top-level directory, or use the multi-skill `skills/<slug>/SKILL.md` layout |

## What's Next

- [MCP Integration](/mcp-integration) — connect external tool servers
- [Custom Tools](/custom-tools) — add shell-backed tools to your agents
- [Scheduling & Cron](/scheduling-cron) — run agents on a schedule



---

# Scheduling & Cron

> Trigger agent turns automatically — once, on a repeating interval, or on a cron expression.

## Overview

GoClaw's cron service lets you schedule any agent to run a message on a fixed schedule. Jobs are persisted to PostgreSQL, so they survive restarts. The scheduler checks for due jobs every second and executes them in parallel goroutines.

Three schedule types are available:

| Type | Field | Description |
|---|---|---|
| `at` | `atMs` | One-time execution at a specific Unix timestamp (ms) |
| `every` | `everyMs` | Repeating interval in milliseconds |
| `cron` | `expr` | Standard 5-field cron expression (parsed by gronx) |

One-time (`at`) jobs are automatically deleted after they run.

```mermaid
stateDiagram-v2
    [*] --> Active: job created / enabled
    Active --> Running: due time reached
    Running --> Active: reschedule (every / cron)
    Running --> Deleted: one-time (at) after run
    Active --> Paused: enabled set to false
    Paused --> Active: enabled set to true
```

## Creating a Job

### Via the Dashboard

Go to **Cron → New Job**, fill in the schedule, the message the agent should process, and (optionally) a delivery channel.

### Via the Gateway WebSocket API

GoClaw uses WebSocket RPC. Send a `cron.create` method call:

```json
{
  "method": "cron.create",
  "params": {
    "name": "daily-standup-summary",
    "schedule": {
      "kind": "cron",
      "expr": "0 9 * * 1-5",
      "tz": "Asia/Ho_Chi_Minh"
    },
    "message": "Summarize yesterday's GitHub activity and post a standup update.",
    "deliver": true,
    "channel": "telegram",
    "to": "123456789",
    "agentId": "3f2a1b4c-0000-0000-0000-000000000000"
  }
}
```

### Via the `cron` built-in tool (agent-created jobs)

Agents can schedule their own follow-up tasks during a conversation using the `cron` tool with `action: "add"`. GoClaw automatically strips leading tab indentation from the `description` field and validates parameters to prevent malformed job creation.

```json
{
  "action": "add",
  "job": {
    "name": "check-server-health",
    "schedule": { "kind": "every", "everyMs": 300000 },
    "message": "Check if the API server is responding and alert me if it's down."
  }
}
```

### Via the CLI

```bash
# List jobs (active only)
goclaw cron list

# List all jobs including disabled
goclaw cron list --all

# List as JSON
goclaw cron list --json

# Enable or disable a job
goclaw cron toggle <jobId> true
goclaw cron toggle <jobId> false

# Delete a job
goclaw cron delete <jobId>
```

## Job Fields

| Field | Type | Description |
|---|---|---|
| `name` | string | Slug label — lowercase letters, numbers, hyphens only (e.g. `daily-report`). Must be unique per agent and tenant — duplicate names are automatically deduplicated |
| `agentId` | string | Agent UUID to run the job (omit for default agent) |
| `enabled` | bool | `true` = active, `false` = paused |
| `schedule.kind` | string | `at`, `every`, or `cron` |
| `schedule.atMs` | int64 | Unix timestamp in ms (for `at`) |
| `schedule.everyMs` | int64 | Interval in ms (for `every`) |
| `schedule.expr` | string | 5-field cron expression (for `cron`) |
| `schedule.tz` | string | IANA timezone — applies to **all** schedule kinds (`at`, `every`, `cron`), not just cron expressions. Omit to use the gateway default timezone |
| `message` | string | Text the agent receives as its input |
| `stateless` | bool | Run without session history — saves tokens for simple scheduled tasks. Default `false` |
| `deliver` | bool | `true` = deliver result to a channel; `false` = agent processes silently. Auto-defaults to `true` when the job is created from a real channel (Telegram, etc.). Delivery is still suppressed if the output contains the `NO_REPLY` token — see [NO_REPLY suppression](#no_reply-suppression) |
| `channel` | string | Target channel: `telegram`, `discord`, etc. Auto-filled from context when `deliver` is `true` |
| `to` | string | Chat ID or recipient identifier. Auto-filled from context when `deliver` is `true` |
| `deleteAfterRun` | bool | Auto-set to `true` for `at` jobs; can be set manually on any job |
| `wakeHeartbeat` | bool | When `true`, triggers an immediate [Heartbeat](heartbeat.md) run after the cron job completes. Useful for jobs that should report status via the heartbeat system |

## Schedule Expressions

### `at` — run once at a specific time

```json
{
  "kind": "at",
  "atMs": 1741392000000
}
```

The job is deleted after it fires. If `atMs` is already in the past when the job is created, it will never run.

### `every` — repeating interval

```json
{ "kind": "every", "everyMs": 3600000 }
```

Common intervals:

| Expression | Interval |
|---|---|
| `60000` | Every minute |
| `300000` | Every 5 minutes |
| `3600000` | Every hour |
| `86400000` | Every 24 hours |

### `cron` — 5-field cron expression

```json
{ "kind": "cron", "expr": "30 8 * * *", "tz": "UTC" }
```

5-field format: `minute hour day-of-month month day-of-week`

| Expression | Meaning |
|---|---|
| `0 9 * * 1-5` | 09:00 on weekdays |
| `30 8 * * *` | 08:30 every day |
| `0 */4 * * *` | Every 4 hours |
| `0 0 1 * *` | Midnight on the 1st of each month |
| `*/15 * * * *` | Every 15 minutes |

Expressions are validated at creation time using [gronx](https://github.com/adhocore/gronx). Invalid expressions are rejected with an error.

## Managing Jobs

GoClaw exposes cron management via WebSocket RPC methods. The available methods are:

| Method | Description |
|---|---|
| `cron.list` | List jobs (`includeDisabled: true` to include disabled) |
| `cron.create` | Create a new job |
| `cron.update` | Update a job (`jobId` + `patch` object) |
| `cron.delete` | Delete a job (`jobId`) |
| `cron.toggle` | Enable or disable a job (`jobId` + `enabled: bool`) |
| `cron.run` | Trigger a job manually (`jobId` + `mode: "force"` or `"due"`) |
| `cron.runs` | View run history (`jobId`, `limit`, `offset`) |
| `cron.status` | Scheduler status (active job count, running flag) |

**Examples:**

```json
// Pause a job
{ "method": "cron.toggle", "params": { "jobId": "<id>", "enabled": false } }

// Update schedule
{ "method": "cron.update", "params": { "jobId": "<id>", "patch": { "schedule": { "kind": "cron", "expr": "0 10 * * *" } } } }

// Manual trigger (run regardless of schedule)
{ "method": "cron.run", "params": { "jobId": "<id>", "mode": "force" } }

// View run history (last 20 entries by default)
{ "method": "cron.runs", "params": { "jobId": "<id>", "limit": 20, "offset": 0 } }
```

## Job Lifecycle

- **Active** — `enabled: true`, `nextRunAtMs` is set; will fire when due.
- **Paused** — `enabled: false`, `nextRunAtMs` is cleared; skipped by the scheduler.
- **Running** — executing the agent turn; `nextRunAtMs` is cleared until execution completes to prevent duplicate runs.
- **Completed (one-time)** — `at` jobs are deleted from the store after firing.

The scheduler checks jobs every 1 second. Due jobs are dispatched in parallel goroutines. Run logs are persisted to the `cron_run_logs` PostgreSQL table and accessible via the `cron.runs` method.

Failed jobs record `lastStatus: "error"` and `lastError` with the message. The job stays enabled and will retry on its next scheduled tick (unless it was a one-time `at` job).

## NO_REPLY suppression

Even when a job is configured to deliver (`deliver: true` with a `channel` and `to`), GoClaw will **not** send the result to the channel if the agent's output contains the `NO_REPLY` token.

- The match is **whole-word** and **case-insensitive** (`NO_REPLY`, `no_reply`, etc.), so the token must stand on its own — it won't match when embedded inside a longer word.
- When suppressed, the run still completes and is logged; only the channel delivery is skipped (an info-level log records that delivery was suppressed).

This lets a scheduled agent decide at runtime that there is nothing worth sending — for example, a health check that only replies when something is wrong:

```json
{
  "name": "api-health-check",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "message": "Check https://api.example.com/health. If it returns 200, reply with exactly NO_REPLY. Otherwise describe what is wrong.",
  "deliver": true,
  "channel": "telegram",
  "to": "123456789"
}
```

The `NO_REPLY` token follows the same convention used across GoClaw — see [How GoClaw Works](../core-concepts/how-goclaw-works.md) and [Sessions & History](../core-concepts/sessions-and-history.md).

## Retry — Exponential Backoff

When a cron job execution fails, GoClaw automatically retries with exponential backoff before logging it as an error.

| Parameter | Default |
|-----------|---------|
| Max retries | 3 |
| Base delay | 2 seconds |
| Max delay | 30 seconds |
| Jitter | ±25% |

**Formula:** `delay = min(base × 2^attempt, max) ± 25% jitter`

Example sequence: fail → 2s → retry → fail → 4s → retry → fail → 8s → retry → fail → logged as error.

## Scheduler Lanes & Queue Behavior

GoClaw routes all requests — cron jobs, user chats, delegations — through named scheduler lanes with configurable concurrency.

### Lane defaults

| Lane | Concurrency | Purpose |
|------|:-----------:|---------|
| `main` | 30 | Primary user chat sessions |
| `subagent` | 50 | Sub-agents spawned by the main agent |
| `team` | 100 | Agent team/delegation executions |
| `cron` | 30 | Scheduled cron jobs |

All values are configurable via environment variables (`GOCLAW_LANE_MAIN`, `GOCLAW_LANE_SUBAGENT`, `GOCLAW_LANE_TEAM`, `GOCLAW_LANE_CRON`).

### Session queue defaults

Each session maintains its own message queue. When the queue is full, the oldest message is dropped to make room for the new one.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `mode` | `queue` | Queue mode (see below) |
| `cap` | 10 | Max messages in the queue |
| `drop` | `old` | Drop oldest on overflow |
| `debounce_ms` | 800 | Collapse rapid messages within this window |

### Queue modes

| Mode | Behavior |
|------|----------|
| `queue` | FIFO — messages wait until a run slot is available |
| `followup` | Same as `queue` — messages are queued as follow-ups |
| `interrupt` | Cancel the active run, drain the queue, start the new message immediately |

### Adaptive throttle

When a session's conversation history exceeds **60% of the context window**, the scheduler automatically reduces concurrency to 1 for that session. This prevents context window overflow during high-throughput periods.

### /stop and /stopall

`/stop` and `/stopall` commands are intercepted **before** the 800ms debouncer so they are never merged with an incoming user message.

| Command | Behavior |
|---------|----------|
| `/stop` | Cancel the oldest active task; others continue |
| `/stopall` | Cancel all active tasks and drain the queue |

## Examples

### Daily news briefing via Telegram

```json
{
  "name": "morning-briefing",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "Asia/Ho_Chi_Minh" },
  "message": "Give me a brief summary of today's tech news headlines.",
  "deliver": true,
  "channel": "telegram",
  "to": "123456789"
}
```

### Periodic health check (silent — agent decides whether to alert)

```json
{
  "name": "api-health-check",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "message": "Check https://api.example.com/health and alert me on Telegram if it returns a non-200 status.",
  "deliver": false
}
```

### One-time reminder

```json
{
  "name": "meeting-reminder",
  "schedule": { "kind": "at", "atMs": 1741564200000 },
  "message": "Remind me that the quarterly review meeting starts in 15 minutes.",
  "deliver": true,
  "channel": "telegram",
  "to": "123456789"
}
```

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| Job never runs | `enabled: false` or `atMs` is in the past | Check job state; re-enable or update schedule |
| `invalid cron expression` on create | Malformed expr (e.g. 6-field Quartz syntax) | Use standard 5-field cron |
| `invalid timezone` | Unknown IANA zone string | Use a valid zone from the IANA tz database, e.g. `America/New_York` |
| Job runs but agent gets no message | `message` field is empty | Set a non-empty `message` |
| `name` validation error | Name not a valid slug | Use lowercase letters, numbers, and hyphens only (e.g. `daily-report`) |
| Duplicate job name | Same `name` already exists for this agent and tenant | Job names must be unique per `(agent_id, tenant_id, name)` — each agent/tenant pair enforces this as a unique constraint (migration 047). Use a different name or update the existing job |
| Duplicate executions | Clock skew between restarts (edge case) | The scheduler clears `next_run_at` in the DB before dispatch; on restart, stale jobs are recomputed automatically |
| Run log is empty | Job hasn't fired yet | Trigger manually via `cron.run` method with `mode: "force"` |

## Evolution Cron (v3 Background Worker)

GoClaw runs an internal background cron for the v3 agent evolution engine. This is not a user-managed job — it starts automatically when the gateway starts.

| Cadence | Action |
|---------|--------|
| 1 minute after startup (warm-up) | Initial suggestion analysis for all evolution-enabled agents |
| Every 24 hours | Re-run suggestion analysis (`SuggestionEngine.Analyze`) for all active agents with `evolution_metrics: true` |
| Every 7 days | Evaluate applied suggestions; roll back if quality metrics regressed (`EvaluateApplied`) |

**How it works:**

1. On startup, `runEvolutionCron` starts as a background goroutine in `cmd/gateway_evolution_cron.go`
2. It lists all active agents and checks the `evolution_metrics` v3 flag on each
3. For eligible agents, `SuggestionEngine.Analyze` generates improvement suggestions based on conversation metrics
4. Weekly, `EvaluateApplied` checks applied suggestions against guardrail thresholds and auto-rolls back regressions

**To enable evolution for an agent**, set `evolution_metrics: true` in the agent's `other_config` via the dashboard. No config.json changes are needed.

> The evolution cron runs with a 5-minute per-cycle timeout. Errors for individual agents are logged at debug level and do not abort the cycle for other agents.

## What's Next

- [Heartbeat](heartbeat.md) — proactive periodic check-ins with smart suppression
- [Custom Tools](/custom-tools) — give agents shell commands to run during scheduled turns
- [Skills](/skills) — inject domain knowledge so scheduled agents are more effective
- [Sandbox](/sandbox) — isolate code execution during scheduled agent runs



---

# Heartbeat

> Proactive periodic check-ins — agents execute a configurable checklist on a timer and report results to your channels.

## Overview

Heartbeat is an application-level monitoring feature: your agent wakes up on a schedule, runs through a HEARTBEAT.md checklist, and delivers results to a messaging channel (Telegram, Discord, Feishu). If everything looks fine, the agent can suppress delivery entirely using a `HEARTBEAT_OK` token — keeping your channels quiet when there's nothing to report.

This is **not** a WebSocket keep-alive. It's a user-facing proactive monitoring system with smart suppression, active-hours windows, and per-heartbeat model overrides.

## Quick Setup

### Via the Dashboard

1. Open **Agent Detail** → **Heartbeat** tab
2. Click **Configure** (or **Setup** if not yet configured)
3. Set interval, delivery channel, and write your HEARTBEAT.md checklist
4. Click **Save** — the agent will run on schedule

### Via the agent tool

Agents can self-configure heartbeat during a conversation:

```json
{
  "action": "set",
  "enabled": true,
  "interval": 1800,
  "channel": "telegram",
  "chat_id": "-100123456789",
  "active_hours": "08:00-22:00",
  "timezone": "Asia/Ho_Chi_Minh"
}
```

## HEARTBEAT.md Checklist

HEARTBEAT.md is an agent context file that defines what the agent should do during each heartbeat run. It lives alongside your other context files (BOOTSTRAP.md, SKILLS.md, etc.).

**How to write one:**

- List concrete tasks using your agent's tools — not just reading the list back
- Use `HEARTBEAT_OK` at the end when all checks pass and there's nothing to deliver
- Keep it focused: short checklists run faster and cost less

**Example HEARTBEAT.md:**

```markdown
# Heartbeat Checklist

1. Check https://api.example.com/health — if non-200, alert immediately
2. Query the DB for any failed jobs in the last 30 minutes — summarize if any
3. If all clear, respond with: HEARTBEAT_OK
```

The agent receives your checklist in its system prompt with explicit instructions to execute the tasks using its tools, not just repeat the checklist text.

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `enabled` | bool | `false` | Master on/off switch |
| `interval_sec` | int | 1800 | Seconds between runs (minimum: 300) |
| `prompt` | string | — | Custom check-in message (default: "Execute your heartbeat checklist now.") |
| `provider_id` | UUID | — | LLM provider override for heartbeat runs |
| `model` | string | — | Model override (e.g. `gpt-4o-mini`) |
| `isolated_session` | bool | `true` | Fresh session per run, auto-deleted after |
| `light_context` | bool | `false` | Skip context files, inject only HEARTBEAT.md |
| `max_retries` | int | 2 | Retry attempts on failure (0–10, exponential backoff) |
| `active_hours_start` | string | — | Window start in `HH:MM` format |
| `active_hours_end` | string | — | Window end in `HH:MM` format (supports midnight wrap) |
| `timezone` | string | — | IANA timezone for active hours (default: UTC) |
| `channel` | string | — | Delivery channel: `telegram`, `discord`, `feishu` |
| `chat_id` | string | — | Target chat or group ID |
| `ack_max_chars` | int | — | Reserved for future threshold logic (not yet active) |

## Scheduling & Wake Modes

The heartbeat ticker polls for due agents every 30 seconds. There are four ways a heartbeat run is triggered:

| Mode | Trigger |
|---|---|
| **Ticker poll** | Background goroutine runs `ListDue(now)` every 30s |
| **Manual test** | "Test" button in Dashboard UI or `{"action": "test"}` agent tool call |
| **RPC test** | `heartbeat.test` WebSocket RPC call |
| **Cron wake** | Cron job with `wake_heartbeat: true` completes → triggers immediate run |

**Stagger mechanism:** When you first enable a heartbeat, the initial `next_run_at` is offset by a deterministic amount (FNV-1a hash of the agent UUID, capped at 10% of `interval_sec`). This prevents multiple agents enabled at the same time from all firing at once. Subsequent runs advance by a flat interval without stagger.

## Execution Flow

```mermaid
flowchart TD
    A[Ticker due] --> B{Active hours?}
    B -- outside window --> Z1[Skip: active_hours]
    B -- inside window --> C{Agent busy?}
    C -- has active sessions --> Z2[Skip: queue_busy\nno next_run_at advance]
    C -- idle --> D{HEARTBEAT.md?}
    D -- empty or missing --> Z3[Skip: empty_checklist]
    D -- found --> E[Emit 'running' event]
    E --> F[Build system prompt\nwith checklist]
    F --> G[Run agent loop\nmax_retries + 1 attempts]
    G -- all failed --> Z4[Log error, advance next_run_at]
    G -- success --> H{Contains HEARTBEAT_OK?}
    H -- yes --> I[Suppress: increment suppress_count]
    H -- no --> J[Deliver to channel/chatID]
```

**Steps:**

1. **Active hours filter** — If outside the configured window, skip and advance `next_run_at`
2. **Queue-aware check** — If agent has active chat sessions, skip *without* advancing `next_run_at` (retried on next 30s poll)
3. **Checklist load** — Reads HEARTBEAT.md from agent context files; skips if empty
4. **Emit event** — Broadcasts `heartbeat: running` to all WebSocket clients
5. **Build prompt** — Injects checklist + suppression rules into the agent's extra system prompt
6. **Run agent loop** — Exponential backoff: immediate → 1s → 2s → ... up to `max_retries + 1` total attempts
7. **Suppression check** — If response contains `HEARTBEAT_OK` anywhere, delivery is cancelled
8. **Deliver** — Publishes to the configured `channel` + `chat_id` via the message bus

## Smart Suppression

When the agent's response contains the token `HEARTBEAT_OK` anywhere, the **entire response is suppressed** — nothing is sent to the channel. This keeps your chat quiet during routine "all clear" runs.

**Use `HEARTBEAT_OK` when:**
- All monitoring checks passed
- No anomalies detected
- The checklist doesn't ask you to send content

**Do NOT use `HEARTBEAT_OK` when:**
- The checklist explicitly asks for a report, summary, joke, greeting, etc.
- Any check failed or needs attention

The `suppress_count` field tracks how often suppression fires, giving you a signal-to-noise ratio for your checklist quality.

## Provider & Model Override

You can run heartbeats on a cheaper model than your agent's default:

```json
{
  "action": "set",
  "provider_name": "openai",
  "model": "gpt-4o-mini"
}
```

This is applied only during heartbeat runs. Your agent's regular conversations continue using its configured model. The override is useful when heartbeat frequency is high and you want to manage costs.

## Light Context Mode

By default, the agent loads all its context files (BOOTSTRAP.md, SKILLS.md, INSTRUCTIONS.md, etc.) before each run. Enabling `light_context` skips all of them and injects only HEARTBEAT.md:

```json
{ "action": "set", "light_context": true }
```

This reduces context size, speeds up execution, and lowers token costs — ideal when the checklist is self-contained and doesn't rely on general agent instructions.

## Delivery Targets

The heartbeat delivers results to the `channel` + `chat_id` pair you configure. GoClaw can suggest targets automatically by inspecting your agent's session history:

- In the Dashboard → **Delivery** tab → click **Fetch targets**
- Via RPC: `heartbeat.targets` returns known `(channel, chatId, title, kind)` tuples

When an agent self-configures heartbeat using the `set` action from within a real channel conversation, the delivery target is auto-filled from the current conversation context.

## Agent Tool

The `heartbeat` built-in tool lets agents read and manage their own heartbeat configuration:

| Action | Requires Permission | Description |
|---|---|---|
| `status` | No | One-line status: enabled, interval, run counts, last/next times |
| `get` | No | Full configuration as JSON |
| `set` | Yes | Create or update config (upsert) |
| `toggle` | Yes | Enable or disable |
| `set_checklist` | Yes | Write HEARTBEAT.md content |
| `get_checklist` | No | Read HEARTBEAT.md content |
| `test` | No | Trigger an immediate run |
| `logs` | No | View paginated run history |

Permission for mutation actions (`set`, `toggle`, `set_checklist`) falls back to: deny list → allow list → agent owner → always allowed in system context (cron, subagent).

## RPC Methods

| Method | Description |
|---|---|
| `heartbeat.get` | Fetch heartbeat config for an agent |
| `heartbeat.set` | Create or update config (upsert) |
| `heartbeat.toggle` | Enable or disable (`agentId` + `enabled: bool`) |
| `heartbeat.test` | Trigger immediate run via wake channel |
| `heartbeat.logs` | Paginated run history (`limit`, `offset`) |
| `heartbeat.checklist.get` | Read HEARTBEAT.md content |
| `heartbeat.checklist.set` | Write HEARTBEAT.md content |
| `heartbeat.targets` | List known delivery targets from session history |

## Dashboard UI

**HeartbeatCard** (Agent Detail → overview) — Quick status overview: enabled toggle, interval, active hours, delivery target, model override badge, last run time, next run countdown, run/suppress counts, and last error.

**HeartbeatConfigDialog** — Five sections:
1. **Basic** — Enable switch, interval slider (5–300 min), custom prompt
2. **Schedule** — Active hours start/end (HH:MM), timezone selector
3. **Delivery** — Channel dropdown, chat ID, fetch-targets button
4. **Model & Context** — Provider/model selectors, isolated session toggle, light context toggle, max retries
5. **Checklist** — HEARTBEAT.md editor with character count, load/save buttons

**HeartbeatLogsDialog** — Paginated run history table: timestamp, status badge (ok / suppressed / error / skipped), duration, token usage, summary or error text.

## Heartbeat vs Cron

| Aspect | Heartbeat | Cron |
|---|---|---|
| Purpose | Health monitoring + proactive check-in | General-purpose scheduled tasks |
| Schedule types | Fixed interval only | `at`, `every`, `cron` (5-field expr) |
| Minimum interval | 300 seconds | No minimum |
| Checklist source | HEARTBEAT.md context file | `message` field in job |
| Suppression | `HEARTBEAT_OK` token | None |
| Queue-aware | Skips if agent busy (no advance) | Runs regardless |
| Model override | Configurable per-heartbeat | Not available |
| Light context | Configurable | Not available |
| Active hours | Built-in HH:MM + timezone | Not built-in |
| Cardinality | One per agent | Many per agent |

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| Heartbeat never fires | `enabled: false` or no `next_run_at` | Enable via Dashboard or `{"action": "toggle", "enabled": true}` |
| Runs but nothing delivered | `HEARTBEAT_OK` in all responses | Check checklist logic; use HEARTBEAT_OK only when truly silent |
| Skipped every time | Agent is always busy | Heartbeat waits for idle; reduce user conversation load or check session leaks |
| Outside active hours | `active_hours` window misconfigured | Verify `timezone` matches your IANA zone and HH:MM values |
| `interval_sec < 300` error | Minimum is 5 minutes | Set `interval_sec` to 300 or higher |
| No delivery targets | No session history for agent | Start a conversation in the target channel first; targets are auto-discovered |
| Error status, no detail | All retries failed | Check `heartbeat.logs` for `error` field; verify tools and provider are reachable |

## What's Next

- [Scheduling & Cron](scheduling-cron.md) — general-purpose scheduled tasks and cron expressions
- [Custom Tools](custom-tools.md) — give your agent shell commands and APIs to call during heartbeat runs
- [Sandbox](sandbox.md) — isolate code execution during agent runs



---

# Sandbox

> Run agent shell commands inside an isolated Docker container so untrusted code never touches your host.

## Overview

When sandbox mode is enabled, every tool call that touches the filesystem or runs a command (`exec`, `read_file`, `write_file`, `list_files`, `edit`) is routed into a Docker container instead of running directly on the host. The container is ephemeral, network-isolated, and heavily restricted by default — dropped capabilities, read-only root filesystem, tmpfs for `/tmp`, and a 512 MB memory cap.

If Docker is unavailable at runtime, GoClaw returns an error and refuses to execute — it will **not** fall back to unsandboxed host execution.

```mermaid
graph LR
    Agent -->|exec / read_file / write_file\nlist_files / edit| Tools
    Tools -->|sandbox enabled| DockerManager
    DockerManager -->|Get or Create| Container["Docker Container\ngoclaw-sbx-*"]
    Container -->|docker exec| Command
    Command -->|stdout/stderr| Tools
    Tools -->|result| Agent
    Tools -->|Docker unavailable| Error["Error\n(sandbox required)"]
```

## Sandbox Modes

Set `GOCLAW_SANDBOX_MODE` (or `agents.defaults.sandbox.mode` in config) to one of:

| Mode | Which agents are sandboxed |
|---|---|
| `off` | None — all commands run on host (default) |
| `non-main` | All agents except `main` and `default` |
| `all` | Every agent |

## Container Scope

Scope controls how containers are reused across requests:

| Scope | Container lifetime | Best for |
|---|---|---|
| `session` | One container per session | Maximum isolation (default) |
| `agent` | One container shared across all sessions for an agent | Persistent state within an agent |
| `shared` | One container for all agents | Lowest overhead |

## Default Security Profile

Out of the box, every sandbox container runs with:

| Setting | Value |
|---|---|
| Root filesystem | Read-only (`--read-only`) |
| Capabilities | All dropped (`--cap-drop ALL`) |
| New privileges | Blocked (`--security-opt no-new-privileges`) |
| tmpfs mounts | `/tmp`, `/var/tmp`, `/run` |
| Network | Disabled (`--network none`) |
| Memory limit | 512 MB |
| CPUs | 1.0 |
| Execution timeout | 300 seconds |
| Max output | 1 MB (stdout + stderr combined) |
| Container prefix | `goclaw-sbx-` |
| Working directory | `/workspace` |

If a command produces more than 1 MB of output, the output is truncated and `...[output truncated]` is appended.

## Configuration

All settings can be provided as environment variables or in `config.json` under `agents.defaults.sandbox`.

### Environment variables

```bash
GOCLAW_SANDBOX_MODE=all
GOCLAW_SANDBOX_IMAGE=goclaw-sandbox:bookworm-slim
GOCLAW_SANDBOX_WORKSPACE_ACCESS=rw   # none | ro | rw
GOCLAW_SANDBOX_SCOPE=session         # session | agent | shared
GOCLAW_SANDBOX_MEMORY_MB=512
GOCLAW_SANDBOX_CPUS=1.0
GOCLAW_SANDBOX_TIMEOUT_SEC=300
GOCLAW_SANDBOX_NETWORK=false
```

### config.json

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "image": "goclaw-sandbox:bookworm-slim",
        "workspace_access": "rw",
        "scope": "session",
        "memory_mb": 512,
        "cpus": 1.0,
        "timeout_sec": 300,
        "network_enabled": false,
        "read_only_root": true,
        "max_output_bytes": 1048576,
        "idle_hours": 24,
        "max_age_days": 7,
        "prune_interval_min": 5
      }
    }
  }
}
```

### Full config reference

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `off` | `off`, `non-main`, or `all` |
| `image` | string | `goclaw-sandbox:bookworm-slim` | Docker image to use |
| `workspace_access` | string | `rw` | Mount workspace as `none`, `ro`, or `rw` |
| `scope` | string | `session` | Container reuse: `session`, `agent`, or `shared` |
| `memory_mb` | int | 512 | Memory limit in MB |
| `cpus` | float | 1.0 | CPU quota |
| `timeout_sec` | int | 300 | Per-command timeout in seconds |
| `network_enabled` | bool | false | Enable container networking |
| `read_only_root` | bool | true | Mount root filesystem read-only |
| `tmpfs_size_mb` | int | 0 | Default size for tmpfs mounts (0 = Docker default) |
| `user` | string | — | Container user, e.g. `1000:1000` or `nobody` |
| `max_output_bytes` | int | 1048576 | Max stdout+stderr capture per exec (1 MB) |
| `setup_command` | string | — | Shell command run once after container creation |
| `env` | object | — | Extra environment variables injected into the container |
| `idle_hours` | int | 24 | Prune containers idle longer than N hours |
| `max_age_days` | int | 7 | Prune containers older than N days |
| `prune_interval_min` | int | 5 | Background prune check interval (minutes) |

Security hardening defaults (`--cap-drop ALL`, `--tmpfs /tmp:/var/tmp:/run`, `--security-opt no-new-privileges`) are applied automatically and are not overridable via config.

## Workspace Access

The workspace directory is mounted at `/workspace` inside the container:

- `none` — no filesystem mount; container has no access to your project files
- `ro` — read-only mount; agent can read files but cannot write
- `rw` — read-write mount (default); agent can read and write project files

## Container Lifecycle

1. **Creation** — on first exec call for a scope key, `docker run -d ... sleep infinity` starts a long-lived container.
2. **Execution** — each command runs via `docker exec` inside the running container.
3. **Pruning** — a background goroutine checks every `prune_interval_min` minutes and destroys containers that have been idle longer than `idle_hours` or exist longer than `max_age_days`.
4. **Destruction** — `docker rm -f <id>` is called on pruning, session end, or `ReleaseAll` at shutdown.

Container names follow the pattern `goclaw-sbx-<sanitized-scope-key>`, where the scope key is derived from the session key, agent ID, or `"shared"` depending on the configured scope.

## Setup with docker-compose

Build the sandbox image first:

```bash
docker build -t goclaw-sandbox:bookworm-slim -f Dockerfile.sandbox .
```

Then add the sandbox overlay to your compose command:

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.sandbox.yml \
  up
```

The `docker-compose.sandbox.yml` overlay mounts the Docker socket and sets sandbox environment variables:

```yaml
services:
  goclaw:
    build:
      args:
        ENABLE_SANDBOX: "true"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - GOCLAW_SANDBOX_MODE=all
      - GOCLAW_SANDBOX_IMAGE=goclaw-sandbox:bookworm-slim
      - GOCLAW_SANDBOX_WORKSPACE_ACCESS=rw
      - GOCLAW_SANDBOX_SCOPE=session
      - GOCLAW_SANDBOX_MEMORY_MB=512
      - GOCLAW_SANDBOX_CPUS=1.0
      - GOCLAW_SANDBOX_TIMEOUT_SEC=300
      - GOCLAW_SANDBOX_NETWORK=false
    # Allow Docker socket access from the goclaw container
    cap_drop: []
    cap_add:
      - NET_BIND_SERVICE
    security_opt: []
    group_add:
      - ${DOCKER_GID:-999}
```

> **Security note:** Mounting the Docker socket gives the GoClaw container control over the host Docker daemon. Only use sandbox mode in environments where you trust the GoClaw process itself.

## Examples

### Sandbox only sub-agents, not the main agent

```bash
GOCLAW_SANDBOX_MODE=non-main
```

The `main` and `default` agents run commands on the host. All other agents (sub-agents, specialized workers) are sandboxed.

### Read-only workspace with custom setup

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "workspace_access": "ro",
        "setup_command": "pip install -q pandas numpy",
        "memory_mb": 1024,
        "timeout_sec": 120
      }
    }
  }
}
```

The `setup_command` runs once after the container is created. Use it to pre-install dependencies so they are available on every subsequent `exec`.

### Check active sandbox containers

GoClaw does not expose a public HTTP endpoint for sandbox stats. You can inspect running containers directly with Docker:

```bash
docker ps --filter "label=goclaw.sandbox=true"
```

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| `docker not available` in logs | Docker daemon not running or socket not mounted | Start Docker; ensure socket is mounted in compose |
| Commands fail with sandbox error | Docker unavailable at exec time | Start Docker; ensure socket is mounted in compose; sandbox mode does not fall back to host |
| `docker run failed` on container creation | Image not found or insufficient permissions | Build the sandbox image; check `DOCKER_GID` |
| Output truncated at 1 MB | Command produced very large output | Increase `max_output_bytes` or pipe output to a file |
| Container not cleaned up after session | Pruner not running or `idle_hours` too high | Lower `idle_hours`; check `sandbox pruning started` in logs |
| Write fails inside container | `workspace_access: ro` or `read_only_root: true` with no tmpfs | Switch to `rw` or add a tmpfs mount for the target path |

## Team-Root Workspace Boundaries

When an agent runs in team-root mode (part of an agent team), it has **read access** to peer-chat workspaces across the team. However, read-allowed and write-allowed paths are kept separate:

| Operation | Path set used |
|---|---|
| `read_file`, `list_files` | Read-allowed — includes team root and peer-chat workspaces |
| `write_file`, `edit` | Write-allowed — restricted to the agent's own chat workspace only |
| `exec` / `shell` | Write-allowed — cwd resolution uses the more restrictive write-allowed prefixes |

This asymmetry prevents a team-root agent from mutating peer-chat workspaces even though it can read them. Absolute paths in shell commands are also bounded by the write-allowed prefix set, closing the path that allowed cross-chat mutations via `cd` or absolute argument injection.

> **Note:** This workspace boundary applies regardless of sandbox mode. Sandbox mode controls whether commands run inside Docker; team-root path restrictions are enforced at the tool layer before Docker is involved.

## What's Next

- [Custom Tools](/custom-tools) — define shell tools that also benefit from sandbox isolation
- [Exec Approval](/exec-approval) — require human approval before any command runs, sandboxed or not
- [Scheduling & Cron](/scheduling-cron) — run sandboxed agent turns on a schedule



---

# Media Generation

> Generate images, videos, and audio directly from your agents — with automatic provider fallback chains.

## Overview

GoClaw includes three built-in media generation tools: `create_image`, `create_video`, and `create_audio`. Each tool uses a **provider chain** — a prioritized list of AI providers that GoClaw tries in order. If the first provider fails or times out, it automatically falls back to the next one.

Generated files are saved to `workspace/generated/{YYYY-MM-DD}/` and returned as `MEDIA:` paths that channels render natively (inline images, video players, audio messages).

Generated files are verified after writing — if the file doesn't exist on disk, the tool reports an error instead of returning a broken path.


## Video Generation

**Tool:** `create_video`

**Default provider chain:** Gemini → MiniMax → OpenRouter

**Default models:** Gemini `veo-3.1-lite-generate-preview`, MiniMax `MiniMax-Hailuo-2.3`, OpenRouter `google/veo-3.1-lite-generate-preview`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | Text description of the video |
| `duration` | int | `8` | Duration in seconds: `4`, `6`, or `8` |
| `aspect_ratio` | string | `16:9` | `16:9` or `9:16` |
| `image_path` | string | — | Path to a workspace image to use as starting frame (image-to-video). Omit for text-to-video. Supported formats: PNG, JPEG, WebP, GIF. Max 20 MB. |
| `filename_hint` | string | — | Short descriptive filename without extension (e.g. `cat-playing-piano`) |

### Image-to-Video

Provide an `image_path` to generate a video starting from a reference image. The image is encoded as base64 and sent to the provider. When using image-to-video mode, duration is fixed at **8 seconds** (API constraint).

**Example agent prompt:** *"Animate this product photo with a slow zoom and subtle lighting changes"* (with `image_path` pointing to a workspace image)

> **Note:** Not all providers support image-to-video. Gemini (Veo 3.1 Lite) supports it natively. Unsupported providers in the chain are skipped automatically.

Video generation is slow — both Gemini and MiniMax poll up to ~6 minutes. The timeout per provider defaults to 120 seconds but can be increased via chain settings.

---

## Audio Generation

**Tool:** `create_audio`

**Default provider:** MiniMax (music, model `music-2.5+`), ElevenLabs (sound effects)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | Description or lyrics |
| `type` | string | `music` | `music` or `sound_effect` |
| `duration` | int | — | Duration in seconds — applies to sound effects only; music length is determined by lyrics length |
| `lyrics` | string | — | Lyrics for music generation. Use `[Verse]`, `[Chorus]` tags |
| `instrumental` | bool | `false` | Instrumental only (no vocals) |
| `provider` | string | — | Force a specific provider (e.g. `minimax`) |

- **Sound effects** route directly to ElevenLabs (max 30 seconds)
- **Music** uses MiniMax as the default provider with a 300-second timeout. Duration is controlled by lyrics length, not the `duration` parameter

---

## Native Image Generation (Codex + OpenAI-compat)

Codex and OpenAI-compatible providers support **native** image generation — an `image_generation` tool object is attached directly to the LLM request rather than going through the `create_image` provider chain.

### Tri-Level Gate

All three conditions must be satisfied for `image_generation` to activate:

| Gate | Source | Default |
|------|--------|---------|
| Provider capability (`ProviderCapabilities.ImageGeneration`) | Auto-set `true` for Codex and OpenAI-compat | — |
| `AgentConfig.AllowImageGeneration` | `other_config.allow_image_generation` in agent config | `true` |
| Header opt-out | Client sends `x-goclaw-no-image-gen` to disable per-request | not sent = allowed |

To disable native image generation for a specific agent:

```json
{
  "other_config": {
    "allow_image_generation": false
  }
}
```

To opt out per-request, the client sends the header:

```
x-goclaw-no-image-gen: 1
```

### Partial-Image Streaming

During image generation, Codex emits `response.image_generation_call.partial_image` events over the SSE stream. GoClaw surfaces these events so clients can display incremental previews before the final image is complete.

### Storage and Metadata

Image files are saved to `{workspace}/media/{sha256}.{ext}` (e.g. `media/a3f7bc12.png`). For PNG files, GoClaw embeds a tEXt metadata chunk immediately before IEND:

| Chunk key | Value |
|-----------|-------|
| `Description` | User prompt |
| `Software` | `goclaw` |

This metadata supports audit and prompt traceability directly from the image file.

### Codex Pool Routing

When a Codex pool is configured, image generation requests go through the `create_image` chain with a **per-modality round-robin counter** — the chat counter and image counter operate independently. This prevents image generation from skewing the chat load distribution.

> Source: `internal/providers/codex_native_image.go`, `internal/providers/openai_image_url.go`, `internal/agent/media.go`, `internal/agent/png_metadata.go`, `internal/providers/capabilities.go`

---

## Customizing the Provider Chain

Override the default chain per agent via `builtin_tools.settings` in the agent config:

```json
{
  "builtin_tools": {
    "settings": {
      "create_image": {
        "providers": [
          {
            "provider": "openai",
            "model": "gpt-image-1",
            "enabled": true,
            "timeout": 60,
            "max_retries": 2
          },
          {
            "provider": "minimax",
            "enabled": true,
            "timeout": 30
          }
        ]
      }
    }
  }
}
```

**Chain fields:**

| Field | Default | Description |
|-------|---------|-------------|
| `provider` | — | Provider name (must have API key configured) |
| `model` | auto | Model override |
| `enabled` | `true` | Skip this entry if `false` |
| `timeout` | `120` | Timeout per attempt in seconds |
| `max_retries` | `2` | Retries before moving to next provider |

The chain executes sequentially — first success wins, last error is returned if all fail.

---

## Image Analysis (read_image)

The `read_image` tool can be configured with a dedicated vision provider chain. When configured, images are routed to the vision provider instead of being attached inline to the main LLM — useful when your main model lacks vision capability or you want a specialized model for image analysis.

Supports the same chain format as `create_*` tools:

```json
{
  "builtin_tools": {
    "settings": {
      "read_image": {
        "providers": [
          { "provider": "gemini", "model": "gemini-2.5-flash", "enabled": true },
          { "provider": "openai", "model": "gpt-4o", "enabled": true }
        ]
      }
    }
  }
}
```

Also supports the legacy flat format:

```json
{
  "builtin_tools": {
    "settings": {
      "read_image": {
        "provider": "gemini"
      }
    }
  }
}
```

If no `read_image` chain is configured, images are attached inline to the main LLM as usual.

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | What you want to know about the image(s) |
| `path` | string | — | Optional path to an image in the workspace (generated images or attachments) |
| `url` | string | — | Optional URL to an image hosted online |

`path` and `url` are **mutually exclusive** — passing both returns an error. If neither is given, the tool analyzes images already attached to the conversation.

> **Provider note:** Anthropic and `claude-cli` providers cannot analyze images directly from a URL — they require base64-encoded image data. If a URL-only image is routed to one of them, that provider errors and the chain falls back to the next provider. Gemini, OpenRouter, and DashScope accept image URLs directly. URLs are SSRF-validated before any fetch.

---

## Video Analysis (read_video)

The `read_video` tool analyzes video files using a video-capable provider chain (Gemini → OpenRouter by default). Use it when the conversation contains `<media:video>` tags, or point it at a workspace file or a hosted URL.

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | What to analyze — e.g. "Summarize the key scenes", "What text appears on screen?" |
| `media_id` | string | — | Optional specific `media_id` from a `<media:video>` tag. If omitted, uses the most recent video |
| `url` | string | — | Optional URL to a video file hosted online |

`media_id` and `url` are **mutually exclusive**. Local video files are capped at **100 MB**.

> **URL streaming:** For video URLs, GoClaw pipes the stream from the URL through the **Gemini File API** rather than downloading the whole file locally first. URLs are SSRF-validated and the resolved IP is pinned for the upload. At the provider layer, image and video parts are now distinct media-content types (`ImageContent` vs `VideoContent`).

The same chain-override format as `create_*` and `read_image` applies under `builtin_tools.settings.read_video`.

---

## Document Analysis (read_document)

The `read_document` tool extracts and analyzes documents — **PDF, DOCX, and images of documents** — using a document-capable provider chain (Gemini → Anthropic → claude-cli → OpenRouter → DashScope by default).

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | What to analyze — e.g. "Extract all tables", "What does page 3 say?" |
| `media_id` | string | — | Optional specific `media_id` from a `<media:document>` tag |
| `path` | string | — | Optional file path from a `<media:document path="...">` tag |

Unlike `read_image` and `read_video`, `read_document` has **no** `url` parameter. Plain-text formats (JSON, CSV, Markdown, HTML, etc.) are returned directly without an LLM call. Files are capped at **20 MB**.

### Local-First Extraction (opt-in)

By default, documents go straight to the cloud vision chain. You can opt into local extraction that runs `pdftotext` (PDF) and `pandoc --sandbox` (DOCX) on the host *before* any cloud call, via the `document_parser` config block:

```json
{
  "local_first": false,
  "max_pages": 200,
  "timeout_sec": 30,
  "min_text_len": 16
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `local_first` | `false` | Enable local extraction. Requires `pdftotext`/`pandoc` on PATH — present in the `full` Docker variant or builds with `ENABLE_FULL_SKILLS=true` |
| `max_pages` | `200` | PDF page limit; passed to `pdftotext -l` |
| `timeout_sec` | `30` | Per-extraction timeout; the process group is killed on timeout |
| `min_text_len` | `16` | Minimum characters (after trim) for a successful extraction; shorter output triggers cloud fallback |

Config is captured at startup (not hot-reloaded); binary availability is re-checked per call, so a runtime install is detected without a restart. Any miss — disabled, unsupported MIME, missing binary, timeout, or too-little text (e.g. a scanned image-only PDF) — falls back transparently to the cloud vision chain. PDF extraction uses `pdftotext -l <max_pages>`; DOCX uses `pandoc --sandbox` so an untrusted document cannot fetch remote resources during conversion.

---

## Required API Keys

Media generation uses your existing provider API keys. Make sure the relevant providers are configured:

| Provider | Used for | Config location |
|----------|----------|-----------------|
| OpenAI | Image, Video | `providers` section |
| OpenRouter | Image, Video | `providers` section |
| Gemini | Image, Video | `providers` section |
| MiniMax | Image, Video, Audio | `providers` section |
| DashScope | Image | `providers` section |
| ElevenLabs | Audio (sound effects) | `tts.providers.elevenlabs` |

---

## File Size Limit

Downloaded media files are capped at **200 MB**. Files exceeding this limit will fail.

---

## What's Next

- [TTS & Voice](/tts-voice) — Text-to-speech for agent replies
- [Custom Tools](/custom-tools) — Build your own tools
- [Provider Overview](/providers-overview) — Configure API keys



---

# TTS Voice

> Add voice replies to your agents — pick from five providers and control exactly when audio fires.

## Overview

GoClaw's TTS system converts agent text replies into audio and delivers them as voice messages on supported channels (e.g. Telegram voice bubbles). You configure a primary provider, set an auto-apply mode, and GoClaw handles the rest — stripping markdown, truncating long text, and choosing the right audio format per channel.

Five providers are available:

| Provider | Key | Requires |
|----------|-----|---------|
| OpenAI | `openai` | API key |
| ElevenLabs | `elevenlabs` | API key |
| Microsoft Edge TTS | `edge` | `edge-tts` CLI (free) — always available as fallback |
| MiniMax | `minimax` | API key + Group ID |
| Google Gemini TTS | `gemini` | API key |


## Provider Setup

### OpenAI

```json
{
  "tts": {
    "provider": "openai",
    "auto": "inbound",
    "openai": {
      "api_key": "sk-...",
      "model": "gpt-4o-mini-tts",
      "voice": "alloy"
    }
  }
}
```

Available voices: `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, `verse`, `marin`, `cedar`. Note: `ballad`, `verse`, `marin`, `cedar` are only compatible with `gpt-4o-mini-tts`.

Supported models: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts` (default).

#### OpenAI Advanced Params

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `speed` | range | 1.0 | 0.25–4.0; agent-overridable |
| `response_format` | enum | `mp3` | mp3, opus, aac, flac, wav, pcm |
| `instructions` | text | — | Style prompt; `gpt-4o-mini-tts` only (advanced) |

---

### ElevenLabs

```json
{
  "tts": {
    "provider": "elevenlabs",
    "auto": "always",
    "elevenlabs": {
      "api_key": "xi-...",
      "voice_id": "pMsXgVXv3BLzUgSXRplE",
      "model_id": "eleven_multilingual_v2"
    }
  }
}
```

Find voice IDs in your [ElevenLabs voice library](https://elevenlabs.io/voice-library). Default model: `eleven_multilingual_v2`.

#### ElevenLabs Model Variants

| Model ID | Characteristic | Best For |
|----------|---------------|---------|
| `eleven_v3` | Latest flagship (Nov 2025), highest quality | Premium voice, complex speech |
| `eleven_multilingual_v2` | High-quality, 29 languages | Default; multilingual content |
| `eleven_turbo_v2_5` | Cost-optimized, fast | High-volume, budget-conscious |
| `eleven_flash_v2_5` | Lowest latency, 32 languages | Real-time / interactive use |

Only these four model IDs are accepted — unknown IDs are rejected at the gateway boundary.

#### ElevenLabs Advanced Params

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `voice_settings.stability` | range | 0.5 | 0–1; voice consistency |
| `voice_settings.similarity_boost` | range | 0.75 | 0–1; closeness to original |
| `voice_settings.style` | range | 0.0 | 0–1; agent-overridable as `style` |
| `voice_settings.use_speaker_boost` | boolean | true | — |
| `voice_settings.speed` | range | 1.0 | 0.7–1.2; agent-overridable as `speed` |
| `apply_text_normalization` | enum | auto | auto / on / off |
| `seed` | integer | 0 | Reproducible output (advanced) |
| `optimize_streaming_latency` | range | 0 | 0–4 (advanced) |
| `language_code` | string | — | ISO 639-1 hint (advanced) |
| `output_format` | enum | `mp3_44100_128` | Codec + bitrate; higher tiers need Creator+/Pro+ (advanced) |

---

### Edge TTS (Free)

Edge TTS uses Microsoft's neural voices via the `edge-tts` Python CLI — no API key needed.

```bash
pip install edge-tts
```

```json
{
  "tts": {
    "provider": "edge",
    "auto": "tagged",
    "edge": {
      "enabled": true,
      "voice": "en-US-MichelleNeural",
      "rate": "+0%"
    }
  }
}
```

The `enabled` field must be `true` to activate the Edge provider — it has no API key to detect automatically.

Browse available voices:

```bash
edge-tts --list-voices
```

Popular voices: `en-US-MichelleNeural`, `en-GB-SoniaNeural`, `vi-VN-HoaiMyNeural`. The `rate` field adjusts speed (e.g. `+20%` faster, `-10%` slower). Output is always MP3.

#### Edge TTS Params

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `rate` | integer | 0 | Speed offset −50 to +100 (%) |
| `pitch` | integer | 0 | Pitch offset −50 to +50 (Hz) |
| `volume` | integer | 0 | Volume offset −50 to +100 (%) |

---

### MiniMax

MiniMax's T2A API supports 300+ system voices and 40+ languages. Voices are fetched dynamically — use the [Voices API](#voices-api) with `?provider=minimax`.

```json
{
  "tts": {
    "provider": "minimax",
    "auto": "always",
    "minimax": {
      "api_key": "...",
      "group_id": "your-group-id",
      "model": "speech-02-hd",
      "voice_id": "Wise_Woman"
    }
  }
}
```

Supported models: `speech-02-hd` (high quality), `speech-02-turbo` (faster), `speech-01-hd`, `speech-01-turbo`.

#### MiniMax Advanced Params

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `speed` | range | 1.0 | 0.5–2.0; agent-overridable as `speed` |
| `vol` | range | 1.0 | Volume 0.01–10.0 |
| `pitch` | integer | 0 | Pitch in semitones −12 to +12 |
| `emotion` | enum | — | happy/sad/angry/fearful/disgusted/surprised/neutral/excited/anxious; agent-overridable |
| `text_normalization` | boolean | — | Omitted when not set |
| `audio.format` | enum | `mp3` | mp3, pcm, flac, wav |
| `language_boost` | enum | Auto | 18 languages; improves pronunciation |
| `subtitle_enable` | boolean | — | Returns word-level timing data |
| `audio.sample_rate` | enum | Default | 8k–44.1 kHz (advanced) |
| `audio.bitrate` | enum | Default | 32–256 kbps; MP3 only (advanced) |
| `audio.channel` | enum | Default | Mono / Stereo (advanced) |
| `pronunciation_dict` | text | — | JSON array of `"word/phoneme"` rules, max 8 KB (advanced) |

Voice metadata (gender + language) is parsed automatically from MiniMax naming conventions and displayed as labels in the voice picker.

---

### Google Gemini TTS

Gemini TTS uses Google's latest preview models. An API key is required.

```json
{
  "tts": {
    "provider": "gemini",
    "auto": "always",
    "gemini": {
      "api_key": "AIza...",
      "model": "gemini-2.5-flash-preview-tts",
      "voice": "Kore"
    }
  }
}
```

Supported models (all preview-stage — UI shows a **Preview** badge):

| Model | Notes |
|-------|-------|
| `gemini-2.5-flash-preview-tts` | Fast + cost-efficient |
| `gemini-2.5-pro-preview-tts` | Highest quality |
| `gemini-3.1-flash-tts-preview` | **Default** |

#### Gemini Voices (30 prebuilt)

Each voice has a style character label shown as a badge in the UI:

| Voice | Style | Voice | Style |
|-------|-------|-------|-------|
| Zephyr | Bright | Puck | Upbeat |
| Charon | Informative | Kore | Firm |
| Fenrir | Excitable | Leda | Youthful |
| Orus | Firm | Aoede | Breezy |
| Callirrhoe | Easy-going | Autonoe | Bright |
| Enceladus | Breathy | Iapetus | Clear |
| Umbriel | Easy-going | Algieba | Smooth |
| Despina | Smooth | Erinome | Clear |
| Algenib | Gravelly | Rasalgethi | Informative |
| Laomedeia | Upbeat | Achernar | Soft |
| Alnilam | Firm | Schedar | Even |
| Gacrux | Mature | Pulcherrima | Forward |
| Achird | Friendly | Zubenelgenubi | Casual |
| Vindemiatrix | Gentle | Sadachbia | Lively |
| Sadaltager | Knowledgeable | Sulafat | Warm |

#### Gemini Params

| Param | Type | Default | Group |
|-------|------|---------|-------|
| `temperature` | range | API default (1.0) | Basic — subtle effect; primary expressiveness via audio tags |
| `seed` | integer | — | Advanced |
| `presencePenalty` | range | — | Advanced — experimental |
| `frequencyPenalty` | range | — | Advanced — experimental |

#### Gemini Multi-Speaker Mode

Up to 2 speakers per request. Each speaker has a `name` and a `voice` from the 30 prebuilt voices. Configure via the portal's Voice Picker — stored as `tts.gemini.speakers` JSON blob.

#### Gemini Audio Tags

Inject expressive markers directly into the text:

```
Hello [laughs] world [sighs] how are you?
```

Categories: Emotion, Pacing, Effect, Voice quality. Full tag list is in the frontend tag picker.

#### Gemini Language Support

70+ languages — no explicit language parameter needed. Gemini detects language from input text automatically.

#### Gemini Validation Errors (422)

| Error | When |
|-------|------|
| `ErrInvalidVoice` | Voice ID not in the 30 prebuilt set |
| `ErrSpeakerLimit` | More than 2 speakers in multi-speaker mode |
| `ErrInvalidModel` | Model ID not in the allowed list |
| `MsgTtsGeminiTextOnly` | Text-only response after auto-retry (see troubleshooting) |

---

## Agent-Level Voice Override

Each agent can override TTS params via its `other_config` JSONB field without changing the system-wide config.

### Voice and Model (ElevenLabs)

| Key | Type | Description |
|-----|------|-------------|
| `tts_voice_id` | string | ElevenLabs voice ID for this agent |
| `tts_model_id` | string | ElevenLabs model ID (must be an [allowed model](#elevenlabs-model-variants)) |

### Per-Agent Params Override (v3.10.0+)

Agents can override a subset of provider params stored in `other_config.tts_params`. Only these generic keys are allowed:

| Generic key | Maps to (OpenAI) | Maps to (ElevenLabs) | Maps to (MiniMax) | Edge / Gemini |
|-------------|------------------|----------------------|-------------------|---------------|
| `speed` | `speed` | `voice_settings.speed` | `speed` | not mapped |
| `emotion` | not mapped | not mapped | `emotion` | not mapped |
| `style` | not mapped | `voice_settings.style` | not mapped | not mapped |

Keys outside this allow-list are rejected at write time. The adapter runs per-attempt inside the provider fallback loop, so each attempt uses the correct mapping for that provider.

**Resolution order:** CLI args → agent `other_config` → tenant override → provider default.

**Example:**

```json
{
  "other_config": {
    "tts_voice_id": "pMsXgVXv3BLzUgSXRplE",
    "tts_model_id": "eleven_flash_v2_5",
    "tts_params": {
      "speed": 1.1,
      "style": 0.3
    }
  }
}
```

---

## Full Config Reference

```json
{
  "tts": {
    "provider": "openai",
    "auto": "inbound",
    "mode": "final",
    "max_length": 1500,
    "timeout_ms": 30000,
    "openai": { "api_key": "sk-...", "voice": "nova" },
    "edge":   { "enabled": true, "voice": "en-US-MichelleNeural" }
  }
}
```

When the primary provider fails, GoClaw automatically tries the other registered providers.

### Tenant Synthesis Timeout

The synthesis deadline is controlled by the `tts.timeout_ms` key in `system_configs` (tenant admin → Config → Audio → TTS). Default is **120000 ms (120 s)**. Set a higher value for slower providers or long-form audio; the gateway enforces a per-request context deadline equal to this value.

```
tts.timeout_ms = 120000   # default; increase for slow providers
```

---

## Voices API

GoClaw exposes HTTP endpoints for discovering available TTS voices. These are tenant-scoped and require tenant admin or operator role.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/voices` | List available voices (in-memory cached, TTL 1h) |
| `GET` | `/v1/voices?provider=minimax` | List MiniMax dynamic voices |
| `POST` | `/v1/voices/refresh` | Force-invalidate the voice cache (admin only) |

### `GET /v1/voices`

Returns the voice list for the current tenant's configured provider. Results are cached in-memory per tenant with a 1-hour TTL. For ElevenLabs, voices are user-account-specific. For MiniMax, the `?provider=minimax` query parameter fetches that provider's voice list at runtime.

```json
[
  {
    "voice_id": "pMsXgVXv3BLzUgSXRplE",
    "name": "Alice",
    "labels": {
      "use_case": "conversational",
      "accent": "american"
    }
  }
]
```

A cache miss triggers an immediate fetch from the provider. Returns `500` if the provider is unreachable.

### `POST /v1/voices/refresh`

Invalidates the voice cache for the current tenant so the next `GET /v1/voices` request fetches a fresh list. Returns `202 Accepted`.

---

## Capabilities API

```
GET /v1/tts/capabilities
```

Returns the full `ProviderCapabilities` schema for all registered providers — models, static voices, param schemas, and custom feature flags. The portal uses this to render dynamic per-provider settings forms and the agent override UI.

---

## Channel Integration

### Telegram Voice Bubbles

When the originating channel is `telegram`, GoClaw automatically requests `opus` format (Ogg/Opus container) instead of MP3 — Telegram requires this for voice messages. No extra config is needed.

```mermaid
flowchart LR
    REPLY["Agent reply text"] --> AUTO{"Auto mode\ncheck"}
    AUTO -->|passes| STRIP["Strip markdown\n& directives"]
    STRIP --> TRUNC["Truncate if >\nmax_length"]
    TRUNC --> FMT{"Channel?"}
    FMT -->|telegram| OPUS["Request opus"]
    FMT -->|other| MP3["Request mp3"]
    OPUS --> SYNTH["Synthesize"]
    MP3 --> SYNTH
    SYNTH --> SEND["Send as voice message"]
```

### Tagged Mode

Add `[[tts]]` anywhere in an agent reply to trigger synthesis in `tagged` mode:

```
Here's your daily briefing. [[tts]]
```

---

## Examples

**Minimal free setup with Edge TTS:**

```bash
pip install edge-tts
```

```json
{
  "tts": {
    "provider": "edge",
    "auto": "inbound",
    "edge": { "enabled": true, "voice": "en-US-JennyNeural" }
  }
}
```

**OpenAI primary with ElevenLabs fallback:**

```json
{
  "tts": {
    "provider": "openai",
    "auto": "always",
    "openai":     { "api_key": "sk-...", "voice": "alloy" },
    "elevenlabs": { "api_key": "xi-...", "voice_id": "pMsXgVXv3BLzUgSXRplE" }
  }
}
```

**Gemini multi-speaker with audio tags:**

```json
{
  "tts": {
    "provider": "gemini",
    "auto": "always",
    "gemini": {
      "api_key": "AIza...",
      "model": "gemini-2.5-flash-preview-tts"
    }
  }
}
```

Configure speakers in the portal Voice Picker — up to 2 speakers, each with a name and one of the 30 Gemini prebuilt voices.

---

## Speech-to-Text (STT)

GoClaw routes all voice/audio transcription through a unified `audio.Manager` with a provider chain. Channels (Telegram, Discord, Feishu, WhatsApp) share the same STT infrastructure.

### Unified Transcription Flow

```mermaid
flowchart TD
    VOICE["Voice/audio message"] --> ROUTE{Channel type?}

    ROUTE -->|Telegram / Discord / Feishu| DOWNLOAD["Download audio file"]
    ROUTE -->|WhatsApp| WA_CHECK{"whatsapp_enabled\nin settings?"}

    WA_CHECK -->|No| WA_FALLBACK["[Voice message]\n(default opt-out)"]
    WA_CHECK -->|Yes| DOWNLOAD

    DOWNLOAD --> STT_CHECK{"STT providers\nconfigured?"}
    STT_CHECK -->|Yes| STT_CHAIN["Try providers in order:\nelevenlabs_scribe, proxy"]
    STT_CHECK -->|No| FALLBACK["[Voice message]"]

    STT_CHAIN -->|Success| TEXT["Transcribed text\n→ agent context"]
    STT_CHAIN -->|Fail / 10s timeout| FALLBACK
```

### WhatsApp Opt-In

WhatsApp STT is **off by default** (`whatsapp_enabled: false`). Rationale: WhatsApp voice messages are end-to-end encrypted. Sending audio bytes to an external STT provider breaks E2E encryption. Admins must explicitly enable it in **Config → Audio → STT** and acknowledge the E2E breaking change.

When disabled (default): voice messages appear in agent context as `[Voice message]` — no audio leaves the device.
When enabled: audio is transcribed via the configured STT chain; falls back to `[Voice message]` on failure or timeout (10 s wall clock).

### STT Provider Chain

| Setting | Behavior |
|---------|----------|
| `providers: ["elevenlabs_scribe", "proxy_stt"]` | Try ElevenLabs Scribe first; fall back to legacy proxy |
| `providers: []` (empty) | Skip all STT; voice → `[Voice message]` |
| `providers` missing (nil) | Check for legacy `STTProxyURL` bridge at startup |

Configure via **Config → Audio → STT** in the web UI (stored in `builtin_tools[stt].settings.providers`). When this list is present it overrides all legacy channel-specific STT configs.

---

## STT Builtin Tool

The `stt` builtin tool (seeded by migration 050) enables agents to transcribe voice/audio input using ElevenLabs Scribe or a compatible proxy — see [Tools Overview](/tools-overview) for how to enable and configure it.

---

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| `tts provider not found: edge` | `enabled` not set | Add `"enabled": true` to `edge` section |
| `edge-tts failed` | CLI not installed | `pip install edge-tts` |
| `all tts providers failed` | All providers errored | Check API keys; inspect gateway logs |
| No voice in Telegram | `auto` is `off` | Set `auto: "inbound"` or `"always"` |
| Voice fires on tool results | `mode` is `all` | Set `mode: "final"` |
| MiniMax returns empty audio | Missing `group_id` | Add `group_id` from MiniMax console |
| Text cut off with `...` | Over `max_length` | Increase `max_length` in config |
| Gemini 422 `ErrInvalidVoice` | Voice not in 30 prebuilt set | Use a valid voice ID from the table above |
| Gemini 422 `ErrSpeakerLimit` | More than 2 speakers | Reduce to ≤ 2 speakers in Voice Picker |
| Gemini 422 `MsgTtsGeminiTextOnly` | Gemini returned text instead of audio after auto-retry | GoClaw retries once with an inline audio prefix; if Gemini still refuses, the error surfaces as HTTP 422. Shorten the text, remove translation/commentary, or switch model. |
| `tts_params` key rejected | Key not in allow-list | Use only `speed`, `emotion`, `style` |

---

## What's Next

- [Scheduling & Cron](/scheduling-cron) — trigger agents on a schedule
- [Extended Thinking](/extended-thinking) — deeper reasoning for complex replies



---

# Knowledge Graph

> Agents automatically extract entities and relationships from conversations, building a searchable graph of people, projects, and concepts.

## Overview

GoClaw's knowledge graph system has two parts:

1. **Extraction** — After conversations, an LLM extracts entities (people, projects, concepts) and relationships from the text
2. **Search** — Agents use the `knowledge_graph_search` tool to query the graph, traverse relationships, and discover connections

The graph is scoped per agent and per user — each agent builds its own graph from its conversations.


## Full-Text Search

Entity search uses PostgreSQL `tsvector` full-text search (migration `000031`). A stored `tsv` column is automatically generated from each entity's name and description:

```sql
tsv tsvector GENERATED ALWAYS AS (to_tsvector('simple', name || ' ' || COALESCE(description, ''))) STORED
```

A GIN index on `tsv` makes text queries fast even with large graphs. Queries like `"john"` or `"project alpha"` match partial words across name and description fields.

---

## Entity Deduplication

After extraction, GoClaw automatically checks new entities for duplicates using two signals:

1. **Embedding similarity** — HNSW KNN query finds the nearest existing entities of the same type
2. **Name similarity** — Jaro-Winkler string similarity (case-insensitive)

### Thresholds

| Scenario | Condition | Action |
|----------|-----------|--------|
| Near-certain duplicate | embedding similarity ≥ 0.98 **and** name similarity ≥ 0.85 | Auto-merged immediately |
| Possible duplicate | embedding similarity ≥ 0.90 | Flagged in `kg_dedup_candidates` for review |

**Auto-merge** keeps the entity with the higher confidence score, re-points all relations from the merged entity to the surviving one, and deletes the source entity. An advisory lock prevents concurrent merges on the same agent.

**Flagged candidates** are stored in `kg_dedup_candidates` with status `pending`. You can list, dismiss, or manually merge them via the API.

### Dedup Management Workflow

**1. Scan for duplicates** — Run a full scan across all entities:

```bash
POST /v1/agents/{agentID}/kg/dedup/scan
Content-Type: application/json

{"threshold": 0.90, "limit": 100}
```

Useful after bulk imports or initial onboarding. Results are added to the review queue.

**2. Review candidates:**

```bash
GET /v1/agents/{agentID}/kg/dedup?user_id=xxx
```

Returns `DedupCandidate[]` with fields: `entity_a`, `entity_b`, `similarity`, `status`.

**3. Merge:**

```bash
POST /v1/agents/{agentID}/kg/merge
Content-Type: application/json

{"target_id": "john-doe-uuid", "source_id": "j-doe-uuid"}
```

Re-points all relations from `source_id` to `target_id`, then deletes the source entity.

**4. Dismiss:**

```bash
POST /v1/agents/{agentID}/kg/dedup/dismiss
Content-Type: application/json

{"candidate_id": "candidate-uuid"}
```

Marks the pair as not-duplicate — it won't appear in future review queues.

---

## Searching the Graph

**Tool:** `knowledge_graph_search`

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Entity name, keyword, or `*` to list all (required) |
| `entity_type` | string | Filter: `person`, `organization`, `project`, `product`, `technology`, `task`, `event`, `document`, `concept`, `location` |
| `entity_id` | string | Start point for relationship traversal |
| `max_depth` | int | Traversal depth (default 2, max 3) |

### 3-Tier Search Fallback

The tool uses a 3-tier fallback strategy to ensure results are always returned:

1. **Traversal** (when `entity_id` provided) — Bidirectional multi-hop traversal up to `max_depth`, returns up to 20 results with path info and relation types
2. **Direct connections** (fallback if traversal returns nothing) — Bidirectional 1-hop relations, capped at 10
3. **Text search** (fallback if no connections) — Full-text search on entity names/descriptions, returns up to 10 results with their relations (5 per entity)

When all three tiers return nothing, the tool returns the top 10 existing entities as hints so the model knows what's available in the graph.

### Search modes

**Text search** — Find entities by name or keyword:
```
query: "John"
```

**List all** — Show all entities (up to 30):
```
query: "*"
```

**Traverse relationships** — Start from an entity and follow connections in both directions:
```
query: "*"
entity_id: "project-alpha"
max_depth: 2
```

Results include entity names, types, descriptions, depth, traversal path, and the relation type used to reach each entity.

---

## REST API Reference

All endpoints require authentication (`Authorization: Bearer <token>`). Add `?user_id=<id>` to scope results to a specific user.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/kg/entities` | List or search entities |
| `GET` | `/v1/agents/{agentID}/kg/entities/{entityID}` | Get entity with its relations |
| `POST` | `/v1/agents/{agentID}/kg/entities` | Upsert entity |
| `DELETE` | `/v1/agents/{agentID}/kg/entities/{entityID}` | Delete entity (cascades relations) |
| `POST` | `/v1/agents/{agentID}/kg/traverse` | Traverse the graph from an entity |
| `POST` | `/v1/agents/{agentID}/kg/extract` | LLM-powered extraction from text |
| `GET` | `/v1/agents/{agentID}/kg/stats` | Graph statistics |
| `GET` | `/v1/agents/{agentID}/kg/graph` | Full graph for visualization |
| `POST` | `/v1/agents/{agentID}/kg/dedup/scan` | Scan for duplicate candidates |
| `GET` | `/v1/agents/{agentID}/kg/dedup` | List dedup candidates |
| `POST` | `/v1/agents/{agentID}/kg/merge` | Merge two entities |
| `POST` | `/v1/agents/{agentID}/kg/dedup/dismiss` | Dismiss a dedup candidate |

---

## Data Model

### Entity

```json
{
  "id": "uuid",
  "agent_id": "agent-uuid",
  "user_id": "optional-user-id",
  "external_id": "john-doe",
  "name": "John Doe",
  "entity_type": "person",
  "description": "Backend engineer on the platform team",
  "properties": {"team": "platform"},
  "source_id": "optional-source-ref",
  "confidence": 0.95,
  "created_at": 1711900000,
  "updated_at": 1711900000
}
```

| Field | Description |
|-------|-------------|
| `external_id` | Human-readable slug (e.g., `john-doe`). Used for upsert dedup. |
| `properties` | Arbitrary key-value metadata from extraction |
| `source_id` | Optional reference to the source conversation or document |
| `confidence` | Extraction confidence (0.0–1.0); surviving entity in merges keeps the higher value |

### Relation

```json
{
  "id": "uuid",
  "agent_id": "agent-uuid",
  "user_id": "optional-user-id",
  "source_entity_id": "john-doe-uuid",
  "relation_type": "works_on",
  "target_entity_id": "project-alpha-uuid",
  "confidence": 0.9,
  "properties": {},
  "created_at": 1711900000
}
```

Relations are directional: `source --relation_type--> target`. Deleting an entity cascades and removes all its relations.

---

## Entity Types

| Type | Examples |
|------|----------|
| `person` | Team members, contacts, stakeholders |
| `organization` | Companies, teams, departments |
| `project` | Initiatives, codebases, programs |
| `product` | Software products, services, features |
| `technology` | Languages, frameworks, platforms |
| `task` | Action items, tickets, assignments |
| `event` | Meetings, deadlines, milestones |
| `document` | Reports, specs, wikis, runbooks |
| `concept` | Methodologies, ideas, principles |
| `location` | Offices, cities, regions |

---

## Graph Statistics & Visualization

### Statistics

```bash
GET /v1/agents/{agentID}/kg/stats?user_id=xxx
```

```json
{
  "entity_count": 42,
  "relation_count": 87,
  "entity_types": {
    "person": 15,
    "project": 8,
    "concept": 12,
    "task": 7
  }
}
```

### Full Graph for Visualization

```bash
GET /v1/agents/{agentID}/kg/graph?user_id=xxx&limit=200
```

Returns all entities and relations suitable for rendering in a graph UI. Default limit is 200 entities; relations are capped at 3× the entity limit.

The web dashboard renders the graph using **ReactFlow** with **D3 Force Simulation** (`d3-force`) for automatic node positioning:

- **Force layout** — `forceSimulation` computes node positions using link distance, charge repulsion (`forceManyBody`), centering (`forceCenter`), and collision avoidance (`forceCollide`). Forces scale by node count (tighter for small graphs, spread for large).
- **Node sizing by type** — Each entity type has a different mass (organization=8, project=6, person=4, etc.), so hub entities naturally sit at the center.
- **Degree centrality** — When entities exceed the display limit (50), the graph keeps the most-connected hub nodes. Nodes with ≥4 connections get a glow highlight.
- **Interactive selection** — Clicking a node highlights its connected edges with labels, dims unrelated edges, and opens the entity detail dialog.
- **Theme support** — Dual-theme color palette (dark/light) with per-entity-type colors. Theme changes update colors without re-running the layout.
- **Performance** — Node components are `memo`-ized, layout runs in `setTimeout(0)` to avoid blocking, and edge updates use `useTransition` for responsive interaction.

---

## Shared Knowledge Graph

By default, the knowledge graph is scoped per agent **and** per user — each user builds their own graph. When `share_knowledge_graph` is enabled in the agent's workspace sharing config, the graph becomes agent-level (shared across all users):

```yaml
workspace_sharing:
  share_knowledge_graph: true
```

In shared mode, `user_id` is ignored for all KG operations — entities and relations from all users are stored and queried together. This is useful for team agents where everyone should see the same entity graph.

> **Note:** `share_knowledge_graph` is independent of `share_memory`. You can share memory without sharing the graph, or vice versa.

---

## Automatic Extraction on Memory Write

When an agent writes to its memory files (e.g., `MEMORY.md` or files under `memory/`), GoClaw automatically triggers KG extraction on the written content. This happens via the `MemoryInterceptor`, which calls the configured LLM to extract entities and relations from the new memory text.

This means agents continuously build their knowledge graph as they learn — no manual `/kg/extract` calls needed for normal conversations. The extract API is available for bulk imports or external integrations.

---

## Confidence Pruning

Remove low-confidence entities and relations in bulk using `PruneByConfidence`:

```bash
# Internal service call — prunes items below threshold
# Returns count of pruned entities and relations
PruneByConfidence(agentID, userID, minConfidence)
```

This is useful after bulk imports where many low-confidence items accumulate. Items with `confidence < minConfidence` are deleted; their relations cascade automatically.

---

## Example

After several conversations about a project, an agent's knowledge graph might contain:

```
Entities:
  [person] Alice — Backend lead
  [person] Bob — Frontend developer
  [project] Project Alpha — E-commerce platform
  [concept] GraphQL — API layer technology

Relations:
  Alice --manages--> Project Alpha
  Bob --works_on--> Project Alpha
  Project Alpha --uses--> GraphQL
```

An agent can then answer questions like *"Who is working on Project Alpha?"* by traversing the graph.

---

## Knowledge Graph vs Knowledge Vault

The Knowledge Graph and [Knowledge Vault](knowledge-vault.md) are complementary systems:

| | Knowledge Graph | Knowledge Vault |
|--|----------------|-----------------|
| **What it stores** | Extracted entities and typed relations | Full documents (notes, specs, context files) |
| **How it's built** | Automatic LLM extraction from conversations | Agent writes files; VaultSyncWorker registers them |
| **Search** | Entity name / relationship traversal | Hybrid FTS + vector on title, path, content |
| **Links** | Typed relation edges (`works_on`, `manages`, …) | Wikilinks `[[target]]` and explicit references |
| **Scope** | Per-agent, optionally shared across team | personal / team / shared scope per document |

When an agent uses `vault_search`, the VaultSearchService fans out to **both** the vault and the knowledge graph simultaneously, merging results with weighted scoring.

---

## What's Next

- [Knowledge Vault](knowledge-vault.md) — Document-level knowledge store with wikilinks and semantic search
- [Memory System](../core-concepts/memory-system.md) — Vector-based long-term memory
- [Sessions & History](../core-concepts/sessions-and-history.md) — Conversation storage



---

# Knowledge Vault

> A structured knowledge store that lets agents curate workspace documents with bidirectional wikilinks, semantic search, and team-scoped access — all layered on top of existing memory systems.

Knowledge Vault is a **v3-only** feature. It sits between agents and the episodic/KG stores, adding document-level notes with explicit relationships.

> **Vault vs Knowledge Graph** — Vault stores full documents (notes, context files, specs) with lexical + semantic search and wikilinks. The [Knowledge Graph](knowledge-graph.md) stores extracted *entities and relations* from conversations. They complement each other: vault for curated docs, KG for auto-extracted facts. The VaultSearchService fans out to both simultaneously.


## Data Model

### vault_documents

Registry of document metadata. Content lives on the filesystem; the registry stores path, hash, embeddings, and links.

| Column | Type | Notes |
|--------|------|-------|
| `id` | UUID | Primary key |
| `tenant_id` | UUID | Multi-tenant isolation |
| `agent_id` | UUID | Per-agent namespace; **nullable** for team-scoped or tenant-shared files (migration 046) |
| `scope` | TEXT | `personal` \| `team` \| `shared` |
| `chat_id` | TEXT | Chat-scope isolation for isolated teams; NULL = no chat scope (team-wide or legacy) |
| `path` | TEXT | Workspace-relative path (e.g., `workspace/notes/foo.md`) |
| `title` | TEXT | Display name |
| `doc_type` | TEXT | `context`, `memory`, `note`, `skill`, `episodic`, `image`, `video`, `audio`, `document` |
| `content_hash` | TEXT | SHA-256 of file content (change detection) |
| `embedding` | vector(1536) | pgvector semantic similarity |
| `tsv` | tsvector | GIN FTS index on title + path + summary |
| `metadata` | JSONB | Optional custom fields |

### Chat-Scope Isolation

Migration `000056` adds the `chat_id` column to `vault_documents` to support isolated teams — groups where each chat channel is fully partitioned.

**Invariant for isolated teams:**
- `chat_id != NULL` → document is visible only to that chat
- `chat_id IS NULL` → document is team-wide (shared or legacy)
- Both rescan and search enforce this filter: `chat_id = <target> OR chat_id IS NULL`

**What migration `000056` does:**

1. Adds column `vault_documents.chat_id TEXT` (nullable)
2. Adds composite index `idx_vault_docs_team_chat` on `(team_id, chat_id) WHERE team_id IS NOT NULL`
3. Drops the `vault_documents_scope_consistency` constraint before running backfill UPDATEs — the constraint was added as `NOT VALID` in migration 055, meaning it skipped existing rows but still re-checked every UPDATE. Legacy data (pre-M46/M43) often violated the invariant, causing the backfill to abort and leaving migration 056 in a dirty state (issue #1035, fixed in v3.11.2). The constraint is re-added at the end of the migration with `NOT VALID`.

**Backfill logic:**

Migration 056 backfills `chat_id` for two groups:

- **Team-scoped docs** (`scope='team'`): extracts the chat segment from the path (`teams/<uuid>/<chat>/...` or `tenants/<slug>/teams/<uuid>/<chat>/...`). Segments starting with `.` (config dirs such as `.goclaw`) are skipped.
- **Legacy docs** (`team_id IS NULL`): a broader regex covers **all channel integrations**: `telegram`, `discord`, `zalo`, `feishu`, `lark`, `whatsapp`, `slack`, `line`, `messenger`, `wechat`, `viber`, `ws`, `delegate`, `api` — not just telegram/discord as in older releases.

**Related search parameters:**

| Parameter | Type | Notes |
|-----------|------|-------|
| `ChatID` | *string | Pointer to the chat ID to filter by; nil = no filter |
| `TeamIsolated` | bool | true = apply ChatID filter; false = skip (shared/personal) |

### vault_links

Bidirectional links between documents (wikilinks, explicit references, and enrichment-generated semantic links).

| Column | Type | Notes |
|--------|------|-------|
| `from_doc_id` | UUID | Source document |
| `to_doc_id` | UUID | Target document |
| `link_type` | TEXT | `wikilink`, `reference`, `depends_on`, `extends`, `related`, `supersedes`, `contradicts`, `task_attachment`, `delegation_attachment` |
| `context` | TEXT | ~50-char surrounding text snippet |
| `metadata` | JSONB | Extra metadata from enrichment pipeline (migration 048) |

Unique constraint: `(from_doc_id, to_doc_id, link_type)` — no duplicate links.

### vault_versions

Version history prepared for v3.1 — table exists but is empty in v3.0.

---

## Wikilinks

Agents can create bidirectional markdown links in `[[target]]` format.

### Syntax

```markdown
See [[architecture/components]] for details.
Reference [[SOUL.md|agent persona]] here.
Link [[../parent-project]] up.
```

- `[[path/to/file.md]]` — path-based target
- `[[name|display text]]` — display text is cosmetic only
- `.md` extension auto-appended if missing
- Empty or whitespace-only targets are skipped

### Resolution Strategy

When resolving a wikilink target:

1. **Exact path match** — find document by path
2. **With .md suffix** — retry if target lacks extension
3. **Basename search** — scan all agent docs, match by filename (case-insensitive)
4. **Unresolved** — silently skipped; backlinks can be incomplete

### Link Sync

`SyncDocLinks` keeps `vault_links` in sync with document content:

1. Extract all `[[...]]` patterns from content
2. Delete existing outgoing links for the document (replace strategy)
3. Resolve each target and create `vault_link` rows for resolved targets

This runs on every document upsert and on each VaultSyncWorker file event.

---

## Search

### Vault Search (Single Store)

Hybrid FTS + vector search on a single vault:

- **FTS**: PostgreSQL `plainto_tsquery()` on `tsv` (title + path keywords)
- **Vector**: pgvector cosine similarity on embeddings (semantic)
- **Scoring**: Scores from each method normalized to 0–1, then combined with query-time weights

### Unified Search (Cross-Store)

`VaultSearchService` fans out in parallel across all knowledge sources:

| Source | Weight | What it searches |
|--------|--------|-----------------|
| Vault | 0.4 | Document titles, paths, embeddings |
| Episodic | 0.3 | Session summaries |
| Knowledge Graph | 0.3 | Entity names and descriptions |

Results are normalized per source (max score = 1.0), weighted, merged, deduplicated by ID, and sorted by final score descending.

### Search Parameters

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `Query` | string | — | Required: natural language |
| `AgentID` | string | — | Scope to agent |
| `TenantID` | string | — | Scope to tenant |
| `Scope` | string | all | `personal`, `team`, `shared` |
| `DocTypes` | []string | all | `context`, `memory`, `note`, `skill`, `episodic` |
| `MaxResults` | int | 10 | Final result set size |
| `MinScore` | float64 | 0.0 | Minimum score filter |

---

## Filesystem Sync

`VaultSyncWorker` watches workspace directories for changes using `fsnotify`:

1. **Debounce**: 500ms — multiple rapid changes collapse to one batch
2. For each changed file:
   - Compute SHA-256 hash
   - Compare to `vault_documents.content_hash`
   - If different: update hash in DB
   - If file deleted: mark `metadata["deleted"] = true`

**Note:** Sync is one-way — only registered documents are watched. New files must first be registered by an agent write. The vault does not write back to the filesystem.

---

## Enrichment Pipeline

After each document upsert, **EnrichWorker** processes the event asynchronously to enrich vault documents with summaries, embeddings, and semantic links.

### What EnrichWorker does

1. Generates a text summary of the document content
2. Computes a vector embedding for semantic search
3. Classifies semantic relationships to other documents in the vault and creates `vault_link` rows

### Semantic link types

The classifier produces links with one of six relationship types:

| Type | Meaning |
|------|---------|
| `reference` | Document cites another as a source |
| `depends_on` | Document requires another to be meaningful |
| `extends` | Document adds to or builds upon another |
| `related` | General topical relationship |
| `supersedes` | Document replaces or obsoletes another |
| `contradicts` | Document conflicts with another |

### Special attachment link types

Two additional link types are created by the task/delegation system rather than the classifier:

- `task_attachment` — links a vault document to a team task it was attached to
- `delegation_attachment` — links a vault document to a delegation it was attached to

These are not affected by enrichment cleanup or rescan.

### Enrichment progress

Real-time enrichment progress is broadcast as WebSocket events. The UI shows per-document status while the worker runs.

### Stop and rescan controls

From the UI (or REST API), users can:
- **Stop enrichment** — halts the EnrichWorker for the current tenant
- **Trigger rescan** — re-queues all vault documents for re-enrichment (useful after model or config changes)

---

## Media Document Support

The vault accepts binary and media files in addition to text documents. Supported file types are controlled by an extension whitelist.

### doc_type values for media files

| `doc_type` | Used for |
|-----------|---------|
| `image` | PNG, JPG, GIF, WEBP, SVG, etc. |
| `video` | MP4, MOV, AVI, etc. |
| `audio` | MP3, WAV, OGG, etc. |
| `document` | PDF, DOCX, XLSX, etc. |

### Synthetic summaries for media

Because media files cannot be read as text, the vault uses `SynthesizeMediaSummary()` to generate a deterministic semantic summary from the filename and parent folder context. No LLM call is needed. The summary is stored in `vault_documents.summary` and included in the FTS index, enabling keyword discovery of media files by name and location.

---

## Agent Tools

### vault_search

Primary discovery tool. Searches across vault, episodic memory, and Knowledge Graph with unified ranking.

```json
{
  "query": "authentication flow",
  "scope": "team",
  "types": "context,note",
  "maxResults": 10
}
```

Each result carries a **source-specific ID field** that tells you which follow-up tool to use:

| Source | ID field | Follow-up tool |
|--------|----------|---------------|
| `vault` | `doc_id` | `vault_read(doc_id=...)` |
| `kg` | `entity_id` | `knowledge_graph_search(entity_id=...)` |
| `episodic` | `episodic_id` | `memory_expand(id=episodic_id)` |

> **ID namespace protection:** If you pass a `entity_id` or `episodic_id` to `vault_read` by mistake, the tool returns a descriptive error telling you the correct tool to use — rather than a generic "document not found". Always use the `doc_id` from vault results with `vault_read`.

> **Note on linking:** Explicit document linking is now handled automatically by the enrichment pipeline. The `vault_link` agent tool has been removed. Links are created via wikilink syntax in document content (`[[target]]`) or generated semantically by EnrichWorker. You can view links via `GET /v1/agents/{agentID}/vault/documents/{docID}/links`.

---

## REST API

All endpoints require `Authorization: Bearer <token>`.

### Per-Agent Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/vault/documents` | List documents (scope, doc_type, limit, offset) |
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}` | Get single document |
| `POST` | `/v1/agents/{agentID}/vault/documents` | Create document (optional `content` body — see below) |
| `PUT` | `/v1/agents/{agentID}/vault/documents/{docID}` | Update document (optional `content` body — see below) |
| `POST` | `/v1/agents/{agentID}/vault/search` | Unified search |
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}/links` | Outlinks + backlinks |

### Cross-Agent Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/vault/documents` | List across all tenant agents (filter by `agent_id`) |
| `POST` | `/v1/vault/documents` | Create document (optional `content` body — see below) |
| `PUT` | `/v1/vault/documents/{docID}` | Update document (optional `content` body — see below) |
| `GET` | `/v1/vault/tree` | Tree view of vault structure |
| `GET` | `/v1/vault/graph` | Cross-tenant graph visualization (node limit: 2000, FA2 layout) |

### Writing Content on Create/Update

`POST`/`PUT` accept an optional `content` field. When supplied, the bytes are materialised at `<tenant-workspace>/<path>`, the SHA-256 hash is stored on the row, and an enrichment event is emitted so summaries, embeddings, and links are computed — the same code path the multipart `/v1/vault/upload` endpoint uses.

| `content` value | Behaviour |
|-----------------|-----------|
| field omitted | Metadata-only stub; no file written, no enrichment event |
| present and non-empty | Bytes written to disk; hash stored; enrichment fires |
| present and empty (`""`) | A 0-byte file is written; enrichment still fires |

The path must use an allowed extension (same whitelist as `/v1/vault/upload`). Writes are sandboxed inside the tenant workspace: lexical `../` checks, symlink-ancestor resolution, and an atomic `O_NOFOLLOW` open reject any attempt to follow a symlink out of the workspace.

```bash
POST /v1/vault/documents
Content-Type: application/json
Authorization: Bearer <token>

{
  "path": "notes/auth.md",
  "title": "Authentication Flow",
  "doc_type": "note",
  "content": "# Authentication Flow\n\nSee [[architecture/components]] for details."
}
```

### Enrichment Control Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/vault/enrichment/stop` | Stop the enrichment worker |

### Example: Unified Search

```bash
POST /v1/agents/agent-123/vault/search
Content-Type: application/json
Authorization: Bearer <token>

{
  "query": "authentication flow",
  "scope": "personal",
  "max_results": 5
}
```

```json
[
  {
    "document": {
      "id": "doc-456",
      "path": "notes/auth.md",
      "title": "Authentication Flow",
      "doc_type": "note"
    },
    "score": 0.92,
    "source": "vault"
  },
  {
    "document": {"id": "episodic-789", "title": "Session-2026-04-06"},
    "score": 0.68,
    "source": "episodic"
  }
]
```

### Example: Get Links

```bash
GET /v1/agents/agent-123/vault/documents/doc-456/links
```

```json
{
  "outlinks": [
    {
      "id": "uuid",
      "to_doc_id": "uuid",
      "link_type": "wikilink",
      "context": "See [[target]] for details."
    }
  ],
  "backlinks": [
    {
      "id": "uuid",
      "from_doc_id": "uuid",
      "link_type": "wikilink",
      "context": "Reference [[auth.md]] here."
    }
  ]
}
```

---

## Recent Migrations

| Migration | Name | What changed |
|-----------|------|--------------|
| 046 | `vault_nullable_agent_id` | Makes `vault_documents.agent_id` nullable for team-scoped and tenant-shared files |
| 048 | `vault_media_linking` | Adds `base_name` generated column on `team_task_attachments`; adds `metadata JSONB` on `vault_links`; fixes CASCADE FK constraints |
| 049 | `vault_path_prefix_index` | Adds concurrent index `idx_vault_docs_path_prefix` with `text_pattern_ops` for fast prefix queries |
| 056 | `vault_chat_id` | Adds `chat_id` column + `idx_vault_docs_team_chat` index; backfills legacy data from all channel integrations; drops and re-adds scope-consistency CHECK (v3.11.1 + fix v3.11.2) |

---

## Requirements

- **PostgreSQL** with `pgvector` extension (embeddings)
- **Migration** `000038_vault_tables` must have run successfully
- **VaultStore** initialized during gateway startup
- **VaultSyncWorker** started for filesystem sync
- **EnrichWorker** started for automatic enrichment (summaries, embeddings, semantic links)

No feature flag. Vault is active if the migration ran and VaultStore initialized.

---

## Limitations

- Vault documents are **not auto-injected** into the agent system prompt — they must be retrieved via `vault_search`
- FTS indexes title + path only; content requires vector embeddings for discovery
- Sync is **one-way** (filesystem → vault; vault does not write back)
- **No conflict resolution** — concurrent edits use last-write-wins
- **Version history** (`vault_versions` table) prepared for v3.1; empty in v3.0

---

## What's Next

- [Knowledge Graph](knowledge-graph.md) — Entity and relation graph auto-extracted from conversations
- [Memory System](../core-concepts/memory-system.md) — Vector-based long-term memory
- [Context Files](../agents/context-files.md) — Static documents injected into agent context



---

# Caching

> Reduce database queries with in-memory or Redis caching for frequently accessed data.

## Overview

GoClaw uses a generic caching layer to reduce repeated database queries. Three cache instances are created at startup:

| Cache instance | Key prefix | What it stores |
|----------------|------------|----------------|
| `ctx:agent` | Agent-level context files | `SOUL.md`, `IDENTITY.md`, etc. per agent |
| `ctx:user` | User-level context files | Per-user context files keyed by `agentID:userID` |
| `grp:writers` | Group file writer lists | Writer permission lists keyed by `agentID:groupID` |

All three instances share the same TTL: **5 minutes**.

Two backends are available:

| Backend | When to use |
|---------|-------------|
| **In-memory** (default) | Single instance, development, small deployments |
| **Redis** | Multi-instance production, shared cache across replicas |

Both backends are **fail-open** — cache errors are logged as warnings but never block operations. A cache miss simply means the operation proceeds with a fresh database query.


## Redis Cache

Enable Redis caching by building GoClaw with the `redis` build tag and setting `GOCLAW_REDIS_DSN`.

```bash
go build -tags redis ./...
export GOCLAW_REDIS_DSN="redis://localhost:6379/0"
```

If `GOCLAW_REDIS_DSN` is unset or the connection fails at startup, GoClaw falls back to in-memory cache automatically.

**Key format:** `goclaw:{prefix}:{key}`

For example, an agent context file entry is stored as `goclaw:ctx:agent:<agentUUID>`.

**Connection settings:**
- Pool size: 10 connections
- Min idle: 2 connections
- Dial timeout: 5s
- Read timeout: 3s
- Write timeout: 3s
- Health check: PING on startup

**DSN format:**
```
redis://localhost:6379/0
redis://:password@redis.example.com:6379/1
```

Values are serialized as JSON. Pattern deletion uses SCAN with batch size of 100 keys per iteration.

---

## Permission Cache

GoClaw includes a dedicated `PermissionCache` for hot permission lookups that happen on every request. Unlike the context file caches, the permission cache is always in-memory — it does not use Redis.

| Cache | TTL | Key format | What it caches |
|---|---|---|---|
| `tenantRole` | 30s | `tenantID:userID` | User's role within a tenant |
| `agentAccess` | 30s | `agentID:userID` | Whether user can access an agent + their role |
| `teamAccess` | 30s | `teamID:userID` | Whether user can access a team |

**Invalidation via pubsub**: When a user's permissions change (e.g., role update, agent access revoked), GoClaw publishes a `CacheInvalidate` event on the internal bus. The permission cache processes these events:

- `CacheKindTenantUsers` — clears all tenant role entries (short TTL makes a full clear acceptable)
- `CacheKindAgentAccess` — removes all entries for that `agentID` prefix
- `CacheKindTeamAccess` — removes all entries for that `teamID` prefix

Permission changes take effect within 30 seconds at most, with immediate invalidation on write paths.

---

## Cache Behavior

Both backends implement the same interface:

| Operation | Behavior |
|-----------|----------|
| `Get` | Returns value + found flag; for in-memory, deletes expired entries on read |
| `Set` | Stores value with TTL; TTL of `0` means the entry never expires |
| `Delete` | Removes single key |
| `DeleteByPrefix` | Removes all keys matching a prefix (in-memory: range scan; Redis: SCAN + DEL) |
| `Clear` | Removes all entries under the cache instance's key prefix |

**Error handling:** All Redis errors are treated as cache misses. Connection failures, serialization errors, and timeouts are logged but never propagated to callers.

---

## What's Next

- [Database Setup](/deploy-database) — PostgreSQL configuration
- [Production Checklist](/deploy-checklist) — Deploy with confidence



---

# Browser Automation

> Give your agents a real browser — navigate pages, take screenshots, scrape content, and fill forms.

## Overview

GoClaw includes a built-in browser automation tool powered by [Rod](https://github.com/go-rod/rod) and the Chrome DevTools Protocol (CDP). Agents can open URLs, interact with elements, capture screenshots, and read page content — all through a structured tool interface.

Two operating modes are supported:

- **Local Chrome**: Rod launches a local Chrome process automatically
- **Remote Chrome sidecar**: Connect to a headless Chrome container via CDP (recommended for servers and Docker)


## Local Chrome (Dev Only)

Without `GOCLAW_BROWSER_REMOTE_URL`, Rod launches a local Chrome process. Chrome must be installed on the host. This is suitable for local development but not recommended for servers.

---

## How the Browser Tool Works

Agents interact with the browser via a single `browser` tool with an `action` parameter:

```mermaid
flowchart LR
    AGENT["Agent"] --> TOOL["browser tool"]
    TOOL --> START["start"]
    TOOL --> OPEN["open URL"]
    TOOL --> SNAP["snapshot\n(get refs)"]
    TOOL --> ACT["act\n(click/type/press)"]
    TOOL --> SHOT["screenshot"]
    SNAP --> REFS["Element refs\ne1, e2, e3..."]
    REFS --> ACT
```

The standard workflow is:

1. `start` — launch or connect to browser (auto-triggered by most actions)
2. `open` — open a URL in a new tab, get `targetId`
3. `snapshot` — get the page accessibility tree with element refs (`e1`, `e2`, ...)
4. `act` — interact with elements using refs
5. `snapshot` again to verify changes

---

## Available Actions

| Action | Description | Required params |
|--------|-------------|----------------|
| `status` | Browser running state and tab count | — |
| `start` | Launch or connect browser | — |
| `stop` | Close local browser or disconnect from remote sidecar (sidecar container keeps running) | — |
| `tabs` | List open tabs with URLs | — |
| `open` | Open URL in new tab | `targetUrl` |
| `close` | Close a tab | `targetId` |
| `snapshot` | Get accessibility tree with element refs | `targetId` (optional) |
| `screenshot` | Capture PNG screenshot | `targetId`, `fullPage` |
| `navigate` | Navigate existing tab to URL | `targetId`, `targetUrl` |
| `console` | Get browser console messages (buffer is cleared after each call) | `targetId` |
| `act` | Interact with an element | `request` object |

### Act Request Kinds

| Kind | What it does | Required fields | Optional fields |
|------|-------------|----------------|----------------|
| `click` | Click an element | `ref` | `doubleClick` (bool), `button` (`"left"`, `"right"`, `"middle"`) |
| `type` | Type text into an element | `ref`, `text` | `submit` (bool — press Enter after), `slowly` (bool — character-by-character) |
| `press` | Press a keyboard key | `key` (e.g. `"Enter"`, `"Tab"`, `"Escape"`) | — |
| `hover` | Hover over an element | `ref` | — |
| `wait` | Wait for condition | one of: `timeMs`, `text`, `textGone`, `url`, or `fn` | — |
| `evaluate` | Run JavaScript and return result | `fn` | — |

---

## Use Cases

### Screenshot a Page

```json
{ "action": "open", "targetUrl": "https://example.com" }
```
```json
{ "action": "screenshot", "targetId": "<id from open>", "fullPage": true }
```

The screenshot is saved to a temp file and returned as `MEDIA:/tmp/goclaw_screenshot_*.png` — the media pipeline delivers it as an image (e.g. Telegram photo).

### Scrape Page Content

```json
{ "action": "open", "targetUrl": "https://example.com" }
```
```json
{ "action": "snapshot", "targetId": "<id>", "compact": true, "maxChars": 8000 }
```

The snapshot returns an accessibility tree. Use `interactive: true` to see only clickable/typeable elements. Use `depth` to limit tree depth.

### Fill and Submit a Form

```json
{ "action": "open", "targetUrl": "https://example.com/login" }
```
```json
{ "action": "snapshot", "targetId": "<id>" }
```
```json
{
  "action": "act",
  "targetId": "<id>",
  "request": { "kind": "type", "ref": "e3", "text": "user@example.com" }
}
```
```json
{
  "action": "act",
  "targetId": "<id>",
  "request": { "kind": "type", "ref": "e4", "text": "mypassword", "submit": true }
}
```

`submit: true` presses Enter after typing.

### Run JavaScript

```json
{
  "action": "act",
  "targetId": "<id>",
  "request": { "kind": "evaluate", "fn": "document.title" }
}
```

---

## Snapshot Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `maxChars` | number | 8000 | Max characters in snapshot output |
| `interactive` | boolean | false | Show only interactive elements |
| `compact` | boolean | false | Remove empty structural nodes |
| `depth` | number | unlimited | Max tree depth |

---

## Selected Cookie Sync

Server-side browser sessions start with no login state. **Selected cookie sync** lets a user pick specific cookies from a site they are logged into and copy them into GoClaw, so an agent's browser can act as that signed-in session — without sharing a password.

A small Chrome extension (`chrome-selected-cookie-sync`) does the picking. There is **no automatic background sync**: the user opens the extension on the active tab, checks the exact cookies to share, and clicks **Sync**. GoClaw stores the values encrypted and replays them into the agent's browser only for matching domains and paths.

```mermaid
flowchart LR
    USER["User on logged-in site"] --> EXT["chrome-selected-cookie-sync\nextension"]
    EXT -->|"POST /v1/browser/cookies/sync"| GW["GoClaw gateway"]
    GW -->|"AES-256-GCM encrypt"| DB[("browser_cookies\ntable")]
    DB -->|"decrypt + domain/path match"| AGENT["Agent browser session"]
```

### Endpoints

All three endpoints require **operator** auth (gateway token, API key, or paired-browser auth).

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/v1/browser/cookies/sync` | Upsert selected cookies for an agent |
| `GET` | `/v1/browser/cookies?agent_id=&domain=&name=&path=` | List synced cookie **metadata** (never values) |
| `DELETE` | `/v1/browser/cookies?agent_id=&domain=&name=&path=` | Revoke synced cookies |

The client only ever chooses `agent_id`. **Tenant and user are derived from the auth context**, not from the request body — a client cannot spoof another user's cookies. Sync is rejected when the auth context has no user, or when no `agent_id` is supplied.

**Sync request body:**

```json
{
  "agent_id": "default",
  "source": "chrome-selected-cookie-sync",
  "cookies": [
    {
      "domain": "example.com",
      "name": "session",
      "path": "/",
      "value": "REDACTED",
      "secure": true,
      "httpOnly": true,
      "sameSite": "lax",
      "expirationDate": 1789999999
    }
  ]
}
```

**Response:** `{ "synced": 1 }`. Limits: max 200 cookies per request, 16 KB per cookie value, 1 MB total body.

The `GET` response returns metadata only — `domain`, `name`, `path`, `secure`, `httpOnly`, `sameSite`, `expiresAt`, `source`, `updatedAt`. Cookie **values are never returned**.

### Scope and uniqueness

Each stored cookie is keyed by `(tenant_id, user_id, agent_id, domain, path, name)`. Re-syncing the same cookie updates the existing row (upsert). This scope is what keeps one user's cookies from leaking into another user's or another agent's browser session.

### Security

- **Encrypted at rest**: cookie values are encrypted with AES-256-GCM before being written to the `browser_cookies` table. Requires the `GOCLAW_ENCRYPTION_KEY` environment variable — **sync and list fail closed (HTTP 503) when it is unset**, so cookies are never persisted in plaintext.
- **Write-only values**: the list endpoint and audit logs return metadata only. Cookie values never appear in API responses or logs.
- **Scoped replay**: the agent browser receives a cookie only when the requested URL's host and path match the stored cookie's domain/path, the cookie has not expired, and the tenant/user/agent scope matches.
- **Explicit selection**: the extension reads cookies only after the user grants host permission for the active site, and sends only the cookies the user checked.
- **Revocation**: delete from the extension or call `DELETE /v1/browser/cookies?agent_id=<agent>&domain=<domain>` to remove synced cookies. Omitting `domain` removes all cookies for that agent.

### How the agent consumes synced cookies

When the agent's browser navigates to an `http(s)` URL, GoClaw's cookie provider looks up cookies for the current browser scope (`tenant_id` / `user_id` / `agent_id`), decrypts them, and injects only those whose domain and path match the target URL (and that have not expired). Non-HTTP schemes get no cookies. The agent never sees raw values — they are applied directly to the Chrome session via CDP.

### Install the extension

The extension lives in the GoClaw repo at `extensions/chrome-selected-cookie-sync/`.

1. Open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the `extensions/chrome-selected-cookie-sync/` folder.
2. Open a tab on the site you are logged into, then click the extension icon.
3. Fill in the popup:
   - **Gateway URL** — e.g. `http://localhost:18790`
   - **Token** — an operator token (sent as `Authorization: Bearer <token>`)
   - **User ID** — sent as the `X-GoClaw-User-Id` header
   - **Agent ID** — e.g. `default`
4. Click **Grant access** to give the extension host permission for the current site, then **Refresh** to list the site's cookies.
5. Check the cookies you want to share (or **Select all**), then click **Sync**. The popup confirms `Synced N cookies.`

Settings are saved in `chrome.storage.local`. The extension requests gateway-origin permission before sending, and asks for active-tab host permission before reading cookies.

---

## Security Considerations

- **SSRF protection**: GoClaw applies SSRF filtering to tool inputs — agents cannot be trivially directed to internal network addresses.
- **No-sandbox flag**: The Docker compose config passes `--no-sandbox` which is required inside containers. Do not use this on the host without container isolation.
- **Shared memory**: Chrome is memory-intensive. The sidecar is configured with `shm_size: 2gb` and a 2GB memory limit. Tune this for your workload.
- **Exposed CDP port**: By default, port 9222 is only accessible within the Docker network. Do not expose it publicly — CDP allows full browser control with no authentication.

---

## Examples

**Agent prompt to trigger browser use:**

```
Take a screenshot of https://news.ycombinator.com and show me the top 5 stories.
```

The agent will call `browser` with `open`, then `screenshot` or `snapshot` depending on the task.

**Check browser status in agent conversation:**

```
Are you connected to a browser?
```

The agent calls:

```json
{ "action": "status" }
```

Returns:

```json
{ "running": true, "tabs": 1, "url": "https://example.com" }
```

---

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| `failed to start browser: launch Chrome` | Chrome not installed locally | Use Docker sidecar instead |
| `resolve remote Chrome at ws://chrome:9222` | Sidecar not healthy yet | Wait for `service_healthy` or increase startup timeout |
| `snapshot failed` | Page not loaded | Add a `wait` action after `open` |
| Screenshots are blank | GPU rendering issue | Ensure `--disable-gpu` flag is set (already in compose) |
| High memory usage | Many open tabs | Call `close` on tabs when done |
| CDP port exposed publicly | Misconfigured ports | Remove `9222` from host port mappings in production |

---

## What's Next

- [Exec Approval](/exec-approval) — require human sign-off before running commands
- [Hooks & Quality Gates](/hooks-quality-gates) — add pre/post checks to agent actions



---

# Extended Thinking

> Let your agent "think out loud" before answering — better results on complex tasks, at the cost of extra tokens and latency.

## Overview

Extended thinking lets a supported LLM reason through a problem before producing its final reply. The model generates internal reasoning tokens that are not part of the visible response but improve the quality of complex analysis, multi-step planning, and decision-making.

GoClaw supports extended thinking across four provider families — Anthropic, OpenAI-compatible, DashScope (Alibaba Qwen), and Codex (OpenAI ChatGPT OAuth, Responses API) — through a single unified `thinking_level` setting per agent.


## Provider Mapping

Each provider translates `thinking_level` differently:

```mermaid
flowchart TD
    CONFIG["Agent config:\nthinking_level = medium"] --> CHECK{"Provider supports\nthinking?"}
    CHECK -->|No| SKIP["Send request\nwithout thinking"]
    CHECK -->|Yes| MAP{"Provider type?"}

    MAP -->|Anthropic| ANTH["budget_tokens: 10,000\nHeader: anthropic-beta\nStrip temperature"]
    MAP -->|OpenAI-compat| OAI["reasoning_effort: medium"]
    MAP -->|DashScope| DASH["enable_thinking: true\nbudget: 16,384\n⚠ No streaming when tools present"]

    ANTH --> SEND["Send to LLM"]
    OAI --> SEND
    DASH --> SEND
```

### Anthropic

| Level | Budget tokens |
|-------|:---:|
| `low` | 4,096 |
| `medium` | 10,000 |
| `high` | 32,000 |

When thinking is active, GoClaw:

- Adds `thinking: { type: "enabled", budget_tokens: N }` to the request body
- Sets the `anthropic-beta: interleaved-thinking-2025-05-14` header
- **Strips the `temperature` parameter** — Anthropic rejects thinking requests that include temperature
- Auto-adjusts `max_tokens` to `budget_tokens + 8,192` to accommodate thinking overhead

> **Sampling params on Claude 4.6+:** For Claude Opus/Sonnet 4.6+ and Opus 4.7+, GoClaw omits `temperature` (and `top_p`/`top_k`) from **every** request — independent of thinking. These models return `HTTP 400` if sampling params are included. This is broader than the thinking-only strip above. See the [Anthropic provider](/provider-anthropic) page.

### OpenAI-Compatible (OpenAI, Groq, DeepSeek, etc.)

Maps `thinking_level` directly to `reasoning_effort`:

- `low` → `reasoning_effort: "low"`
- `medium` → `reasoning_effort: "medium"`
- `high` → `reasoning_effort: "high"`

Reasoning content arrives in `reasoning_content` during streaming and does not require special passback handling between turns.

> **Kimi Coding (`kimi_coding`):** Kimi is OpenAI-compatible but has **server-side thinking on by default** for `kimi-k2-turbo-preview`. As a result, assistant tool-call messages replayed in history **must carry** a `reasoning_content` field — GoClaw auto-emits an empty string when none was captured, otherwise upstream returns `HTTP 400`. See the [Kimi Coding](/provider-kimi) page.

> **Bailian Coding (`bailian`):** Bailian is a separate OpenAI-compatible Coding endpoint. Its hardcoded catalog includes `qwen3.7-plus` (advertised with Deep Thinking and Visual Understanding), but the DashScope `enable_thinking`/`thinking_budget` injection path described below does **not** apply to Bailian — it is treated as a plain OpenAI-compatible provider. See [Bailian](/provider-bailian).

### DashScope (Alibaba Qwen)

| Level | Budget tokens |
|-------|:---:|
| `low` | 4,096 |
| `medium` | 16,384 |
| `high` | 32,768 |

Thinking is enabled via `enable_thinking: true` plus a `thinking_budget` parameter.

**Per-model guard**: GoClaw checks whether the resolved model is in the supported thinking model list before sending `enable_thinking`. If the model does not support thinking (e.g., an older Qwen2 variant), the parameters are silently omitted and a debug log is emitted. This guard means `thinking_level` on a DashScope agent is safe to set even if you later switch to a non-thinking Qwen model.

**Important limitation**: DashScope cannot stream responses when tools are present — this is a provider-level constraint independent of thinking. Whenever an agent has tools defined, GoClaw automatically falls back to non-streaming mode (single `Chat()` call) and synthesizes chunk callbacks so the event flow remains consistent for clients.

---

## Streaming

When thinking is active, reasoning content streams alongside the regular reply content. Clients receive both separately:

```mermaid
flowchart TD
    LLM["LLM generates response"] --> THINK["Thinking tokens\n(internal reasoning)"]
    THINK --> CONTENT["Content tokens\n(final response)"]

    THINK -->|Stream| CT["StreamChunk\nThinking: 'reasoning text...'"]
    CONTENT -->|Stream| CC["StreamChunk\nContent: 'response text...'"]

    CT --> CLIENT["Client receives\nthinking + content separately"]
    CC --> CLIENT
```

| Provider | Thinking event | Content event |
|----------|---------------|---------------|
| Anthropic | `thinking_delta` in content blocks | `text_delta` in content blocks |
| OpenAI-compat | `reasoning_content` in delta | `content` in delta |
| DashScope | No streaming with tools (falls back to non-streaming) | Same |
| Codex | `OutputTokensDetails.ReasoningTokens` tracked | Standard content |

Thinking tokens are estimated as `character_count / 4` for context window tracking.

> **Channel delivery is separate from provider streaming.** Whether a provider streams reasoning is one decision; whether a chat channel (e.g. Telegram) shows that reasoning to end users is another. Telegram exposes a `reasoning_delivery` setting for this — see the channel documentation for its modes.

---

## Tool Loop Handling

When an agent uses tools, thinking must survive across multiple turns. GoClaw handles this automatically — but the mechanics differ by provider.

```mermaid
flowchart TD
    T1["Turn 1: LLM thinks + calls tool"] --> PRESERVE["Preserve thinking blocks\nin raw assistant content"]
    PRESERVE --> TOOL["Tool executes,\nresult appended to history"]
    TOOL --> T2["Turn 2: LLM receives history\nincluding preserved thinking blocks"]
    T2 --> CONTINUE["LLM continues reasoning\nwith full context"]
```

**Anthropic**: Thinking blocks include cryptographic `signature` fields that must be echoed back exactly in subsequent turns. GoClaw accumulates raw content blocks during streaming (including `thinking` type blocks) and re-sends them on the next turn. Dropping or modifying these blocks causes the API to reject the request or produce degraded responses.

**OpenAI-compatible**: Reasoning content is treated as metadata. Each turn's reasoning is independent — no passback is needed.

---

## Limitations

| Provider | Limitation |
|----------|-----------|
| DashScope | Cannot stream when tools are present (provider-level, not thinking-specific) — falls back to non-streaming |
| Anthropic | `temperature` is stripped when thinking is enabled |
| All | Thinking tokens count against the context window budget |
| All | Thinking increases latency and cost proportional to the budget level |

---

## Examples

**Enable medium thinking on an Anthropic agent:**

```json
{
  "agent": {
    "key": "analyst",
    "provider": "claude-opus-4-5",
    "thinking_level": "medium"
  }
}
```

At `medium`, Anthropic gets `budget_tokens: 10,000`. The agent's visible reply is unchanged — thinking happens internally.

**High thinking for a complex research agent:**

```json
{
  "agent": {
    "key": "researcher",
    "provider": "claude-opus-4-5",
    "thinking_level": "high"
  }
}
```

This sets `budget_tokens: 32,000`. Use this for tasks that require deep multi-step analysis. Expect higher latency and token cost.

**OpenAI o-series agent with low reasoning:**

```json
{
  "agent": {
    "key": "quick-reviewer",
    "provider": "o4-mini",
    "thinking_level": "low"
  }
}
```

Maps to `reasoning_effort: "low"` on the OpenAI API.

---

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| `temperature` stripped unexpectedly | Anthropic thinking enabled | Expected behavior — Anthropic requires no temperature with thinking |
| DashScope agent slow with tools | Streaming always disabled when tools present | Expected — DashScope provider limitation; reduce tool count if latency matters |
| High context usage | Thinking tokens fill the window | Use `low` or `medium` level; monitor context % in logs |
| No visible thinking output | Thinking is internal by default | Reasoning chunks stream separately; check client WebSocket events |
| Thinking has no effect | Provider doesn't support thinking | Check provider type — only Anthropic, OpenAI-compat, and DashScope are supported |

---

## What's Next

- [Agents Overview](/agents-explained) — per-agent configuration reference
- [Hooks & Quality Gates](/hooks-quality-gates) — validate agent outputs after reasoning



---

# Agent Hooks

> Intercept, observe, or inject behavior at defined points in the agent loop — block unsafe tool calls, auto-audit after writes, inject session context, or notify on stop.

## Overview

GoClaw's hook system attaches lifecycle handlers to agent sessions. Each hook targets a specific **event**, runs a **handler** (shell command, HTTP webhook, or LLM evaluator), and returns an **allow/block** decision for blocking events.

Hooks are stored in the `agent_hooks` DB table (migration `000052`) and managed via the `hooks.*` WebSocket methods or the **Hooks** panel in the Web UI.


## Execution Flow

```mermaid
flowchart TD
    EVENT["Lifecycle event fires\ne.g. pre_tool_use"] --> RESOLVE["Dispatcher resolves hooks\nby scope + event + priority"]
    RESOLVE --> MATCH{"Matcher / if_expr\ncheck"}
    MATCH -->|no match| SKIP["Skip hook"]
    MATCH -->|matches| HANDLER["Run handler\n(command / http / prompt)"]
    HANDLER -->|allow| NEXT["Continue chain"]
    HANDLER -->|block| BLOCKED["Block operation\nFail-closed"]
    HANDLER -->|timeout| TIMEOUT_DECISION{"OnTimeout\npolicy"}
    TIMEOUT_DECISION -->|block| BLOCKED
    TIMEOUT_DECISION -->|allow| NEXT
    NEXT --> AUDIT["Write hook_executions row\n+ emit trace span"]
```

---

## Handler Reference

### command

```json
{
  "handler_type": "command",
  "event": "pre_tool_use",
  "scope": "tenant",
  "config": {
    "command": "bash /path/to/script.sh",
    "allowed_env_vars": ["MY_VAR"],
    "cwd": "/workspace"
  }
}
```

- **Stdin**: JSON-encoded event payload.
- **Exit 0**: allow (optional `{"continue": false}` → block).
- **Exit 2**: block.
- **Other non-zero**: error → fail-closed for blocking events.
- **Env allowlist**: only keys listed in `allowed_env_vars` are passed; prevents secret leakage.

### http

```json
{
  "handler_type": "http",
  "event": "user_prompt_submit",
  "scope": "tenant",
  "config": {
    "url": "https://example.com/webhook",
    "headers": { "Authorization": "<AES-encrypted>" }
  }
}
```

- Method: POST, body = event JSON.
- Authorization header values stored AES-256-GCM encrypted; decrypted at dispatch.
- 1 MiB response cap. Retries once on 5xx with 1 s backoff; 4xx fail-closed.
- Expected response body:
  ```json
  { "decision": "allow", "additionalContext": "...", "updatedInput": {}, "continue": true }
  ```
- Non-JSON 2xx → allow.

### prompt

```json
{
  "handler_type": "prompt",
  "event": "pre_tool_use",
  "scope": "tenant",
  "matcher": "^(exec|shell|write_file)$",
  "config": {
    "prompt_template": "Evaluate safety of this tool call.",
    "model": "haiku",
    "max_invocations_per_turn": 5
  }
}
```

- `prompt_template` — system-level instruction the evaluator receives.
- `matcher` or `if_expr` — required; prevents firing the LLM on every event.
- Evaluator MUST call a `decide(decision, reason, injection_detected, updated_input)` tool. Free-text responses fail-closed.
- Only `tool_input` reaches the evaluator (anti-injection sandboxing); raw user message is never included.

---

## Matchers

| Field | Description |
|---|---|
| `matcher` | POSIX-ish regex applied to `tool_name`. Example: `^(exec|shell|write_file)$` |
| `if_expr` | [cel-go](https://github.com/google/cel-go) expression over `{tool_name, tool_input, depth}`. Example: `tool_name == "exec" && size(tool_input.cmd) > 80` |

Both optional for `command`/`http`. At least one required for `prompt`.

---

## Config Fields Reference

| Field | Type | Required | Description |
|---|---|---|---|
| `event` | string | yes | Lifecycle event name |
| `handler_type` | string | yes | `command`, `http`, or `prompt` |
| `scope` | string | yes | `global`, `tenant`, or `agent` |
| `name` | string | no | Human-readable label |
| `matcher` | string | no | Tool name regex filter |
| `if_expr` | string | no | CEL expression filter |
| `timeout_ms` | int | no | Per-hook timeout (default 5000, max 10000) |
| `on_timeout` | string | no | `block` (default) or `allow` |
| `priority` | int | no | Higher = runs first (default 0) |
| `enabled` | bool | no | Default true |
| `config` | object | yes | Handler-specific sub-config |
| `agent_ids` | array | no | Restrict to specific agent UUIDs (scope=agent) |

---

## Security Model

- **Edition gating**: `command` handler blocked on Standard at both config-time and dispatch-time (defense in depth).
- **Tenant isolation**: all reads/writes scope by `tenant_id` unless caller is in master scope. Global hooks use a sentinel tenant id.
- **SSRF protection**: HTTP handler validates URLs before request, pins resolved IP, blocks loopback/link-local/private ranges.
- **PII redaction**: audit rows truncate error text to 256 chars; full error encrypted (AES-256-GCM) in `error_detail`.
- **Fail-closed**: any unhandled error in a blocking event yields `block`. Timeouts respect `on_timeout` (default `block` for blocking events).
- **Circuit breaker**: 5 consecutive blocks/timeouts in a 1-minute rolling window auto-disables the hook (`enabled=false`).
- **Loop detection**: sub-agent hook chains bounded at depth 3.

---

## Safeguards Summary

| Safeguard | Default | Overridable per hook |
|---|---|---|
| Per-hook timeout | 5 s | yes (`timeout_ms`, max 10 s) |
| Chain budget | 10 s | no |
| Circuit threshold | 5 blocks in 1 minute | no |
| Prompt per-turn cap | 5 invocations | yes (`max_invocations_per_turn`) |
| Prompt decision cache TTL | 60 s | no |
| Tenant monthly token budget | 1,000,000 tokens | seeded per tenant in `tenant_hook_budget` |

---

## Managing Hooks via WebSocket

All CRUD is available over the `hooks.*` WS methods (see [WebSocket Protocol](/websocket-protocol#hooks)).

**Create a hook:**
```json
{
  "type": "req", "id": "1", "method": "hooks.create",
  "params": {
    "event": "pre_tool_use",
    "handler_type": "http",
    "scope": "tenant",
    "name": "Safety webhook",
    "matcher": "^exec$",
    "config": { "url": "https://safety.internal/check" }
  }
}
```

Response:
```json
{ "type": "res", "id": "1", "ok": true, "payload": { "hookId": "uuid..." } }
```

**Toggle a hook on/off:**
```json
{ "type": "req", "id": "2", "method": "hooks.toggle",
  "params": { "hookId": "uuid...", "enabled": false } }
```

**Dry-run test (no audit row written):**
```json
{
  "type": "req", "id": "3", "method": "hooks.test",
  "params": {
    "config": { "event": "pre_tool_use", "handler_type": "command",
                "scope": "tenant", "config": { "command": "cat" } },
    "sampleEvent": { "toolName": "exec", "toolInput": { "cmd": "ls" } }
  }
}
```

---

## Web UI Walkthrough

Navigate to **Hooks** in the sidebar.

1. **Create** — pick event, handler type (`command` greyed out on Standard edition), scope, matcher, then fill the handler-specific sub-form.
2. **Test panel** — fires the hook with a sample event (`dryRun=true`, no audit row written). Shows decision badge, duration, stdout/stderr (command), status code (http), reason (prompt). If the response includes `updatedInput`, a side-by-side JSON diff is rendered.
3. **History tab** — paginated executions from `hook_executions`.
4. **Overview tab** — summary card with event, type, scope, matcher.

---

## Database Schema

Three tables land with migration `000052_agent_hooks`:

**`agent_hooks`** — hook definitions:

| Column | Type | Notes |
|---|---|---|
| `id` | UUID PK | — |
| `tenant_id` | UUID FK | sentinel UUID for global scope |
| `agent_ids` | UUID[] | empty = applies to all agents in scope |
| `event` | VARCHAR(32) | one of the 7 event names |
| `handler_type` | VARCHAR(16) | `command`, `http`, `prompt` |
| `scope` | VARCHAR(16) | `global`, `tenant`, `agent` |
| `config` | JSONB | handler sub-config |
| `matcher` | TEXT | tool name regex (optional) |
| `if_expr` | TEXT | CEL expression (optional) |
| `timeout_ms` | INT | default 5000 |
| `on_timeout` | VARCHAR(16) | `block` or `allow` |
| `priority` | INT | higher fires first |
| `enabled` | BOOL | circuit breaker writes false here |
| `version` | INT | increments on update; busts prompt cache |
| `source` | VARCHAR(16) | `builtin` (read-only) or `user` |

**`hook_executions`** — audit log:

| Column | Notes |
|---|---|
| `hook_id` | `ON DELETE SET NULL` — executions preserved after hook deletion |
| `dedup_key` | Unique index prevents double rows on retry |
| `error` | Truncated to 256 chars |
| `error_detail` | BYTEA, AES-256-GCM encrypted full error |
| `metadata` | JSONB: `matcher_matched`, `cel_eval_result`, `stdout_len`, `http_status`, `prompt_model`, `prompt_tokens`, `trace_id` |

**`tenant_hook_budget`** — per-tenant monthly token limits (prompt handler only).

---

## Observability

Every hook execution emits a trace span named `hook.<handler_type>.<event>` (e.g. `hook.prompt.pre_tool_use`) with fields: `status`, `duration_ms`, `metadata.decision`, `parent_span_id`.

Slog keys:
- `security.hook.circuit_breaker` — breaker tripped.
- `security.hook.audit_write_failed` — audit row write error.
- `security.hook.loop_depth_exceeded` — `MaxLoopDepth` violation.
- `security.hook.prompt_parse_error` — evaluator returned malformed structured output.
- `security.hook.budget_deduct_failed` / `budget_precheck_failed` — budget store error.

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| HTTP hook always returns `error` | SSRF block on loopback | Use a public/internal URL accessible from the gateway process |
| Prompt hook blocks everything | Evaluator returning free-text (no tool call) | Review `prompt_template`; keep it short + imperative |
| Hook stopped firing | Circuit breaker tripped (5 blocks/min) | Fix upstream cause, then re-enable: `hooks.toggle { enabled: true }` |
| UI `command` radio greyed out | Standard edition | Use `http` or `prompt`, or upgrade to Lite |
| Per-turn cap hit | `max_invocations_per_turn` too low | Raise in hook config; tighten `matcher` to reduce LLM calls |
| Budget exceeded | Tenant spent monthly token budget | Raise `tenant_hook_budget.budget_total` or wait for rollover |
| `handler_type, event, and scope are required` | Missing fields in create payload | Include all three required fields |

---

## Migration from Old Quality Gates

Prior to the hooks system, delegation quality gates were configured inline in the source agent's `other_config.quality_gates` array. That system supported only `delegation.completed` events and two handler types (`command`, `agent`).

The new hooks system replaces it with:

| Old | New |
|---|---|
| `other_config.quality_gates[].event: "delegation.completed"` | `subagent_stop` (non-blocking) or `subagent_start` (blocking) |
| `other_config.quality_gates[].type: "command"` | `handler_type: "command"` (Lite) or `handler_type: "http"` (Standard) |
| `other_config.quality_gates[].type: "agent"` | `handler_type: "prompt"` with an LLM evaluator |
| `block_on_failure: true` + `max_retries` | Built-in blocking semantics; no retry loop needed (block is immediate) |

No data migration required when upgrading from a pre-hooks release. Migration `000052_agent_hooks` creates all three tables cleanly.

---

## What's Next

- [WebSocket Protocol](/websocket-protocol) — full `hooks.*` method reference
- [Exec Approval](/exec-approval) — human-in-the-loop approval for shell commands
- [Extended Thinking](/extended-thinking) — deeper reasoning before producing output



---

# Authentication

> Connect GoClaw to ChatGPT via OAuth — no API key needed, uses your existing OpenAI account.

## Overview

GoClaw supports OAuth 2.0 PKCE authentication for the OpenAI/Codex provider. This lets you use ChatGPT (the `openai-codex` provider) without a paid API key by authenticating through your OpenAI account via browser. Tokens are stored securely in the database and refreshed automatically before expiry.

This flow is distinct from standard API key providers — it is only needed if you want to use the `openai-codex` provider type.


## How It Works

```mermaid
flowchart TD
    UI["Web UI: click Connect ChatGPT"] --> START["POST /v1/auth/openai/start"]
    START --> PKCE["Gateway generates\nPKCE verifier + challenge"]
    PKCE --> SERVER["Callback server starts\non port 1455"]
    SERVER --> URL["Auth URL returned to UI"]
    URL --> BROWSER["User opens browser\n→ auth.openai.com"]
    BROWSER --> LOGIN["User logs in to OpenAI"]
    LOGIN --> CB["Browser redirects to\nlocalhost:1455/auth/callback"]
    CB --> EXCHANGE["Code exchanged for tokens\nat auth.openai.com/oauth/token"]
    EXCHANGE --> SAVE["Access token → llm_providers\nRefresh token → config_secrets"]
    SAVE --> READY["openai-codex provider\nregistered and ready"]
```

The gateway starts a temporary HTTP server on port **1455** to receive the OAuth callback. This port must be reachable from the browser (i.e. accessible on localhost when using the web UI locally, or via port forwarding for remote servers).

---

## Starting the OAuth Flow

### Via Web UI

1. Open the GoClaw web dashboard
2. Navigate to **Providers** → **ChatGPT OAuth**
3. Click **Connect** — the gateway calls `POST /v1/auth/openai/start` and returns an auth URL
4. Your browser opens `auth.openai.com` — log in and approve access
5. The callback lands on `localhost:1455/auth/callback` — tokens are saved automatically

### Remote / VPS Environments

If the browser callback can't reach port 1455 on the server, use the **manual redirect URL** fallback:

1. Start the flow via web UI — copy the auth URL
2. Open the auth URL in your local browser
3. After approving, your browser tries to redirect to `localhost:1455/auth/callback` and fails (since the server is remote)
4. Copy the full redirect URL from the browser address bar (it starts with `http://localhost:1455/auth/callback?code=...`)
5. Paste it into the web UI's manual callback field — the UI calls `POST /v1/auth/openai/callback` with the URL
6. The gateway extracts the code, completes the exchange, and saves the tokens

---

## CLI Commands

The `./goclaw auth` subcommand talks to the running gateway to check and manage OAuth state.

### Check Status

```bash
./goclaw auth status
```

Output when authenticated:

```
OpenAI OAuth: active (provider: openai-codex)
Use model prefix 'openai-codex/' in agent config (e.g. openai-codex/gpt-4o).
```

Output when not authenticated:

```
No OAuth tokens found.
Use the web UI to authenticate with ChatGPT OAuth.
```

The command hits `GET /v1/auth/openai/status` on the running gateway. The gateway URL is resolved from environment variables:

| Variable | Default |
|----------|---------|
| `GOCLAW_GATEWAY_URL` | — (overrides host+port) |
| `GOCLAW_HOST` | `127.0.0.1` |
| `GOCLAW_PORT` | `3577` |

Set `GOCLAW_TOKEN` to authenticate the CLI request if the gateway requires a token.

### Logout

```bash
./goclaw auth logout
# or explicitly:
./goclaw auth logout openai
```

This calls `POST /v1/auth/openai/logout`, which:

1. Deletes the `openai-codex` provider row from `llm_providers`
2. Deletes the refresh token from `config_secrets`
3. Unregisters the `openai-codex` provider from the in-memory registry

---

## Gateway OAuth Endpoints

All endpoints require `Authorization: Bearer <GOCLAW_TOKEN>`.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/auth/openai/status` | Check if OAuth is active and token is valid — returns `{ authenticated, provider_name? }` |
| `POST` | `/v1/auth/openai/start` | Start OAuth flow — returns `{ auth_url }` or `{ status: "already_authenticated" }` |
| `POST` | `/v1/auth/openai/callback` | Submit redirect URL for manual exchange — body: `{ redirect_url }` — returns `{ authenticated, provider_name, provider_id }` |
| `POST` | `/v1/auth/openai/logout` | Remove stored tokens and unregister provider — returns `{ status: "logged out" }` |

---

## Token Storage and Refresh

GoClaw stores OAuth tokens across two tables:

| Storage | What is stored |
|---------|---------------|
| `llm_providers` | Access token (as `api_key`), expiry timestamp in `settings` JSONB |
| `config_secrets` | Refresh token under key `oauth.openai-codex.refresh_token` |

The `DBTokenSource` handles the full lifecycle:

- **Cache**: the access token is cached in memory and reused until within 5 minutes of expiry
- **Auto-refresh**: when the token is about to expire, the refresh token is retrieved from `config_secrets` and a new token is fetched from `auth.openai.com/oauth/token`
- **Persistence**: both the new access token (in `llm_providers`) and new refresh token (in `config_secrets`) are written back to the database after refresh
- **Graceful degradation**: if refresh fails but a token still exists, the existing token is returned and a warning is logged — the provider stays usable until the token actually expires

The OAuth scopes requested during login are:

```
openid profile email offline_access api.connectors.read api.connectors.invoke
```

`offline_access` is what grants the refresh token for long-lived sessions.

---

## Using the Provider in Agent Config

Once authenticated, reference the provider with the `openai-codex/` prefix:

```json
{
  "agent": {
    "key": "my-agent",
    "provider": "openai-codex/gpt-4o"
  }
}
```

The `openai-codex` provider name is fixed — it matches the `DefaultProviderName` constant in the oauth package.

---

## Examples

**Check status after onboarding:**

```bash
source .env.local
./goclaw auth status
```

**Force re-authentication (logout then reconnect via UI):**

```bash
./goclaw auth logout
# then open web UI → Providers → Connect ChatGPT
```

---

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| `cannot reach gateway at http://127.0.0.1:3577` | Gateway not running | Start gateway first: `./goclaw` |
| `failed to start OAuth flow (is port 1455 available?)` | Port 1455 in use | Stop whatever is using port 1455 |
| Callback fails on remote server | Browser can't reach server port 1455 | Use the manual redirect URL flow (paste URL into web UI) |
| `token invalid or expired` from status endpoint | Refresh failed | Run `./goclaw auth logout` then re-authenticate |
| `unknown provider: xyz` from logout | Unsupported provider name | Only `openai` is supported: `./goclaw auth logout openai` |
| Agent gets 401 from ChatGPT | Token expired and refresh failed | Re-authenticate via web UI |

---

## What's Next

- [Providers Overview](/providers-overview) — all supported LLM providers and how to configure them
- [Hooks & Quality Gates](/hooks-quality-gates) — add validation to agent outputs



---

# API Keys & RBAC

> Manage API keys with role-based access control for multi-user and programmatic access deployments.

## Overview

GoClaw uses a **5-layer permission system**. API keys and roles sit at layer 1 — gateway authentication. When a request arrives, GoClaw checks the `Authorization: Bearer <token>` header, resolves the token to a role, and enforces that role against the method being called.

> API keys and tenant RBAC are only the first layer. Agent-config permissions, group/channel scopes, and channel-context credentials are documented in the [Permission Matrix](/permission-matrix).

Three roles exist:

| Role | Level | Description |
|------|-------|-------------|
| `admin` | 3 | Full access — can manage API keys, agents, config, teams, and everything below |
| `operator` | 2 | Read + write — can chat, manage sessions, crons, approvals, pairing |
| `viewer` | 1 | Read-only — can list/get resources but cannot modify anything |

Roles are **not set directly on an API key**. Instead, you assign **scopes** and GoClaw derives the effective role from those scopes at runtime.


## Method Permissions

| Methods | Required role |
|---------|---------------|
| `api_keys.list`, `api_keys.create`, `api_keys.revoke` | admin |
| `config.apply`, `config.patch` | admin |
| `agents.create`, `agents.update`, `agents.delete` | admin |
| `channels.toggle` | admin |
| `teams.list`, `teams.create`, `teams.delete` | admin |
| `pairing.approve`, `pairing.revoke` | admin |
| `chat.send`, `chat.abort` | operator |
| `sessions.delete`, `sessions.reset`, `sessions.patch` | operator |
| `cron.create`, `cron.update`, `cron.delete`, `cron.toggle` | operator |
| `approvals.*`, `exec.approval.*` | operator |
| `pairing.*`, `device.pair.*` | operator |
| `send` | operator |
| Everything else (list, get, read) | viewer |

---

## Backward Compatibility

If `gateway.token` is empty (no gateway token configured), all requests — including unauthenticated ones — are granted `RoleAdmin` access automatically. This lets self-hosted setups work without strict auth. Once a token is set, all requests must provide valid credentials or they receive `401 Unauthorized`.

---

## Authentication

All API requests use HTTP Bearer token authentication:

```
Authorization: Bearer <your-api-key>
```

The gateway also accepts the static token from `auth.token` in `config.json`. That token acts as a super-admin with no scope restrictions. API keys are the recommended way to grant scoped, revocable access to external systems.

---

## Key Format

API keys follow the format `goclaw_` + 32 lowercase hex characters (16 random bytes, 128-bit entropy):

```
goclaw_a1b2c3d4e5f6789012345678901234567890abcdef
```

The **display prefix** shown in list responses is `goclaw_` + the first 8 hex chars of the random part (e.g., `goclaw_a1b2c3d4`). This lets you identify a key in the UI without storing the secret.

**Show-once pattern:** the raw `key` field is returned only in the create response. All subsequent list/get calls return only `prefix`. Copy the key immediately after creation — it cannot be retrieved again.

---

## Creating an API Key

**Requires: admin role**

```bash
curl -X POST http://localhost:8080/v1/api-keys \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "scopes": ["operator.read", "operator.write"],
    "expires_in": 2592000
  }'
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Display name, max 100 characters |
| `scopes` | yes | One or more valid scope strings |
| `expires_in` | no | TTL in seconds; omit or set `null` for a non-expiring key |

Response (HTTP 201):

```json
{
  "id": "01944f3a-1234-7abc-8def-000000000001",
  "name": "ci-pipeline",
  "prefix": "goclaw_a1b2c3d4",
  "key": "goclaw_a1b2c3d4e5f6789012345678901234567890abcdef",
  "scopes": ["operator.read", "operator.write"],
  "expires_at": "2026-04-15T00:00:00Z",
  "created_at": "2026-03-16T10:00:00Z"
}
```

**The `key` field is shown only once.** Store it immediately — it cannot be retrieved again. Only the SHA-256 hash is kept in the database.

---

## Listing API Keys

**Requires: admin role**

```bash
curl http://localhost:8080/v1/api-keys \
  -H "Authorization: Bearer <admin-token>"
```

Response (HTTP 200):

```json
[
  {
    "id": "01944f3a-1234-7abc-8def-000000000001",
    "name": "ci-pipeline",
    "prefix": "goclaw_a1b2c3d4",
    "scopes": ["operator.read", "operator.write"],
    "expires_at": "2026-04-15T00:00:00Z",
    "last_used_at": "2026-03-16T09:55:00Z",
    "revoked": false,
    "created_at": "2026-03-16T10:00:00Z"
  }
]
```

The `prefix` field (first 8 characters) lets you identify a key without storing the secret. The raw key is never returned after creation.

---

## Revoking an API Key

**Requires: admin role**

```bash
curl -X POST http://localhost:8080/v1/api-keys/<id>/revoke \
  -H "Authorization: Bearer <admin-token>"
```

Response (HTTP 200):

```json
{ "status": "revoked" }
```

Revocation takes effect immediately — the key is marked revoked in the database and the in-process cache is cleared via pubsub.

---

## WebSocket RPC Methods

API key management is also available over the WebSocket connection. All three methods require `operator.admin` scope.

### List keys

```json
{ "type": "req", "id": "1", "method": "api_keys.list" }
```

### Create a key

```json
{
  "type": "req",
  "id": "2",
  "method": "api_keys.create",
  "params": {
    "name": "dashboard-readonly",
    "scopes": ["operator.read"]
  }
}
```

### Revoke a key

```json
{
  "type": "req",
  "id": "3",
  "method": "api_keys.revoke",
  "params": { "id": "01944f3a-1234-7abc-8def-000000000001" }
}
```

---

## Security Details

### SHA-256 hashing

Raw API keys are never stored. On creation, GoClaw generates a random key, stores only its `SHA-256` hex digest, and returns the raw value once. Every inbound request is hashed before the database lookup.

### In-process cache with TTL

After the first lookup, the resolved key data and role are cached in memory for **5 minutes**. This eliminates repeated database round-trips on busy endpoints. The cache is keyed by hash — not the raw token.

### Negative cache

If an unknown token is presented (e.g., a typo or a revoked key that has since been evicted), GoClaw caches the miss as a **negative entry** to avoid hammering the database. The negative cache is capped at **10,000 entries** to prevent memory exhaustion from token-spraying attacks.

### Cache invalidation

When a key is created or revoked, a `cache.invalidate` event is broadcast on the internal message bus. All active HTTP handlers clear their caches immediately — no stale entries survive a revocation.

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| `401 Unauthorized` on key management endpoints | Caller is not admin role | Use the gateway token or a key with `operator.admin` scope |
| `400 invalid scope: X` | Scope string is not recognised | Use only: `operator.admin`, `operator.read`, `operator.write`, `operator.approvals`, `operator.pairing` |
| `400 name is required` | `name` field missing or empty | Add `"name": "..."` to the request body |
| `400 scopes is required` | `scopes` array is empty or missing | Include at least one scope |
| Key shows `revoked: false` after revocation | Cache TTL (5 min) not yet expired | Wait up to 5 minutes or restart the gateway |
| Raw key lost after creation | Raw key is only returned once by design | Revoke the key and create a new one |
| `404` on revoke | Key ID is wrong or already revoked | Double-check the UUID from the list endpoint |

---

## What's Next

- [Permission Matrix](/permission-matrix) — agent-config permissions, group/channel scopes, and the full authorization-layer table
- [Authentication & OAuth](/authentication) — gateway token and OAuth flow
- [Exec Approval](/exec-approval) — require `operator.approvals` scope
- [Security Hardening](/deploy-security) — full 5-layer permission overview
- [CLI Credentials](./cli-credentials.md) — SecureCLI: inject credentials into CLI tools (gh, aws, gcloud) without exposing secrets to the agent



---

# Agent Permission Matrix

> The full set of authorization layers that decide what an agent can do across channels, groups, and workspaces — and how those layers combine.

## Overview

A single agent action (sending a reply, writing a workspace file, editing a context file) passes through several independent permission layers. Each layer can allow or deny, and they stack: an action is only permitted when every applicable layer allows it. This page maps those layers, the agent-config permission rules you can grant from chat, the per-channel matrix, and the rules that most often surprise people (Zalo context writes and channel-context credentials).

If you only need gateway-token roles, see [API Keys & RBAC](/api-keys-rbac) — that is layer 1. This page covers the layers above it.

## Permission Layers

| Layer | Scope | Notes |
|-------|-------|-------|
| Tenant RBAC | Dashboard, HTTP, WebSocket RPC | Viewer / operator / admin / owner. Admin-only methods include `config.permissions.*`. |
| Agent ownership / share | Which agents a user can see and manage | Owner plus explicit shares; see [Sharing & Access Control](/sharing-and-access). |
| Channel membership | Platform delivery | The platform can still reject outbound delivery after GoClaw allows the action. |
| Agent config permissions | Config mutations driven from chat | Matched by `agent_id`, `scope`, `config_type`, and `user_id`, including wildcard rows. |
| Workspace file boundary | Filesystem access | Prevents path escape and unsupported writes. |
| Context file boundary | Agent identity / context files | Protected files are routed to the store and require group writer permission in group contexts. |
| Channel context capabilities | MCP + Secure CLI tool execution | Credential precedence: user credentials > context credentials/grants > agent grants > global defaults. |

## Agent Config Permission Rows

Agents can have parts of their configuration changed from chat (for example, enabling a file writer or a heartbeat). Each permission rule is a row with four fields:

| Field | Examples | Meaning |
|-------|----------|---------|
| `scope` | `agent`, `group:*`, `group:zalo:123`, `group:telegram:-100`, `*` | Where the grant applies. |
| `config_type` | `file_writer`, `heartbeat`, `cron`, `context_files`, `*` | Which family of actions the grant covers. |
| `user_id` | `123456`, `zalo-user-id`, `*` | Who the grant covers. `*` grants every member in the selected scope. |
| `permission` | `allow`, `deny` | The decision. A deny can override a broader allow. |

### Effective precedence

When several rows match a request, GoClaw resolves them top-down and stops at the first that applies:

1. Individual deny.
2. Individual allow.
3. Scope/user wildcard deny.
4. Scope/user wildcard allow.
5. Default deny.

So a specific `deny` for one user always beats a wildcard `allow`, and anything not matched is denied by default.

## Channel Matrix

What an agent can do depends on where the request came from. This table summarizes the common channel contexts.

| Channel context | Read agent output | Send reply | Write workspace file | Write protected context file | Grant all members |
|-----------------|-------------------|------------|----------------------|------------------------------|-------------------|
| Dashboard | RBAC controlled | N/A | Admin/operator path, then workspace boundary | Admin path, then context interceptor | Use the Permissions tab |
| Direct message | Agent/session access | Channel adapter | Allowed by workspace boundary | Allowed by agent/context rules | Usually not needed |
| Telegram group | Group scope + sender ID | Channel adapter | Requires `file_writer` when group-gated | Requires `context_files` or `file_writer` and a real sender | `scope=group:telegram:<chatId>`, `user_id=*` |
| Zalo group | Group scope + sender ID | Channel adapter, group thread metadata | Requires `file_writer` when group-gated | Requires `context_files` or `file_writer` and a real sender | `scope=group:zalo:<chatId>`, `user_id=*` |
| Discord guild/channel | Guild scope + sender ID | Channel adapter | Requires `file_writer` when guild-gated | Requires `context_files` or `file_writer` and a real sender | `scope=guild:<id>` or matching group scope, `user_id=*` |
| Scheduled / proactive run | System sender | Channel adapter | Denied for group-gated writes unless elevated context | Denied for protected group context writes | Configure explicit rules, or run from a dashboard/admin context |

## Zalo Context-Write Rule

A common Zalo group failure is an agent trying to write a protected context file — `SOUL.md`, `IDENTITY.md`, `AGENTS.md`, `USER.md`, `USER_PREDEFINED.md`, or `CAPABILITIES.md` — from a group session where the acting sender is missing. Protected context writes go through the group permission gate, which requires:

- `sender_id` is a **real platform user**, not empty or synthetic.
- `user_id` identifies the group scope, for example `group:zalo:<chatId>`.
- The sender matches a `context_files` allow (or a legacy `file_writer` allow), including wildcard rows such as `user_id="*"`.
- Missing tenant context or permission-store errors **fail closed** — the write is denied rather than allowed.

If a Zalo group write is being rejected, check that the message carries a real sender and that a matching `context_files` rule exists for that group scope.

## Permissions Tab (UX)

The dashboard Permissions tab is a full matrix editor for the rows above:

| Control | Behavior |
|---------|----------|
| User/contact picker | Accepts explicit user IDs and contact search results. |
| All members button | Sets `user_id="*"` for the current rule. |
| Config type selector | `file_writer`, `heartbeat`, `cron`, `context_files`, or `*`. |
| Scope selector | Known groups, `group:*`, `agent`, or `*`. |
| Check access | Calls `config.permissions.check` and shows the effective allow/deny decision before or after saving. |

Use **Check access** to preview the effective decision for a specific user and scope without saving — it runs the same precedence resolution the runtime uses.

## Channel Context Capabilities

Channel instances expose stored contexts in the dashboard and API. The base context is the channel instance itself; group contexts come from stored channel contacts. Each capability row combines MCP and Secure CLI visibility for that context — source, enabled state, tool allow/deny lists, and whether a credential is present.

Context credential rows **never return secret material**. They project only metadata such as `has_api_key`, `has_env`, `credential_source`, and key names where available. Writes are tenant-admin gated, and runtime resolution carries a `ChannelContextScope` so grants and credentials apply only to the matching channel/group scope.

### Channel-context credential precedence

When a tool runs in a channel context, GoClaw resolves credentials in this order — first match wins:

1. User credentials.
2. Context credentials / grants.
3. Agent grants.
4. Global defaults.

This mirrors the typed-credential precedence used by the git adapter (see [CLI Credentials](/cli-credentials)).

## Security Notes

- A wildcard `user_id="*"` should be easy to grant but always **visually explicit** — it expands access to every member in scope.
- Synthetic senders stay denied for group file/context writes, so a system turn never inherits permissions from a real user it isn't.
- Permission-store errors **fail closed** at group mutation boundaries.
- Backend validation rejects unknown config types and permissions before any rule is written.
- Platform send permissions are separate from GoClaw permissions: a channel adapter may still reject delivery even when GoClaw allows the agent action.

## Common Issues

| Problem | Solution |
|---------|----------|
| Zalo group context write rejected | Ensure the message has a real `sender_id` and a matching `context_files` (or `file_writer`) allow for `group:zalo:<chatId>`. |
| Wildcard allow not taking effect | An individual `deny` beats a wildcard `allow`. Remove the deny or scope it more narrowly. |
| Scheduled run can't write a group file | Proactive/system runs are denied for group-gated writes — configure an explicit rule or run from a dashboard/admin context. |
| Reply sent by GoClaw never arrives | The channel adapter rejected delivery — GoClaw permissions and platform send permissions are independent. |

## What's Next

- [API Keys & RBAC](/api-keys-rbac) — layer 1: gateway-token roles and scopes
- [Sharing & Access Control](/sharing-and-access) — agent ownership and shares
- [CLI Credentials](/cli-credentials) — typed credentials and channel-context credential precedence
- [Security Hardening](/deploy-security) — the full five-layer security overview



---

# CLI Credentials

> Securely store and manage named credential sets for shell tool execution, with per-agent access control via grants.

## Overview

CLI Credentials let you define named credential sets (API keys, tokens, connection strings) that agents can reference when running shell commands via the `exec` tool — without exposing secrets in the system prompt or conversation history.

Each credential is stored as a **secure CLI binary** — a named configuration that maps a binary (e.g. `gh`, `gcloud`, `aws`) to an AES-256-GCM encrypted set of environment variables. When an agent runs the binary, GoClaw decrypts the env vars and injects them into the child process at execution time.

## Global vs Per-Agent Binaries

Since migration 036, the access model uses a **grants system** instead of per-binary agent assignment:

- **Global binaries** (`is_global = true`): available to all agents unless a grant overrides settings
- **Restricted binaries** (`is_global = false`): only accessible to agents that have an explicit grant

This separates credential definition from access control, allowing you to define a binary once and grant it to specific agents with optional per-agent overrides.

```
secure_cli_binaries (credential + defaults)
        │
        ├── is_global = true  → all agents can use it
        └── is_global = false → only agents with a grant
                    │
                    └── secure_cli_agent_grants (per-agent override)
                            ├── deny_args (NULL = use binary default)
                            ├── deny_verbose (NULL = use binary default)
                            ├── timeout_seconds (NULL = use binary default)
                            ├── tips (NULL = use binary default)
                            ├── enabled
                            └── encrypted_env (BYTEA, AES-256-GCM — optional per-grant env override)
```

## Agent Grants

The `secure_cli_agent_grants` table links a binary to a specific agent and optionally overrides any of the binary's default settings. `NULL` fields inherit the binary default.

| Field | Behaviour |
|-------|-----------|
| `deny_args` | Override forbidden argument patterns for this agent |
| `deny_verbose` | Override verbose flag stripping for this agent |
| `timeout_seconds` | Override process timeout for this agent |
| `tips` | Override the hint injected into TOOLS.md for this agent |
| `enabled` | Disable a grant without deleting it |
| `encrypted_env` | Optional per-grant env-var overrides (AES-256-GCM encrypted at rest) |

When an agent runs a binary, GoClaw resolves settings in this order:
1. Binary defaults
2. Grant overrides (any non-null fields replace the binary default)
3. Per-grant `encrypted_env` is decrypted and merged into the child process environment at execution time (overrides binary-level env vars for this agent only)

## Per-Agent Env Overrides

Since migration `000058`, each `secure_cli_agent_grants` row can carry an optional `encrypted_env` column (BYTEA, AES-256-GCM). This lets you give one agent a different set of environment variables for the same binary — for example, a different AWS account, a separate API key, or a staging endpoint — without creating a separate binary definition.

**How it works:**

- On grant create/update, send `env_vars` (a plaintext `string → string` map) in the request body.
- GoClaw validates the keys against the denylist, then encrypts and persists them in `encrypted_env`.
- Plaintext values are never stored or logged; the store layer encrypts before write and decrypts on read.
- List and get responses expose only `env_keys` (sorted list of key names) and `env_set` (boolean). Values are never returned except via the `env:reveal` endpoint.

**Create a grant with env overrides:**

```bash
curl -X POST http://localhost:8080/v1/cli-credentials/{id}/agent-grants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "019...",
    "env_vars": {
      "AWS_PROFILE": "staging",
      "AWS_DEFAULT_REGION": "us-west-2"
    }
  }'
```

Response (`201 Created`) includes `env_keys` but no values:

```json
{
  "id": "019...",
  "binary_id": "019...",
  "agent_id": "019...",
  "env_keys": ["AWS_DEFAULT_REGION", "AWS_PROFILE"],
  "env_set": true,
  "enabled": true,
  "created_at": "2026-05-21T00:00:00Z",
  "updated_at": "2026-05-21T00:00:00Z"
}
```

**Update env vars on an existing grant:**

Send `env_vars` in the `PUT` body. Three-state semantics:
- **Absent** — existing env is unchanged
- **`null`** — clears the env override (removes `encrypted_env`)
- **`{...}`** — replaces the entire env map (empty `{}` treated the same as `null`)

```bash
curl -X PUT http://localhost:8080/v1/cli-credentials/{id}/agent-grants/{grantId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"env_vars": null}'
```

## Revealing Decrypted Env Vars

`POST /v1/cli-credentials/{id}/agent-grants/{grantId}/env:reveal` returns the decrypted plaintext env vars for a specific grant. The endpoint is POST (not GET) to prevent HTTP caching and satisfy CSRF semantics.

**Security controls:**
- Requires `admin` role scoped to the correct tenant — master-scope callers are rejected.
- Rate-limited to **10 reveals per minute per authenticated user** (burst of 3). Returns `429` when exceeded.
- Response headers include `Cache-Control: no-store` to prevent proxy caching.
- Every call is audited: caller ID, tenant ID, grant ID, binary ID, and timestamp are logged at INFO level.

```bash
curl -X POST http://localhost:8080/v1/cli-credentials/{id}/agent-grants/{grantId}/env:reveal \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json
{
  "env_vars": {
    "AWS_PROFILE": "staging",
    "AWS_DEFAULT_REGION": "us-west-2"
  }
}
```

Returns `{"env_vars": {}}` when no env override is set for the grant.

## Env Denylist

Not all environment variable names are accepted. GoClaw rejects keys that could allow privilege escalation, shell injection, TLS bypass, or exfiltration.

**Key shape requirement:** keys must match `^[A-Z_][A-Z0-9_]*$` — uppercase, digits, underscores only. Lowercase, spaces, and special characters (including Shellshock-class function definitions) are rejected.

**Exact-match denials:**

| Key | Reason |
|-----|--------|
| `PATH`, `HOME`, `USER`, `SHELL`, `PWD` | Core shell/user identity |
| `LD_PRELOAD`, `LD_LIBRARY_PATH`, `LD_AUDIT` | Dynamic linker hijack |
| `NODE_OPTIONS`, `NODE_PATH` | Node.js code injection |
| `PYTHONPATH`, `PYTHONHOME`, `PYTHONSTARTUP` | Python path/startup injection |
| `GIT_SSH_COMMAND`, `GIT_SSH`, `GIT_EXEC_PATH`, `GIT_CONFIG_SYSTEM` | Git command injection |
| `SSH_AUTH_SOCK` | SSH key forwarding |
| `BASH_ENV`, `ENV` | Non-interactive shell sourcing |
| `PROMPT_COMMAND` | Shell prompt execution |
| `PERL5LIB`, `RUBYOPT` | Perl/Ruby library injection |
| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | Exfiltration channel / proxy bypass |
| `SSL_CERT_FILE`, `SSL_CERT_DIR`, `CURL_CA_BUNDLE` | TLS CA override (MitM) |
| `IFS` | Shell Internal Field Separator injection |

**Prefix-match denials:** any key beginning with `DYLD_`, `GOCLAW_`, `LD_`, or `NPM_CONFIG_` is rejected.

**Limits:** maximum 50 keys per grant; maximum 4 096 bytes per value; values must not contain NUL bytes or newlines.

A `400` response on create/update includes the rejected key names in `rejected_keys`:

```json
{
  "error": "env keys denied: LD_PRELOAD, PATH",
  "rejected_keys": "LD_PRELOAD,PATH"
}
```

## REST API

All grant endpoints are nested under the binary resource and require the `admin` role.

### List grants for a binary

```
GET /v1/cli-credentials/{id}/agent-grants
```

```json
{
  "grants": [
    {
      "id": "019...",
      "binary_id": "019...",
      "agent_id": "019...",
      "deny_args": null,
      "timeout_seconds": 60,
      "enabled": true,
      "env_keys": [],
      "env_set": false,
      "created_at": "2026-04-05T00:00:00Z",
      "updated_at": "2026-04-05T00:00:00Z"
    }
  ]
}
```

### Create a grant

```
POST /v1/cli-credentials/{id}/agent-grants
```

```json
{
  "agent_id": "019...",
  "timeout_seconds": 120,
  "tips": "Use --output json for all commands",
  "env_vars": {
    "MY_API_KEY": "secret-value"
  }
}
```

Omitted fields (`deny_args`, `deny_verbose`, `tips`, `enabled`, `env_vars`) default to `null` / `true`. `env_vars` values are encrypted at rest; only key names are returned in subsequent list/get calls.

### Get a grant

```
GET /v1/cli-credentials/{id}/agent-grants/{grantId}
```

### Update a grant

```
PUT /v1/cli-credentials/{id}/agent-grants/{grantId}
```

Send only the fields to change. Allowed fields: `deny_args`, `deny_verbose`, `timeout_seconds`, `tips`, `enabled`, `env_vars`.

### Delete a grant

```
DELETE /v1/cli-credentials/{id}/agent-grants/{grantId}
```

Deleting a grant from a restricted binary (`is_global = false`) immediately revokes the agent's access to that binary.

### Reveal env vars for a grant

```
POST /v1/cli-credentials/{id}/agent-grants/{grantId}/env:reveal
```

Returns the decrypted plaintext env vars. Rate-limited to 10 calls/minute per user. See [Revealing Decrypted Env Vars](#revealing-decrypted-env-vars) for full details.

## Typed Credential Adapters

The sections above describe the **legacy env-paste model** — you paste arbitrary environment variables and GoClaw injects them verbatim into the child process. That works for tools that read auth from a single stable env var (`GH_TOKEN`, `AWS_ACCESS_KEY_ID`, …), but it fails for tools like `git` that read credentials from config files, credential helpers, or per-remote URLs — pasting a PAT into `GIT_TOKEN` does nothing.

**Typed credential adapters** solve this. Instead of pasting raw env vars, you choose a credential *type*, and GoClaw routes the credential through a server-side adapter that knows how to inject it correctly and securely for that specific tool.

### Credential types

A typed credential row carries a `credential_type`:

| `credential_type` | Meaning |
|-------------------|---------|
| `NULL` / `env` | Legacy env passthrough — env vars injected verbatim, exactly as before. No host scoping. |
| `pat` | Personal Access Token, for HTTPS git remotes (GitHub/GitLab/Gitea). Requires a `host_scope`. |
| `ssh_key` | SSH private key (PEM), for git over SSH. Requires a `host_scope`. |

`NULL`/`env` rows are never migrated — existing legacy credentials keep working unchanged. Typed adapters are opt-in per credential.

### Agent credentials (default git path)

Agent credentials are the **default** path for git auth. They avoid channel-user ID ambiguity: the selected agent owns the credential, and anyone allowed to use that agent can cause it to run git with the stored credential.

Agent credentials live in the `secure_cli_agent_credentials` table (migration `000077`), which stores the typed secret material **separately** from the `secure_cli_agent_grants` policy row. There is one credential per `(agent, binary)`.

**Add an agent credential (UI):**

1. Open **Packages → CLI Credentials**.
2. Pick the `git` row and open **Agent Access**.
3. On the **Credential** tab, select the agent.
4. Choose **Credential Type**: `Personal Access Token` or `SSH Private Key`.
5. Enter the **Host Scope** (required for PAT/SSH): the hostname the credential authenticates to (e.g. `github.com`, `gitlab.example.com`, `gitea.internal:8443`).
6. Paste the token (PAT) or the unencrypted PEM body (SSH).
7. Save.

The **Agent Access** dialog has two tabs:

- **Credential** — pick the agent, credential type, host scope, and secret (above).
- **Access policy** — change deny args, timeout, tips, or env overrides for that agent (the `secure_cli_agent_grants` row).

Policy and secret storage stay separate internally, but you manage them as one access decision in this single dialog. The stored secret is AES-256-GCM encrypted and can never be read back — editing the row shows a `••••••••` placeholder.

### Effective credential precedence

When git runs, GoClaw resolves which typed credential to inject in this order — the **first** match wins:

1. **User override** — a per-user typed credential (Advanced user overrides, below).
2. **Channel/context credential** — a credential scoped to the channel or group context the run originated from.
3. **Agent credential** — the agent's own `secure_cli_agent_credentials` row. This is the default trust boundary.
4. **Binary-level env defaults** — the legacy passthrough env on the binary definition.

Granting an agent access to git effectively grants use of its stored git credential, so the agent credential is the default boundary unless a higher layer (user override or channel/context credential) is present.

### Advanced user overrides

Per-user credentials remain available for personal overrides and backward compatibility. Use them only when a stable tenant user ID is the intended credential boundary — they sit **above** agent credentials in the precedence order.

Manage them in the dashboard under **Packages → CLI Credentials → Advanced User Overrides → Add**: select the user, choose the credential type (`Personal Access Token` or `SSH Private Key`), enter the **Host Scope**, and paste the secret. The stored secret is AES-256-GCM encrypted and can never be read back — leaving the secret field blank on edit preserves the stored value, typing a new value replaces it.

These rows live in the `secure_cli_user_credentials` table.

### Agent credentials REST API

The agent-credentials endpoints manage the typed secret for one `(binary, agent)` pair. They require the `admin` role.

#### List agent credentials for a binary

```
GET /v1/cli-credentials/{id}/agent-credentials
```

Returns the agents that have a stored credential for this binary, with metadata only (credential type, host scope, key presence) — never the secret.

#### Get one agent's credential

```
GET /v1/cli-credentials/{id}/agent-credentials/{agentId}
```

#### Set (create or replace) an agent's credential

```
PUT /v1/cli-credentials/{id}/agent-credentials/{agentId}
```

Send `credential_type`, `host_scope`, and the secret (`env_vars` for `env`, or the typed PAT/SSH key body). The secret is encrypted at rest and never returned.

#### Delete an agent's credential

```
DELETE /v1/cli-credentials/{id}/agent-credentials/{agentId}
```

Removes the stored secret. The agent's `secure_cli_agent_grants` policy row (deny args, timeout, etc.) is unaffected — delete the grant separately to revoke access.

### The git adapter

The `git` adapter is the first shipped typed adapter. It injects credentials **only** for network subcommands:

```
clone   fetch   pull   push   submodule
```

Any other subcommand (`status`, `log`, `diff`, `commit`, `branch`, …) is a local operation and runs **uncredentialed** — no injection, no audit-log line.

**PAT flow.** The token is injected through environment variables, never on `argv`:

```
GIT_CONFIG_COUNT=1
GIT_CONFIG_KEY_0=http.https://<host>/.extraheader
GIT_CONFIG_VALUE_0=Authorization: Basic base64("x-access-token:<token>")
```

The header value is HTTP Basic auth: the literal username `x-access-token` and your token joined by a colon, base64-encoded. Because the token lives in an env value (not a command-line flag), it never appears in `ps`, `/proc/<pid>/cmdline`, or shell history. The injected vars are scoped to the spawned `git` process only — GoClaw's own environment and sibling exec calls never see them.

The raw token, the base64 payload, **and** the full `Authorization: Basic …` header are all registered with the output scrubber, so none of the three can leak back to the agent through stdout, stderr, error messages, or the audit log.

**SSH flow.** The PEM key is written to a `0600`-mode tmpfile in the system temp dir (prefix `goclaw-gitkey-*`), and `GIT_SSH_COMMAND` is set to:

```
ssh -i <tmpfile> -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=accept-new
```

`BatchMode=yes` means SSH never prompts and fails fast in the agent context. `StrictHostKeyChecking=accept-new` accepts unknown host keys on **first contact (TOFU)**. Pre-seed `~/.ssh/known_hosts` to close the window (see [Security Hardening](/deploy-security)). The tmpfile is removed after exec via a deferred cleanup. **SSH private keys are validated twice at save time** — first with Go's SSH parser, then with OpenSSH (`ssh-keygen -y -f <tmpfile>`) when `ssh-keygen` is available — to catch keys that would save but later fail with OpenSSH diagnostics. **Passphrase-protected SSH keys are rejected at save time** — re-export your key without a passphrase, or use a dedicated deploy key.

### Host scope

Both `pat` and `ssh_key` require a **`host_scope`** — the exact ASCII `host` or `host:port` the credential is valid for. It is normalized to lowercase ASCII (via `idna.ToASCII`) and matched **exactly**. v1 has **no wildcards**, and the port is part of the key:

| Stored `host_scope` | `github.com` | `api.github.com` | `github.com:8443` |
|---------------------|:---:|:---:|:---:|
| `github.com` | ✓ | ✗ | ✗ |

If you run a self-hosted server on the scheme's default port (443 HTTPS, 22 SSH), omit the port; if on a non-default port, include it (e.g. `gitea.internal:8443`). When no typed PAT/SSH credential is selected, or the selected credential cannot match the resolved remote host, **adapter-managed remote git commands fail closed with a GoClaw diagnostic**. `git` is **not** allowed to fall through to an interactive username/password prompt in agent runtime.

### Env visibility: sensitive vs non-sensitive

Stored env entries now carry a `kind`. When the dashboard or admin API reads a credential back, the response masks values according to kind:

| `kind` | In API response |
|--------|-----------------|
| `sensitive` (default; legacy string maps decode here) | `value: null`, `masked: true` |
| `value` (explicitly non-sensitive, e.g. a region or profile name) | plain value returned, `masked: false` |

This lets operators see non-secret context (e.g. `AWS_DEFAULT_REGION=us-west-2`) in the UI while secrets stay masked. Secrets are still never returned except via the dedicated `env:reveal` endpoint.

### Migrating from legacy env credentials

There is no forced migration. A row with `credential_type IS NULL` or `= 'env'` keeps emitting its env vars exactly as before. To upgrade a git credential, create a matching **Agent Credential** (or, if a stable user ID is the intended boundary, an Advanced user override), enter the host scope, paste the secret, and save. Existing user overrides remain higher precedence than agent credentials, so you can migrate gradually and remove the user override when it is no longer needed.

### v1 limitations

- **One credential per `(agent, binary)` row**, plus a legacy one credential per `(user, binary)` override.
- **No wildcard hosts** — one credential per exact `host[:port]`; `*.github.com` is not supported.
- **No passphrase-protected SSH keys** — rejected at validation time.
- **No sandbox propagation** — the adapter mutates the forked child's environment, which is incompatible with the bind-mount Docker sandbox path. Credentialed exec runs on the host only in v1.
- **No host-key pinning** — SSH uses TOFU (`accept-new`); pre-seed `known_hosts`.

### Google Workspace CLI (gws)

GoClaw ships a `gws` preset for the Google Workspace CLI (`@googleworkspace/cli`).

**Availability.** The `gws` binary is preinstalled **only in the published `full` Docker image**. On `latest`/`base` images, install `@googleworkspace/cli` from the Packages page (requires a Node-enabled build, `ENABLE_NODE=true`; Node.js 18+).

**Credentials.** Create a SecureCLI credential from the `gws` preset and provide at least one auth source:

| Env var | Purpose |
|---------|---------|
| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to exported `gws` credentials or an OAuth credentials JSON file |
| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained Google OAuth access token (optional) |
| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID for manual auth flows (optional) |
| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret for manual auth flows (optional) |

**Blocked commands.** The preset blocks interactive and credential-exporting auth flows:

```
gws auth setup    gws auth login    gws auth export    gws auth logout
```

Run those flows outside agent execution, then store the resulting token or credentials-file path in SecureCLI.

**Usage.** Default usage is read-oriented. Use `--params` for query parameters, `--json` for request bodies, and `--page-all` for paginated reads:

```sh
gws drive files list --params '{"pageSize": 10}'
gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'
```

> **Write caution.** Write commands can modify Workspace data. Keep the default preset read-oriented and create a separate, reviewed SecureCLI config for any approved write workflow.

## Common Patterns

### Allow only one agent to use a sensitive CLI tool

1. Create the binary with `is_global = false`
2. Create a grant for the target agent

### Give all agents access but restrict args for one agent

1. Create the binary with `is_global = true`
2. Create a grant for the restricted agent with `deny_args` set to additional blocked patterns

### Temporarily disable an agent's access

Update the grant: `{"enabled": false}`. The binary remains accessible to other agents.

## Common Issues

| Problem | Solution |
|---------|----------|
| Agent cannot run a binary | Check `is_global` on the binary — if `false`, the agent needs an explicit grant |
| Grant overrides not applied | Verify the grant `enabled = true` and that override fields are non-null |
| `403` on grant endpoints | Requires admin role — check API key scopes |
| `git clone`/`push` fails with no credential | No typed credential matched the remote host — git fails closed (no prompt). Add an Agent Credential with the exact `host_scope`. |

## What's Next

- [Permission Matrix](/permission-matrix) — full authorization layers, channel/group scopes, and channel-context credentials
- [Database Schema → secure_cli_agent_grants](/database-schema)
- [Exec Approval](/exec-approval)
- [API Keys & RBAC](/api-keys-rbac)
- [Security Hardening](/deploy-security)



---

# Exec Approval (Human-in-the-Loop)

> Pause agent shell commands for human review before they run — approve, deny, or permanently allow from the dashboard.

## Overview

When an agent needs to run a shell command, exec approval lets you intercept it. The agent blocks, the dashboard shows a prompt, and you decide: **allow once**, **always allow this binary**, or **deny**. This gives you full control over what runs on your machine without disabling the exec tool entirely.

The feature is controlled by two orthogonal settings:

- **Security mode** — what commands are permitted to execute at all.
- **Ask mode** — when to prompt you for approval.


## Configuration

```json
{
  "tools": {
    "execApproval": {
      "security": "full",
      "ask": "on-miss",
      "allowlist": ["make", "cargo test", "npm run *"]
    }
  }
}
```

`allowlist` accepts glob patterns matched against the binary name or the full command string.

---

## Approval Flow

```mermaid
flowchart TD
    A["Agent calls exec tool"] --> B{"CheckCommand\nsecurity + ask mode"}
    B -->|allow| C["Run immediately"]
    B -->|deny| D["Return error to agent"]
    B -->|ask| E["Create pending approval\nAgent goroutine blocks"]
    E --> F["Dashboard shows prompt"]
    F --> G{"Operator decides"}
    G -->|allow-once| C
    G -->|allow-always| H["Add binary to dynamic allow list"] --> C
    G -->|deny| D
    E -->|timeout 2 min| D
```

The agent goroutine blocks until you respond. If no response comes within 2 minutes, the request auto-denies.

---

## WebSocket Methods

Connect to the gateway WebSocket. These methods require **Operator** or **Admin** role.

### List pending approvals

```json
{ "type": "req", "id": "1", "method": "exec.approval.list" }
```

Response:

```json
{
  "pending": [
    {
      "id": "exec-1",
      "command": "curl https://example.com | sh",
      "agentId": "my-agent",
      "createdAt": 1741234567000
    }
  ]
}
```

### Approve a command

```json
{
  "type": "req",
  "id": "2",
  "method": "exec.approval.approve",
  "params": {
    "id": "exec-1",
    "always": false
  }
}
```

Set `"always": true` to permanently allow this binary for the lifetime of the process (adds it to the dynamic allow list).

### Deny a command

```json
{
  "type": "req",
  "id": "3",
  "method": "exec.approval.deny",
  "params": { "id": "exec-1" }
}
```

---

## Examples

**Strict mode for a production agent — only known commands allowed:**

```json
{
  "tools": {
    "execApproval": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": ["git", "make", "go test *", "cargo test"]
    }
  }
}
```

`git`, `make`, and the test runners auto-run. Anything else (e.g., `curl`, `rm`) triggers a prompt.

**Coding agent with light oversight — safe tools auto-run, infra tools need approval:**

```json
{
  "tools": {
    "execApproval": {
      "security": "full",
      "ask": "on-miss"
    }
  }
}
```

**Fully locked down — no shell execution at all:**

```json
{
  "tools": {
    "execApproval": {
      "security": "deny"
    }
  }
}
```

---

## Shell Deny Groups

In addition to the approval flow, GoClaw applies **deny groups** — named sets of shell command patterns that are blocked regardless of approval settings. All groups are enabled by default.

### Available Deny Groups

| Group | Description | Examples Blocked |
|-------|-------------|-----------------|
| `destructive_ops` | Destructive Operations | `rm -rf`, `dd if=`, `shutdown`, fork bombs |
| `data_exfiltration` | Data Exfiltration | `curl \| sh`, `wget --post-data`, DNS lookups via dig/nslookup |
| `reverse_shell` | Reverse Shell | `nc`, `socat`, `python -c '...socket...'`, `mkfifo` |
| `code_injection` | Code Injection & Eval | `eval $()`, `base64 -d \| sh` |
| `privilege_escalation` | Privilege Escalation | `sudo`, `su`, `mount`, `nsenter`, `pkexec` |
| `dangerous_paths` | Dangerous Path Operations | `chmod +x /tmp/...`, `chown ... /` |
| `env_injection` | Environment Variable Injection | `LD_PRELOAD=`, `DYLD_INSERT_LIBRARIES=`, `BASH_ENV=` |
| `container_escape` | Container Escape | `/var/run/docker.sock`, `/proc/sys/kernel/`, `/sys/kernel/` |
| `crypto_mining` | Crypto Mining | `xmrig`, `cpuminer`, `stratum+tcp://` |
| `filter_bypass` | Filter Bypass (CVE mitigations) | `sed .../e`, `sort --compress-program`, `git --upload-pack=` |
| `network_recon` | Network Reconnaissance & Tunneling | `nmap`, `ssh user@host`, `ngrok`, `chisel` |
| `package_install` | Package Installation | `pip install`, `npm install`, `apk add` |
| `persistence` | Persistence Mechanisms | `crontab`, writing to `~/.bashrc` or `~/.profile` |
| `process_control` | Process Manipulation | `kill -9`, `killall`, `pkill` |
| `env_dump` | Environment Variable Dumping | `printenv`, `env \| ...`, reading `GOCLAW_` secrets |

### Per-Agent Deny Group Overrides

Each agent can selectively enable or disable specific deny groups via `shell_deny_groups` in its config. This is a `map[string]bool` where `true` means deny (block) and `false` means allow (unblock).

All groups default to `true` (denied). Explicitly set a group to `false` to allow those commands for a specific agent.

**Example: allow package installs but keep everything else blocked**

```json
{
  "agents": {
    "my-agent": {
      "shell_deny_groups": {
        "package_install": false
      }
    }
  }
}
```

**Example: allow SSH/tunneling for a DevOps agent, but block crypto mining**

```json
{
  "agents": {
    "devops-agent": {
      "shell_deny_groups": {
        "network_recon": false,
        "crypto_mining": true
      }
    }
  }
}
```

Deny groups and the exec approval flow operate independently — a command can pass the deny-group check but still be held for human approval based on your `ask` mode setting.

### Live-reload persistence

Global deny-group changes apply immediately without a restart. The reload clones the config snapshot before applying it, so **disables persist correctly** across reload — a group you turned off stays off until you turn it back on. The same reload also refreshes provider-level shell-deny policies (Claude CLI / ACP), not just the global exec tool.

### venv Python exemption

GoClaw blocks shell access to its internal `.goclaw/` data directory. The **GoClaw-managed Python interpreter is exempt**: invoking it by its absolute path (`<home>/.goclaw/venv/bin/python3`) is allowed. GoClaw resolves that path (following symlinks) once at startup and exempts the resolved interpreter directory; if no venv is present it falls back silently. This is the only path under `.goclaw/` an agent's shell commands can reach.

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| No approval prompt appears | `ask` is `"off"` (default) | Set `ask` to `"on-miss"` or `"always"` |
| Command denied with no prompt | `security = "allowlist"`, command not in allowlist, `ask = "off"` | Add to `allowlist` or change `ask` to `"on-miss"` |
| Approval request timed out | Operator didn't respond within 2 minutes | Command is auto-denied; agent may retry or ask you to re-run |
| `exec approval is not enabled` | No `execApproval` block in config, method called anyway | Add `tools.execApproval` section to config |
| `id is required` error | Calling approve/deny without passing the approval `id` | Include `"id": "exec-N"` in params (from the list response) |

---

## What's Next

- [Sandbox](/sandbox) — run exec commands inside an isolated Docker container
- [Custom Tools](/custom-tools) — define tools backed by shell commands
- [Security Hardening](/deploy-security) — full five-layer security overview



---

# Context Pruning

> Automatically trim old tool results to keep agent context within token limits.

## Overview

As agents run long tasks, tool results accumulate in the conversation history. Large tool outputs — file reads, API responses, search results — can consume most of the context window, leaving little room for new reasoning.

**Context pruning** trims these old tool results in-memory before each LLM request, without touching the persisted session history. It uses a two-pass strategy:

1. **Soft trim** — truncate oversized tool results to head + tail, dropping the middle.
2. **Hard clear** — if the context is still too full, replace entire tool results with a short placeholder.

Context pruning is distinct from [session compaction](../core-concepts/sessions-and-history.md). Compaction permanently summarizes and truncates conversation history. Pruning is non-destructive: the original tool results remain in the session store and are never modified — only the message slice sent to the LLM is trimmed.


## Soft Trim

Soft trim keeps the beginning and end of a long tool result, dropping the middle.

A tool result is eligible for soft trim when its character count exceeds `softTrim.maxChars`.

The trimmed result looks like:

```
<first 3000 chars of tool output>
...
<last 3000 chars of tool output>

[Tool result trimmed: kept first 3000 chars and last 3000 chars of 38400 chars.]
```

**Media tool protection:** Results from `read_image`, `read_document`, `read_audio`, and `read_video` receive a higher soft trim budget (headChars=4000, tailChars=4000) because their content is an irreplaceable description generated by a dedicated vision/audio provider. Re-generating it would require another LLM call. Media tool results are also **exempt from hard clear** — they are never replaced with the placeholder.

The agent retains enough context to understand what the tool returned without consuming the full output.

---

## Hard Clear

Hard clear replaces the entire content of old tool results with a short placeholder string. It runs as a second pass only if the context ratio is still too high after soft trim.

Hard clear processes prunable tool results one by one, recalculating the ratio after each replacement, and stops as soon as the ratio drops below `hardClearRatio`.

A hard-cleared tool result becomes:

```
[Old tool result content cleared]
```

This placeholder is configurable. Hard clear can also be disabled entirely.

---

## Configuration

Context pruning runs with `cache-ttl` mode **by default** — no config needed to activate it. To disable pruning entirely, set `mode: "off"`.

```json
{
  "contextPruning": {
    "mode": "off"
  }
}
```

All other fields have sensible defaults and are optional.

### Full configuration reference

```json
{
  "contextPruning": {
    "mode": "cache-ttl",
    "keepLastAssistants": 3,
    "softTrimRatio": 0.25,
    "hardClearRatio": 0.5,
    "minPrunableToolChars": 50000,
    "softTrim": {
      "maxChars": 6000,
      "headChars": 3000,
      "tailChars": 3000
    },
    "hardClear": {
      "enabled": true,
      "placeholder": "[Old tool result content cleared]"
    }
  }
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `mode` | `"cache-ttl"` *(enabled by default)* | Set to `"off"` to disable pruning. Omit or leave empty to keep the default `cache-ttl` mode. |
| `keepLastAssistants` | `3` | Number of recent assistant turns to protect from pruning. |
| `softTrimRatio` | `0.25` | Trigger soft trim when context fills this fraction of the context window. |
| `hardClearRatio` | `0.5` | Trigger hard clear when context fills this fraction after soft trim. |
| `minPrunableToolChars` | `50000` | Minimum total chars in prunable tool results before hard clear runs. Prevents aggressive clearing on small contexts. |
| `softTrim.maxChars` | `6000` | Tool results longer than this are eligible for soft trim. |
| `softTrim.headChars` | `3000` | Characters to keep from the start of a trimmed tool result. |
| `softTrim.tailChars` | `3000` | Characters to keep from the end of a trimmed tool result. |
| `hardClear.enabled` | `true` | Set to `false` to disable hard clear entirely (soft trim only). |
| `hardClear.placeholder` | `"[Old tool result content cleared]"` | Replacement text for hard-cleared tool results. |

---

## Configuration Examples

### Disable pruning

Pruning is on by default. To turn it off:

```json
{
  "contextPruning": {
    "mode": "off"
  }
}
```

### Aggressive — for long tool-heavy workflows

Trigger earlier and keep less context per tool result:

```json
{
  "contextPruning": {
    "mode": "cache-ttl",
    "softTrimRatio": 0.2,
    "hardClearRatio": 0.4,
    "softTrim": {
      "maxChars": 2000,
      "headChars": 800,
      "tailChars": 800
    }
  }
}
```

### Soft trim only — disable hard clear

```json
{
  "contextPruning": {
    "mode": "cache-ttl",
    "hardClear": {
      "enabled": false
    }
  }
}
```

### Custom placeholder

```json
{
  "contextPruning": {
    "mode": "cache-ttl",
    "hardClear": {
      "placeholder": "[Tool output removed to save context]"
    }
  }
}
```

---

## Pruning and the Consolidation Pipeline

Context pruning and memory consolidation serve complementary roles — pruning manages live context during a session; consolidation manages long-term recall across sessions.

```
Within a session:          pruning trims tool results → keeps LLM context lean
On session.completed:      episodic_worker summarizes → L1 episodic memory
After ≥5 episodes:         dreaming_worker promotes → L0 long-term memory
```

**Key distinction**: pruning never touches the persisted session store. Once a session completes, the consolidation pipeline (not pruning) takes over and determines what is worth keeping long-term. This means:

- Pruned tool results are still visible to `episodic_worker` via the session store when it reads messages for summarization.
- Content that was hard-cleared from live context is still summarized into episodic memory on session completion — nothing is permanently lost by pruning.
- For content that has been promoted to episodic or long-term memory by `dreaming_worker`, the **auto-injector** re-surfaces it as concise L0 abstracts at the start of the next turn. This replaces the need to keep bulky tool results alive in context.

### Practical consequence

Once the consolidation pipeline has promoted a body of knowledge to L0 (via dreaming) or L1 (via episodic), you can allow pruning to be more aggressive for that agent. The agent will not lose information — it will be re-injected from memory rather than carried forward in raw session history.

---

## Impact on Agent Behavior

- **No session data is modified.** Pruning only affects the message slice passed to the LLM. The original tool results remain in the session store.
- **Recent context is always preserved.** The last `keepLastAssistants` assistant turns and their associated tool results are never touched.
- **Soft-trimmed results still provide signal.** The agent sees the beginning and end of long outputs, which usually contain the most relevant information (headers, summaries, final lines).
- **Hard-cleared results may cause repeated tool calls.** If an agent can no longer see a tool result, it may re-run the tool to recover the information. This is expected behavior.
- **Context window size matters.** Pruning thresholds are ratios of the actual model context window. Agents configured with larger context windows will prune less aggressively.

---

## Common Issues

**Pruning never triggers**

Pruning is enabled by default. If it appears inactive, confirm that `mode` is not explicitly set to `"off"` in the agent config. Also confirm that `contextWindow` is set on the agent — pruning needs a token count to calculate ratios. Finally, verify the context ratio is actually reaching `softTrimRatio` (0.25 by default).

**Agent re-runs tools unexpectedly**

Hard clear removes tool result content entirely. If the agent needs that content, it will call the tool again. Lower `hardClearRatio` or increase `minPrunableToolChars` to delay hard clear, or disable it with `hardClear.enabled: false`.

**Trimmed results cut off important content**

Increase `softTrim.headChars` and `softTrim.tailChars`, or raise `softTrim.maxChars` so fewer results are eligible for trimming.

**Context still overflows despite pruning being enabled**

Pruning only acts on tool results. If long user messages or system prompt components dominate the context, pruning will not help. Consider [session compaction](../core-concepts/sessions-and-history.md) or reduce the system prompt size.

---

## Pipeline Improvements

### Tiktoken BPE Token Counting

GoClaw now uses the tiktoken BPE tokenizer for accurate token counting instead of the legacy `chars / 4` heuristic. This matters especially for CJK content (Vietnamese and Chinese characters), where the heuristic significantly underestimates token usage. With tiktoken enabled, all pruning ratios are calculated against actual token counts rather than character estimates.

### Pass 0 Per-Result Guard

Before normal pruning passes begin, any single tool result that exceeds **30% of the context window** is force-trimmed. This catches outlier outputs (e.g., a massive file read or API response) even when the overall context ratio is still below `softTrimRatio`. The trimmed result keeps a 70/30 head/tail split.

### Media Tool Protection

Results from `read_image`, `read_document`, `read_audio`, and `read_video` are handled specially:

- They receive a higher soft trim budget: **headChars=4000, tailChars=4000** (vs. the standard 3000/3000).
- They are **exempt from hard clear** — media descriptions are generated by dedicated vision/audio providers (Gemini, Anthropic) and cannot be regenerated without another LLM call.

### MediaRefs Compaction

During history compaction, up to **30 most recent `MediaRefs`** are preserved. This ensures the agent can still reference previously shared images and documents after compaction without losing track of media context.

### Structured Compaction Summary

When context is compacted, the summary now preserves key identifiers — agent IDs, task IDs, and session keys — in a structured format. This ensures that agents can continue referencing their active tasks and sessions after compaction without losing critical tracking context.

### Tool Output Capping at Source

Tool output is now capped at the source before being added to context. Rather than waiting for the pruning pipeline to trim oversized results after the fact, GoClaw limits tool output size at ingestion time. This reduces unnecessary memory pressure and makes the pruning pipeline more predictable.

### Dynamic Compaction Summary Budget

When session compaction runs, the output-token budget for the summary is no longer a static cap. It is now computed dynamically:

```
max_tokens = clamp(input_tokens / 25, 1024, 8192)
```

Short histories get a smaller budget (floor: 1024 tokens) and long histories get a larger one (cap: 8192 tokens). This replaces any previously documented static 4096-token cap.

### Tool-Schema Tokens in OverheadTokens

`OverheadTokens` — the token count that ContextStage subtracts from the usable window before pruning — now includes the tokens consumed by all registered tool schemas, in addition to the system prompt. Previously only system-prompt tokens were counted. This means agents with many or large tools will see a higher overhead value and pruning will trigger slightly earlier.

### Compaction Overflow Recovery

When the context remains over budget even after a compaction sweep (for example, the system prompt and tool schemas alone nearly fill the window), GoClaw performs a secondary recovery sweep before surfacing an error. This overflow recovery path (PR #958) caps retries at one attempt and returns a `context overflow after compaction` error only when the second sweep also fails. In practice this prevents hard failures for agents with large tool schemas or system prompts.

### Pending-Message Preservation

Compaction can trigger **mid-loop**, between an assistant message that requests tool calls and the `tool` results that answer them. GoClaw now preserves the in-flight assistant `tool_calls` message across a mid-loop compaction sweep, so the next provider request never sends `tool` result messages without their preceding `tool_calls` message. Without this, the provider would reject the request with an **HTTP 400** (orphaned tool results). If you previously saw intermittent 400 errors on long tool-heavy turns, this is the fix.

---

## What's Next

- [Sessions & History](../core-concepts/sessions-and-history.md) — session compaction, history limits
- [Memory System](../core-concepts/memory-system.md) — 3-tier memory architecture and consolidation pipeline
- [Configuration Reference](/config-reference) — full agent config reference



---

# Channel Instances

> Run multiple accounts per channel type — each with its own credentials, agent binding, and writer permissions.

## Overview

A **channel instance** is a named connection between one messaging account and one agent. It stores the account credentials (encrypted at rest), an optional channel-specific config, and the ID of the agent that owns it.

Because instances are stored in the database and identified by UUID, you can:

- Connect multiple Telegram bots to different agents on the same server
- Add a second Slack workspace without touching the first
- Disable a channel without deleting it or its credentials
- Rotate credentials with a single `PUT` call

Every instance belongs to exactly one agent. When a message arrives on that channel account, GoClaw routes it to the bound agent.

```mermaid
graph LR
    TelegramBot1["Telegram bot @sales"] -->|channel_instance| AgentSales["Agent: sales"]
    TelegramBot2["Telegram bot @support"] -->|channel_instance| AgentSupport["Agent: support"]
    SlackWS["Slack workspace A"] -->|channel_instance| AgentOps["Agent: ops"]
```

### Default instances

Instances whose `name` equals a bare channel type (`telegram`, `discord`, `feishu`, `zalo_oa`, `whatsapp`) or ends with `/default` are **default** (seeded) instances. Default instances **cannot be deleted** via the API — they are managed by GoClaw at startup.


## Instance object

All API responses return an instance object with credentials masked:

```json
{
  "id": "3f2a1b4c-0000-0000-0000-000000000001",
  "name": "telegram/sales-bot",
  "display_name": "Sales Bot",
  "channel_type": "telegram",
  "agent_id": "a1b2c3d4-...",
  "credentials": { "token": "***" },
  "has_credentials": true,
  "config": {},
  "enabled": true,
  "is_default": false,
  "created_by": "admin",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

| Field | Type | Notes |
|---|---|---|
| `id` | UUID | Auto-generated |
| `name` | string | Unique identifier slug (e.g. `telegram/sales-bot`) |
| `display_name` | string | Human-readable label (optional) |
| `channel_type` | string | One of the supported types above |
| `agent_id` | UUID | Agent that owns this instance |
| `credentials` | object | Credential keys are shown; values are always `"***"` |
| `has_credentials` | bool | `true` if credentials are stored |
| `config` | object | Channel-specific config (optional) |
| `enabled` | bool | `false` disables the instance without deleting it |
| `is_default` | bool | `true` for seeded instances — cannot be deleted |

---

## Instance `config` reference

The `config` object holds channel-specific settings. Beyond the per-channel keys documented on each channel page, two cross-channel concerns are worth calling out here.

### Delivery overrides (`chat_behavior`, `block_reply`)

Channel instances can override the workspace-level [human-like delivery](/channels-overview#human-like-delivery) behavior:

| Key | Type | Notes |
|---|---|---|
| `chat_behavior` | object | Override `gateway.chat_behavior` for this instance (omit = inherit). Set only the fields you want to change. |
| `block_reply` | bool | **Legacy.** Read as the inherited default for `intermediate_replies.enabled` when the newer field is unset. |

Resolution order is **Channel > Agent > Workspace**:

1. **Workspace** — `gateway.chat_behavior` (the base).
2. **Agent** — `agents.other_config.delivery_behavior` overrides the workspace base.
3. **Channel** — the instance's `config.chat_behavior` has the final say.

Each level only overrides the fields it sets, so you can tune one knob per channel and inherit the rest. Only channels that implement the `ChatBehaviorChannel` interface honor these overrides (Bitrix24, Discord, Feishu/Lark, Pancake, Slack, Telegram, WhatsApp, Zalo OA, Zalo Personal).

### Passive channel memory (`passive_memory`)

An instance can opt into [passive channel memory extraction](/memory-system#passive-channel-memory-extraction) by adding a `passive_memory` block to its `config`:

```json
{
  "config": {
    "passive_memory": {
      "enabled": true,
      "review_mode": true,
      "interval_minutes": 360,
      "min_messages": 5
    }
  }
}
```

Disabled by default, group-only in v1, and review-gated. See [Memory System › Passive Channel Memory Extraction](/memory-system#passive-channel-memory-extraction) for the full field table and behavior.

---

## REST API

All endpoints require `Authorization: Bearer <token>`.

### List instances

```bash
GET /v1/channels/instances
```

Query parameters: `search`, `limit` (max 200, default 50), `offset`.

```bash
curl http://localhost:8080/v1/channels/instances \
  -H "Authorization: Bearer $GOCLAW_TOKEN"
```

Response:

```json
{
  "instances": [...],
  "total": 4,
  "limit": 50,
  "offset": 0
}
```

---

### Get instance

```bash
GET /v1/channels/instances/{id}
```

```bash
curl http://localhost:8080/v1/channels/instances/3f2a1b4c-... \
  -H "Authorization: Bearer $GOCLAW_TOKEN"
```

---

### Create instance

```bash
POST /v1/channels/instances
```

Required fields: `name`, `channel_type`, `agent_id`.

```bash
curl -X POST http://localhost:8080/v1/channels/instances \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "telegram/sales-bot",
    "display_name": "Sales Bot",
    "channel_type": "telegram",
    "agent_id": "a1b2c3d4-...",
    "credentials": {
      "token": "7123456789:AAF..."
    },
    "enabled": true
  }'
```

Returns `201 Created` with the new instance object (credentials masked).

---

### Update instance

```bash
PUT /v1/channels/instances/{id}
```

Send only the fields you want to change. Credential updates are **merged** into existing credentials — partial updates do not wipe other credential keys.

```bash
# Rotate just the bot token, keep other credentials intact
curl -X PUT http://localhost:8080/v1/channels/instances/3f2a1b4c-... \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "token": "7999999999:BBG..." }
  }'
```

```bash
# Disable an instance without deleting it
curl -X PUT http://localhost:8080/v1/channels/instances/3f2a1b4c-... \
  -H "Authorization: Bearer $GOCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

Returns `{ "status": "updated" }`.

---

### Delete instance

```bash
DELETE /v1/channels/instances/{id}
```

Returns `403 Forbidden` if the instance is a default (seeded) instance.

```bash
curl -X DELETE http://localhost:8080/v1/channels/instances/3f2a1b4c-... \
  -H "Authorization: Bearer $GOCLAW_TOKEN"
```

---

## Channel Health

Each channel instance exposes a runtime health snapshot. GoClaw tracks the current lifecycle state, failure classification, failure counters, and an operator remediation hint.

### Health states

| State | Meaning |
|---|---|
| `registered` | Instance created but not yet started |
| `starting` | Channel is initializing (connecting to upstream) |
| `healthy` | Channel is running and accepting messages |
| `degraded` | Channel is running but experiencing issues |
| `failed` | Channel failed to start or crashed |
| `stopped` | Channel was intentionally stopped |

### Failure classification

When a channel enters `failed` or `degraded` state, GoClaw classifies the error into one of four kinds:

| Kind | Examples | Retryable |
|---|---|---|
| `auth` | 401 Unauthorized, invalid token | No |
| `config` | Missing credentials, invalid proxy URL, agent not found | No |
| `network` | Timeout, connection refused, DNS failure, EOF | Yes |
| `unknown` | Unexpected errors | Yes |

### Remediation hints

Each failed channel includes a `remediation` object with a `code`, `headline`, and `hint` pointing to the relevant UI surface (`credentials`, `advanced`, `reauth`, or `details`). For example, a Zalo Personal auth failure suggests re-opening the sign-in flow rather than checking credentials.

Health data is available in the channel instance detail view in the Web UI and via the `GET /v1/channels/instances/{id}` endpoint.

---

## Group file writers

Each channel instance exposes writer-management endpoints that delegate to its bound agent. Writers control who can upload files through the group file feature.

```bash
# List writer groups for a channel instance
GET /v1/channels/instances/{id}/writers/groups

# List writers in a group
GET /v1/channels/instances/{id}/writers?group_id=<group_id>

# Add a writer
POST /v1/channels/instances/{id}/writers
{
  "group_id": "...",
  "user_id": "123456789",
  "display_name": "Alice",
  "username": "alice"
}

# Remove a writer
DELETE /v1/channels/instances/{id}/writers/{userId}?group_id=<group_id>
```

---

## Credentials security

- Credentials are **AES-encrypted** before storage in PostgreSQL.
- API responses **never return plaintext credentials** — all values are replaced with `"***"`.
- `has_credentials: true` in the response confirms credentials are stored.
- Partial credential updates are safe: GoClaw merges the new keys into the existing (decrypted) object before re-encrypting.

---

## Common issues

| Issue | Cause | Fix |
|---|---|---|
| `403` on delete | Instance is a default/seeded instance | Default instances cannot be deleted; disable them with `enabled: false` instead |
| `400 invalid channel_type` | Typo or unsupported type | Use one of: `telegram`, `discord`, `slack`, `whatsapp`, `zalo_oa`, `zalo_personal`, `feishu`, `bitrix24`, `pancake`, `facebook` |
| Messages not routing to agent | Instance is disabled or `agent_id` is wrong | Verify `enabled: true` and the correct `agent_id` |
| Credentials not persisted | `GOCLAW_ENCRYPTION_KEY` not set | Set the encryption key env var; credentials require it |
| Cache stale after update | In-memory cache not yet refreshed | GoClaw broadcasts a cache-invalidate event on every write; cache refreshes within seconds |

---

## What's Next

- [Channel Overview](/channels-overview)
- [Multi-Channel Setup](/recipe-multi-channel)
- [Multi-Tenancy](/multi-tenancy)



---

# Webhooks

> Trigger agents or deliver channel messages from external systems via HMAC-authenticated HTTP endpoints.

## Overview

GoClaw webhooks expose two HTTP entry points that let external systems drive the gateway without speaking the WebSocket RPC protocol:

| Kind | Endpoint | Purpose | Editions |
|------|----------|---------|----------|
| `llm` | `POST /v1/webhooks/llm` | Invoke an agent with a user prompt (sync or async) | Standard + Lite |
| `message` | `POST /v1/webhooks/message` | Send a message to a user on a connected channel | Standard only |

Each webhook is a tenant-scoped registry row. An admin creates the row via the CRUD API and receives a one-time bearer secret plus an HMAC signing key; callers then authenticate inbound requests with either credential.

> **Encryption key required.** The webhook subsystem only mounts when `GOCLAW_ENCRYPTION_KEY` is set. Without it, all `/v1/webhooks/*` routes return `404` and the gateway logs `webhook subsystem disabled`. See [Security Hardening](/deploy-security) and [Environment Variables](/env-vars).

## Admin CRUD

All admin endpoints require a tenant-admin gateway token (`Authorization: Bearer <admin-token>`).

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/v1/webhooks` | Create a webhook; returns raw secret and HMAC key (once) |
| `GET` | `/v1/webhooks` | List webhooks for the tenant. Optional `?agent_id=<uuid>` filter |
| `GET` | `/v1/webhooks/{id}` | Fetch a single webhook (no secret) |
| `PATCH` | `/v1/webhooks/{id}` | Partial update; `kind` is immutable |
| `POST` | `/v1/webhooks/{id}/rotate` | Issue a new secret (old secret invalidated immediately) |
| `DELETE` | `/v1/webhooks/{id}` | Revoke; subsequent inbound calls return `401` |

See [REST API → Webhooks](/rest-api) and the [Endpoint Catalog](/api-endpoints-catalog) for full request/response shapes.

### Create

```bash
curl -X POST https://gw.example.com/v1/webhooks \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-sync",
    "kind": "llm",
    "agent_id": "9c5a...e4",
    "require_hmac": true,
    "rate_limit_per_min": 60,
    "ip_allowlist": ["10.0.0.0/8"]
  }'
```

Response (201 Created):

```json
{
  "id": "f5a1...",
  "name": "billing-sync",
  "secret_prefix": "wh_ABCD",
  "secret": "wh_ABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGH",
  "hmac_signing_key": "a3f4...hex64chars",
  "kind": "llm",
  "rate_limit_per_min": 60,
  "require_hmac": true,
  "localhost_only": false,
  "ip_allowlist": ["10.0.0.0/8"],
  "created_at": "2026-05-21T12:00:00Z"
}
```

> `secret` and `hmac_signing_key` are returned **once** — on create and on rotate. Store them in your secret manager immediately; they cannot be retrieved again.

### Create payload fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `name` | string | yes | Max 100 chars |
| `kind` | string | yes | `"llm"` or `"message"` |
| `agent_id` | UUID | for `llm` kind | Agent to invoke |
| `channel_id` | UUID | optional | Pin a `message` webhook to one channel instance |
| `require_hmac` | bool | no | Force HMAC-only auth (disables bearer) |
| `localhost_only` | bool | no | Restrict callers to 127.0.0.1/::1. Forced `true` on Lite |
| `rate_limit_per_min` | int | no | Per-webhook cap (0 = use tenant default) |
| `ip_allowlist` | []string | no | IPs or CIDR ranges. Empty allows any source |

## Authentication

The `require_hmac` flag on the webhook row decides which modes are accepted.

### Bearer auth

```
Authorization: Bearer wh_ABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGH
```

The gateway hashes the token with SHA-256, compares it to `secret_hash` via constant-time comparison, then decrypts the stored secret material with `GOCLAW_ENCRYPTION_KEY`. Bearer auth is **rejected** when `require_hmac=true`.

### HMAC auth (recommended)

Send three headers:

```
X-Webhook-Id: <webhook-uuid>
X-GoClaw-Signature: t=<unix_seconds>,v1=<hmac_hex>
Content-Type: application/json
```

Signing algorithm:

```
signing_key = hex.Decode(hmac_signing_key)   // hex_64 → 32 raw bytes
payload     = "{unix_ts}.{request_body_bytes}"
signature   = HMAC_SHA256(signing_key, payload)
header      = "t={unix_ts},v1={hex(signature)}"
```

`hmac_signing_key` equals `hex(SHA-256(raw_secret))`. The gateway never stores the raw secret — only its hash and an AES-256-GCM ciphertext used by background workers to recompute HMAC at delivery time.

**Timestamp skew.** Requests with `|now - t| > 300` seconds are rejected. Synchronize clocks via NTP.

**Replay protection.** After a valid signature is accepted, the gateway records `sha256(tenant_id|signature_hex)` in an in-memory nonce cache (TTL 320s). Replays return `401` with the audit event `security.webhook.hmac_replay`. The cache is per-process — a multi-node deployment can theoretically accept a replay on a sibling node.

**IP allowlist.** When `ip_allowlist` is non-empty, each entry is matched against the request's `RemoteAddr` after authentication. CIDR ranges and bare addresses are supported. `X-Forwarded-For` is **not** trusted.

## POST /v1/webhooks/llm

Triggers an agent with an input prompt. Available in all editions (Standard + Lite).

```bash
curl -X POST https://gw.example.com/v1/webhooks/llm \
  -H "Authorization: Bearer wh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarize the latest metrics",
    "session_key": "user-123-session",
    "mode": "sync"
  }'
```

Request fields:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `input` | string or array | yes | Plain string, or `[{role, content}]` array |
| `session_key` | string | no | Stable key for multi-turn conversation continuity |
| `user_id` | string | no | External user identifier for scoping |
| `model` | string | no | Per-request model override |
| `mode` | string | no | `"sync"` (default) or `"async"` |
| `callback_url` | string | required when async | HTTPS URL; validated against the SSRF policy |
| `metadata` | object | no | Echoed back to the async callback (max 8 KB) |

**Sync mode** times out at 30 seconds and returns the full agent output:

```json
{
  "call_id": "<uuid>",
  "agent_id": "<uuid>",
  "output": "Here are the metrics: ...",
  "usage": {"prompt_tokens": 150, "completion_tokens": 200, "total_tokens": 350},
  "finish_reason": "stop"
}
```

**Async mode** returns `202 Accepted` with `{"call_id": "...", "status": "queued"}`; the result lands on `callback_url` via outbound delivery (see [Outbound callbacks](#outbound-callbacks)).

Error codes:

| Status | Code | When |
|--------|------|------|
| 400 | `invalid_request` | Missing `input`, bad `mode`, missing `callback_url` for async |
| 401 | — | Bearer invalid, HMAC mismatch, revoked, HMAC replay |
| 403 | `unauthorized` | `localhost_only` violated, IP denied, kind mismatch, tenant mismatch |
| 404 | `not_found` | Agent not found |
| 429 | — | Rate limit exceeded (`Retry-After: 60`) |
| 503 | — | Webhook processing lane at capacity |
| 504 | — | LLM timeout (sync only) |

## POST /v1/webhooks/message

Sends a message to a user on a connected channel. **Standard edition only.**

```json
{
  "channel_name": "telegram-prod",
  "chat_id": "123456789",
  "content": "Hello from the integration!",
  "media_url": "https://example.com/image.jpg",
  "media_caption": "Optional caption",
  "fallback_to_text": false
}
```

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `channel_name` | string | yes (unless the webhook has a bound `channel_id`) | Channel instance name |
| `chat_id` | string | yes | Channel-specific recipient ID |
| `content` | string | yes (unless `media_url`) | Text body; max 16 KB |
| `media_url` | string | no | HTTPS URL. SSRF-guarded + HEAD-probed before fetch |
| `media_caption` | string | no | Caption for media |
| `fallback_to_text` | bool | no | If true, send text-only when channel cannot handle media |

Response:

```json
{
  "call_id": "<uuid>",
  "status": "sent",
  "channel_name": "telegram-prod",
  "chat_id": "123456789",
  "warning": ""
}
```

`warning` is set to `"media_not_supported_fallback_text"` when `fallback_to_text=true` and the channel dropped the media. Channels that cannot deliver media (e.g., `zalo_oa`) return `501 Not Implemented` unless `fallback_to_text=true`.

## Idempotency

All webhook endpoints accept an `Idempotency-Key` header (max 255 chars).

- First request with a key: processed normally.
- Same key + identical body: returns the cached response with `200 OK`.
- Same key + different body: returns `409 Conflict` (`webhook.idempotency_conflict`).
- Keys expire after 24 hours (`webhook_calls` table TTL).

Use a UUID or a hash of the request payload. Re-send the **exact same body** on retry.

## Outbound callbacks

Async LLM calls deliver results to `callback_url` via `HTTP POST`. Delivery is **at-least-once** — receivers must be idempotent.

Every attempt carries these headers:

```
X-Webhook-Delivery-Id: <uuid>          ; stable across retries — dedupe on this
X-Webhook-Signature:   t=<unix>,v1=<hex>; same HMAC scheme as inbound
Content-Type:          application/json
User-Agent:            goclaw-webhook/1
```

Payload:

```json
{
  "call_id": "<uuid>",
  "delivery_id": "<uuid>",
  "agent_id": "<uuid>",
  "status": "done",
  "output": "Agent response text...",
  "usage": {"prompt_tokens": 150, "completion_tokens": 200, "total_tokens": 350},
  "metadata": {},
  "error": ""
}
```

`status` is `"done"` on success or `"failed"` on agent error (with `error` populated).

Retry schedule (±10% jitter):

| Attempt | Delay |
|---------|-------|
| 1 | 30 seconds |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 1 hour |
| 5 | 6 hours |

After 5 failures the row moves to `status=dead`. A `429 Retry-After` from the receiver is respected (capped at 6 hours). `4xx` responses other than `429` are treated as permanent failures. Any `2xx` marks the delivery as done.

## Verifying signatures

### Go

```go
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "strings"
    "time"
)

func verify(body []byte, sigHeader, hmacSigningKey string) error {
    var ts int64
    var sigHex string
    for _, part := range strings.Split(sigHeader, ",") {
        switch {
        case strings.HasPrefix(part, "t="):
            fmt.Sscanf(part[2:], "%d", &ts)
        case strings.HasPrefix(part, "v1="):
            sigHex = part[3:]
        }
    }
    if abs(time.Now().Unix()-ts) > 300 {
        return fmt.Errorf("timestamp skew")
    }
    key, err := hex.DecodeString(hmacSigningKey)
    if err != nil {
        return err
    }
    mac := hmac.New(sha256.New, key)
    fmt.Fprintf(mac, "%d.", ts)
    mac.Write(body)
    expected := mac.Sum(nil)
    received, err := hex.DecodeString(sigHex)
    if err != nil || !hmac.Equal(expected, received) {
        return fmt.Errorf("signature mismatch")
    }
    return nil
}
```

### Node.js

```js
const crypto = require('crypto');

function signWebhookRequest(body, hmacSigningKeyHex) {
  const ts = Math.floor(Date.now() / 1000);
  const key = Buffer.from(hmacSigningKeyHex, 'hex');
  const payload = Buffer.concat([Buffer.from(`${ts}.`), Buffer.from(body)]);
  const sig = crypto.createHmac('sha256', key).update(payload).digest('hex');
  return { ts, header: `t=${ts},v1=${sig}` };
}

const body = JSON.stringify({ input: 'hello', mode: 'sync' });
const { header } = signWebhookRequest(body, process.env.WEBHOOK_HMAC_KEY);

await fetch('https://gw.example.com/v1/webhooks/llm', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Id': process.env.WEBHOOK_ID,
    'X-GoClaw-Signature': header,
  },
  body,
});
```

### Python

```python
import hashlib, hmac, json, os, time, requests

def sign(body: bytes, hmac_signing_key_hex: str) -> str:
    ts = int(time.time())
    key = bytes.fromhex(hmac_signing_key_hex)
    payload = f"{ts}.".encode() + body
    sig = hmac.new(key, payload, hashlib.sha256).hexdigest()
    return f"t={ts},v1={sig}"

body = json.dumps({"input": "hello", "mode": "sync"}).encode()
requests.post(
    "https://gw.example.com/v1/webhooks/llm",
    headers={
        "Content-Type": "application/json",
        "X-Webhook-Id": os.environ["WEBHOOK_ID"],
        "X-GoClaw-Signature": sign(body, os.environ["WEBHOOK_HMAC_KEY"]),
    },
    data=body,
)
```

## Rate limits

Two tiers must both pass:

| Tier | Cap | Notes |
|------|-----|-------|
| Per-webhook | `rate_limit_per_min` field (0 = disabled) | Set on the webhook row |
| Per-tenant | Platform default | Shared across all webhooks for one tenant |

A reject from either tier returns `429 Too Many Requests` with `Retry-After: 60`.

## Edition differences

| Feature | Standard | Lite |
|---------|----------|------|
| `/v1/webhooks/llm` | Available | Available (`localhost_only` forced) |
| `/v1/webhooks/message` | Available | Disabled |
| `localhost_only=false` | Configurable | Always `true`; cannot be unset |
| Creating `kind="message"` | Allowed | Rejected (`403`) |

On Lite, every webhook is auto-created with `localhost_only=true`. A `PATCH` that tries to clear it returns `403`.

## Security

- **SSRF protection.** `media_url` and `callback_url` are validated against the SSRF policy and HEAD-probed; callback URLs are re-validated at delivery time to defeat DNS rebinding (`security.webhook.callback_ssrf_blocked`).
- **Secret storage.** Only `SHA-256(secret)` and an AES-256-GCM ciphertext are persisted; raw secrets are never logged.
- **Tenant isolation.** Agents and channels must belong to the webhook's tenant (`security.webhook.tenant_mismatch`).
- **Rotation.** `POST /v1/webhooks/{id}/rotate` invalidates the old secret immediately — there is no grace window. Coordinate the cutover with your callers.
- **Encryption key.** `GOCLAW_ENCRYPTION_KEY` (base64, 32 raw bytes) must be the same across every gateway replica. Rotating it re-encrypts all webhook secrets via the standard key-rotation migration.

## Audit payload

Every call writes one row to `webhook_calls` with `request_payload`:

```json
{
  "body_hash": "<sha256-hex-64-chars>",
  "meta": { /* handler-specific */ }
}
```

`body_hash` is the SHA-256 of the raw request bytes — used by the idempotency checker to detect body-mismatch replays. For `llm` calls, `meta` mirrors the decoded request fields (`input`, `session_key`, `user_id`, `model`, `mode`, `callback_url`, `metadata`). For `message` calls, `meta` is `{channel_name, chat_id, has_media}`.

## Common pitfalls

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `404` on every `/v1/webhooks/*` route | `GOCLAW_ENCRYPTION_KEY` not set | Set the env var and restart the gateway |
| `401 timestamp skew` | Clock drift | Run NTP on the caller |
| `401 hmac_replay` after retry | Re-sending the same signed payload | Re-sign with a fresh timestamp on each retry |
| `409 idempotency_conflict` | Same `Idempotency-Key` with a different body | Always re-send the exact same body, or use a new key |
| `403 unauthorized` from a Lite gateway | Trying to create a `message` webhook or unset `localhost_only` | Use a Standard gateway or change the request |
| Async callback never arrives | `callback_url` failed SSRF validation or returned `4xx` | Inspect `webhook_calls.status` and the worker logs |

## What's Next

- [REST API → Webhooks](/rest-api)
- [Environment Variables → `GOCLAW_ENCRYPTION_KEY`](/env-vars)
- [Security Hardening](/deploy-security)
- [Channels Overview](/channels-overview)



---

# Workstations

> Run agent commands on remote machines through SSH or Docker, with a per-workstation allowlist and a full audit trail.

## Overview

A **workstation** is a remote execution target registered in GoClaw. When an agent calls the built-in `workstation_exec` tool, the gateway opens a session against the linked workstation, runs the command, streams stdout/stderr back as event-bus chunks, and writes one row to the activity log.

Workstations are tenant-scoped and Standard-edition only. Two backend types are shipped:

| Backend | `backendType` | Transport | Notes |
|---------|---------------|-----------|-------|
| SSH | `ssh` | OpenSSH client + pooled sessions | Inline PEM private key or password. TOFU host-key fingerprinting |
| Docker | `docker` | Docker engine API | Image + container name; useful for ephemeral sandbox targets |

The connection pool is shared per workstation row, so repeated `workstation_exec` calls reuse a warm SSH client instead of paying the TCP+TLS handshake every time.

## Lifecycle

1. **Create** the workstation — POST `/v1/workstations` with `workstationKey`, `name`, `backendType`, and `metadata`.
2. **Test** the connection — `POST /v1/workstations/{id}/test`. The SSH backend dials, runs `echo ok`, and tears down within 5 seconds.
3. **Seed the allowlist** — happens automatically on create. See [Permission model](#permission-model).
4. **Link an agent** — over WebSocket: `workstations.linkAgent` with `{agentId, workstationId, isDefault}`.
5. **Use it** — the agent calls the `workstation_exec` tool. Every call passes through the permission checker and is recorded in `workstation_activity`.

`workstationKey` is the stable slug used in API calls; the regex is `^[a-z0-9][a-z0-9-]{0,99}$`.

## Endpoints

All HTTP endpoints require a tenant-admin gateway token (`Authorization: Bearer <admin-token>`).

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/v1/workstations` | List active workstations |
| `POST` | `/v1/workstations` | Create a workstation |
| `GET` | `/v1/workstations/{id}` | Fetch one (sanitized view) |
| `PUT` | `/v1/workstations/{id}` | Partial update |
| `DELETE` | `/v1/workstations/{id}` | Hard delete (tenant-scoped) |
| `POST` | `/v1/workstations/{id}/test` | Health-check the backend |
| `GET` | `/v1/workstations/{id}/permissions` | List allowlist patterns |
| `POST` | `/v1/workstations/{id}/permissions` | Add a pattern (default enabled) |
| `DELETE` | `/v1/workstations/{id}/permissions/{permId}` | Remove a pattern |
| `PUT` | `/v1/workstations/{id}/permissions/{permId}/toggle` | Enable/disable a pattern |
| `GET` | `/v1/workstations/{id}/activity` | Paged audit log (`limit`, `cursor`) |

The same operations are also exposed as WebSocket RPC methods under `workstations.*` (see [WebSocket Protocol](/websocket-protocol)). `workstations.linkAgent` / `workstations.unlinkAgent` are only available over WebSocket.

### Create

```bash
curl -X POST https://gw.example.com/v1/workstations \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workstationKey": "build-vm",
    "name": "Build VM (us-west)",
    "backendType": "ssh",
    "metadata": {
      "host": "10.0.4.21",
      "port": 22,
      "user": "deploy",
      "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----\n",
      "knownHostsFingerprint": "SHA256:abcdef..."
    },
    "defaultCwd": "/srv/builds",
    "defaultEnv": {"PATH": "/usr/local/bin:/usr/bin"}
  }'
```

Response (201 Created) returns a **sanitized view** — the private key and password are never echoed back. Only a metadata summary (`host`, `port`, `user`, `hasKey`) is included:

```json
{
  "workstation": {
    "id": "1c2d...",
    "workstationKey": "build-vm",
    "tenantId": "...",
    "name": "Build VM (us-west)",
    "backendType": "ssh",
    "defaultCwd": "/srv/builds",
    "active": true,
    "createdAt": "2026-05-21T12:00:00Z",
    "metadataSummary": {"host": "10.0.4.21", "port": 22, "user": "deploy", "hasKey": true}
  }
}
```

### SSH metadata

| Field | Required | Notes |
|-------|----------|-------|
| `host` | yes | DNS name or IP |
| `user` | yes | Remote user |
| `port` | no | Defaults to `22`; must be 1–65535 |
| `privateKey` | one of `privateKey`/`password` | PEM-encoded; stored AES-256-GCM encrypted |
| `password` | one of `privateKey`/`password` | Prefer key auth |
| `knownHostsFingerprint` | recommended | `SHA256:...` of the host key. Empty → TOFU on first connect |
| `connectTimeoutSec` | no | Overrides the 10s TCP dial timeout |

### Docker metadata

| Field | Required | Notes |
|-------|----------|-------|
| `image` | yes | Container image reference |
| `host` | one of `host`/`socketPath` | Remote Docker daemon URL |
| `socketPath` | one of `host`/`socketPath` | Local UNIX socket path |
| `network` | no | Docker network to attach to |

## Permission model

Workstations run a **default-deny** allowlist scoped to `argv[0]` — the binary name. Wildcard `*` is intentionally not supported.

`workstation_permissions` rows live in their own table (migration `000063`) and seed automatically when a workstation is created. The default seed is a small set of read-only or low-risk binaries:

```
echo, pwd, ls, cat, git, whoami, hostname, date, uname, claude
```

Shells (`bash`, `sh`, `zsh`) are deliberately excluded — adding one would bypass the entire model by accepting arbitrary commands as arguments.

Each pattern is either a literal binary name (`git`) or a prefix-glob (`python*`). To extend the allowlist:

```bash
curl -X POST https://gw.example.com/v1/workstations/<id>/permissions \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"pattern": "make"}'
```

Toggle a pattern off without deleting it:

```bash
curl -X PUT https://gw.example.com/v1/workstations/<id>/permissions/<permId>/toggle \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"enabled": false}'
```

A disabled pattern stays in the table but is skipped by the runtime checker.

## Linking an agent

Use the WebSocket RPC method `workstations.linkAgent`:

```json
{
  "id": "req-1",
  "method": "workstations.linkAgent",
  "params": {
    "agentId": "<agent-uuid>",
    "workstationId": "<ws-uuid>",
    "isDefault": true
  }
}
```

The `agent_workstation_links` table allows one default workstation per agent — setting `isDefault=true` clears any prior default. To unlink, call `workstations.unlinkAgent` with the same `agentId` and `workstationId`.

When an agent runs the `workstation_exec` tool without explicitly naming a workstation, the gateway resolves it through this link table.

## Activity audit

Every call to `workstation_exec` writes one row to `workstation_activity` (migration `000064`). The table is append-only and pruned nightly via `Prune(before)` on the store interface.

| Field | Notes |
|-------|-------|
| `action` | `"exec"` or `"deny"` |
| `cmdHash` | SHA-256 of the full command (forensics) |
| `cmdPreview` | First 200 chars with secrets redacted |
| `exitCode`, `durationMs` | Populated for `exec` rows; null for `deny` |
| `denyReason` | Populated for `deny` rows (e.g. `"binary 'curl' not allowed"`) |

Read the log paged from newest to oldest:

```bash
curl "https://gw.example.com/v1/workstations/<id>/activity?limit=50" \
  -H "Authorization: Bearer <admin-token>"
```

The response includes `activity` (array) and `nextCursor` (pass back as `?cursor=...` to page further).

## Using `workstation_exec`

Once a workstation is linked and the allowlist contains the binary you need, an agent can call the tool directly. The tool streams stdout/stderr as event-bus chunks (`execChunkSize` 64 KiB), enforces caps on command length (`4 KiB`), argument bytes (`1 KiB`), env count (`50`) and env value size (`256` bytes each), and returns the exit code plus a 2 KiB tail of each stream.

Each call rebuilds env from `defaultEnv` on the workstation row plus any overrides passed to the tool. Env keys denied by [`env_denylist`](/cli-credentials) (e.g. `LD_PRELOAD`, AWS root creds) are stripped before the SSH session is created.

## Security considerations

- **Encrypted at rest.** `metadata` and `defaultEnv` are stored AES-256-GCM encrypted. The same `GOCLAW_ENCRYPTION_KEY` env var that gates webhooks also encrypts workstation credentials.
- **Sanitized responses.** Every API response uses `SanitizedWorkstation` — private keys, passwords, and the raw `defaultEnv` map never leave the gateway.
- **Tenant isolation.** Every store query is tenant-scoped; the handler also re-checks ownership via `GetByID` before permission and activity operations.
- **Host-key TOFU.** A workstation with an empty `knownHostsFingerprint` accepts the first host key and pins it for all subsequent connections. Pre-populate the fingerprint for production targets.
- **Env denylist.** Forbidden env keys (loader hooks, ambient cloud credentials) are stripped before exec — see [CLI Credentials](/cli-credentials) for the full list.
- **Default-deny allowlist.** Only seeded safe binaries can run until an admin extends the list. There is no `*` shortcut.

## Common workflows

**Wire a remote build host to an agent.**

```bash
# 1. Create the workstation
curl -X POST .../v1/workstations -d @ssh-build-host.json

# 2. Extend the allowlist with the binaries the build needs
curl -X POST .../v1/workstations/<id>/permissions -d '{"pattern":"make"}'
curl -X POST .../v1/workstations/<id>/permissions -d '{"pattern":"npm"}'

# 3. Link the agent (over WebSocket) with isDefault=true
# 4. Ask the agent to run `make build`; the tool streams output back live.
```

**Audit what an agent ran overnight.**

```bash
curl ".../v1/workstations/<id>/activity?limit=200" \
  -H "Authorization: Bearer <admin-token>"
```

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `501 not implemented` from `/test` | Test connection is a stub; full implementation pending | Validate connectivity with a tiny `echo` exec instead |
| `invalid slug: workstationKey` | Key contains uppercase, underscores, or `>100` chars | Use kebab-case ASCII, e.g. `build-vm-west` |
| `invalid metadata shape: ssh: privateKey or password is required` | Empty creds in SSH metadata | Supply either an inline PEM or a password |
| `binary 'curl' not allowed` deny rows | Allowlist doesn't include the binary | Add a pattern via `POST /v1/workstations/{id}/permissions` |
| `404 workstation not found` after a cross-tenant call | Workstation belongs to a different tenant | Use a token scoped to the correct tenant |
| `ssh: health check dial` errors | Host unreachable, wrong port, or bad fingerprint | Verify network reachability and `knownHostsFingerprint` |

## What's Next

- [Tools Overview](/tools-overview) — how `workstation_exec` fits among the built-in tools
- [CLI Credentials](/cli-credentials) — env denylist, secret injection
- [REST API → Workstations](/rest-api)
- [WebSocket Protocol → workstations.*](/websocket-protocol)
- [Database Schema](/database-schema) — `workstations`, `workstation_permissions`, `workstation_activity`



---

# Usage & Quota

> Track token consumption per agent and session, and enforce per-user request limits across hour, day, and week windows.

## Overview

GoClaw gives you two related but distinct features:

- **Usage tracking** — how many tokens each agent/session consumed, queryable via the dashboard or WebSocket.
- **Quota enforcement** — optional per-user/group message limits (e.g., 10 requests/hour for Telegram users) backed by the traces table.

Both are always available when PostgreSQL is connected. Quota enforcement is opt-in via config.


## Edition Rate Limits (Sub-Agent)

Starting with v3 (#600), the active **edition** enforces tenant-scoped sub-agent concurrency limits. These prevent a single tenant from monopolizing sub-agent resources.

| Edition field | Lite default | Standard default | Description |
|---|---|---|---|
| `MaxSubagentConcurrent` | 2 | unlimited (0) | Max sub-agents running in parallel per tenant |
| `MaxSubagentDepth` | 1 | uses config default | Max spawn nesting depth (1 = no sub-agents spawning sub-agents) |

A value of `0` means unlimited. Lite edition is the constrained preset; Standard edition ships with no concurrency caps.

When a spawn request would exceed `MaxSubagentConcurrent`, GoClaw rejects the spawn and returns an error to the parent agent. When `MaxSubagentDepth` is exceeded, nested delegation via `team_tasks` is blocked (`SubagentDenyAlways`).

These limits are edition-level — they apply to every tenant on that GoClaw instance regardless of per-agent budget settings.

---

## Quota Enforcement

Quota is checked against the `traces` table (top-level traces only — sub-agent delegations don't count against user quota). Counts are cached in memory for 60 seconds to avoid hammering the database on every request.

### Config

Add a `quota` block inside `gateway` in your `config.json`:

```json
{
  "gateway": {
    "quota": {
      "enabled": true,
      "default": { "hour": 20, "day": 100, "week": 500 },
      "channels": {
        "telegram": { "hour": 10, "day": 50 }
      },
      "providers": {
        "anthropic": { "day": 200 }
      },
      "groups": {
        "group:telegram:-1001234567": { "hour": 5, "day": 20 }
      }
    }
  }
}
```

All limits are optional — a value of `0` (or omitting the field) means unlimited.

**Priority order (most specific wins):** `groups` > `channels` > `providers` > `default`

| Field | Key format | Description |
|-------|-----------|-------------|
| `default` | — | Fallback for any user not matched by a more specific rule |
| `channels` | Channel name, e.g. `"telegram"` | Applies to all users on that channel |
| `providers` | Provider name, e.g. `"anthropic"` | Applies when that LLM provider is used |
| `groups` | User/group ID, e.g. `"group:telegram:-100123"` | Per-user or per-group override |

### What happens when quota is exceeded

The channel layer checks quota before dispatching a message to the agent. If the user is over limit, the agent never runs and the user receives an error message. The response includes which window was exceeded and the current counts:

```
Quota exceeded: 10/10 requests this hour. Try again later.
```

### `quota.usage` — dashboard view

```json
{ "type": "req", "id": "3", "method": "quota.usage" }
```

Response when quota is enabled:

```json
{
  "enabled": true,
  "requestsToday": 284,
  "inputTokensToday": 1240000,
  "outputTokensToday": 310000,
  "costToday": 1.84,
  "uniqueUsersToday": 12,
  "entries": [
    {
      "userId": "user:telegram:123456",
      "hour": { "used": 3, "limit": 10 },
      "day":  { "used": 47, "limit": 100 },
      "week": { "used": 200, "limit": 500 }
    }
  ]
}
```

`entries` is capped at 50 users (the top 50 by weekly request count).

When quota is disabled (`"enabled": false`), the response still includes today's aggregate stats (`requestsToday`, `inputTokensToday`, `costToday`, etc.) — the `entries` array is empty and `"enabled": false`.

---

## AI Budget Usage Caps

Separate from the channel-layer request quota above, GoClaw has a **token- and cost-based cap system** that enforces limits on the LLM provider spend itself. Where request quota counts messages, usage caps count *tokens and dollar cost*, and they apply not only to the main agent turn but to every billable LLM call GoClaw makes on a tenant's behalf.

Caps are stored as **policies** in PostgreSQL (migrations `000070`–`000072`) and managed through a REST API. They are always active once at least one policy exists for a tenant — there is no global on/off config flag.

### Policy model

A cap policy answers: *for this scope, in this time window, how many tokens and/or how much cost is allowed?*

**Scope dimensions** — every policy can leave any dimension unset (NULL) to mean "matches everything":

| Dimension | Meaning |
|-----------|---------|
| `tenant_id` | Always set — every policy belongs to one tenant |
| `agent_id` | Limit one agent (unset = all agents in the tenant) |
| `provider_id` | Limit one configured LLM provider record |
| `provider_type` | Limit a provider family, e.g. `anthropic`, `openai` |
| `model_id` | Limit one model, e.g. `claude-sonnet-4-5` |

**Window types** (`window`): `hour`, `day`, `week`, or `month`. Windows are aligned to UTC calendar boundaries — `day` starts at 00:00 UTC, `week` starts Monday, `month` starts on the 1st.

**Limits** — a policy must set `max_tokens`, `max_cost_micros`, or both:

| Field | Unit |
|-------|------|
| `max_tokens` | Total tokens (input + output + cache read + cache write) |
| `max_cost_micros` | Cost in **micro-dollars** (1 USD = 1,000,000 micros). The API also accepts `max_cost_usd` as a convenience and converts it for you |

**How multiple matching policies combine.** When a request comes in, GoClaw finds *every* enabled policy whose scope matches (NULL dimensions match anything, set dimensions must equal the request). A request must fit under **all** matched policies — the most restrictive one wins. The `priority` field (lower number = evaluated first, default `100`) controls evaluation order, which determines which policy is reported as the blocker when a cap is hit.

### Reservation + counter enforcement

Caps use a **reserve-then-settle** model so concurrent calls can't overspend a window:

1. **Preflight (reserve)** — before the LLM call, GoClaw estimates token usage (and cost, if any matched policy has a cost cap), then atomically adds it to each policy's per-window counter. If the reservation would push `used + reserved + estimate` over a policy's `max_tokens` or `max_cost_micros`, the call is **blocked** before it runs.
2. **Reconcile (settle)** — after the call returns, the reservation is replaced with the *actual* tokens and cost from the provider's usage response. The reserved amount is released and the used amount is recorded. Failed calls settle to zero (the reservation is freed) unless a partial response was received.

Cost estimation needs a price for the model. If a cost-capped policy matches but no pricing is known for the model, the call is **blocked** with reason `pricing_unknown` — see [Cost Tracking → Model Pricing](/cost-tracking) for how to populate prices.

### Caps apply to auxiliary LLM calls too

Usage caps are enforced on **every billable LLM call**, not just the user-facing agent turn. This includes auxiliary calls GoClaw makes internally:

- Conversation title generation
- Intent classification
- Mid-loop and history compaction
- Memory flush
- Knowledge-graph extraction
- Memory consolidation (dreaming / episodic workers)
- Vault enrichment
- Provider verification and summoner regeneration

Each of these reserves and reconciles against the same policies, so a tight `day` token cap will also throttle background work, not only chat replies.

> **Subscription / OAuth providers are exempt.** Caps only apply to providers billed by API key. Providers that are flat-rate or subscription-based (Claude CLI, ChatGPT OAuth, Bailian, ACP, Ollama) are skipped, and so are providers configured without an API key.

### Agent monthly budget bridge

The legacy per-agent `budget_monthly_cents` field (see [Cost Tracking → Monthly Budget Enforcement](/cost-tracking)) is automatically mirrored into the cap system. Migration `000072` creates, for every agent with a positive `budget_monthly_cents`, a managed `month`-window cost-cap policy:

- `max_cost_micros` = `budget_monthly_cents × 10,000` (cents → micro-dollars)
- `source` = `agent_budget_monthly_cents`, `priority` = `90`

These bridged policies are **managed** — the REST API refuses to edit or delete them (returns `409 Conflict`). Adjust the agent's `budget_monthly_cents` instead. Manually created policies have `source` = `manual`.

### What happens when a cap is hit

When a reservation is rejected, GoClaw returns a `usage cap exceeded` error from the LLM call. For the main agent turn this surfaces as a failed run — the agent does not produce a reply. A `block` decision is also written to the events log (see below) recording which policy and reason (`cap_exceeded` or `pricing_unknown`) triggered it.

### Decision tracing

Every cap decision is recorded in two places:

- **`usage_cap_events`** — an append-only audit log of `allow` / `block` / `skip` decisions with the policy, reservation key, estimated/actual tokens and cost, and reason. Queryable via the events endpoint.
- **Trace metadata** — each agent trace carries a `usage_caps` block listing the decision, matched policy IDs, reservation key, and estimated vs. actual tokens/cost per LLM attempt, so you can see cap behavior inline with the rest of the trace.

### REST endpoints

All usage-cap endpoints require an admin Bearer token. Write operations (create/update/delete policy, pricing overrides) additionally require tenant-admin scope; the OpenRouter sync endpoint requires master scope.

| Method & path | Scope | Description |
|---------------|-------|-------------|
| `GET /v1/usage-caps/policies` | admin | List all cap policies for the tenant (includes disabled) |
| `POST /v1/usage-caps/policies` | tenant-admin | Create a cap policy |
| `PATCH /v1/usage-caps/policies/{id}` | tenant-admin | Update a policy (managed agent-budget policies are rejected) |
| `DELETE /v1/usage-caps/policies/{id}` | tenant-admin | Delete a policy (managed policies are rejected) |
| `GET /v1/usage-caps/utilization` | admin | Current per-policy usage vs. limit for the active window |
| `GET /v1/usage-caps/events` | admin | Recent cap decisions (`?limit=`, default 50, max 200) |

**Create a policy** — cap one agent to 1M tokens per day:

```bash
curl -X POST -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/usage-caps/policies" \
  -d '{
    "agent_id": "11111111-1111-1111-1111-111111111111",
    "window": "day",
    "max_tokens": 1000000
  }'
```

**Create a cost cap** — limit Anthropic spend to $20/month tenant-wide (`max_cost_usd` is converted to micros):

```bash
curl -X POST -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/usage-caps/policies" \
  -d '{
    "provider_type": "anthropic",
    "window": "month",
    "max_cost_usd": 20.00
  }'
```

**Check utilization:**

```bash
curl -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/usage-caps/utilization"
```

Model pricing (which feeds the cost calculation behind cost caps) is configured through a separate set of endpoints — see [Cost Tracking → Model Pricing](/cost-tracking).

---

## Webhook Rate Limiting (Channel Layer)

Separate from per-user quota, there is a webhook-level rate limiter that protects against incoming webhook floods. It uses a fixed 60-second window with a hard cap of **30 requests per key** per window. Up to **4096 unique keys** are tracked simultaneously; beyond that, oldest entries are evicted.

This rate limiter operates at the HTTP webhook receiver layer, before messages reach the agent. It is not configurable — it is a fixed DoS protection measure.

---

## Database Index

Quota lookups use a partial index added in migration `000009`:

```sql
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_traces_quota
ON traces (user_id, created_at DESC)
WHERE parent_trace_id IS NULL AND user_id IS NOT NULL;
```

This index covers 89% of traces (top-level only) and makes hourly/daily/weekly window queries fast even with large trace tables.

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| `quota.usage` returns `enabled: false` | `quota.enabled` not set to `true` in config | Set `"enabled": true` in `gateway.quota` |
| Users hit quota despite low usage | Cache TTL is 60s — counts lag by up to 1 minute | Expected behavior; the optimistic increment mitigates rapid bursts |
| `requestsToday` is 0 even with activity | No traces written — tracing may be disabled | Ensure PostgreSQL is connected and `GOCLAW_POSTGRES_DSN` is set |
| Quota not enforced on a channel | Channel name in config doesn't match actual channel key | Use exact channel name: `telegram`, `discord`, `feishu`, `zalo`, `whatsapp` |
| Sub-agent messages count against user quota | They shouldn't — only top-level traces count | Verify `parent_trace_id IS NULL` filter; check if agent is delegating via subagent tool |

---

## What's Next

- [Observability](/deploy-observability) — OpenTelemetry tracing and Jaeger integration
- [Security Hardening](/deploy-security) — rate limiting at the gateway level
- [Database Setup](/deploy-database) — PostgreSQL setup including the quota index



---

# Cost Tracking

> Monitor token costs per agent and provider using configurable per-model pricing.

## Overview

GoClaw calculates USD costs for every LLM call when you configure pricing in `telemetry.model_pricing`. Cost data is stored on individual trace spans and aggregated into the `usage_snapshots` table. You can view it via the REST usage API or the WebSocket `quota.usage` method.

Cost tracking requires:
- PostgreSQL connected (`GOCLAW_POSTGRES_DSN`)
- `telemetry.model_pricing` configured in `config.json`

If pricing is not configured, token counts are still tracked — only dollar amounts will be zero.


## How Cost Is Calculated

For each LLM call, GoClaw computes:

```
cost = (prompt_tokens × input_per_million / 1_000_000)
     + (completion_tokens × output_per_million / 1_000_000)
     + (cache_read_tokens × cache_read_per_million / 1_000_000)   // if > 0
     + (cache_creation_tokens × cache_create_per_million / 1_000_000)  // if > 0
```

Token counts come directly from the provider's API response. Cost is recorded on the LLM call span and rolled up to the trace level. Tools that make internal LLM calls (e.g., `read_image`, `read_document`) also have their costs tracked separately on their own spans.

---

## Querying Cost Data

### REST API

Cost is included in the standard usage endpoints. All endpoints require `Authorization: Bearer <token>` if `gateway.token` is set.

**`GET /v1/usage/summary`** — current vs. previous period totals:

```bash
curl -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/usage/summary?period=30d"
```

```json
{
  "current": {
    "requests": 1240,
    "input_tokens": 8420000,
    "output_tokens": 1980000,
    "cost": 42.31,
    "unique_users": 18,
    "errors": 3,
    "llm_calls": 3810,
    "tool_calls": 6200,
    "avg_duration_ms": 3200
  },
  "previous": {
    "requests": 890,
    "cost": 29.17,
    ...
  }
}
```

`period` values: `24h` (default), `today`, `7d`, `30d`.

**`GET /v1/usage/breakdown`** — cost grouped by provider, model, or channel:

```bash
curl -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/usage/breakdown?from=2026-03-01T00:00:00Z&to=2026-03-16T00:00:00Z&group_by=model"
```

```json
{
  "rows": [
    {
      "group": "claude-sonnet-4-5",
      "input_tokens": 6100000,
      "output_tokens": 1400000,
      "total_cost": 35.10,
      "request_count": 820
    },
    {
      "group": "gpt-4o",
      "input_tokens": 2320000,
      "output_tokens": 580000,
      "total_cost": 7.21,
      "request_count": 420
    }
  ]
}
```

`group_by` options: `provider` (default), `model`, `channel`.

**`GET /v1/usage/timeseries`** — cost over time:

```bash
curl -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/usage/timeseries?from=2026-03-01T00:00:00Z&to=2026-03-16T00:00:00Z&group_by=hour"
```

```json
{
  "points": [
    {
      "bucket_time": "2026-03-01T00:00:00Z",
      "request_count": 48,
      "input_tokens": 320000,
      "output_tokens": 78000,
      "total_cost": 1.73,
      "llm_call_count": 142,
      "tool_call_count": 230,
      "error_count": 0,
      "unique_users": 5,
      "avg_duration_ms": 2800
    }
  ]
}
```

**Common query parameters** (timeseries and breakdown):

| Parameter | Example | Notes |
|-----------|---------|-------|
| `from` | `2026-03-01T00:00:00Z` | RFC 3339, required |
| `to` | `2026-03-16T00:00:00Z` | RFC 3339, required |
| `group_by` | `hour`, `model`, `provider`, `channel` | Defaults vary per endpoint |
| `agent_id` | UUID | Filter by agent |
| `provider` | `anthropic` | Filter by provider |
| `model` | `claude-sonnet-4-5` | Filter by model |
| `channel` | `telegram` | Filter by channel |

### WebSocket

The `quota.usage` method returns today's cost alongside usage counters:

```json
{ "type": "req", "id": "1", "method": "quota.usage" }
```

```json
{
  "enabled": true,
  "requestsToday": 284,
  "inputTokensToday": 1240000,
  "outputTokensToday": 310000,
  "costToday": 1.84,
  "uniqueUsersToday": 12,
  "entries": [...]
}
```

`costToday` is always present. If pricing is not configured it will be `0`.

---

## Per-Sub-Agent Token Cost Tracking

As of v3 (#600), token costs are accumulated per sub-agent and included in announce messages. This means:

- Each spawned sub-agent accumulates its own `input_tokens` and `output_tokens` independently
- When a sub-agent completes, its token totals are included in the announce message sent to the parent agent's LLM context
- Token costs are persisted to the `subagent_tasks` table (migration 000034) for billing and observability queries
- Sub-agent token costs roll up to the parent trace's cost via the existing trace span hierarchy

Sub-agent costs appear in the same REST endpoints (`/v1/usage/timeseries`, `/v1/usage/breakdown`) under the sub-agent's own `agent_id`. To see the total cost of a multi-agent workflow, sum costs across all `agent_id` values that share the same root trace.

---

## Monthly Budget Enforcement

You can cap an agent's monthly spend by setting `budget_monthly_cents` on the agent record. When set, GoClaw queries the current month's accumulated cost before each run and blocks execution if the budget is exceeded.

Set via the agents API or directly in the `agents` table:

```json
{
  "budget_monthly_cents": 500
}
```

This example sets a $5.00/month limit. When the agent hits the limit, it returns an error:

```
monthly budget exceeded ($5.02 / $5.00)
```

The check runs once per request, before any LLM calls. Sub-agent delegations run under their own agent records with their own budgets.

> The agent's `budget_monthly_cents` is also mirrored into the [AI Budget Usage Caps](/usage-quota) system as a managed `month`-window cost-cap policy, so the same limit is enforced there too.

---

## Model Pricing (Catalog & Overrides)

The static `telemetry.model_pricing` map above is the simplest way to price models. For dynamic, database-backed pricing — used by the [AI Budget Usage Caps](/usage-quota) cost caps — GoClaw also keeps a **pricing catalog** and per-tenant **overrides** in PostgreSQL (migration `000070`).

### OpenRouter catalog sync

GoClaw can pull a full model price list from [OpenRouter](https://openrouter.ai) and store it in the `usage_pricing_catalog` table. Each entry captures per-unit prices for input, output, cache read/write, reasoning, request, image, and web-search units, stored as high-precision decimals.

```bash
curl -X POST -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/model-pricing/sync-openrouter"
```

This endpoint requires **master scope** (it updates the shared global catalog). The catalog is upserted by `model_id`, so re-running the sync refreshes prices in place.

### Per-model price overrides

When you want different prices for a specific tenant + provider + model (e.g. a negotiated rate, or a model OpenRouter doesn't list), set an **override** in the `usage_pricing_overrides` table. Overrides are scoped to one tenant and take priority over the global catalog.

```bash
# List the synced catalog (optionally filter by model)
curl -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/model-pricing?model=claude-sonnet-4-5"

# Set a tenant override
curl -X PUT -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  "http://localhost:8080/v1/model-pricing/overrides" \
  -d '{
    "provider_id": "22222222-2222-2222-2222-222222222222",
    "provider_type": "anthropic",
    "model_id": "claude-sonnet-4-5",
    "pricing": { "input": "0.000003", "output": "0.000015" }
  }'

# List / delete overrides
curl -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/model-pricing/overrides"
curl -X DELETE -H "Authorization: Bearer your-token" \
  "http://localhost:8080/v1/model-pricing/overrides/{id}"
```

| Method & path | Scope | Description |
|---------------|-------|-------------|
| `POST /v1/model-pricing/sync-openrouter` | master | Refresh the global price catalog from OpenRouter |
| `GET /v1/model-pricing` | admin | List the synced catalog (`?model=`, `?limit=`) |
| `PUT /v1/model-pricing/overrides` | tenant-admin | Create or update a per-tenant model price override |
| `GET /v1/model-pricing/overrides` | admin | List overrides (`?provider_id=`) |
| `DELETE /v1/model-pricing/overrides/{id}` | tenant-admin | Remove an override |

### How pricing resolves

When a cost cap needs a price for a model, GoClaw resolves in this order:

1. **Tenant override** for the matching provider + model (highest priority)
2. **Global OpenRouter catalog** entry by `model_id` / canonical id

If neither is found, a cost-capped call is blocked with reason `pricing_unknown`. Prices are stored as decimal USD **per token/unit** and converted to micro-dollars when caps compute cost.

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| `cost` is always `0` in API responses | `model_pricing` not configured | Add pricing under `telemetry.model_pricing` in `config.json` |
| Cost recorded for some models only | Key mismatch in pricing map | Use exact `"provider/model"` key (e.g., `"anthropic/claude-sonnet-4-5"`) or bare model name |
| Budget check blocks all runs | Monthly cost already exceeds `budget_monthly_cents` | Increase the budget or reset it; costs reset automatically at month rollover |
| Timeseries/breakdown returns empty | `from`/`to` missing or outside snapshot range | Snapshots are hourly; data older than retention period may be pruned |
| `costToday` in `quota.usage` is stale | Snapshots are pre-aggregated hourly | The current incomplete hour is gap-filled live from traces |

---

## What's Next

- [Usage & Quota](/usage-quota) — per-user request limits and token counts
- [Observability](/deploy-observability) — OpenTelemetry export for spans including cost fields
- [Configuration Reference](/config-reference) — full `telemetry` config options



---

# Model Steering

> How GoClaw guides small models through 3 control layers: Track (scheduling), Hint (contextual nudges), and Guard (safety boundaries).

## Overview

Small models (< 70B params) running agent loops commonly hit three problems:

| Problem | Symptom |
|---------|---------|
| **Losing direction** | Uses up iteration budget without answering, loops on meaningless tool calls |
| **Forgetting context** | Doesn't report progress, ignores existing information |
| **Safety violations** | Runs dangerous commands, falls to prompt injection, writes malicious code |

GoClaw addresses these with **3 steering layers** that run concurrently on every request:

```mermaid
flowchart LR
    REQ([Request]) --> TRACK

    subgraph TRACK["Track — Where to run?"]
        direction TB
        T1[Lane routing]
        T2[Concurrency control]
        T3[Session serialization]
    end

    TRACK --> GUARD

    subgraph GUARD["Guard — What's allowed?"]
        direction TB
        G1[Input validation]
        G2[Shell deny patterns]
        G3[Skill content scan]
    end

    GUARD --> HINT

    subgraph HINT["Hint — What should it do?"]
        direction TB
        H1[Budget warnings]
        H2[Error guidance]
        H3[Progress nudges]
    end

    HINT --> LOOP([Agent Loop])
```

**Design principles:**
- **Track** — infrastructure layer; the model has no visibility into which lane it runs on
- **Guard** — hard boundary; blocks dangerous behavior regardless of which model is running
- **Hint** — soft guidance; injected as messages into the conversation; the model can ignore hints (but usually doesn't)


## Hint System (Contextual Guidance Injection)

Hints are **messages injected into the conversation** at strategic points during the agent loop. Small models benefit most from hints because they tend to forget initial instructions as conversations grow long.

### When Hints Are Injected

```mermaid
flowchart TD
    subgraph LOOP["Agent Loop Phases"]
        PH3["Phase 3: Build Messages"]
        PH4["Phase 4: LLM Iteration"]
        PH5["Phase 5: Tool Execution"]
    end

    CH["Channel Formatting Hint"] -.-> PH3
    SR["System Prompt Reminders"] -.-> PH3

    BH["Budget Hint (75%)"] -.-> PH4
    OT["Output Truncation Hint"] -.-> PH4
    SE["Skill Nudge (70% / 90%)"] -.-> PH4
    TN["Team Progress Nudge (every 6 iter)"] -.-> PH4

    SH["Sandbox Error Hint"] -.-> PH5
    TC["Task Creation Guide"] -.-> PH5
```

### 8 Hint Types

#### 1. Budget Hints — Preventing Directionless Looping

Fires when the model uses up its iteration budget without producing a text response:

| Trigger | Injected Message |
|---------|-----------------|
| 75% of iterations used, no text response yet | "You've used 75% of your budget. Start synthesizing results." |
| Max iterations reached | Loop stops and returns final result |

This is especially effective with small models — instead of letting them loop indefinitely, it forces early summarization.

#### 2. Output Truncation Hints — Error Recovery

When the LLM response is cut off due to `max_tokens`:

> `[System] Output was truncated. Tool call arguments are incomplete. Retry with shorter content — split writes or reduce text.`

Small models often don't recognize that their output was truncated. This hint explains the cause and prompts them to adjust.

#### 3. Skill Evolution Nudges — Encouraging Self-Improvement

| Trigger | Content |
|---------|---------|
| 70% of iteration budget used | Suggests creating a skill to reuse the current workflow |
| 90% of iteration budget used | Stronger reminder about skill creation |

These hints are **ephemeral** (not persisted to session history) and support **i18n** (en/vi/zh).

#### 4. Team Progress Nudges — Progress Reporting Reminders

Every 6 iterations when the agent is working on a team task:

> `[System] You're at iteration 12/20 (~60% budget) for task #3: 'Implement auth module'. Report progress now: team_tasks(action="progress", percent=60, text="...")`

Without this, small models tend to forget to call progress reporting → the lead agent doesn't know the status → bottleneck.

#### 5. Sandbox Error Hints — Explaining Environment Errors

When a command in a Docker sandbox encounters an error, the hint is **attached directly to the error output**:

| Error Pattern | Hint |
|--------------|------|
| Exit code 127 / "command not found" | Binary not installed in sandbox image |
| "permission denied" / EACCES | Workspace mounted read-only |
| "network is unreachable" / DNS fail | `--network none` is enabled |
| "read-only file system" / EROFS | Writing outside workspace volume |
| "no space left" / ENOSPC | Disk/memory exhausted in container |
| "no such file" | File doesn't exist in sandbox |

Hint priority: exit code 127 is checked first, then pattern-matched in priority order.

#### 6. Channel Formatting Hints — Platform-Specific Guidance

Injected into the system prompt based on the channel type:

- **Zalo** — "Use plain text, no markdown, no HTML"
- **Group chat** — Instructions on using the `NO_REPLY` token when a message doesn't require a response

#### 7. Task Creation Guidance — Lead Agent Help

When the model lists or searches team tasks, the response includes:
- List of team members + their models
- 4 rules: write self-contained descriptions, split complex tasks, match task complexity to model capability, ensure task independence

Especially useful when small models (MiniMax, Qwen) act as lead agents — they tend to create vague tasks or misassign complexity.

#### 8. System Prompt Reminders — Recency Zone Reinforcement

Injected at the end of the system prompt (the "recency zone" — the part the model pays most attention to):
- Reminder to search memory before answering
- Persona/character reinforcement if the agent has a custom identity
- Onboarding nudges for new users

### Hint Summary Table

| Hint | Trigger | Ephemeral? | Injection Point |
|------|---------|:----------:|-----------------|
| Budget 75% | iteration == max×¾, no text yet | Yes | Message list (Phase 4) |
| Output Truncation | `finish_reason == "length"` | Yes | Message list (Phase 4) |
| Skill Nudge 70% | iteration/max ≥ 0.70 | Yes | Message list (Phase 4) |
| Skill Nudge 90% | iteration/max ≥ 0.90 | Yes | Message list (Phase 4) |
| Team Progress | iteration % 6 == 0 and has TeamTaskID | Yes | Message list (Phase 4) |
| Sandbox Error | Pattern match on stderr/exit code | No | Tool result suffix (Phase 5) |
| Channel Format | Channel type == "zalo" etc. | No | System prompt (Phase 3) |
| Task Creation | `team_tasks` list/search response | No | Tool result JSON (Phase 5) |
| Memory/Persona | Config flags | No | System prompt (Phase 3) |

---

## Guard System (Safety Boundaries)

Guards create **hard boundaries** — they don't depend on model compliance. Even if a small model is tricked by a prompt injection attack, guards block dangerous behavior at the infrastructure level.

### 4-Layer Guard Architecture

```mermaid
flowchart TD
    INPUT([User Message]) --> IG

    subgraph IG["Layer 1: InputGuard"]
        IG1["6 regex patterns"]
        IG2["Action: log / warn / block / off"]
    end

    IG --> LOOP([Agent Loop])
    LOOP --> TOOL{Tool call?}

    TOOL -->|exec / shell| SDG
    TOOL -->|write SKILL.md| SCG
    TOOL -->|other| SAFE[Allow]

    subgraph SDG["Layer 2: Shell Deny Groups"]
        SDG1["15 categories, 200+ patterns"]
        SDG2["Per-agent overrides"]
    end

    subgraph SCG["Layer 3: Skill Content Guard"]
        SCG1["25 security rules"]
        SCG2["Line-by-line scan"]
    end

    SDG --> RESP([Response])
    SCG --> RESP
    SAFE --> RESP

    RESP --> VG

    subgraph VG["Layer 4: Voice Guard"]
        VG1["Error → friendly fallback"]
    end
```

### Layer 1: InputGuard — Prompt Injection Detection

Scans **every user message** before it enters the agent loop, plus injected messages and web fetch/search results.

| Pattern | Detects |
|---------|---------|
| `ignore_instructions` | "Ignore all previous instructions…" |
| `role_override` | "You are now a…", "Pretend you are…" |
| `system_tags` | `<system>`, `[SYSTEM]`, `[INST]`, `<<SYS>>`, `<\|im_start\|>system` |
| `instruction_injection` | "New instructions:", "Override:", "System prompt:" |
| `null_bytes` | `\x00` characters (null byte injection) |
| `delimiter_escape` | "End of system", `</instructions>`, `</prompt>` |

**4 action modes** (config: `gateway.injection_action`):

| Mode | Behavior |
|------|---------|
| `log` | Log info, do not block |
| `warn` | Log warning (default) |
| `block` | Reject message, return error to user |
| `off` | Disable scanning entirely |

**3 scan points:** incoming user message (Phase 2), mid-run injected messages, and tool results from `web_fetch`/`web_search`.

### Layer 2: Shell Deny Groups — Command Safety

15 deny groups, all **ON by default**. Admin must explicitly allow a group to disable it.

| Group | Example Patterns |
|-------|-----------------|
| `destructive_ops` | `rm -rf`, `mkfs`, `dd if=`, `shutdown`, fork bomb |
| `data_exfiltration` | `curl \| sh`, `wget POST`, DNS lookup, `/dev/tcp/` |
| `reverse_shell` | `nc`, `socat`, `openssl s_client`, Python/Perl socket |
| `code_injection` | `eval $()`, `base64 -d \| sh` |
| `privilege_escalation` | `sudo`, `su`, `doas`, `pkexec`, `runuser`, `nsenter` |
| `dangerous_paths` | `chmod`/`chown` on system paths |
| `env_injection` | `LD_PRELOAD`, `BASH_ENV`, `GIT_EXTERNAL_DIFF` |
| `container_escape` | Docker socket, `/proc/sys/`, `/sys/` |
| `crypto_mining` | `xmrig`, `cpuminer`, `stratum+tcp://` |
| `filter_bypass` | `sed -e`, `git --exec`, `rg --pre` |
| `network_recon` | `nmap`, `ssh`/`scp`/`sftp`, tunneling |
| `package_install` | `pip install`, `npm install`, `apk add` |
| `persistence` | `crontab`, shell RC file writes |
| `process_control` | `kill -9`, `killall`, `pkill` |
| `env_dump` | `env`, `printenv`, `/proc/*/environ`, `GOCLAW_*` |

**Special case:** `package_install` triggers an approval flow (not a hard deny) — the agent pauses and asks the user for permission. All other groups are hard-blocked.

**Per-agent override:** Admins can allow specific deny groups for specific agents via DB config.

### Layer 3: Skill Content Guard

Scans **SKILL.md content** before writing the file. 25 regex rules detect:

- Shell injection and destructive operations
- Code obfuscation (`base64 -d`, `eval`, `curl | sh`)
- Credential theft (`/etc/passwd`, `.ssh/id_rsa`, `AWS_SECRET_ACCESS_KEY`)
- Path traversal (`../../..`)
- SQL injection (`DROP TABLE`, `TRUNCATE`)
- Privilege escalation (`sudo`, `chmod 777`)

Any violation results in a **hard reject** — the file is not written and the model receives an error.

### Layer 4: Voice Guard

Specialized for Telegram voice agents. When voice/audio processing encounters a technical error, Voice Guard replaces the raw error message with a friendly fallback for end users. This is a UX guard, not a security guard.

### Guard Summary

| Guard | Scope | Default Action | Configurable? |
|-------|-------|:--------------:|:-------------:|
| InputGuard | All user messages + injected + tool results | warn | Yes (log/warn/block/off) |
| Shell Deny | All `exec`/`shell` tool calls | hard block | Yes (per-agent group override) |
| Skill Content | SKILL.md file writes | hard reject | No |
| Voice Guard | Telegram voice error replies | friendly fallback | No |

---

## How the 3 Layers Work Together

```mermaid
flowchart TD
    REQ([User Request]) --> TRACK_ROUTE

    subgraph TRACK["TRACK"]
        TRACK_ROUTE["Lane routing"]
        TRACK_ROUTE --> QUEUE["Session queue"]
        QUEUE --> THROTTLE["Adaptive throttle"]
    end

    THROTTLE --> GUARD_INPUT

    subgraph GUARD["GUARD"]
        GUARD_INPUT["InputGuard scan"]
        GUARD_INPUT --> LOOP_START["Agent Loop"]
        LOOP_START --> TOOL_CALL{Tool call?}
        TOOL_CALL -->|exec/shell| SHELL_DENY["Shell Deny Groups"]
        TOOL_CALL -->|write skill| SKILL_GUARD["Skill Content Guard"]
        TOOL_CALL -->|other| SAFE[Allow]
    end

    SHELL_DENY --> HINT_INJECT
    SKILL_GUARD --> HINT_INJECT
    SAFE --> HINT_INJECT

    subgraph HINT["HINT"]
        HINT_INJECT["Sandbox hints"]
        HINT_INJECT --> BUDGET["Budget / truncation hints"]
        BUDGET --> PROGRESS["Progress nudges"]
        PROGRESS --> SKILL_EVO["Skill evolution nudges"]
    end

    SKILL_EVO --> LLM([LLM continues iteration])
    LLM --> TOOL_CALL
```

| Layer | Question answered | Mechanism | Nature |
|-------|------------------|-----------|--------|
| **Track** | Where to run? | Lane + Queue + Semaphore | Infrastructure, invisible to model |
| **Guard** | What's allowed? | Regex pattern matching, hard deny | Security boundary, model-agnostic |
| **Hint** | What should it do? | Message injection into conversation | Soft guidance, model can ignore |

**When using large models** (Claude, GPT-4): Guard is still necessary. Hint is less critical because large models track context better.

**When using small models** (MiniMax, Qwen, Gemini Flash): all 3 layers are critical.

---

## Mode Prompt System

Beyond the runtime steering layers, GoClaw applies **prompt-level steering** by varying which system prompt sections are included based on context. This reduces token cost for background tasks while keeping full guidance for user-facing interactions.

### Prompt Modes

| Mode | Who gets it | Sections included |
|------|-------------|------------------|
| `full` | Main user-facing agents | All sections — persona, skills, MCP, memory, spawn guidance, recency reinforcements |
| `task` | Enterprise automation agents | Lean but capable — execution bias, skills search, memory slim, safety slim |
| `minimal` | Subagents spawned via `spawn` | Reduced — tooling, safety, workspace, pinned skills only |
| `none` | Identity-only (rare) | Identity line only, no tooling guidance |

**3-layer resolution** (highest priority wins):

1. **Runtime override** — caller passes explicit mode (e.g. subagent dispatch sets `minimal`)
2. **Auto-detect** — heartbeat sessions → `minimal`; subagent/cron sessions → `task` (capped)
3. **Agent config** — `prompt_mode` field in agent config
4. **Default** — `full`

```go
// Priority: runtime > auto-detect > config > default
func resolvePromptMode(runtimeOverride, sessionKey, configMode PromptMode) PromptMode
```

### Orchestration Modes

Each agent is assigned an orchestration mode based on its capabilities. This determines which inter-agent tools are available and which sections appear in the system prompt:

| Mode | How assigned | Tools available | Prompt section |
|------|-------------|----------------|----------------|
| `spawn` | Default (no links or team) | `spawn` only | Sub-Agent Spawning |
| `delegate` | Agent has AgentLink targets | `spawn` + `delegate` | Delegation Targets |
| `team` | Agent is in a team | `spawn` + `delegate` + `team_tasks` | Team Workspace + Team Members |

Resolution priority: team > delegate > spawn.

The `delegate` and `team_tasks` tools are hidden from the LLM unless the agent's mode explicitly enables them (`orchModeDenyTools`).

### Prompt Cache Boundary

For Anthropic providers, GoClaw splits the system prompt at a cache boundary marker:

```


---

# Agent Evolution

> Let predefined agents refine their communication style and build reusable skills over time — automatically, with your consent.

## Overview

GoClaw includes three subsystems that allow predefined agents to evolve their behavior across conversations. All three are **opt-in** and **restricted to predefined agents** — open agents are not eligible.

| Subsystem | What it does | Config key |
|---|---|---|
| Self-Evolution | Agent refines its own tone/voice (SOUL.md) and domain expertise (CAPABILITIES.md) | `self_evolve` |
| Skill Learning Loop | Agent captures reusable workflows as skills | `skill_evolve` |
| Skill Management | Create, patch, delete, and grant skills | `skill_manage` tool |

Both `self_evolve` and `skill_evolve` are disabled by default. Enable them per-agent in **Agent Settings → Config tab**.


## Skill Learning Loop

### What it does

When `skill_evolve` is enabled, GoClaw encourages agents to capture complex multi-step processes as reusable skills. The loop has three touch points:

1. **System prompt guidance** — injected at the start of every request with SHOULD/SHOULD NOT criteria
2. **Budget nudges** — ephemeral reminders injected mid-loop at 70% and 90% of the iteration budget
3. **Postscript suggestion** — appended to the agent's final response when enough tool calls happened; requires explicit user consent

No skill is ever created without the user replying "save as skill". Replying "skip" does nothing.

### Enabling it

| Setting | Location | Default |
|---|---|---|
| `skill_evolve` | Agent Settings → Config tab → Skill Learning toggle | `false` |
| `skill_nudge_interval` | Config tab → interval input | `15` |

`skill_nudge_interval` is the minimum number of tool calls in a run before the postscript fires. Set to `0` to disable postscripts entirely while keeping budget nudges.

Open agents always get `skill_evolve=false` regardless of the database setting — enforcement happens at the resolver level.

### How the loop flows

```
Admin enables skill_evolve
        ↓
System prompt includes Skill Creation guidance (every request)
        ↓
Agent processes request (think → act → observe)
        ↓
  ≥70% iteration budget? → ephemeral nudge (soft suggestion)
  ≥90% iteration budget? → ephemeral nudge (moderate urgency)
        ↓
Agent completes task
        ↓
  totalToolCalls ≥ skill_nudge_interval?
    No  → Normal response
    Yes → Postscript appended: "Save as skill? or skip?"
              ↓
        User replies "skip"        → No action
        User replies "save as skill" → Agent calls skill_manage(create)
                                          ↓
                                      Skill created + auto-granted
                                          ↓
                                      Available on next turn
```

### System prompt guidance

When `skill_evolve=true` and the `skill_manage` tool is registered, GoClaw injects this block (~135 tokens per request):

```
### Skill Creation (recommended after complex tasks)

After completing a complex task (5+ tool calls), consider:
"Would this process be useful again in the future?"

SHOULD create skill when:
- Process is repeatable with different inputs
- Multiple steps that are easy to forget
- Domain-specific workflow others could benefit from

SHOULD NOT create skill when:
- One-time task specific to this user/context
- Debugging or troubleshooting (too context-dependent)
- Simple tasks (< 5 tool calls)
- User explicitly said "skip" or declined

Creating: skill_manage(action="create", content="---\nname: ...\n...")
Improving: skill_manage(action="patch", slug="...", find="...", replace="...")
Removing: skill_manage(action="delete", slug="...")

Constraints:
- You can only manage skills you created (not system or other users' skills)
- Quality over quantity — one excellent skill beats five mediocre ones
- Ask user before creating if unsure
```

### Budget nudges

These are ephemeral user messages injected into the agent loop. They are **not** persisted to session history and fire at most once per run each.

**At 70% of iteration budget (~31 tokens):**
```
[System] You are at 70% of your iteration budget. Consider whether any
patterns from this session would make a good skill.
```

**At 90% of iteration budget (~48 tokens):**
```
[System] You are at 90% of your iteration budget. If this session involved
reusable patterns, consider saving them as a skill before completing.
```

### Postscript suggestion

When `totalToolCalls >= skill_nudge_interval`, this text is appended to the agent's final response (~35 tokens, persisted in session):

```
---
_This task involved several steps. Want me to save the process as a
reusable skill? Reply "save as skill" or "skip"._
```

The postscript fires at most once per run. Subsequent runs reset the flag.

### Tool gating

When `skill_evolve=false`, the `skill_manage` tool is completely hidden from the LLM — filtered from tool definitions before they are sent to the provider, and excluded from tool names in system prompt construction. The agent has zero awareness of it.

---

## Skill Management

### skill_manage tool

The `skill_manage` tool is available to agents when `skill_evolve=true`. It supports three actions:

| Action | Required params | What it does |
|---|---|---|
| `create` | `content` | Creates a new skill from a SKILL.md content string |
| `patch` | `slug`, `find`, `replace` | Applies a find-and-replace patch to an existing skill |
| `delete` | `slug` | Soft-deletes a skill (moved to `.trash/`) |

**Full parameter reference:**

| Parameter | Type | Required for | Description |
|---|---|---|---|
| `action` | string | all | `create`, `patch`, or `delete` |
| `slug` | string | patch, delete | Unique skill identifier |
| `content` | string | create | Full SKILL.md including YAML frontmatter |
| `find` | string | patch | Exact text to find in current SKILL.md |
| `replace` | string | patch | Replacement text |
| `files` | object | optional (create, patch) | Companion text files keyed by relative path (e.g. `references/guide.md`). Each file is capped at **2 MB**; paths are validated (no `..`, absolute/Windows paths, null bytes, `SKILL.md` overwrite, dotfiles, or system artifacts) |
| `visibility` | string | optional (patch) | Metadata-only visibility change (`private` or `public`) — updates who can discover the skill without creating a new version when no `content`/`files` change |

**Example — creating a skill from conversation:**

```
skill_manage(
  action="create",
  content="---\nname: Deploy Checklist\ndescription: Steps to deploy the app safely.\n---\n\n## Steps\n1. Run tests\n2. Build image\n3. Push to registry\n4. Apply manifests\n5. Verify rollout"
)
```

**Example — patching an existing skill:**

```
skill_manage(
  action="patch",
  slug="deploy-checklist",
  find="5. Verify rollout",
  replace="5. Verify rollout\n6. Notify team in Slack"
)
```

**Example — deleting a skill:**

```
skill_manage(action="delete", slug="deploy-checklist")
```

**Example — creating a skill with a companion reference file:**

```
skill_manage(
  action="create",
  content="---\nname: Deploy Checklist\ndescription: Steps to deploy the app safely.\n---\n\n## Steps\nSee {baseDir}/references/runbook.md",
  files={"references/runbook.md": "# Runbook\n1. Run tests\n2. Build image\n3. Push to registry"}
)
```

### publish_skill tool

`publish_skill` is an alternative path that registers an entire local directory as a skill. It is always available as a built-in tool toggle (not gated by `skill_evolve`).

```
publish_skill(path="./skills/my-skill")
```

The directory must contain a `SKILL.md` with a `name` in frontmatter. The skill starts with `private` visibility and is auto-granted to the calling agent. Use the Dashboard or API to grant it to other agents.

**Comparison:**

| | `skill_manage` | `publish_skill` |
|---|---|---|
| Input | Content string | Directory path |
| Files | SKILL.md plus direct text companion files (`files=...`); patch copies existing companions forward | Entire directory (scripts, assets, etc.) |
| Gated by | `skill_evolve` config | Built-in tool toggle (always available) |
| Guidance | Injected via skill_evolve prompt | Uses `skill-creator` core skill |
| Auto-grant | Yes | Yes |

---

## Security

Every skill mutation passes through four layers before anything is written to disk.

### Layer 1 — Content Guard

Line-by-line regex scan of the SKILL.md content. Hard-reject on any match. 25 rules across 6 categories:

| Category | Examples |
|---|---|
| Destructive shell | `rm -rf /`, fork bomb, `dd of=/dev/`, `mkfs`, `shred` |
| Code injection | `base64 -d \| sh`, `eval $(...)`, `curl \| bash`, `python -c exec()` |
| Credential exfil | `/etc/passwd`, `.ssh/id_rsa`, `AWS_SECRET_ACCESS_KEY`, `GOCLAW_DB_URL` |
| Path traversal | `../../../` deep traversal |
| SQL injection | `DROP TABLE`, `TRUNCATE TABLE`, `DROP DATABASE` |
| Privilege escalation | `sudo`, world-writable `chmod`, `chown root` |

This is a defense-in-depth layer — not exhaustive. GoClaw's `exec` tool has its own runtime deny-list for shell commands.

### Layer 2 — Ownership Enforcement

Three-layer ownership check across all mutation paths:

| Layer | Check |
|---|---|
| `skill_manage` tool | `GetSkillOwnerIDBySlug(slug)` before patch/delete |
| HTTP API | `GetSkillOwnerID(uuid)` + admin role bypass |
| WebSocket gateway | `skillOwnerGetter` interface + admin role bypass |

Agents can only modify skills they created. Admins can bypass ownership checks. System skills (`is_system=true`) cannot be modified through any path.

### Layer 3 — System Skill Guard

System skills are always read-only. Any attempt to patch or delete a skill with `is_system=true` is rejected before reaching the filesystem.

### Layer 4 — Filesystem Safety

| Protection | Detail |
|---|---|
| Symlink detection | `filepath.WalkDir` checks for symlinks — rejects any |
| Path traversal | Rejects paths containing `..` segments |
| SKILL.md size limit | 100 KB max |
| Companion files size limit | 20 MB max total (scripts, assets) |
| Soft-delete | Files moved to `.trash/`, never hard-deleted |

---

## Versioning and Storage

Each create or patch produces a new immutable version directory. GoClaw always serves the highest-numbered version.

```
skills-store/
├── deploy-checklist/
│   ├── 1/
│   │   └── SKILL.md
│   └── 2/              ← patch created this version
│       └── SKILL.md
├── .trash/
│   └── old-skill.1710000000   ← soft-deleted
```

Concurrent version creation for the same skill is serialized via `pg_advisory_xact_lock` keyed on FNV-64a hash of the slug. Version numbers are computed inside the transaction using `COALESCE(MAX(version), 0) + 1`.

---

## Token Cost

| Component | When active | Approx tokens | Persisted? |
|---|---|---|---|
| Self-evolve section | `self_evolve=true` | ~95 | Every request |
| Skill creation guidance | `skill_evolve=true` | ~135 | Every request |
| `skill_manage` tool definition | `skill_evolve=true` | ~290 | Every request |
| Budget nudge 70% | iter ≥ 70% of max | ~31 | No (ephemeral) |
| Budget nudge 90% | iter ≥ 90% of max | ~48 | No (ephemeral) |
| Postscript | toolCalls ≥ interval | ~35 | Yes |

Maximum overhead per run with both features enabled: ~305 tokens for skill learning (~1.5% of a 128K context). When both are disabled (the default), zero token overhead.

---

## v3: Evolution Metrics and Suggestion Engine

v3 adds automated, metrics-driven evolution for predefined agents. This operates separately from the manual skill learning loop above.

### How It Works

```
Metrics collected during agent runs (7-day rolling window)
    ↓
SuggestionEngine.Analyze() — runs daily via cron
    ├─ LowRetrievalUsageRule  (avg recall < threshold)
    ├─ ToolFailureRule         (single tool failure rate > 20%)
    └─ RepeatedToolRule        (tool called 5+ consecutive times)
    ↓
Suggestion created with status "pending"
    ↓
Admin reviews → approve / reject / rollback
```

### Metric Types

| Type | What is tracked | Examples |
|------|----------------|---------|
| `tool` | Per-tool performance | invocation_count, success_rate, failure_count, avg_duration_ms |
| `retrieval` | Knowledge retrieval quality | recall_rate, precision, relevance_score |
| `feedback` | User satisfaction signals | rating, sentiment, effectiveness_score |

Metrics aggregate over 7-day rolling windows. At least 100 data points are required before a suggestion can be auto-applied (configurable via `min_data_points` guardrail).

### Suggestion Types

| Type | Trigger | Recommendation |
|------|---------|----------------|
| `low_retrieval_usage` | Avg recall below threshold for 7 days | Lower `retrieval_threshold` by ≤ 0.1 |
| `tool_failure` | Single tool failure rate > 20% | Review tool config or add fallback |
| `repeated_tool` | Same tool called 5+ consecutive times | Extract workflow as a skill |

Only one pending suggestion of each type per agent exists at a time (duplicate prevention).

### Auto-Adapt Guardrails

Suggestions can be auto-applied when approved. Guardrails prevent runaway parameter changes:

| Guardrail | Default | Purpose |
|-----------|---------|---------|
| `max_delta_per_cycle` | 0.1 | Max parameter change per apply cycle |
| `min_data_points` | 100 | Minimum metrics required before applying |
| `rollback_on_drop_pct` | 20.0 | Auto-rollback if quality drops >20% after apply |
| `locked_params` | `[]` | Parameters that cannot be auto-changed |

Baseline parameter values are stored in the suggestion's `parameters._baseline` field for rollback.

### Evolution Cron

Analysis runs on a configurable schedule (default: daily at 02:00). Set via `evolution_cron_schedule` in agent config:

```json
{
  "evolution_enabled": true,
  "evolution_cron_schedule": "every day at 02:00",
  "evolution_guardrails": {
    "max_delta_per_cycle": 0.1,
    "min_data_points": 100,
    "rollback_on_drop_pct": 20.0,
    "locked_params": []
  }
}
```

Set `evolution_enabled: false` to disable all metrics collection for an agent.

### HTTP API

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{id}/evolution/metrics` | Query/aggregate metrics |
| `GET` | `/v1/agents/{id}/evolution/suggestions` | List suggestions |
| `PATCH` | `/v1/agents/{id}/evolution/suggestions/{sid}` | Approve / reject / rollback |

WebSocket equivalents: `agent.evolution.metrics`, `agent.evolution.suggestions`, `agent.evolution.apply`, `agent.evolution.rollback`.

---

## Skill Self-Evolution (per-skill metrics)

This is a **separate subsystem** from the agent-level "v3 Evolution Metrics" above. Where agent-level evolution tunes an *agent's* parameters, skill self-evolution tracks how each **existing skill** performs over time and proposes improvements to that skill. It is also distinct from the `skill_evolve` learning loop, which teaches an agent *when* to create or patch reusable skills.

### Runtime recording

Usage is recorded automatically as agents use skills — there is **no public usage endpoint**:

- `use_skill` tool calls record tenant-scoped usage with status `succeeded` or `failed`, plus duration, session key, run/trace ID, agent ID, and user scope.
- Slash-command activation (`/<slug>` or `/use <skill>`) records a `started` event when it resolves to a skill.
- Usage writes are **internal only**. v1 intentionally has no public `POST /v1/skills/{id}/usage` endpoint, so clients cannot forge success rates.

### Persistent tables

| Table | Purpose |
|---|---|
| `skill_evolution_settings` | Per-tenant, per-skill `enabled` flag and `mode` |
| `skill_usage_metrics` | Runtime usage events and status counts |
| `skill_improvement_suggestions` | Skill-scoped suggestions with evidence and draft patches |
| `skill_versions` | Immutable applied-version records linked to changed files and the originating suggestion |

### Modes and statuses

| Field | Values | Notes |
|---|---|---|
| Settings `mode` | `suggest_only` (default), `auto_analyze` | No automatic *patching* happens in v1 — `auto_analyze` only generates suggestions automatically |
| Usage `status` | `started`, `succeeded`, `failed`, `abandoned` | Recorded per skill invocation |
| Suggestion `status` | `pending`, `approved`, `rejected`, `applied` | Lifecycle of an improvement suggestion |

### Applying a suggestion

Suggestions are reviewed and applied by admins. Applying a suggestion to a **custom** skill:

1. Copies the current skill directory forward to the next version.
2. Validates the target path (same rules as `skill_manage` companion files).
3. Runs the SKILL.md content guard scanner when SKILL.md changes.
4. Updates the active skill and records a new `skill_versions` row.
5. Writes an activity log entry.

**System/bundled skill mutation is refused** — the apply path returns `403` for any skill with `is_system = true`, before touching the filesystem.

### Admin-gated surfaces

Viewer surfaces are sanitized. Failure evidence, draft patches, actor IDs, and activity details require **admin** visibility — non-admins see only aggregate, non-sensitive data.

### HTTP API

| Method | Path | Access |
|---|---|---|
| `GET` | `/v1/skills/{id}/evolution` | Read self-evolution settings |
| `PATCH` | `/v1/skills/{id}/evolution` | Set `enabled` / `mode` (tenant admin) |
| `GET` | `/v1/skills/{id}/metrics` | Usage metrics (total / started / succeeded / failed / abandoned / success rate) |
| `GET` | `/v1/skills/{id}/activity` | Recent self-evolution activity (admin only) |
| `GET` | `/v1/skills/{id}/evolution/suggestions` | List suggestions for the skill |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{sid}/approve` | Approve a suggestion (tenant admin) |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{sid}/reject` | Reject a suggestion (tenant admin) |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{sid}/apply` | Apply an approved suggestion (tenant admin) |

The matching CLI commands are `goclaw skills evolve`, `goclaw skills metrics`, `goclaw skills suggestions`, and `goclaw skills activity`. The Dashboard surfaces all of this in the skill detail's **Evolution** tab.

---

## Common Issues

| Issue | Cause | Fix |
|---|---|---|
| Self-Evolution toggle not visible | Agent is not predefined type | Self-evolution is only for predefined agents |
| Skill not saved after postscript | User did not reply "save as skill" | Postscript requires explicit consent — reply with exact phrase |
| `skill_manage` not available to agent | `skill_evolve=false` or agent is open type | Enable `skill_evolve` in Config tab; verify agent is predefined |
| Patch fails with "not owner" | Agent trying to patch another agent's skill | Each agent can only modify skills it created |
| Patch fails with "system skill" | Attempting to modify a built-in system skill | System skills are always read-only |
| Skill content rejected | Content matched a security rule in guard.go | Remove the flagged pattern; see Layer 1 categories above |
| Companion file rejected by `skill_manage` | Path uses `..`, an absolute/Windows path, a dotfile, or a system artifact; or the file exceeds 2 MB | Use a clean relative path under the skill root and keep each text file under 2 MB |
| Cannot apply a skill suggestion | Target is a system/bundled skill, or the suggestion is not yet `approved` | System skills are read-only; approve the suggestion first, then apply |
| Skill metrics show no data | No `use_skill`/slash-command activations recorded yet, or self-evolution disabled | Usage is recorded internally as agents use the skill; enable self-evolution in the skill's Evolution tab |

---

## What's Next

- [Skills](./skills.md) — skill format, hierarchy, and hot reload
- [Predefined Agents](../core-concepts/agents-explained.md) — how predefined agents differ from open agents



---

# Docker Compose Deployment

> GoClaw ships a composable docker-compose setup: a base file, a `compose.d/` directory of always-active overlays, and a `compose.options/` directory of opt-in overlays you mix and match.

> **Auto-upgrade on start:** The Docker entrypoint runs `goclaw upgrade` automatically before starting the gateway. This applies pending database migrations so you don't need a separate upgrade step for simple deployments. For production, consider running the upgrade overlay explicitly first.

## Overview

The compose setup is modular. The base `docker-compose.yml` defines the core `goclaw` service. Active overlays live in `compose.d/` and are assembled automatically. Optional overlays in `compose.options/` can be copied into `compose.d/` to activate them.

### `compose.d/` — always-active overlays

Files in `compose.d/` are loaded automatically by `prepare-compose.sh` (sorted by filename):

```
compose.d/
  00-goclaw.yml        # Core service definition
  11-postgres.yml      # PostgreSQL 18 + pgvector
  12-selfservice.yml   # Web dashboard UI (nginx + React, port 3000)
  13-upgrade.yml       # One-shot DB migration runner
  14-browser.yml       # Headless Chrome sidecar (CDP, port 9222)
  15-otel.yml          # Jaeger for OpenTelemetry trace visualization
  16-redis.yml         # Redis 7 cache backend
  17-sandbox.yml       # Docker-in-Docker sandbox for agent code execution
  18-tailscale.yml     # Tailscale tsnet for secure remote access
```

### `compose.options/` — opt-in overlays

The `compose.options/` directory holds the same overlay files as reference copies. Copy the ones you want into `compose.d/` to activate them.

### `prepare-compose.sh` — build the COMPOSE_FILE

Run this script once after changing `compose.d/` to regenerate the `COMPOSE_FILE` variable in `.env`:

```bash
./prepare-compose.sh
```

The script reads all `compose.d/*.yml` files (sorted), validates the merged config with `docker compose config`, and writes the `COMPOSE_FILE` value to `.env`. Docker Compose reads `COMPOSE_FILE` automatically on every `docker compose` command.

```bash
# Flags
./prepare-compose.sh --quiet             # suppress output
./prepare-compose.sh --skip-validation   # skip docker compose config check
```

> **podman-compose:** `COMPOSE_FILE` is not read automatically. Run `source .env` before each `podman-compose` command.


## Overlay Reference

### `docker-compose.postgres.yml`

Starts `pgvector/pgvector:pg18` and wires `GOCLAW_POSTGRES_DSN` automatically. GoClaw waits for the health check before starting.

Environment variables (set in `.env` or shell):

| Variable | Default | Description |
|----------|---------|-------------|
| `POSTGRES_USER` | `goclaw` | Database user |
| `POSTGRES_PASSWORD` | `goclaw` | Database password — **change for production** |
| `POSTGRES_DB` | `goclaw` | Database name |
| `POSTGRES_PORT` | `5432` | Host port to expose |

### `docker-compose.selfservice.yml`

Builds the React SPA from `ui/web/` and serves it via nginx on port 3000.

| Variable | Default | Description |
|----------|---------|-------------|
| `GOCLAW_UI_PORT` | `3000` | Host port for the dashboard |

### `docker-compose.sandbox.yml`

Mounts `/var/run/docker.sock` so GoClaw can spin up isolated containers for agent shell execution. Requires the sandbox image to be built first.

> **Security note:** Mounting the Docker socket gives the container control over host Docker. Only use in trusted environments.

| Variable | Default | Description |
|----------|---------|-------------|
| `GOCLAW_SANDBOX_MODE` | `all` | `off`, `non-main`, or `all` |
| `GOCLAW_SANDBOX_IMAGE` | `goclaw-sandbox:bookworm-slim` | Image to use for sandbox containers |
| `GOCLAW_SANDBOX_WORKSPACE_ACCESS` | `rw` | `none`, `ro`, or `rw` |
| `GOCLAW_SANDBOX_SCOPE` | `session` | `session`, `agent`, or `shared` |
| `GOCLAW_SANDBOX_MEMORY_MB` | `512` | Memory limit per sandbox container |
| `GOCLAW_SANDBOX_CPUS` | `1.0` | CPU limit per sandbox container |
| `GOCLAW_SANDBOX_TIMEOUT_SEC` | `300` | Max execution time in seconds |
| `GOCLAW_SANDBOX_NETWORK` | `false` | Enable network access in sandbox |
| `DOCKER_GID` | `999` | GID of the `docker` group on the host |

### `docker-compose.browser.yml`

Starts `chromedp/headless-shell:latest` with CDP enabled on port 9222. GoClaw connects via `GOCLAW_BROWSER_REMOTE_URL=ws://chrome:9222`.

### `docker-compose.otel.yml`

Starts Jaeger (`jaegertracing/all-in-one:1.68.0`) and rebuilds GoClaw with the `ENABLE_OTEL=true` build arg to include the OTel exporter.

| Variable | Default | Description |
|----------|---------|-------------|
| `GOCLAW_TELEMETRY_ENABLED` | `true` | Enable OTel export |
| `GOCLAW_TELEMETRY_ENDPOINT` | `jaeger:4317` | OTLP gRPC endpoint |
| `GOCLAW_TELEMETRY_PROTOCOL` | `grpc` | `grpc` or `http` |
| `GOCLAW_TELEMETRY_SERVICE_NAME` | `goclaw-gateway` | Service name in traces |

### `docker-compose.tailscale.yml`

Rebuilds with `ENABLE_TSNET=true` to embed Tailscale directly in the binary (no sidecar needed).

| Variable | Required | Description |
|----------|----------|-------------|
| `GOCLAW_TSNET_AUTH_KEY` | Yes | Tailscale auth key from the admin console |
| `GOCLAW_TSNET_HOSTNAME` | No (default: `goclaw-gateway`) | Device name on the tailnet |

### `docker-compose.redis.yml`

Rebuilds GoClaw with `ENABLE_REDIS=true` and starts a Redis 7 Alpine instance with AOF persistence enabled.

| Variable | Default | Description |
|----------|---------|-------------|
| `GOCLAW_REDIS_DSN` | `redis://redis:6379/0` | Redis connection string (auto-set) |

Build arg: `ENABLE_REDIS=true` — compiles in the Redis cache backend.

Volume: `redis-data` → `/data` (AOF persistence).

### `docker-compose.upgrade.yml`

A one-shot service that runs `goclaw upgrade` and exits. Use it to apply database migrations without downtime.

```bash
# Preview what will change (dry-run)
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade --dry-run

# Apply upgrade
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade

# Check migration status
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade --status
```

---

## Build Arguments

These are compile-time flags passed during `docker build`. Each enables optional dependencies.

| Build Arg | Default | Effect |
|-----------|---------|--------|
| `ENABLE_OTEL` | `false` | OpenTelemetry span exporter |
| `ENABLE_TSNET` | `false` | Tailscale networking |
| `ENABLE_REDIS` | `false` | Redis cache backend |
| `ENABLE_SANDBOX` | `false` | Docker CLI in container (for sandbox) |
| `ENABLE_PYTHON` | `false` | Python 3 runtime for skills |
| `ENABLE_NODE` | `false` | Node.js runtime for skills |
| `ENABLE_FULL_SKILLS` | `false` | Pre-install skill dependencies (pandas, pypdf, etc.) |
| `ENABLE_CLAUDE_CLI` | `false` | Install `@anthropic-ai/claude-code` npm package |
| `VERSION` | `dev` | Semantic version string |

---

## Privilege Separation (v3)

Starting in v3, the Docker image uses **privilege separation** via `su-exec`:

```
docker-entrypoint.sh (runs as root)
  ├── Installs persisted apk packages (reads /app/data/.runtime/apk-packages)
  ├── Starts pkg-helper as root (Unix socket /tmp/pkg.sock, permissions 0660 root:goclaw)
  └── su-exec goclaw → starts /app/goclaw serve (drops to non-root)
```

### pkg-helper

`pkg-helper` is a small root-privileged binary that handles system package management on behalf of the `goclaw` process. It listens on a Unix socket and accepts requests to install/uninstall Alpine packages (`apk`). The `goclaw` user cannot call `apk` directly but can request it through this helper.

Required Docker capabilities when using pkg-helper (added by default in the compose setup):

```yaml
cap_add:
  - SETUID
  - SETGID
  - CHOWN
  - DAC_OVERRIDE
```

> If you override `cap_drop: ALL` in a security-hardened compose setup, you must explicitly add these four capabilities back, or pkg-helper will fail and package installs via the admin UI will not work.

### Runtime Package Directories

On-demand packages (pip/npm) installed via the admin UI go to the data volume:

| Path | Owner | Contents |
|------|-------|---------|
| `/app/data/.runtime/pip` | `goclaw` | pip-installed Python packages |
| `/app/data/.runtime/npm-global` | `goclaw` | npm global packages |
| `/app/data/.runtime/pip-cache` | `goclaw` | pip download cache |
| `/app/data/.runtime/apk-packages` | `root:goclaw` | persisted apk package list (0640) |

These persist across container recreation because they live on the `goclaw-data` volume.

---

## Volumes

| Volume | Mount path | Contents |
|--------|-----------|----------|
| `goclaw-data` | `/app/data` | `config.json` and runtime data |
| `goclaw-workspace` | `/app/workspace` or `/app/.goclaw` | Agent workspaces |
| `goclaw-skills` | `/app/skills` | Skill files |
| `postgres-data` | `/var/lib/postgresql` | PostgreSQL data |
| `tsnet-state` | `/app/tsnet-state` | Tailscale node state |
| `redis-data` | `/data` | Redis AOF persistence |

---

## Base Container Hardening

The base `docker-compose.yml` applies these security settings to the `goclaw` service:

```yaml
security_opt:
  - no-new-privileges:true
cap_drop:
  - ALL
read_only: true
tmpfs:
  - /tmp:rw,noexec,nosuid,size=256m
deploy:
  resources:
    limits:
      memory: 1G
      cpus: '2.0'
      pids: 200
```

> The sandbox overlay (`docker-compose.sandbox.yml`) overrides `cap_drop` and `security_opt` because Docker socket access requires relaxed capabilities.

---

## Update / Upgrade Procedure

```bash
# 1. Pull latest images / rebuilt code
docker compose pull

# 2. Run DB migrations before starting new binary
docker compose run --rm upgrade

# 3. Restart the stack
docker compose up -d --build
```

> `COMPOSE_FILE` in `.env` (set by `prepare-compose.sh`) includes `13-upgrade.yml` automatically, so no explicit `-f` flags are needed.

---

## Installation Alternatives

### Binary installer (no Docker)

Download the latest binary directly:

```bash
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash -s -- --version v1.19.1

# Custom directory
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash -s -- --dir /opt/goclaw
```

Supports Linux and macOS (amd64 and arm64).

### Interactive Docker setup

The setup script generates `.env` and builds the right compose command:

```bash
./scripts/setup-docker.sh              # Interactive mode
./scripts/setup-docker.sh --variant full --with-ui   # Non-interactive
```

Variants: `alpine` (base), `node`, `python`, `full`. Add `--with-ui` for the dashboard, `--dev` for development mode with live reload.

---

## Pre-built Docker Images

Official multi-arch images (amd64 + arm64) are published on every release to both registries:

| Registry | Gateway | Web Dashboard |
|----------|---------|--------------|
| Docker Hub | `digitop/goclaw` | `digitop/goclaw-web` |
| GHCR | `ghcr.io/nextlevelbuilder/goclaw` | `ghcr.io/nextlevelbuilder/goclaw-web` |

### Tag variants

Images are split into **runtime variants** (what's pre-installed) and **build-tag variants** (compiled-in features):

**Runtime variants:**

| Tag | Node.js | Python | Skill deps | Use case |
|-----|---------|--------|------------|----------|
| `latest` / `vX.Y.Z` | — | — | — | Minimal base (~50 MB) |
| `node` / `vX.Y.Z-node` | ✓ | — | — | JS/TS skills |
| `python` / `vX.Y.Z-python` | — | ✓ | — | Python skills |
| `full` / `vX.Y.Z-full` | ✓ | ✓ | ✓ | All skill dependencies pre-installed |

**Build-tag variants:**

| Tag | OTel | Tailscale | Redis | Use case |
|-----|------|-----------|-------|----------|
| `otel` / `vX.Y.Z-otel` | ✓ | — | — | OpenTelemetry tracing |
| `tsnet` / `vX.Y.Z-tsnet` | — | ✓ | — | Tailscale remote access |
| `redis` / `vX.Y.Z-redis` | — | — | ✓ | Redis caching |

> **Tip:** Runtime and build-tag variants are independent. If you need Python + OTel, build locally with `ENABLE_PYTHON=true` and `ENABLE_OTEL=true`.

Pull example:

```bash
# Latest minimal
docker pull digitop/goclaw:latest

# With Python runtime
docker pull digitop/goclaw:python

# Full runtime (Node + Python + all deps)
docker pull digitop/goclaw:full

# With OTel tracing
docker pull ghcr.io/nextlevelbuilder/goclaw:otel
```

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| `goclaw` exits immediately on start | PostgreSQL not ready | The postgres overlay adds a health check dependency; ensure you include it |
| Sandbox containers not starting | Docker socket not mounted or wrong GID | Add the sandbox overlay and set `DOCKER_GID` to match `stat -c %g /var/run/docker.sock` |
| Dashboard returns 502 | `goclaw` service not healthy yet | Check `docker compose logs goclaw`; dashboard depends on `goclaw` being up |
| OTel traces not appearing in Jaeger | Binary built without `ENABLE_OTEL=true` | Add `--build` flag when using the otel overlay; it rebuilds with the build arg |
| Port 5432 already in use | Local Postgres running | Set `POSTGRES_PORT=5433` in `.env` |
| `database schema is outdated` | Migrations not applied after update | Add `GOCLAW_AUTO_UPGRADE=true` to `.env` **file** (not as shell prefix — compose reads from `env_file`), or run the upgrade overlay before starting |
| `network goclaw-net … incorrect label` | A `goclaw-net` Docker network already exists with conflicting labels | Run `docker network rm goclaw-net` then retry — Compose creates its own `goclaw-net` network automatically |

---

## What's Next

- [Database Setup](/deploy-database) — manual PostgreSQL setup and migrations
- [Security Hardening](/deploy-security) — five-layer security overview
- [Observability](/deploy-observability) — OpenTelemetry and Jaeger configuration
- [Tailscale](/deploy-tailscale) — secure remote access via Tailscale



---

# Database Setup

> GoClaw requires **PostgreSQL 15+** with `pgvector` for multi-tenant storage, semantic memory search, and Knowledge Vault features. A **SQLite** backend is also available for desktop (single-user) deployments with reduced feature set — see [SQLite vs PostgreSQL](#sqlite-vs-postgresql) below.

## Overview

All persistent state lives in PostgreSQL: agents, sessions, memory, traces, skills, cron jobs, channel configs, Knowledge Vault documents, and episodic summaries. The schema is managed via numbered migration files in `migrations/`. Two extensions are required: `pgcrypto` (UUID generation) and `vector` (semantic memory search via pgvector).


## Manual Setup

### 1. Install PostgreSQL 15+ with pgvector

On Ubuntu/Debian:

```bash
# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

# Install pgvector (choose your PG version)
sudo apt install postgresql-16-pgvector
```

Using the official pgvector Docker image (recommended):

```bash
docker run -d \
  --name goclaw-postgres \
  -e POSTGRES_USER=goclaw \
  -e POSTGRES_PASSWORD=your-secure-password \
  -e POSTGRES_DB=goclaw \
  -p 5432:5432 \
  pgvector/pgvector:pg18
```

### 2. Create the database and enable extensions

```sql
-- Connect as superuser
CREATE DATABASE goclaw;
\c goclaw

-- Required extensions (both are enabled by migration 000001 automatically)
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
CREATE EXTENSION IF NOT EXISTS "vector";
```

> The `vector` extension provides HNSW vector indexes used for memory similarity search. `pgcrypto` provides UUID v7 generation via `gen_random_bytes()`.

### 3. Set the connection string

Add to your `.env` file or shell environment:

```bash
GOCLAW_POSTGRES_DSN=postgres://goclaw:your-secure-password@localhost:5432/goclaw?sslmode=disable
```

For production with TLS:

```bash
GOCLAW_POSTGRES_DSN=postgres://goclaw:password@db.example.com:5432/goclaw?sslmode=require
```

The DSN is a standard `lib/pq` / `pgx` connection string. All standard PostgreSQL parameters are supported (`connect_timeout`, `pool_max_conns`, etc.).

---

## Run Migrations

GoClaw uses [golang-migrate](https://github.com/golang-migrate/migrate) with numbered SQL files.

```bash
# Apply all pending migrations
./goclaw migrate up

# Check current migration version
./goclaw migrate status

# Roll back one step
./goclaw migrate down

# Roll back to a specific version
./goclaw migrate down 3
```

With Docker (using the upgrade overlay):

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade
```

### Migration files

| File | What it creates |
|------|----------------|
| `000001_init_schema` | All core tables: agents, sessions, memory, traces, spans, skills, cron, pairing, MCP, custom tools, channels |
| `000002_agent_links` | `agent_links` table for agent-to-agent delegation |
| `000003_agent_teams` | Team and task tables for multi-agent teams |
| `000004_teams_v2` | Team metadata and task status improvements |
| `000005_phase4` | Additional phase-4 schema changes |
| `000006_builtin_tools` | Built-in tool configuration storage |
| `000007_team_metadata` | Team metadata JSONB fields |
| `000008_team_tasks_user_scope` | Per-user task scoping |
| `000009_add_quota_index` | Partial index for quota checker performance |
| `000010_agents_md_v2` | Agent metadata v2 schema |
| `000011_session_profile_metadata` | JSONB `metadata` columns on sessions, profiles, pairing |
| `000012_channel_pending_messages` | `channel_pending_messages` table for group chat history buffer |
| `000013_knowledge_graph` | `kg_entities`, `kg_relations` tables for semantic entity storage |
| `000014_channel_contacts` | `channel_contacts` table — global contact directory from channels |
| `000015_agent_budget` | `budget_monthly_cents` on agents; `activity_logs` audit trail |
| `000016_usage_snapshots` | `usage_snapshots` table — hourly token/cost aggregation |
| `000017_system_skills` | `is_system`, `deps`, `enabled` columns on skills |
| `000018_team_tasks_workspace_followup` | Team workspace files, file versions, comments; task events and comments |
| `000019_team_id_columns` | `team_id` FK on memory, KG, traces, spans, cron, sessions (9 tables) |
| `000020_secure_cli_and_api_keys` | `secure_cli_binaries` for credentialed exec; `api_keys` for fine-grained auth |
| `000021_paired_devices_expiry` | `expires_at` on paired devices; `confidence_score` on team tasks, messages, comments |
| `000022`–`000036` | Heartbeats, agent hard-delete, team attachments refactor, KG semantic search, tenant foundation, subagent tasks, CLI grants, and more — see [Database Schema → Migration History](/database-schema) |
| `000037_v3_memory_evolution` | **v3** — `episodic_summaries`, `agent_evolution_metrics`, `agent_evolution_suggestions`; KG temporal columns; 12 agent config fields promoted from `other_config` JSONB |
| `000038_vault_tables` | **v3** — `vault_documents`, `vault_links`, `vault_versions` for Knowledge Vault |
| `000039_episodic_summaries` | Clears stale `agent_links` data |
| `000040_episodic_search_index` | Adds `search_vector` generated FTS column + HNSW index to `episodic_summaries` |
| `000041_episodic_promoted` | Adds `promoted_at` column for long-term memory promotion pipeline |
| `000042_vault_tsv_summary` | Adds `summary` column to `vault_documents`; rebuilds FTS to include summary |
| `000043_vault_team_custom_scope` | Adds `team_id`, `custom_scope` to `vault_documents`; team-safe unique constraint; scope-fix trigger; `custom_scope` on 9 other tables |
| `000044_seed_agents_core_task_files` | Seeds `AGENTS_CORE.md` and `AGENTS_TASK.md` context files; removes deprecated `AGENTS_MINIMAL.md` |

> **Data hooks:** GoClaw tracks post-migration Go transforms in a separate `data_migrations` table. Run `./goclaw upgrade --status` to see both SQL migration version and pending data hooks.

> Migrations `000045`–`000080` continue the schema: model fallback config, REST endpoint catalog, Bitrix24 portal OAuth state (`bitrix_portals`), server-side browser cookie sync (`browser_cookies`), the usage-cap pricing and enforcement tables (`usage_pricing_catalog`, `usage_pricing_overrides`, `usage_cap_policies`, `usage_cap_counters`, `usage_cap_reservations`, `usage_cap_events`), the agent-budget bridge, typed secure-CLI credentials, archived run timelines (`run_timeline_items`), per-channel context capabilities (scoped MCP/secure-CLI grants and credentials), passive channel memory extraction, per-agent secure-CLI credentials, skill self-evolution (`skill_usage_metrics`, `skill_improvement_suggestions`, `skill_versions`), and usage event analytics (`usage_events`, `usage_event_rollups`) — see [Database Schema → Migration History](/database-schema).

Run `./goclaw migrate status` after deployment to confirm the current schema is version **80**.

---

## SQLite vs PostgreSQL

GoClaw v3 supports two database backends:

| Feature | PostgreSQL | SQLite (desktop) |
|---------|-----------|-----------------|
| Full schema (all 80 migrations) | Yes | Yes |
| Vector similarity search (HNSW) | Yes — pgvector | No |
| Episodic summaries vector search | Yes | Keyword (FTS) only |
| Knowledge Vault auto-linking | Yes — similarity threshold 0.7 | No (summarise only) |
| `kg_entities` semantic search | Yes | No |
| Multi-tenant isolation | Yes | Single-tenant only |
| Connection pooling | Yes — pgx/v5, 25 max | N/A (embedded) |

Use PostgreSQL for all production and multi-user deployments. SQLite is supported only in the desktop (single-binary) build and lacks vector operations.

---

## Key Tables

| Table | Purpose |
|-------|---------|
| `agents` | Agent definitions, model config, tool config |
| `sessions` | Conversation history, token counts per session |
| `traces` / `spans` | LLM call tracing, token usage, costs |
| `memory_chunks` | Semantic memory (pgvector HNSW index, `vector(1536)`) |
| `memory_documents` | Memory document metadata |
| `embedding_cache` | Cached embeddings keyed by content hash + model |
| `llm_providers` | LLM provider configs (API keys encrypted AES-256-GCM) |
| `mcp_servers` | External MCP server connections |
| `cron_jobs` / `cron_run_logs` | Scheduled tasks and run history |
| `skills` | Skill files with BM25 + vector search |
| `channel_instances` | Messaging channel configs (Telegram, Discord, etc.) |
| `activity_logs` | Audit trail — admin actions, config changes, security events |
| `usage_snapshots` | Hourly aggregated token counts and costs per agent/user |
| `kg_entities` / `kg_relations` | Knowledge graph — semantic entities and relationships (v3: temporal validity via `valid_from`/`valid_until`) |
| `channel_contacts` | Unified contact directory synced from all channels |
| `channel_pending_messages` | Pending group messages buffer for batch processing |
| `api_keys` | Scoped API keys with SHA-256 hash lookup and revocation |
| `episodic_summaries` | **v3** — Tier 2 memory: compressed session summaries with FTS and vector search |
| `agent_evolution_metrics` | **v3** — Self-evolution Stage 1: raw metric observations per session |
| `agent_evolution_suggestions` | **v3** — Self-evolution Stage 2: proposed behavioural changes for review |
| `vault_documents` | **v3** — Knowledge Vault document registry (path, hash, embedding, FTS) |
| `vault_links` | **v3** — Bidirectional wikilinks between vault documents |
| `subagent_tasks` | Subagent task persistence for lifecycle tracking, cost attribution |

---

## Backup and Restore

### Backup

```bash
# Full database dump (recommended — includes schema + data)
pg_dump -h localhost -U goclaw -d goclaw -Fc -f goclaw-backup.dump

# Schema only (for inspecting structure)
pg_dump -h localhost -U goclaw -d goclaw --schema-only -f goclaw-schema.sql

# Exclude large tables if needed (e.g., skip spans for smaller backups)
pg_dump -h localhost -U goclaw -d goclaw -Fc \
  --exclude-table=spans \
  -f goclaw-backup-no-spans.dump
```

### Restore

```bash
# Restore to a fresh database
createdb -h localhost -U postgres goclaw_restore
pg_restore -h localhost -U goclaw -d goclaw_restore goclaw-backup.dump
```

### Docker volume backup

```bash
# Backup the postgres-data volume
docker run --rm \
  -v goclaw_postgres-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/postgres-data-$(date +%Y%m%d).tar.gz -C /data .
```

---

## Performance

### Connection pooling

GoClaw uses `pgx/v5` with `database/sql`. The connection pool is hard-coded to **25 max open / 10 max idle** connections. For high-concurrency deployments, ensure your PostgreSQL `max_connections` accommodates this. You can also set pool parameters in the DSN:

```bash
GOCLAW_POSTGRES_DSN=postgres://goclaw:password@localhost:5432/goclaw?sslmode=disable&pool_max_conns=20
```

Or use PgBouncer in front of PostgreSQL for connection pooling at scale.

### Key indexes

The schema includes these performance-critical indexes out of the box:

| Index | Table | Purpose |
|-------|-------|---------|
| `idx_traces_quota` | `traces` | Per-user quota window queries (partial, top-level only) |
| `idx_mem_vec` | `memory_chunks` | HNSW cosine similarity search (`vector_cosine_ops`) |
| `idx_mem_tsv` | `memory_chunks` | Full-text BM25 search via `tsvector` GIN index |
| `idx_traces_user_time` | `traces` | Usage queries by user + time |
| `idx_sessions_updated` | `sessions` | Listing recent sessions |

The `idx_traces_quota` index is added as `CONCURRENTLY` in migration `000009` — it can be created without locking the table on live systems.

### Disk growth

The `spans` table grows quickly under heavy use (one row per LLM call span). Consider periodic pruning:

```sql
-- Delete spans older than 30 days
DELETE FROM spans WHERE created_at < NOW() - INTERVAL '30 days';

-- Delete traces older than 90 days (cascades to spans)
DELETE FROM traces WHERE created_at < NOW() - INTERVAL '90 days';

VACUUM ANALYZE traces, spans;
```

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| `extension "vector" does not exist` | pgvector not installed | Install `postgresql-XX-pgvector` or use the `pgvector/pgvector` Docker image |
| `migrate up` fails on first run | Extensions not enabled | Ensure the DB user has `SUPERUSER` or `CREATE EXTENSION` privilege |
| Connection refused | Wrong host/port in DSN | Check `GOCLAW_POSTGRES_DSN`; verify PostgreSQL is running |
| Memory search returns no results | Embedding model dimension mismatch | Schema uses `vector(1536)` — ensure your embedding model outputs 1536 dims |
| High disk usage | `spans` table unbounded growth | Schedule periodic `DELETE` + `VACUUM` on `spans` and `traces` |

---

## What's Next

- [Docker Compose](/deploy-docker-compose) — compose-based deployment with the postgres overlay
- [Security Hardening](/deploy-security) — AES-256-GCM encryption for secrets in the database
- [Observability](/deploy-observability) — querying traces and spans for LLM cost monitoring



---

# Security Hardening

> GoClaw uses five independent defense layers — transport, input, tools, output, and isolation — so a bypass of one layer doesn't compromise the rest.

## Overview

Each layer operates independently. Together they form a defense-in-depth architecture covering the full request lifecycle from incoming WebSocket connection to agent tool execution output.

```mermaid
flowchart TD
    REQ["Incoming Request"] --> L1["Layer 1: Transport\nCORS · size limits · timing-safe auth · rate limiting"]
    L1 --> L2["Layer 2: Input\nInjection detection · message truncation · ILIKE escape"]
    L2 --> L3["Layer 3: Tools\nShell deny patterns · path traversal · SSRF · exec approval · file serving protection"]
    L3 --> L4["Layer 4: Output\nCredential scrubbing · web content tagging · MCP content tagging"]
    L4 --> L5["Layer 5: Isolation\nPer-user workspace · Docker sandbox · privilege separation"]
```


## Layer 2: Input — Injection Detection

The input guard scans every user message for 6 prompt injection patterns before it reaches the LLM.

| Pattern ID | Detects |
|-----------|---------|
| `ignore_instructions` | "ignore all previous instructions" |
| `role_override` | "you are now…", "pretend you are…" |
| `system_tags` | `<system>`, `[SYSTEM]`, `[INST]`, `<<SYS>>` |
| `instruction_injection` | "new instructions:", "override:", "system prompt:" |
| `null_bytes` | Null characters `\x00` (obfuscation attempts) |
| `delimiter_escape` | "end of system", `</instructions>`, `</prompt>` |

**Configurable action** via `gateway.injection_action`:

| Value | Behavior |
|-------|----------|
| `"off"` | Disable detection entirely |
| `"log"` | Log at info level, continue |
| `"warn"` (default) | Log at warning level, continue |
| `"block"` | Log warning, return error, stop processing |

For public-facing deployments or shared multi-user agents, set `"block"`.

**Message truncation:** Messages exceeding `gateway.max_message_chars` (default 32,000) are truncated — not rejected — and the LLM is notified of the truncation.

**ILIKE ESCAPE:** All database ILIKE queries (search/filter operations) escape `%`, `_`, and `\` characters before execution, preventing SQL wildcard injection attacks.

---

## Layer 3: Tool Security

Protects against dangerous command execution, unauthorized file access, and server-side request forgery.

### Shell deny groups

15 categories of commands are blocked by default. All groups are **on (denied)** out of the box. Per-agent overrides are possible via `shell_deny_groups` in agent config.

| # | Group | Examples |
|---|-------|----------|
| 1 | `destructive_ops` | `rm -rf /`, `dd if=`, `mkfs`, `reboot`, `shutdown` |
| 2 | `data_exfiltration` | `curl \| sh`, localhost access, DNS queries |
| 3 | `reverse_shell` | `nc -e`, `socat`, Python/Node socket |
| 4 | `code_injection` | `eval $()`, `base64 -d \| sh` |
| 5 | `privilege_escalation` | `sudo`, `su -`, `nsenter`, `mount`, `setcap`, `halt`, `doas`, `pkexec`, `runuser` |
| 6 | `dangerous_paths` | `chmod`/`chown` on `/` paths |
| 7 | `env_injection` | `LD_PRELOAD=`, `DYLD_INSERT_LIBRARIES=` |
| 8 | `container_escape` | `docker.sock`, `/proc/sys/`, `/sys/kernel/` |
| 9 | `crypto_mining` | `xmrig`, `cpuminer`, stratum URLs |
| 10 | `filter_bypass` | `sed /e`, `git --upload-pack=`, CVE mitigations |
| 11 | `network_recon` | `nmap`, `ssh@`, `ngrok`, `chisel` |
| 12 | `package_install` | `pip install`, `npm i`, `apk add`, `yarn` |
| 13 | `persistence` | `crontab`, `.bashrc`, tee shell init |
| 14 | `process_control` | `kill -9`, `killall`, `pkill` |
| 15 | `env_dump` | `env`, `printenv`, `GOCLAW_*` vars, `/proc/*/environ` |

To allow a specific group for one agent, set it to `false` in the agent's config:

```json
{
  "agents": {
    "list": {
      "devops-bot": {
        "shell_deny_groups": {
          "package_install": false,
          "process_control": false
        }
      }
    }
  }
}
```

### Global shell deny-groups — runtime toggle

`config.tools.shellDenyGroups` is a `map[string]bool` that lets you enable or disable deny-groups globally without restarting the gateway. Changes take effect immediately via `bus.TopicConfigChanged` live-reload. The reload clones the config snapshot before applying it, so group *disables* persist correctly across reload, and it also reloads provider-level shell-deny policies (Claude CLI / ACP), not just the global exec tool.

```json
{
  "tools": {
    "shellDenyGroups": {
      "package_install": false,
      "env_dump": false
    }
  }
}
```

**Precedence:** per-agent `shell_deny_groups` always wins over the global setting. The global value only applies when a given group is not explicitly set in the agent's own config. This lets you relax a group gateway-wide while still locking it down for specific agents.

See [`reference/config-reference.md`](../reference/config-reference.md) for the full `tools.shellDenyGroups` field reference.

### Path traversal prevention

`resolvePath()` applies `filepath.Clean()` then `HasPrefix()` to ensure all file paths stay within the agent's workspace. With `restrict_to_workspace: true` (the default on agents), any path outside the workspace is blocked.

All four filesystem tools (`read_file`, `write_file`, `list_files`, `edit`) implement the `PathDenyable` interface. The agent loop calls `DenyPaths(".goclaw")` at startup — agents cannot read GoClaw's internal data directory. The `list_files` tool filters denied paths from directory listings entirely, so agents never see them.

**venv interpreter exemption.** The GoClaw-managed Python interpreter is exempt from the `.goclaw/` deny so agents can run it directly. GoClaw resolves `<home>/.goclaw/venv/bin/python3` (following symlinks) once at startup and exempts the *resolved* interpreter directory; if no venv is present it falls back silently. This is the only path under `.goclaw/` that exec can reach.

### File serving path traversal protection

The file serving endpoint (`/v1/files/...`) validates all requested paths to prevent directory traversal attacks. Any path containing `../` sequences or resolving outside the permitted base directory is rejected with a 400 error.

### SSRF protection (3-step validation)

Applied to all outbound URL fetches by the `web_fetch` tool:

```mermaid
flowchart TD
    U["URL to fetch"] --> S1["Step 1: Blocked hostnames\nlocalhost · *.local · *.internal\nmetadata.google.internal"]
    S1 --> S2["Step 2: Private IP ranges\n10.0.0.0/8 · 172.16.0.0/12\n192.168.0.0/16 · 127.0.0.0/8\n169.254.0.0/16 · IPv6 loopback"]
    S2 --> S3["Step 3: DNS pinning\nResolve domain · check every resolved IP\nApplied to redirect targets too"]
    S3 --> A["Allow request"]
```

### Credentialed exec (Direct Exec Mode)

For tools that need credentials (e.g., `gh`, `aws`), GoClaw uses direct process execution instead of a shell — eliminating shell injection entirely.

4-layer defense:
1. **No shell** — `exec.CommandContext(binary, args...)`, never `sh -c`
2. **Path verification** — binary resolved to absolute path via `exec.LookPath()`, matched against config
3. **Deny patterns** — per-binary regex deny lists on arguments (`deny_args`) and verbose flags (`deny_verbose`)
4. **Output scrubbing** — credentials registered at runtime are scrubbed from stdout/stderr

Shell metacharacters (`;`, `|`, `&`, `$()`, backticks) are detected and rejected before execution.

### Exec grant enforcement

Agent-level grant enforcement runs **before** any process spawn, blocking ungranted agents from executing registered binaries:

| Control | Detail |
|---------|--------|
| **Grant lookup** | `store.SecureCLIStore.IsRegisteredBinary()` checks the `secure_cli_agent_grants` table. Non-global binaries require a row for the calling agent. |
| **Fail-closed** | If the grant lookup errors (DB down, timeout), exec is denied with a retry message. Per-lookup timeout: 2 seconds. |
| **Env scrubbing** | When a command bypasses the credentialed path (e.g., via adversarial use of the `exec` tool), the child process environment is scrubbed of all credential keys before spawn — static deny list plus dynamic keys from every registered binary in the tenant. |
| **Wrapper unwrap** | Shell wrappers (`sh -c`, `bash -c`, etc.) that attempt to evade binary path matching are blocked. GoClaw checks up to 3 levels of nesting; deeper chains are rejected as adversarial. |
| **Subagent wiring** | Subagent `ExecTool`s use the same `SecureCLIStore` via `buildSubagentToolsRegistry`. Parent agents cannot bypass the gate by delegating exec to spawned subagents. |

Security log events emitted by the grant gate:

| Event | Meaning |
|-------|---------|
| `security.credentialed_binary_denied` | Agent attempted to run a binary it has no grant for |
| `security.credentialed_binary_gate_error` | Grant lookup failed (DB error); exec denied |
| `security.credentialed_binary_wrapper_too_deep` | Shell wrapper nesting exceeded 3 levels; rejected as adversarial |

All three events include: `binary`, `wrapper`, `agent_id`, `tenant_id`, and `command` prefix fields.

### Shell output limit

Host-executed commands have stdout and stderr capped at **1 MB** each. If a command exceeds this limit, output is truncated with a flag to prevent further writes. Sandboxed execution uses Docker container limits instead.

### XML parsing (XXE prevention)

GoClaw replaced the stdlib `xml.etree.ElementTree` XML parser with `defusedxml` in all XML processing paths. `defusedxml` blocks XML eXternal Entity (XXE) attacks — where a crafted XML payload references external entities to read local files or trigger SSRF. This applies to any agent tool or skill that parses XML input.

### Exec approval

See [Exec Approval](/exec-approval) for the full interactive approval flow. At minimum, enable `ask: "on-miss"` to prompt before network and infrastructure tools run:

```json
{
  "tools": {
    "execApproval": {
      "security": "full",
      "ask": "on-miss"
    }
  }
}
```

---

## Layer 4: Output Security

Prevents secrets from leaking back through tool output or LLM responses.

### Credential scrubbing (automatic)

All tool output passes through a regex scrubber that redacts known secret formats. Replaced with `[REDACTED]`:

| Pattern | Examples |
|---------|----------|
| OpenAI keys | `sk-...` |
| Anthropic keys | `sk-ant-...` |
| GitHub tokens | `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_` |
| AWS access keys | `AKIA...` |
| Connection strings | `postgres://...`, `mysql://...` |
| Env var patterns | `KEY=...`, `SECRET=...`, `DSN=...` |
| Long hex strings | 64+ character hex sequences |
| DSN / database URLs | `DSN=...`, `DATABASE_URL=...`, `REDIS_URL=...`, `MONGO_URI=...` |
| Generic key-value | `api_key=...`, `token=...`, `secret=...`, `bearer=...` (case-insensitive) |
| Runtime env vars | `VIRTUAL_*=...` patterns |

13 regex patterns in total cover all major secret formats.

Scrubbing is enabled by default. To disable (not recommended):

```json
{ "tools": { "scrub_credentials": false } }
```

You can also register runtime values for dynamic scrubbing (e.g., server IPs discovered at runtime) via `AddDynamicScrubValues()` in custom tool integrations.

### Web content tagging

Content fetched from external URLs is wrapped:

```
<<<EXTERNAL_UNTRUSTED_CONTENT>>>
[fetched content here]
<<<END_EXTERNAL_UNTRUSTED_CONTENT>>>
```

This signals to the LLM that the content is untrusted and should not be treated as instructions.

The content markers are protected against Unicode homoglyph spoofing — GoClaw sanitizes lookalike characters (e.g., Cyrillic `а` vs Latin `a`) to prevent external content from forging the boundary markers.

### MCP content tagging

Tool results from MCP servers are wrapped with the same untrusted content markers:

```
<<<EXTERNAL_UNTRUSTED_CONTENT>>> (MCP server: my-server, tool: search)
[tool result here]
<<<END_EXTERNAL_UNTRUSTED_CONTENT>>>
```

The header identifies the server and tool name. The footer warns the LLM not to follow instructions from the content. Marker breakout attempts are sanitized.

---

## Layer 5: Isolation

### Per-user workspace isolation

Every user gets a sandboxed directory. Two levels:

| Level | Directory pattern |
|-------|-----------------|
| Per-agent | `~/.goclaw/{agent-key}-workspace/` |
| Per-user | `{agent-workspace}/user_{sanitized_user_id}/` |

User IDs are sanitized — characters outside `[a-zA-Z0-9_-]` become underscores. Example: `group:telegram:-1001234` → `group_telegram_-1001234`.

### Docker entrypoint — privilege separation

GoClaw's Docker container uses a three-phase privilege model:

**Phase 1: Root (`docker-entrypoint.sh`)**
- Re-installs persisted system packages from `/app/data/.runtime/apk-packages`
- Starts `pkg-helper` (root-privileged service listening on Unix socket `/tmp/pkg.sock`, mode 0660, group `goclaw`)
- Sets up Python and Node.js runtime directories

**Phase 2: Drop to `goclaw` user (`su-exec`)**
- Main app runs as `goclaw` (UID 1000) via `su-exec goclaw /app/goclaw`
- All agent operations execute in this context
- System package requests are delegated to `pkg-helper` via Unix socket

**Phase 3: Optional sandbox (per-agent)**
- Shell execution can be sandboxed in Docker containers (configurable)

### pkg-helper — root service

`pkg-helper` runs as root on a Unix socket (`/tmp/pkg.sock`, 0660 `root:goclaw`). It accepts only `apk add` / `apk del` requests from the `goclaw` user. Required Docker Compose capabilities:

| Capability | Purpose |
|-----------|---------|
| `SETUID` | `su-exec` privilege drop |
| `SETGID` | Group membership for socket |
| `CHOWN` | Runtime directory ownership setup |
| `DAC_OVERRIDE` | pkg-helper socket access |

All other capabilities are dropped (`cap_drop: ALL`). The full compose security config:

```yaml
cap_drop:
  - ALL
cap_add:
  - SETUID
  - SETGID
  - CHOWN
  - DAC_OVERRIDE
security_opt:
  - no-new-privileges:true
tmpfs:
  - /tmp:size=256m,noexec,nosuid
```

### Runtime directories

Packages and runtime data are stored under `/app/data/.runtime`, which survives container recreation:

| Path | Owner | Purpose |
|------|-------|---------|
| `/app/data/.runtime/apk-packages` | 0666 | Persisted apk package list |
| `/app/data/.runtime/pip` | goclaw | Python packages (`$PIP_TARGET`) |
| `/app/data/.runtime/npm-global` | goclaw | npm packages (`$NPM_CONFIG_PREFIX`) |
| `/tmp/pkg.sock` | root:goclaw 0660 | pkg-helper Unix socket |

### Docker sandbox

For agent shell execution, enable the Docker sandbox to run commands in an isolated container:

```bash
# Build the sandbox image
docker build -t goclaw-sandbox:bookworm-slim -f Dockerfile.sandbox .
```

```json
{
  "sandbox": {
    "mode": "all",
    "image": "goclaw-sandbox:bookworm-slim",
    "workspace_access": "rw",
    "scope": "session"
  }
}
```

Container hardening applied automatically:

| Setting | Value |
|---------|-------|
| Root filesystem | Read-only (`--read-only`) |
| Capabilities | All dropped (`--cap-drop ALL`) |
| New privileges | Disabled (`--security-opt no-new-privileges`) |
| Memory limit | 512 MB |
| CPU limit | 1.0 |
| Network | Disabled (`--network none`) |
| Max output | 1 MB |
| Timeout | 300 seconds |

Sandbox modes: `off` (direct host exec), `non-main` (sandbox all except the main agent), `all` (sandbox every agent).

---

## Session IDOR Fix

All five `chat.*` WebSocket methods (`chat.send`, `chat.abort`, `chat.stop`, `chat.stopall`, `chat.reset`) verify that the caller owns the session before acting on it. The `requireSessionOwner` helper in `internal/gateway/methods/access.go` performs this check. Non-admin users supplying a `sessionKey` that belongs to another user receive an authorization error — the operation is never executed.

---

## Pairing Auth Hardening

Browser device pairing is fail-closed:

| Control | Detail |
|---------|--------|
| Fail-closed | `IsPaired()` check blocks unpaired sessions — no fallback to open access |
| Rate limiting | Max 3 pending pairing requests per account; prevents enumeration spam |
| TTL enforcement | Pairing codes expire after 60 minutes; paired device tokens expire after 30 days |
| Approval flow | Requires WebSocket `device.pair.approve` from an authenticated admin session |

---

## Encryption

Secrets stored in PostgreSQL are encrypted with AES-256-GCM:

| What | Table | Column |
|------|-------|--------|
| LLM provider API keys | `llm_providers` | `api_key` |
| MCP server API keys | `mcp_servers` | `api_key` |
| Custom tool env vars | `custom_tools` | `env` |
| Channel credentials | `channel_instances` | `credentials` |
| Webhook secrets | `webhooks` | `secret_hash`, `secret_enc` |
| Workstation credentials | `workstations` | `metadata` |

Set the encryption key before first run:

```bash
# Generate a strong key (base64, 44 chars = 32 raw bytes)
openssl rand -base64 32

# Add to .env
GOCLAW_ENCRYPTION_KEY=your-44-char-base64-key
```

The key is accepted in three formats: base64-encoded (44 chars, output of `openssl rand -base64 32`), hex-encoded (64 chars, output of `openssl rand -hex 32`), or raw 32 bytes. All three resolve to the same 32-byte AES key; use base64 as the canonical form to match the environment-variables reference.

Format stored: `"aes-gcm:" + base64(12-byte nonce + ciphertext + GCM tag)`. Values without the prefix are returned as plaintext for migration compatibility.

> **Must match across replicas.** In a clustered deployment, every gateway instance must use the same `GOCLAW_ENCRYPTION_KEY`. Rotating the key requires re-encrypting all stored secrets before restarting.

Credentialed-CLI env vars are also AES-256-GCM encrypted: `secure_cli_binaries`, `secure_cli_agent_grants`, `secure_cli_user_credentials`, and `secure_cli_agent_credentials` all store secrets in an `encrypted_env` column. Each entry carries a visibility `kind` — `sensitive` entries are masked in normal API/UI responses and only returned via the audited `env:reveal` flow; `value` entries (e.g. region or profile names) are returned to admins for operational review.

---

## Credential Adapter Security Model

[Typed credential adapters](/cli-credentials) are the **system-trusted** path for injecting auth material into spawned CLI subprocesses (`git clone`, `git push`, …). This is a second trust boundary, distinct from the user-paste env denylist — not a replacement for it.

| Path | Trust boundary |
|------|----------------|
| User-pasted env vars (`env` credential type) | First line of defense — `ValidateGrantEnvVars` rejects `GIT_SSH_COMMAND`, `LD_PRELOAD`, `PATH`, and the rest of the denylist |
| System-injected adapter env (e.g. `git` adapter) | Second, audit-trailed line — bypasses the denylist by design and emits one audit event per injection |

A typo in the adapter name falls back to passthrough (the legacy denylist-only behavior) — there is **no silent bypass**.

### Effective credential precedence

When an adapter resolves which credential to inject, it picks the **first** match in this order: **user override → channel/context credential → agent credential → binary-level env defaults**. Agent credentials (`secure_cli_agent_credentials`) are the default trust boundary for git; a user override or a channel/context credential takes precedence when present. The `credential_source` audit field records which layer was used.

For the PAT path, the adapter synthesizes an `http.<remote>.extraheader` config entry with `Authorization: Basic base64("x-access-token:<token>")`. The raw token, the base64 payload, and the full header are all registered with the scrubber. SSH private keys are validated **twice** at save time — first with Go's SSH parser, then with OpenSSH (`ssh-keygen -y -f`) when available — so keys that would fail later with OpenSSH diagnostics are rejected up front.

### Audit event: `security.system_env_injection`

Every adapter injection emits **exactly one** structured `slog.Warn` line. The plaintext hostname is intentionally **never logged** — keeping audit logs PII-safe inside regulated tenants.

| Field | Notes |
|-------|-------|
| `msg` | always `security.system_env_injection` |
| `adapter` | e.g. `git`, `passthrough` |
| `binary` | binary name (`git`, …) |
| `user_id` | tenant user UUID (empty in global-only contexts) |
| `env_keys` | sorted env-var **names** only — never values |
| `argv_prefix_len` | number of argv elements prepended, not their content |
| `host_scope_hash` | first 8 hex chars of `SHA-256(normalized host_scope)`, or `"none"` |
| `credential_source` | which precedence layer supplied the credential: `user`, `context`, `agent`, or empty when no scoped credential row was selected |

There is **no dedicated audit table** in v1 — the line routes through `slog` to stderr → systemd/journald or Docker logs. To grep for activity against a specific host, pre-compute its hash:

```sh
echo -n "github.com" | sha256sum | cut -c1-8
```

### Output scrubbing for credentialed exec

Output of credentialed commands passes through the same regex scrubber as all tool output, plus credentials registered at runtime for the binary are scrubbed from stdout/stderr before the result reaches the LLM. Secrets injected through an adapter never round-trip back into the conversation.

### SSH TOFU MITM caveat

The git adapter's SSH path sets `StrictHostKeyChecking=accept-new`, which accepts an unknown host key on first contact. A network attacker positioned between GoClaw and the git host can capture that **first** SSH session. Pre-seed `known_hosts` at deploy time to close the window — after that, `accept-new` enforces match-or-fail:

```sh
ssh-keyscan github.com >> ~/.ssh/known_hosts
ssh-keyscan -p 22 gitea.internal >> ~/.ssh/known_hosts
```

### Ephemeral credential tmpfiles

The SSH adapter writes the PEM key to a `0600`-mode tmpfile in `os.TempDir()` (prefix `goclaw-gitkey-*`) and removes it via a deferred cleanup after exec returns. A `SIGKILL` of the GoClaw process skips that cleanup, leaving the file behind. `os.TempDir()` is per-user on POSIX, so exposure is limited to the GoClaw uid. High-security deployments should run a periodic sweep:

```sh
find "$TMPDIR" -name 'goclaw-gitkey-*' -mmin +60 -delete
```

---

## Webhook Security

> See [Webhooks](/advanced/webhooks) for the full API reference.

### Encryption key required

The webhook subsystem only mounts when `GOCLAW_ENCRYPTION_KEY` is set. Without it, all `/v1/webhooks/*` routes return `404` and the gateway logs:

```
webhook subsystem disabled: GOCLAW_ENCRYPTION_KEY not set
```

This is intentional: an empty key would silently persist raw webhook secrets to the database, defeating the stated DB-leak protection. Set the key and restart to re-enable the subsystem.

### HMAC signing (recommended)

Each webhook row has an `hmac_signing_key` (returned once on create and on rotate). Use HMAC-SHA256 to sign requests instead of the bearer secret:

```
X-Webhook-Id: <webhook-uuid>
X-GoClaw-Signature: t=<unix_seconds>,v1=<hmac_hex>
```

Signing algorithm:

```
signing_key = hex.Decode(hmac_signing_key)       // hex_64 → 32 raw bytes
payload     = "{unix_ts}.{raw_request_body}"
signature   = HMAC_SHA256(signing_key, payload)
header      = "t={unix_ts},v1={hex(signature)}"
```

**Timestamp skew protection.** Requests where `|now - t| > 300` seconds are rejected. Keep caller clocks synchronized via NTP.

**Replay protection.** After a valid HMAC signature is accepted, the gateway records `sha256(tenant_id|signature_hex)` in a per-process nonce cache (TTL 320 s). Replays return `401` with audit event `security.webhook.hmac_replay`.

**Force HMAC-only auth.** Set `require_hmac: true` on the webhook row to disable bearer-secret authentication entirely. This is the recommended posture for production integrations.

### Additional knobs

| Field | Notes |
|-------|-------|
| `localhost_only` | Restrict callers to `127.0.0.1` / `::1`. Auto-set to `true` on Lite edition. |
| `ip_allowlist` | IPs or CIDR ranges. Empty = any source. `X-Forwarded-For` not trusted. |
| `rate_limit_per_min` | Per-webhook cap (0 = use tenant default). |

See [Webhooks](/advanced/webhooks) for full create payload reference and signature verification examples in Go, Node.js, and Python.

---

## RBAC — 3 Roles

WebSocket RPC methods and HTTP endpoints are gated by role. Roles are hierarchical.

| Role | Key permissions |
|------|----------------|
| **Viewer** | `agents.list`, `config.get`, `sessions.list`, `health`, `status`, `skills.list` |
| **Operator** | + `chat.send`, `chat.abort`, `sessions.delete/reset`, `cron.*`, `skills.update` |
| **Admin** | + `config.apply/patch`, `agents.create/update/delete`, `channels.toggle`, `device.pair.approve/revoke` |

### API Keys

For fine-grained access control, create scoped API keys instead of sharing the gateway token. Keys are hashed with SHA-256 before storage and cached for 5 minutes.

Authentication priority:
1. **Gateway token** → Admin role (full access)
2. **API key** → Role derived from scopes
3. **No token** → Operator (backward compatibility); if no gateway token is configured at all → Admin (dev mode)

Available scopes:

| Scope | Access level |
|-------|-------------|
| `operator.admin` | Full admin access |
| `operator.read` | Read-only (viewer-equivalent) |
| `operator.write` | Read + write operations |
| `operator.approvals` | Exec approval management |
| `operator.pairing` | Device pairing management |

API keys are passed via `Authorization: Bearer {key}` header, same as the gateway token.

---

## Memory File Overwrite Protection

The memory interceptor prevents silent data loss when an agent attempts to overwrite an existing memory file with different content. When a write is issued in replace mode (not append) and the target already contains different content, the previous value is captured and returned to the caller so the agent can be warned before data is lost.

---

## Config Permissions System

GoClaw exposes three RPC methods to control which users can modify an agent's configuration:

| Method | Description |
|--------|-------------|
| `config.permissions.list` | List all granted permissions for an agent |
| `config.permissions.grant` | Grant a specific user permission to modify a config type |
| `config.permissions.revoke` | Revoke a previously granted permission |

By default, config modifications require admin access. Granting permission to a `userId` for a given `scope` and `configType` allows that user to make the specific change without full admin rights.

---

## Goroutine Panic Recovery

GoClaw wraps all background goroutines (tool execution, cron jobs, summarization) in a panic recovery handler via the `safego` package. If a goroutine panics, the error is caught and logged instead of crashing the entire server process. No configuration required — panic recovery is always active.

---

## Hardening Checklist

Use this before exposing GoClaw to the internet or shared users:

- [ ] Set `GOCLAW_GATEWAY_TOKEN` to a strong random token
- [ ] Set `GOCLAW_ENCRYPTION_KEY` to a base64-encoded 32-byte key (`openssl rand -base64 32`) — required for webhooks, workstation credentials, and CLI grant env overrides
- [ ] Store `GOCLAW_ENCRYPTION_KEY` in a secret manager (Vault, AWS Secrets Manager, etc.) — never commit to `config.json` or version control
- [ ] Set `gateway.allowed_origins` to your dashboard domain
- [ ] Set `gateway.rate_limit_rpm` (e.g., `20`) to limit per-user request rate
- [ ] Set `gateway.injection_action` to `"block"` for public-facing deployments
- [ ] Enable exec approval with `tools.execApproval.ask: "on-miss"` (or `"always"`)
- [ ] Enable Docker sandbox with `sandbox.mode: "all"` for untrusted agent workloads
- [ ] Set `POSTGRES_PASSWORD` to a strong password (not the default `"goclaw"`)
- [ ] Enable TLS on PostgreSQL (`sslmode=require` in DSN)
- [ ] Review `gateway.owner_ids` — only trusted user IDs should have owner-level access
- [ ] Set `agents.restrict_to_workspace: true` (this is the default — do not disable)
- [ ] Create scoped API keys for integrations instead of sharing the gateway token
- [ ] Configure `tools.credentialed_exec` for secure CLI tool integrations (gh, aws, etc.)
- [ ] Review shell deny groups — all 15 are on by default; only relax for specific agents that need it
- [ ] Verify sandbox mode does not fall back to host execution (fail-closed)
- [ ] Confirm `GOCLAW_GATEWAY_TOKEN` is set — empty token enables dev mode (admin for all)
- [ ] For webhooks: use `require_hmac: true` on webhook rows — disables bearer auth, forces HMAC-SHA256 signing
- [ ] For webhooks: set `localhost_only: true` (or use `ip_allowlist`) on any webhook not meant to be public
- [ ] No plaintext credentials anywhere in config files — use env vars and secret managers

---

## Security Logging

All security events log at `slog.Warn` with a `security.*` prefix:

| Event | Meaning |
|-------|---------|
| `security.injection_detected` | Prompt injection pattern found |
| `security.injection_blocked` | Message rejected (action = block) |
| `security.rate_limited` | Request rejected by rate limiter |
| `security.cors_rejected` | WebSocket connection rejected by CORS policy |
| `security.message_truncated` | Message truncated at `max_message_chars` |
| `security.credentialed_binary_denied` | Agent attempted exec without a grant |
| `security.credentialed_binary_gate_error` | Grant lookup failed; exec denied fail-closed |
| `security.credentialed_binary_wrapper_too_deep` | Shell wrapper nesting > 3 levels rejected |

Filter all security events:

```bash
./goclaw 2>&1 | grep '"security\.'
# or with structured logs:
journalctl -u goclaw | grep 'security\.'
```

---

## Common Issues

| Problem | Cause | Fix |
|---------|-------|-----|
| Legitimate messages blocked | `injection_action: "block"` too aggressive | Switch to `"warn"` and review logs before re-enabling block |
| Agent can read files outside workspace | `restrict_to_workspace: false` on agent | Re-enable (default is `true`) |
| Credentials appear in tool output | `scrub_credentials: false` | Remove that override — scrubbing is on by default |
| Sandbox not isolating | Sandbox mode is `"off"` | Set `sandbox.mode` to `"non-main"` or `"all"` |
| Encryption key not set | `GOCLAW_ENCRYPTION_KEY` empty | Set before first run; rotating requires re-encrypting stored secrets |
| All users have admin access | `GOCLAW_GATEWAY_TOKEN` not set | Set a strong token; empty = dev mode |

---

## What's Next

- [Exec Approval](../advanced/exec-approval.md) — interactive human-in-the-loop for shell commands
- [Sandbox](../advanced/sandbox.md) — Docker sandbox configuration details
- [Docker Compose](./docker-compose.md) — deploying with security settings via compose overlays
- [Database Setup](./database-setup.md) — PostgreSQL TLS and encrypted secret storage
- [Webhooks](../advanced/webhooks.md) — HMAC-authenticated HTTP endpoints, signature verification, and replay protection
- [Workstations](../advanced/workstations.md) — remote execution targets, permission model, and activity audit



---

# Observability

> Monitor every LLM call, tool use, and agent run — from the built-in dashboard to Jaeger and beyond.

## Overview

GoClaw ships with built-in tracing that records every agent run as a **trace** and each LLM call or tool use as a **span**. Traces are stored in PostgreSQL and visible immediately in the dashboard. If you need to integrate with your existing observability stack (Grafana Tempo, Datadog, Honeycomb, Jaeger), you can export spans over OTLP by building with `-tags otel`.

```mermaid
graph LR
    A[Agent Run] --> B[Collector]
    B --> C[(PostgreSQL)]
    B --> D[OTel Exporter]
    D --> E[Jaeger / Tempo / etc.]
    C --> F[Dashboard UI]
    C --> G[HTTP API]
```

## How Tracing Works

The `tracing.Collector` runs a background flush loop (every 5 seconds) that:

1. Drains a 1000-span in-memory buffer
2. Batch-inserts spans into PostgreSQL
3. Forwards spans to any attached `SpanExporter` (OTel, etc.)
4. Updates per-trace aggregate counters (total tokens, duration, status)

Traces and spans are linked by `trace_id`. Each agent run creates one trace; LLM calls and tool invocations inside that run become child spans.

**Span types recorded:**

| Span type | What it captures |
|-----------|-----------------|
| `llm_call` | Model, tokens in/out, finish reason, latency |
| `tool_call` | Tool name, call ID, duration, status |
| `agent` | Full run lifecycle, output preview |
| `embedding` | Embedding generation for vector store operations |
| `event` | Discrete event marker (no duration) |

## Viewing Traces

### Dashboard

Open the **Traces** section in the web UI (default: `http://localhost:18790`). You can filter by agent, date range, and status.

The Traces UI includes:
- **Timestamps** on each span for precise timing
- **Copy button** on span details for easy export of trace data
- **Syntax highlighting** on JSON payloads in span previews

### Verbose Mode

By default, input messages are truncated to 500 characters in span previews. To store full LLM inputs (useful for debugging):

```bash
export GOCLAW_TRACE_VERBOSE=1
./goclaw
```

In verbose mode, LLM spans store full input/output up to 200 KB; tool spans store full input and output up to 200 KB.

> Use verbose mode only in dev — full messages can be large.

## Trace Export

Individual traces (including all spans and sub-traces) can be exported via HTTP:

```
GET /v1/traces/{traceID}/export
```

The response is **gzip-compressed JSON** containing the trace, its spans, and recursively collected child traces (`sub_traces`). This is useful for offline analysis, bug reports, or archiving long agent runs.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:18790/v1/traces/{traceID}/export \
  --output trace.json.gz

gunzip trace.json.gz
```

## Trace HTTP API

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/traces` | List traces with pagination and filters |
| GET | `/v1/traces/follow` | Poll trace changes for one session or agent |
| GET | `/v1/traces/{id}` | Get trace details with all spans |
| GET | `/v1/traces/{id}/export` | Export trace + sub-traces as gzip JSON |
| GET | `/v1/runs/{runID}/timeline` | Get persisted run-archive timeline items |

### Query Filters (GET /v1/traces)

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Contains-search across trace ID, trace previews, session/channel labels, agent/channel labels, and span previews/tool names |
| `agent_id` | UUID | Filter by agent |
| `user_id` | string | Filter by user |
| `session_key` | string | Filter by session key |
| `status` | string | `running`, `completed`, `error`, `cancelled` |
| `channel` | string | Filter by raw channel |
| `agent` | string | Contains-search over agent display name and key |
| `channel_query` | string | Contains-search over tenant-scoped channel instance labels |
| `tool_name` | string | Contains-search over span tool names |
| `has_tool_calls` | boolean | Traces with (`true`) or without (`false`) tool calls |
| `from` / `to` | timestamp | `start_time` range filter — `from` inclusive, `to` exclusive |
| `min_input_tokens` / `max_input_tokens` | int | Input token range |
| `min_output_tokens` / `max_output_tokens` | int | Output token range |
| `min_tool_calls` / `max_tool_calls` | int | Tool-call count range |
| `limit` | int | Page size (default 50) |
| `offset` | int | Pagination offset |

> The `goclaw traces` operator CLI wraps these same endpoints. See [CLI Commands](../reference/cli-commands.md) for the command reference.

### Pointing operator commands at a gateway

HTTP operator commands (and the dashboard's API) resolve their base URL in this order:

1. `--server <url>` flag (highest priority)
2. `GOCLAW_SERVER` environment variable
3. `GOCLAW_GATEWAY_URL` environment variable (fallback)
4. The gateway host/port from `config.json` (defaults to `http://127.0.0.1:18790`)

`GOCLAW_GATEWAY_URL` now drives **all** HTTP operator commands, not just `auth`. Pair it with `--token` / `GOCLAW_GATEWAY_TOKEN` for the bearer token.

## OpenTelemetry Export

The OTel exporter is compiled in only when you add `-tags otel`. The default build has zero OTel dependencies, saving approximately 15–20 MB from the binary.

### Build with OTel support

```bash
go build -tags otel -o goclaw .
```

### Configure via environment

```bash
export GOCLAW_TELEMETRY_ENABLED=true
export GOCLAW_TELEMETRY_ENDPOINT=localhost:4317   # OTLP gRPC endpoint
export GOCLAW_TELEMETRY_PROTOCOL=grpc             # "grpc" (default) or "http"
export GOCLAW_TELEMETRY_INSECURE=true             # skip TLS for local dev
export GOCLAW_TELEMETRY_SERVICE_NAME=goclaw-gateway
```

Or via `config.json`:

```json
{
  "telemetry": {
    "enabled": true,
    "endpoint": "tempo:4317",
    "protocol": "grpc",
    "insecure": false,
    "service_name": "goclaw-gateway"
  }
}
```

Spans are exported using `gen_ai.*` semantic conventions (OpenTelemetry GenAI SIG), plus `goclaw.*` custom attributes for correlation with the PostgreSQL trace store.

The OTel exporter batches spans with a max batch size of 100 and a 5-second timeout.

## Jaeger Integration

The included `docker-compose.otel.yml` overlay spins up Jaeger all-in-one and wires it to GoClaw automatically:

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.otel.yml \
  up
```

Jaeger UI is available at **http://localhost:16686**.

The overlay sets:

```yaml
# docker-compose.otel.yml (excerpt)
services:
  jaeger:
    image: jaegertracing/all-in-one:1.68.0
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP
    environment:
      - COLLECTOR_OTLP_ENABLED=true

  goclaw:
    build:
      args:
        ENABLE_OTEL: "true"   # compiles with -tags otel
    environment:
      - GOCLAW_TELEMETRY_ENABLED=true
      - GOCLAW_TELEMETRY_ENDPOINT=jaeger:4317
      - GOCLAW_TELEMETRY_PROTOCOL=grpc
      - GOCLAW_TELEMETRY_INSECURE=true
```

## Key Attributes in Exported Spans

| Attribute | Description |
|-----------|-------------|
| `gen_ai.request.model` | LLM model name |
| `gen_ai.system` | Provider (anthropic, openai, etc.) |
| `gen_ai.usage.input_tokens` | Tokens consumed as input |
| `gen_ai.usage.output_tokens` | Tokens produced as output |
| `gen_ai.response.finish_reason` | Why the model stopped |
| `goclaw.span_type` | `llm_call`, `tool_call`, `agent`, `embedding`, `event` |
| `goclaw.tool.name` | Tool name for tool spans |
| `goclaw.trace_id` | UUID linking back to PostgreSQL |
| `goclaw.duration_ms` | Wall-clock duration |

## Usage Analytics

GoClaw aggregates token counts and costs into hourly snapshots via a background worker (runs at HH:05:00 UTC). These power the dashboard's usage charts and the `/v1/usage` API endpoint.

The `usage_snapshots` table stores pre-computed aggregates per agent, user, and provider — so dashboard queries stay fast even with millions of spans. On startup, the worker backfills any missed hours automatically.

An `activity_logs` table records admin actions, config changes, and security events as an audit trail.

## Real-Time Log Streaming

Connected WebSocket clients can subscribe to live log events. The `LogTee` layer intercepts all `slog` records and:

1. Caches the last 100 entries in a ring buffer (new subscribers get recent history)
2. Broadcasts to subscribed clients at their chosen log level
3. Auto-redacts sensitive fields: `key`, `token`, `secret`, `password`, `dsn`, `credential`, `authorization`, `cookie`

This means dashboard users see real-time logs without SSH access, and secrets never leak through the log stream.

## Common Issues

| Issue | Likely cause | Fix |
|-------|-------------|-----|
| No spans in Jaeger | Binary built without `-tags otel` | Rebuild with `go build -tags otel` |
| `GOCLAW_TELEMETRY_ENABLED` ignored | OTel build tag missing | Check `ENABLE_OTEL: "true"` in docker build args |
| Span buffer full (log warning) | High agent throughput | Increase buffer or reduce flush interval in code |
| Input previews truncated | Normal behavior | Set `GOCLAW_TRACE_VERBOSE=1` for full inputs |
| Spans appear in DB but not Jaeger | Endpoint misconfigured | Check `GOCLAW_TELEMETRY_ENDPOINT` and port reachability |

## What's Next

- [Production Checklist](/deploy-checklist) — monitoring and alerting recommendations
- [Docker Compose Setup](/deploy-docker-compose) — full compose file reference
- [Security Hardening](/deploy-security) — securing your deployment



---

# Tailscale Integration

> Expose your GoClaw gateway securely on your Tailscale network — no port forwarding, no public IP required.

## Overview

GoClaw can join your [Tailscale](https://tailscale.com) network as a named node, making the gateway reachable from any of your devices without opening firewall ports. This is ideal for self-hosted setups where you want private remote access from your laptop, phone, or CI runners.

The Tailscale listener runs **alongside** the regular HTTP listener on the same handler — you get both local and Tailscale access simultaneously.

This feature is opt-in and compiled in only when you build with `-tags tsnet`. The default binary has zero Tailscale dependencies.

## How It Works

```mermaid
graph LR
    A[Your laptop] -->|Tailscale network| B[goclaw-gateway node]
    C[Your phone] -->|Tailscale network| B
    B --> D[Gateway handler]
    E[Local network] -->|Port 18790| D
```

When `GOCLAW_TSNET_HOSTNAME` is set, GoClaw starts a `tsnet.Server` that connects to Tailscale and listens on port 80 (or 443 with TLS). The Tailscale node appears in your Tailscale admin console as a regular device.

## Build with Tailscale Support

```bash
go build -tags tsnet -o goclaw .
```

Or with Docker Compose using the provided overlay:

```bash
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.tailscale.yml \
  up
```

The overlay passes `ENABLE_TSNET: "true"` as a build arg, which compiles the binary with `-tags tsnet`.

## Configuration

### Required

```bash
# From https://login.tailscale.com/admin/settings/keys
# Use a reusable auth key for long-lived deployments
export GOCLAW_TSNET_AUTH_KEY=tskey-auth-xxxxxxxxxxxxxxxx
```

### Optional

```bash
# Tailscale device name (default: goclaw-gateway)
export GOCLAW_TSNET_HOSTNAME=my-goclaw

# Directory for Tailscale state (persisted across restarts)
# Default: OS user config dir
export GOCLAW_TSNET_DIR=/app/tsnet-state
```

Or via `config.json` (auth key is **never** stored in config — env only):

```json
{
  "tailscale": {
    "hostname": "my-goclaw",
    "state_dir": "/app/tsnet-state",
    "ephemeral": false,
    "enable_tls": false
  }
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `hostname` | `goclaw-gateway` | Tailscale device name |
| `state_dir` | OS user config dir | Persists Tailscale identity across restarts |
| `ephemeral` | `false` | If true, node is automatically removed from your tailnet when GoClaw stops — useful for CI/CD or short-lived containers |
| `enable_tls` | `false` | Use Tailscale-managed HTTPS certs via Let's Encrypt (listens on `:443` instead of `:80`) |

## Docker Compose Setup

The `docker-compose.tailscale.yml` overlay mounts a named volume for Tailscale state so the node identity survives container restarts:

```yaml
# docker-compose.tailscale.yml (full file)
services:
  goclaw:
    build:
      args:
        ENABLE_TSNET: "true"
    environment:
      - GOCLAW_TSNET_HOSTNAME=${GOCLAW_TSNET_HOSTNAME:-goclaw-gateway}
      - GOCLAW_TSNET_AUTH_KEY=${GOCLAW_TSNET_AUTH_KEY}
    volumes:
      - tsnet-state:/app/tsnet-state

volumes:
  tsnet-state:
```

Set your auth key in `.env`:

```bash
GOCLAW_TSNET_AUTH_KEY=tskey-auth-xxxxxxxxxxxxxxxx
GOCLAW_TSNET_HOSTNAME=my-goclaw
```

Then bring it up:

```bash
docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.tailscale.yml up -d
```

## Accessing the Gateway

Once running, your gateway is reachable at:

```
http://my-goclaw.your-tailnet.ts.net     # HTTP (default)
https://my-goclaw.your-tailnet.ts.net    # HTTPS (if enable_tls: true)
```

You can find the full hostname in your [Tailscale admin console](https://login.tailscale.com/admin/machines).

## Common Issues

| Issue | Likely cause | Fix |
|-------|-------------|-----|
| Node not appearing in Tailscale console | Invalid or expired auth key | Generate a new reusable key at admin/settings/keys |
| Tailscale listener not starting | Binary built without `-tags tsnet` | Rebuild with `go build -tags tsnet` |
| `GOCLAW_TSNET_HOSTNAME` ignored | Tag missing from build | Check `ENABLE_TSNET: "true"` in docker build args |
| State lost on container restart | Missing volume mount | Ensure `tsnet-state` volume is mounted to `state_dir` |
| Connection refused from Tailscale | `enable_tls` mismatch | Check whether you're using HTTP or HTTPS |

## What's Next

- [Production Checklist](/deploy-checklist) — secure your deployment end to end
- [Security Hardening](/deploy-security) — CORS, rate limits, and token auth
- [Docker Compose Setup](/deploy-docker-compose) — full compose overlay reference



---

# Production Checklist

> Everything you need to verify before taking GoClaw from development to production.

## Overview

This checklist covers the critical steps to harden, secure, and reliably operate a GoClaw gateway in production. Work through each section top to bottom before going live.


## 2. Secrets and Encryption

- [ ] `GOCLAW_ENCRYPTION_KEY` is set to a random 32-byte hex string — **back this up**. Losing it means losing all encrypted API keys stored in the database.
- [ ] `GOCLAW_GATEWAY_TOKEN` is set to a strong random value — required for WebSocket and HTTP auth
- [ ] Neither secret appears in `config.json`, git history, or logs
- [ ] All provider API keys are set via environment (`GOCLAW_ANTHROPIC_API_KEY`, etc.) or added through the dashboard (where they are stored encrypted with AES-256-GCM)

```bash
# Generate secrets if you haven't run onboard/prepare-env.sh
export GOCLAW_ENCRYPTION_KEY=$(openssl rand -hex 32)
export GOCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
```

> Back up `GOCLAW_ENCRYPTION_KEY` in a secrets manager (e.g. AWS Secrets Manager, 1Password, Vault). If you rotate it, all encrypted API keys in the database become unreadable.

---

## 3. Network and TLS

- [ ] TLS termination is in place (nginx, Caddy, Cloudflare, or load balancer) — GoClaw itself does not terminate TLS in standard mode
- [ ] Gateway is **not** exposed directly on a public port without TLS
- [ ] `gateway.allowed_origins` is set to your actual client origins (empty = allow all WebSocket origins)

```json
{
  "gateway": {
    "allowed_origins": ["https://your-dashboard.example.com"]
  }
}
```

---

## 4. Rate Limiting

- [ ] `gateway.rate_limit_rpm` is set (default: 20 requests/minute per user, 0 = disabled)
- [ ] `tools.rate_limit_per_hour` is set (default: 150 tool executions/hour per session, 0 = disabled)
- [ ] Webhook rate limiting is built-in (30 requests/60s per source, max 4096 tracked sources) — no configuration needed

```json
{
  "gateway": {
    "rate_limit_rpm": 20
  },
  "tools": {
    "rate_limit_per_hour": 150
  }
}
```

---

## 5. Sandbox Configuration

If agents execute code, review the sandbox settings:

- [ ] `sandbox.mode` is set: `"off"` (no sandbox), `"non-main"` (sandbox subagents only), or `"all"` (sandbox everything)
- [ ] `sandbox.memory_mb` and `sandbox.cpus` are tuned for your workload (defaults: 512 MB, 1 CPU)
- [ ] `sandbox.network_enabled` is `false` unless agents explicitly need network access
- [ ] `sandbox.read_only_root` is `true` (default) for immutable container root filesystem
- [ ] `sandbox.timeout_sec` is set to a reasonable limit (default: 300s)
- [ ] `sandbox.idle_hours` tuned (default: 24 — removes containers idle longer than this)
- [ ] `sandbox.max_age_days` set (default: 7 — removes containers older than this)

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "memory_mb": 512,
        "cpus": 1.0,
        "network_enabled": false,
        "read_only_root": true,
        "timeout_sec": 120
      }
    }
  }
}
```

---

## 6. Security Settings

- [ ] `gateway.injection_action` is set to `"warn"` (default) or `"block"` — never `"off"` in production
- [ ] `tools.exec_approval.security` is `"full"` (default) — blocks dangerous shell patterns
- [ ] `agents.defaults.restrict_to_workspace` is `true` (default) — prevents path traversal outside workspace
- [ ] Review `tools.web_fetch` domain allow/deny lists if agents browse the web

---

## 7. Monitoring and Alerting

- [ ] Log output is collected (stdout/stderr) — GoClaw uses structured JSON logging via `slog`
- [ ] Alert on repeated `slog.Warn("security.*")` log entries — these indicate blocked attacks or anomalies
- [ ] Alert on `tracing: span buffer full` — indicates the collector is falling behind under load
- [ ] Uptime monitoring is configured (e.g. ping `/health` or the gateway port)
- [ ] Consider enabling OTel export for trace-level visibility — see [Observability](/deploy-observability)
- [ ] Interactive API documentation is available at `/docs` (Swagger UI) and `/v1/openapi.json` for integration testing

---

## 8. Operational Hygiene

- [ ] Log rotation is configured if writing to files (use `logrotate` or your container runtime's log driver)
- [ ] `GOCLAW_AUTO_UPGRADE=true` is set **only** if you accept automatic schema migrations on startup; otherwise upgrade explicitly with `./goclaw upgrade`
- [ ] A runbook exists for: restart, rollback, DB restore, and encryption key rotation
- [ ] Upgrade procedure is documented and tested — see [Upgrading](/deploy-upgrading)

---

## 9. API Key Management

- [ ] Consider creating scoped API keys instead of sharing the gateway token
- [ ] API keys support fine-grained scopes: `operator.admin`, `operator.read`, `operator.write`, `operator.approvals`, `operator.pairing`
- [ ] Keys are hashed (SHA-256) before storage — the plaintext is shown only at creation time
- [ ] Set up key rotation policy — keys can be revoked individually without affecting others

```json
// Example: create a read-only key for monitoring
// via dashboard or API
{
  "name": "monitoring-readonly",
  "scopes": ["operator.read"]
}
```

---

## 10. Concurrency Tuning

GoClaw uses lane-based scheduling to limit concurrent agent runs by type:

| Environment Variable | Default | Purpose |
|---------------------|---------|---------|
| `GOCLAW_LANE_MAIN` | `30` | Max concurrent main agent runs |
| `GOCLAW_LANE_SUBAGENT` | `50` | Max concurrent subagent runs |
| `GOCLAW_LANE_DELEGATE` | `100` | Max concurrent delegated runs |
| `GOCLAW_LANE_CRON` | `30` | Max concurrent cron job runs |

Tune these based on your server resources and expected load. Lower values reduce memory pressure; higher values improve throughput.

---

## 11. Gateway Tuning

Review these gateway settings for your deployment:

| Setting | Default | Description |
|---------|---------|-------------|
| `gateway.owner_ids` | `[]` | User IDs with owner-level access — keep this list minimal |
| `gateway.max_message_chars` | `32000` | Max user message size before truncation |
| `gateway.inbound_debounce_ms` | `1000` | Merge rapid consecutive messages (ms) |
| `gateway.task_recovery_interval_sec` | `300` | How often team tasks are checked for recovery |

- [ ] `gateway.owner_ids` contains only trusted admin user IDs
- [ ] `gateway.max_message_chars` is appropriate for your use case (lower = less token spend)

---

## Quick Verification

### First-Time Setup

For new installations, the `onboard` command handles initial setup interactively:

```bash
./goclaw onboard
```

It generates encryption and gateway tokens, runs database migrations, and walks you through basic configuration. You can also run `prepare-env.sh` for non-interactive secret generation.

### System Health Check

The `doctor` command runs a comprehensive check of your environment:

```bash
./goclaw doctor
```

It validates: runtime info, config file, database connection and schema version, provider API keys, channel credentials, external tools (docker, curl, git), and workspace directories.

```bash
# Check schema and pending migrations
./goclaw upgrade --status

# Verify gateway starts and connects to DB
./goclaw &
curl http://localhost:18790/health

# Confirm secrets are not exposed in logs
# Look for "***" masking, not raw key values
```

## Common Issues

| Issue | Likely cause | Fix |
|-------|-------------|-----|
| Gateway refuses to start | Schema outdated | Run `./goclaw upgrade` |
| Encrypted API keys unreadable | Wrong `GOCLAW_ENCRYPTION_KEY` | Restore correct key from backup |
| WebSocket connections rejected | `allowed_origins` too restrictive | Add your dashboard origin to the list |
| Rate limit too aggressive | Default 20 RPM for high-traffic use | Increase `gateway.rate_limit_rpm` |
| Agents escape workspace | `restrict_to_workspace` disabled | Set to `true` in config |

## What's Next

- [Upgrading](/deploy-upgrading) — how to upgrade GoClaw safely
- [Observability](/deploy-observability) — set up tracing and alerting
- [Security Hardening](/deploy-security) — deeper security configuration
- [Docker Compose Setup](/deploy-docker-compose) — production compose patterns



---

# Upgrading

> How to safely upgrade GoClaw — binary, database schema, and data migrations — with zero surprises.

## Overview

A GoClaw upgrade has two parts:

1. **SQL migrations** — schema changes applied by `golang-migrate` (idempotent, versioned)
2. **Data hooks** — optional Go-based data transformations that run after schema migrations (e.g. backfilling a new column)

The `./goclaw upgrade` command handles both in the correct order. It is safe to run multiple times — it is fully idempotent. The current required schema version is **80**.

```mermaid
graph LR
    A[Backup DB] --> B[Replace binary]
    B --> C[goclaw upgrade --dry-run]
    C --> D[goclaw upgrade]
    D --> E[Start gateway]
    E --> F[Verify]
```

## The Upgrade Command

```bash
# Preview what would happen (no changes applied)
./goclaw upgrade --dry-run

# Show current schema version and pending items
./goclaw upgrade --status

# Apply all pending SQL migrations and data hooks
./goclaw upgrade
```

### Status output explained

```
  App version:     v1.2.0 (protocol 3)
  Schema current:  12
  Schema required: 14
  Status:          UPGRADE NEEDED (12 -> 14)

  Pending data hooks: 1
    - 013_backfill_agent_slugs

  Run 'goclaw upgrade' to apply all pending changes.
```

| Status | Meaning |
|--------|---------|
| `UP TO DATE` | Schema matches binary — nothing to do |
| `UPGRADE NEEDED` | Run `./goclaw upgrade` |
| `BINARY TOO OLD` | Your binary is older than the DB schema — upgrade the binary |
| `DIRTY` | A migration failed partway — see recovery below |

## Standard Upgrade Procedure

### Step 1 — Back up the database

```bash
pg_dump -Fc "$GOCLAW_POSTGRES_DSN" > goclaw-backup-$(date +%Y%m%d).dump
```

Never skip this. Schema migrations are not automatically reversible.

### Step 2 — Replace the binary

```bash
# Download new binary or build from source
go build -o goclaw-new .

# Verify version
./goclaw-new upgrade --status
```

### Step 3 — Dry run

```bash
./goclaw-new upgrade --dry-run
```

Review what SQL migrations and data hooks will be applied.

### Step 4 — Apply

```bash
./goclaw-new upgrade
```

Expected output:

```
  App version:     v1.2.0 (protocol 3)
  Schema current:  12
  Schema required: 14

  Applying SQL migrations... OK (v12 -> v14)
  Running data hooks... 1 applied

  Upgrade complete.
```

### Step 5 — Start the gateway

```bash
mv goclaw-new goclaw
./goclaw
```

### Step 6 — Verify

- Open the dashboard and confirm agents load correctly
- Check logs for any `ERROR` or `WARN` lines during startup
- Run a test agent message end-to-end

## Docker Compose Upgrade

Use the `docker-compose.upgrade.yml` overlay to run the upgrade as a one-shot container:

```bash
# Dry run
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade --dry-run

# Apply
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade

# Check status
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml \
  run --rm upgrade --status
```

The `upgrade` service starts, runs `goclaw upgrade`, then exits. The `--rm` flag removes the container automatically.

> Make sure `GOCLAW_ENCRYPTION_KEY` is set in your `.env` — the upgrade service needs it to access encrypted config.

## Auto-Upgrade on Startup

For CI or ephemeral environments where manual upgrade steps are impractical:

```bash
export GOCLAW_AUTO_UPGRADE=true
./goclaw
```

When set, the gateway checks the schema on startup and applies any pending SQL migrations and data hooks automatically before serving traffic.

**Use with caution in production** — prefer explicit `./goclaw upgrade` so you control timing and have a backup first.

## Rollback Procedure

GoClaw does not provide automatic rollback. If something goes wrong:

### Option A — Restore from backup (safest)

```bash
# Stop gateway
# Restore DB from pre-upgrade backup
pg_restore -d "$GOCLAW_POSTGRES_DSN" goclaw-backup-20250308.dump

# Restore previous binary
./goclaw-old
```

### Option B — Fix a dirty schema

If a migration failed partway, the schema is marked dirty:

```
  Status: DIRTY (failed migration)
  Fix:  ./goclaw migrate force 13
  Then: ./goclaw upgrade
```

Force the migration version back to the last known good state, then re-run upgrade:

```bash
./goclaw migrate force 13
./goclaw upgrade
```

Only do this if you understand what the failed migration was doing. When in doubt, restore from backup.

### All migrate subcommands

```bash
./goclaw migrate up              # Apply pending migrations
./goclaw migrate down            # Roll back one step
./goclaw migrate down 3          # Roll back 3 steps
./goclaw migrate version         # Show current version + dirty state
./goclaw migrate force <version> # Force version (recovery only)
./goclaw migrate goto <version>  # Migrate to a specific version
./goclaw migrate drop            # DROP ALL TABLES (dangerous — use only in dev)
```

> **Data hooks tracking:** GoClaw tracks post-migration Go transforms in a separate `data_migrations` table (distinct from `schema_migrations`). Run `./goclaw upgrade --status` to see both SQL migration version and pending data hooks.

## Recent Migrations

### v3.12.x — Highlights and Breaking Changes

#### Schema 58 → 73

Migrations `000058`–`000073` are applied automatically on next startup (`./goclaw upgrade` or `GOCLAW_AUTO_UPGRADE=true`) — no manual steps required. Highlights:

- `000068_bitrix_portals` — adds `bitrix_portals` for per-tenant Bitrix24 portal OAuth state (credentials + tokens stored AES-256-GCM).
- `000069_browser_cookies` — adds `browser_cookies` for user-selected, encrypted server-side browser cookies, scoped by tenant/user/agent.
- `000070_usage_caps_pricing` — adds `usage_pricing_catalog` (synced per-model pricing) and `usage_pricing_overrides` (per-tenant price overrides).
- `000071_usage_cap_policies` — adds the usage-cap enforcement tables: `usage_cap_policies`, `usage_cap_counters`, `usage_cap_reservations`, `usage_cap_events`.
- `000072_agent_budget_usage_cap_bridge` — adds a `source` column to `usage_cap_policies` and **backfills** one `month`-window policy per agent that has a non-NULL `budget_monthly_cents` (1 cent = 10,000 micros, `source = 'agent_budget_monthly_cents'`). Existing per-agent monthly budgets are now enforced through the usage-cap engine. Idempotent (`ON CONFLICT DO NOTHING`); no action required.
- `000073_secure_cli_credential_type` — adds nullable `credential_type` + `host_scope` to `secure_cli_user_credentials` and `adapter_name` to `secure_cli_binaries` for the typed credential-adapter framework. All columns NULL-by-default to preserve legacy passthrough behavior — no action required.

#### Schema 73 → 80

Migrations `000074`–`000080` are applied automatically on next startup (`./goclaw upgrade` or `GOCLAW_AUTO_UPGRADE=true`) — no manual steps required. All new tables; existing data is untouched. Highlights:

- `000074_run_timeline_items` — adds `run_timeline_items` for an archived, ordered per-run timeline (messages/tool calls) used to replay runs; links to traces and spans.
- `000075_channel_context_capabilities` — adds `mcp_context_grants`, `mcp_context_credentials`, `secure_cli_context_grants`, and `secure_cli_context_credentials` for per-channel-instance scoped MCP and secure-CLI grants with encrypted credentials.
- `000076_channel_memory_extraction` — adds `channel_memory_extraction_runs` and `channel_memory_extraction_items` for passive, scheduled extraction of durable memory from channel history (summaries only, no raw bodies) with a review queue.
- `000077_secure_cli_agent_credentials` — adds `secure_cli_agent_credentials` for per-agent typed CLI credentials, separate from the grants policy; uses composite FKs `(binary_id, tenant_id)` and `(agent_id, tenant_id)`.
- `000078_skill_user_grants_tenant_unique` — replaces the `skill_user_grants` unique key with tenant-scoped `(skill_id, user_id, tenant_id)`. No action required.
- `000079_skill_self_evolution` — adds `skill_evolution_settings`, `skill_usage_metrics`, `skill_improvement_suggestions`, and `skill_versions` for per-skill usage tracking and suggested/applied improvements. **Backfills** one `skill_versions` row per existing non-deleted skill. Idempotent (`ON CONFLICT DO NOTHING`).
- `000080_usage_event_analytics` — adds `usage_events` (raw per-event analytics) and `usage_event_rollups` (pre-aggregated hourly rollups) backing the usage analytics dashboard.

**Gateway-triggered upgrades (host release-upgrade flow):** When a dashboard/API-triggered upgrade is run on a systemd host, `goclaw-upgrade-release` now re-launches itself as a transient `systemd-run` unit so stopping `goclaw` during deploy no longer kills the upgrade job. Stale `running` status records are also superseded after 30 minutes, and the deploy wait loop tolerates transient `502`s during restart. No configuration change required.

#### v3.11.3

- fix(migrations): `000057_heartbeat_provider_fk_set_null` — defensive orphan cleanup; drops existing FK by constraint-name lookup (handles auto-generated name drift), re-adds with `ON DELETE SET NULL`. Brief `ACCESS EXCLUSIVE` lock on `agent_heartbeats` during `ALTER TABLE` (sub-second on small tables; heartbeat workers may pause briefly).
- SQLite: schema v25 → v26 — full table rebuild for `agent_heartbeats` with updated FK clause; explicit 25-column `INSERT … SELECT` preserves all existing rows. `idx_heartbeats_due` recreated.

**Docker users:** MUST pull `ghcr.io/nextlevelbuilder/goclaw:v3.11.3` AND run `goclaw upgrade`. A stale v3.11.2 image fails on boot with:

```
schema version mismatch: required 57, current 56
```

**Bare-metal users:** rebuild binary and run `./goclaw upgrade`.

#### v3.11.2

- fix(migrations): drop scope-consistency check before backfill UPDATEs — migration #56 follow-up; prevents constraint errors when backfilling over legacy data

**Migration step:** Migration #56 is applied automatically on next startup (`goclaw upgrade` or `GOCLAW_AUTO_UPGRADE=true`). No manual steps required.

#### v3.11.1

- ci(release): native arm64 runners + split-build manifest pattern

> **Asset naming note:** The OTel variant asset has been dropped from the release pipeline. If your deploy script downloads an asset matching `*-otel*`, switch to the regular asset.

#### v3.11.0

**New features:**

- feat: Native `image_generation` for Codex + OpenAI-compat — tri-level gate (provider capability → agent flag → per-request header `x-goclaw-no-image-gen`)
- feat: `send_file` builtin tool + `DeliveredMedia` cross-tool dedup
- feat: `tools.shellDenyGroups` — runtime-reloadable global config for deny-groups (no restart required)
- feat: Vault `chat_id` isolation — migration #56 adds `chat_id` column to `vault_documents` to scope documents per chat
- feat: Pancake — TikTok + Shopee sub-platform support; private-reply stateless DM refactor
- feat: Codex pool — collapse `primary_first` on public surface, per-modality round-robin (chat vs image)
- feat: Dynamic compact `max_tokens = clamp(in/25, 1024, 8192)` replaces static 4096; tool-schema tokens counted in `OverheadTokens`
- feat: TTS — tenant `tts.timeout_ms`; Gemini text-only 400 fix; default model bump `gemini-3.1-flash-tts-preview`
- feat: Telegram bot self-identity injection + own @mention strip
- fix: Discord allowlist gate (#985/#1010)
- chore: Release pipeline — native arm64 runners, OTel variant DROPPED (asset renamed)

**BREAKING (clients):** Codex pool API responses now return `priority_order` in place of legacy `primary_first` / `manual` for the same routing config. Request bodies still accept legacy values for backward compatibility. Update consumers comparing strategy strings literally.



---

# Personal Assistant

> Single-user AI assistant on Telegram with memory and a custom personality.

## Overview

This recipe walks you from zero to a personal assistant: one gateway, one agent, one Telegram bot. By the end your assistant will remember things across conversations and respond with the personality you give it.

**What you need:**
- GoClaw binary (see [Getting Started](../getting-started/))
- PostgreSQL database with pgvector
- A Telegram bot token from @BotFather
- An API key from any supported LLM provider

## Step 1: Run the setup wizard

```bash
./goclaw onboard
```

The interactive wizard covers everything in one pass:

1. **Provider** — choose your LLM provider (OpenRouter is recommended for access to many models)
2. **Gateway port** — default `18790`
3. **Channel** — select `Telegram`, paste your bot token
4. **Features** — select `Memory` (vector search) and `Browser` (web access)
5. **Database** — paste your Postgres DSN

The wizard saves a `config.json` (no secrets) and a `.env.local` file (secrets only). Start the gateway:

```bash
source .env.local && ./goclaw
```

## Step 2: Understand the default config

After onboarding, `config.json` looks roughly like this:

```json
{
  "agents": {
    "defaults": {
      "workspace": "~/.goclaw/workspace",
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "max_tokens": 8192,
      "max_tool_iterations": 20,
      "memory": {
        "enabled": true,
        "embedding_provider": ""
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "",
      "dm_policy": "pairing",
      "reaction_level": "minimal"
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790
  },
  "tools": {
    "browser": {
      "enabled": true,
      "headless": true
    }
  }
}
```

`dm_policy: "pairing"` means new users must pair via a browser code before the bot responds. This protects your bot from strangers.

## Step 3: Pair your Telegram account

Open the web dashboard at `http://localhost:18790`. Go to the pairing page and follow the instructions — you'll send a code to your Telegram bot, and the dashboard confirms the link. Once paired, the bot responds to your messages.

Alternatively, use `./goclaw agent chat` to chat directly in the terminal without pairing.

## Step 4: Customize the personality (SOUL.md)

On first chat, the agent seeds a `SOUL.md` file in your user context. Edit it in the dashboard:

Go to **Agents → your agent → Files tab → SOUL.md** and edit inline. For example:

```markdown
You are a sharp, direct research partner. You prefer short answers over long explanations
unless the user explicitly asks to dig deeper. You have a dry sense of humor.
You never hedge with "I think" or "I believe" — just state your answer.
```

Click **Save** when done.

<details>
<summary><strong>Via API</strong></summary>

```bash
curl -X PUT http://localhost:18790/v1/agents/default/files/SOUL.md \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: your-user-id" \
  -H "Content-Type: text/plain" \
  --data-binary @- <<'EOF'
You are a sharp, direct research partner. You prefer short answers over long explanations
unless the user explicitly asks to dig deeper. You have a dry sense of humor.
You never hedge with "I think" or "I believe" — just state your answer.
EOF
```

</details>

See [Editing Personality](/editing-personality) for full SOUL.md reference.

## Step 5: Enable memory

Memory is already on if you selected it in the wizard. The agent uses SQLite + pgvector for hybrid search. Notes are stored with `memory_save` and searched with `memory_search` automatically.

To verify memory is active, send your bot: "Remember that I prefer Python over JavaScript." Then in a later session: "What programming language do I prefer?" — the agent recalls from memory.

You can also check memory status in the dashboard: go to **Agents → your agent** and verify the memory config shows as enabled.

## Optional: Personalize your agent

A few extra touches you can configure in the dashboard under **Agents → your agent**:

- **Emoji:** Set an emoji icon via the emoji selector in the agent detail page — this shows in the agent list and chat UI
- **Skill learning:** (Predefined agents only) Toggle **Skill Learning** to let the agent capture reusable workflows as skills after complex tasks. Set the nudge interval to control how often the agent suggests creating skills.

## Common Issues

| Problem | Solution |
|---------|----------|
| Bot doesn't respond in Telegram | Check `dm_policy`. With `"pairing"`, you must complete browser pairing first. Set `"open"` to skip pairing. |
| Memory not working | Confirm `memory.enabled: true` in config and that an embedding provider has an API key. Check gateway logs for embedding errors. |
| "No provider configured" error | Ensure the API key env var is set. Run `source .env.local` before `./goclaw`. |
| Bot responds to everyone | Set `dm_policy: "allowlist"` and `allow_from: ["your_username"]` in `channels.telegram`. |

## What's Next

- [Editing Personality](/editing-personality) — customize SOUL.md, IDENTITY.md, USER.md
- [Telegram Channel](/channel-telegram) — full Telegram configuration reference
- [Team Chatbot](/recipe-team-chatbot) — add specialist agents for different tasks
- [Multi-Channel Setup](/recipe-multi-channel) — put the same agent on Discord and WebSocket too



---

# Team Chatbot

> Multi-agent team with a lead coordinator and specialist sub-agents for different tasks.

## Overview

This recipe builds a team of three agents: a lead that handles conversation and delegates, plus two specialists (a researcher and a coder). Users talk only to the lead — it decides when to call in a specialist. Teams use GoClaw's built-in delegation system, so the lead can run specialists in parallel and synthesize results.

**What you need:**
- A working gateway (run `./goclaw onboard` first)
- Web dashboard access at `http://localhost:18790`
- At least one LLM provider configured

## Step 1: Create the specialist agents

Specialists must be **predefined** agents — only predefined agents can receive delegations.

Open the web dashboard and go to **Agents → Create Agent**. Create two specialists:

**Researcher agent:**
- **Key:** `researcher`
- **Display name:** Research Specialist
- **Type:** Predefined
- **Provider / Model:** Choose your preferred provider and model
- **Description:** "Deep research specialist. Searches the web, reads pages, synthesizes findings into concise reports with sources. Factual, thorough, cites everything."

Click **Save**. The `description` field triggers **summoning** — the gateway uses the LLM to auto-generate SOUL.md and IDENTITY.md. The agent status shows `summoning` then transitions to `active`.

**Coder agent:**

Repeat the same flow with:
- **Key:** `coder`
- **Display name:** Code Specialist
- **Type:** Predefined
- **Description:** "Senior software engineer. Writes clean, production-ready code. Explains implementation decisions. Prefers simple solutions. Tests edge cases."

Wait for both agents to reach `active` status before proceeding.

<details>
<summary><strong>Via API</strong></summary>

```bash
# Researcher
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "researcher",
    "display_name": "Research Specialist",
    "agent_type": "predefined",
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929",
    "other_config": {
      "description": "Deep research specialist. Searches the web, reads pages, synthesizes findings into concise reports with sources. Factual, thorough, cites everything."
    }
  }'

# Coder
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "coder",
    "display_name": "Code Specialist",
    "agent_type": "predefined",
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929",
    "other_config": {
      "description": "Senior software engineer. Writes clean, production-ready code. Explains implementation decisions. Prefers simple solutions. Tests edge cases."
    }
  }'
```

Poll agent status until `summoning` → `active`:

```bash
curl http://localhost:18790/v1/agents/researcher \
  -H "Authorization: Bearer YOUR_TOKEN"
```

</details>

## Step 2: Create the lead agent

The lead is an **open** agent — each user gets their own context, making it feel like a personal assistant that happens to have a team behind it.

In the dashboard, go to **Agents → Create Agent**:
- **Key:** `lead`
- **Display name:** Assistant
- **Type:** Open
- **Provider / Model:** Choose your preferred provider and model

Click **Save**.

<details>
<summary><strong>Via API</strong></summary>

```bash
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "lead",
    "display_name": "Assistant",
    "agent_type": "open",
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929"
  }'
```

</details>

## Step 3: Create the team

Go to **Teams → Create Team** in the dashboard:
- **Name:** Assistant Team
- **Description:** Personal assistant team with research and coding capabilities
- **Lead:** Select `lead`
- **Members:** Add `researcher` and `coder`

Click **Save**. Creating a team automatically sets up delegation links from the lead to each member. The lead agent's context now includes a `TEAM.md` file listing available specialists and how to delegate to them.

<details>
<summary><strong>Via API</strong></summary>

Team management uses WebSocket RPC. Connect to `ws://localhost:18790/ws` and send:

```json
{
  "type": "req",
  "id": "1",
  "method": "teams.create",
  "params": {
    "name": "Assistant Team",
    "lead": "lead",
    "members": ["researcher", "coder"],
    "description": "Personal assistant team with research and coding capabilities"
  }
}
```

</details>

## Step 4: Connect a channel

Go to **Channels → Create Instance** in the dashboard:
- **Channel type:** Telegram (or Discord, Slack, etc.)
- **Name:** `team-telegram`
- **Agent:** Select `lead`
- **Credentials:** Paste your bot token
- **Config:** Set DM policy and other channel-specific options

Click **Save**. The channel is immediately active — no gateway restart needed.

> **Important:** Only bind the lead agent to the channel. Specialists should not have their own channel bindings — they receive work exclusively through delegation.

<details>
<summary><strong>Via config.json</strong></summary>

Alternatively, add a binding to `config.json` and restart the gateway:

```json
{
  "bindings": [
    {
      "agentId": "lead",
      "match": {
        "channel": "telegram"
      }
    }
  ]
}
```

```bash
./goclaw
```

</details>

## Step 5: Test delegation

Send your bot a message that requires both research and code:

> "What are the key differences between Rust's async model and Go's goroutines? Then write me a simple HTTP server in each."

The lead will:
1. Delegate the research question to `researcher`
2. Delegate the code request to `coder`
3. Run both in parallel (up to `maxConcurrent` limit, default 3 per link)
4. Synthesize and reply with both results

## Step 6: Monitor with the Task Board

Open **Teams → Assistant Team → Task Board** in the dashboard. The Kanban board shows delegation tasks in real time:

- **Columns:** To-Do, In-Progress, Done — tasks move automatically as specialists work
- **Real-time updates:** The board refreshes via delta updates, no manual reload needed
- **Task details:** Click any task to see the assigned agent, status, and output
- **Bulk operations:** Select multiple tasks with checkboxes for bulk delete or status changes

The Task Board is the best way to verify that delegation is working correctly and to debug issues when specialists don't respond as expected.

## Workspace scope

Each team has a workspace for files produced during task execution. The scope is configurable:

| Mode | Behavior | Best for |
|------|----------|----------|
| **Isolated** (default) | Each conversation gets its own folder (`teams/{teamID}/{chatID}/`) | Privacy between users, independent tasks |
| **Shared** | All members access one folder (`teams/{teamID}/`) | Collaborative tasks where agents build on each other's output |

Configure via team settings — in the dashboard, go to **Teams → your team → Settings** and set **Workspace Scope** to `shared` or `isolated`.

**Limits:** Max 10 MB per file, 100 files per scope.

## Progress notifications

Teams support automatic progress notifications with two modes:

| Mode | Behavior |
|------|----------|
| **Direct** | Progress updates sent directly to the chat channel — the user sees real-time status |
| **Leader** | Progress updates injected into the lead agent's session — the lead decides what to surface |

Enable in team settings: set **Progress Notifications** to on, then choose the **Escalation Mode**.

## How delegation works

```mermaid
flowchart TD
    USER["User message"] --> LEAD["Lead agent"]
    LEAD -->|"delegate to researcher"| RESEARCHER["Researcher specialist"]
    LEAD -->|"delegate to coder"| CODER["Coder specialist"]
    RESEARCHER -->|result| LEAD
    CODER -->|result| LEAD
    LEAD -->|"synthesized reply"| USER
```

The lead delegates via the `delegate` tool. Specialists run as sub-sessions and return their output. The lead sees all results and composes the final response.

## Common Issues

| Problem | Solution |
|---------|----------|
| "cannot delegate to open agents" | Specialists must be `agent_type: "predefined"`. Re-create them with the correct type. |
| Lead doesn't delegate | The lead needs to know about its team. Check that `TEAM.md` appears in the lead's context files (Dashboard → Agent → Files tab). Restart the gateway if missing. |
| Specialist summoning stuck | Check gateway logs for LLM errors. Summoning uses the configured provider — ensure it has a valid API key. |
| Users see specialist responses directly | Only the lead should be bound to the channel. Check Dashboard → Channels to verify specialists have no channel bindings. |
| Tasks not appearing on board | Ensure you're viewing the correct team. Delegation tasks appear automatically — if missing, check that the team was created correctly with all members. |

## What's Next

- [What Are Teams?](/teams-what-are-teams) — team concepts and architecture
- [Task Board](/teams-task-board) — full task board reference
- [Open vs. Predefined](/open-vs-predefined) — why specialists must be predefined
- [Customer Support](/recipe-customer-support) — predefined agent handling many users



---

# Customer Support

> A predefined agent that handles customer queries consistently across all users, with specialist escalation.

## Overview

This recipe sets up a customer support agent with a fixed personality (same for every user), per-user profiles, and a specialist escalation path. Unlike the personal assistant recipe, this agent is **predefined** — its SOUL.md and IDENTITY.md are shared across all users, ensuring consistent brand voice.

**What you need:**
- A working gateway (`./goclaw onboard`)
- Web dashboard access at `http://localhost:18790`
- At least one LLM provider configured

## Step 1: Create the support agent

Open the web dashboard and go to **Agents → Create Agent**:

- **Key:** `support`
- **Display name:** Support Assistant
- **Type:** Predefined
- **Provider / Model:** Choose your preferred provider and model
- **Description:** "Friendly customer support agent for Acme Corp. Patient, empathetic, solution-focused. Answers questions about our product, helps with account issues, and escalates complex technical problems to the engineering team. Always confirms resolution before closing. Responds in the user's language."

Click **Save**. The `description` field triggers **summoning** — the gateway uses the LLM to auto-generate SOUL.md and IDENTITY.md from your description.

Wait for the agent status to transition from `summoning` → `active`. You can watch this on the Agents list page.

<details>
<summary><strong>Via API</strong></summary>

```bash
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "support",
    "display_name": "Support Assistant",
    "agent_type": "predefined",
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929",
    "other_config": {
      "description": "Friendly customer support agent for Acme Corp. Patient, empathetic, solution-focused. Answers questions about our product, helps with account issues, and escalates complex technical problems to the engineering team. Always confirms resolution before closing. Responds in the user'\''s language."
    }
  }'
```

Poll status:

```bash
curl http://localhost:18790/v1/agents/support \
  -H "Authorization: Bearer YOUR_TOKEN"
```

</details>

## Step 2: Write a manual SOUL.md (optional)

If you prefer to write the personality yourself instead of relying on summoning, go to **Dashboard → Agents → support → Files tab → SOUL.md** and edit inline:

```markdown
# Support Agent — SOUL.md

You are the support face of Acme Corp. Your core traits:

- **Patient**: Never rush a user. Repeat yourself if needed without frustration.
- **Empathetic**: Acknowledge problems before solving them. "That sounds frustrating — let me fix it."
- **Precise**: Give exact steps, not vague advice. If unsure, say so and escalate.
- **On-brand**: Friendly but professional. No slang. No emojis in formal replies.

You always confirm: "Does that solve the issue for you?" before ending.
```

Click **Save** when done.

<details>
<summary><strong>Via API</strong></summary>

```bash
curl -X PUT http://localhost:18790/v1/agents/support/files/SOUL.md \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @- <<'EOF'
# Support Agent — SOUL.md

You are the support face of Acme Corp. Your core traits:

- **Patient**: Never rush a user. Repeat yourself if needed without frustration.
- **Empathetic**: Acknowledge problems before solving them. "That sounds frustrating — let me fix it."
- **Precise**: Give exact steps, not vague advice. If unsure, say so and escalate.
- **On-brand**: Friendly but professional. No slang. No emojis in formal replies.

You always confirm: "Does that solve the issue for you?" before ending.
EOF
```

</details>

## Step 3: Add a technical escalation specialist

Create a second predefined agent for complex issues. Go to **Agents → Create Agent**:

- **Key:** `tech-specialist`
- **Display name:** Technical Specialist
- **Type:** Predefined
- **Description:** "Senior technical support specialist. Handles complex API issues, integration problems, and bug reports. Methodical, detail-oriented, documents every issue with reproduction steps."

Click **Save** and wait for summoning to complete.

Then set up the escalation link: go to **Agents → support → Links tab → Add Link**:
- **Target agent:** `tech-specialist`
- **Direction:** Outbound
- **Description:** Escalate complex technical issues
- **Max concurrent:** 3

Click **Save**. The support agent can now delegate complex issues to the specialist.

<details>
<summary><strong>Via API</strong></summary>

```bash
# Create specialist
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "tech-specialist",
    "display_name": "Technical Specialist",
    "agent_type": "predefined",
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929",
    "other_config": {
      "description": "Senior technical support specialist. Handles complex API issues, integration problems, and bug reports. Methodical, detail-oriented, documents every issue with reproduction steps."
    }
  }'

# Create delegation link
curl -X POST http://localhost:18790/v1/agents/support/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAgent": "support",
    "targetAgent": "tech-specialist",
    "direction": "outbound",
    "description": "Escalate complex technical issues",
    "maxConcurrent": 3
  }'
```

</details>

## Step 4: Configure per-user profiles

Because `support` is predefined, each user gets their own `USER.md` seeded on first chat. You can pre-populate profiles to give the agent context about who the user is.

Go to **Agents → support → Instances tab → select a user → Files → USER.md** and edit:

```markdown
# User Profile: Alice

- **Plan**: Enterprise (annual)
- **Company**: Acme Widgets Ltd
- **Joined**: 2023-08
- **Known issues**: Reported API rate limit problems in Nov 2024
- **Preferences**: Prefers technical explanations, not simplified answers
```

<details>
<summary><strong>Via API</strong></summary>

```bash
curl -X PUT http://localhost:18790/v1/agents/support/users/alice123/files/USER.md \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @- <<'EOF'
# User Profile: Alice

- **Plan**: Enterprise (annual)
- **Company**: Acme Widgets Ltd
- **Joined**: 2023-08
- **Known issues**: Reported API rate limit problems in Nov 2024
- **Preferences**: Prefers technical explanations, not simplified answers
EOF
```

</details>

## Step 5: Restrict tools for support context

Support agents rarely need file system or shell access. Go to **Agents → support → Config tab** and configure tool permissions:

- **Allowed tools:** `web_fetch`, `web_search`, `memory_search`, `memory_save`, `delegate`
- Deny everything else

This limits the attack surface while keeping the agent functional for support tasks.

<details>
<summary><strong>Via config.json</strong></summary>

```json
{
  "agents": {
    "list": {
      "support": {
        "tools": {
          "allow": ["web_fetch", "web_search", "memory_search", "memory_save", "delegate"]
        }
      }
    }
  }
}
```

Restart the gateway after config changes.

</details>

## Step 6: Connect a channel

Go to **Channels → Create Instance** in the dashboard:
- **Channel type:** Telegram (or Discord, Slack, Zalo OA, etc.)
- **Agent:** Select `support`
- **Credentials:** Paste your bot token
- **Config:** Set `dm_policy` to `open` so any customer can message the bot

Click **Save**. The channel is immediately active.

> **Tip:** For customer-facing bots, set `dm_policy: "open"` so users don't need to pair via browser first.

## File attachments

When the support agent uses `write_file` to generate a document (e.g., a troubleshooting report or account summary), the file is automatically delivered as a channel attachment to the user. No extra configuration needed — this works across all channel types.

## How context isolation works

```
support (predefined)
├── SOUL.md         ← shared: same personality for all users
├── IDENTITY.md     ← shared: same "who I am" for all users
├── AGENTS.md       ← shared: operating instructions
│
├── User: alice123
│   ├── USER.md     ← per-user: Alice's profile, tier, history
│   └── BOOTSTRAP.md ← first-run onboarding (clears itself)
│
└── User: bob456
    ├── USER.md     ← per-user: Bob's profile
    └── BOOTSTRAP.md
```

## Common Issues

| Problem | Solution |
|---------|----------|
| Agent personality differs between users | If the agent is `open`, each user shapes their own personality. Switch to `predefined` for shared SOUL.md. |
| USER.md not being seeded | First chat triggers seeding. If pre-populating via Instances tab, ensure you select the correct user. |
| Summoning failed, no SOUL.md | Check gateway logs for LLM errors during summoning. Manually write SOUL.md via the Files tab as shown in Step 2. |
| Support agent escalates too aggressively | Edit SOUL.md to add criteria: "Only delegate to tech-specialist when the user reports an API error code or integration failure." |
| Specialist not responding | Check the specialist's status is `active` and the delegation link exists (Agent → Links tab). |

## What's Next

- [Open vs. Predefined](/open-vs-predefined) — deep dive on context isolation
- [Summoning & Bootstrap](/summoning-bootstrap) — how personality is auto-generated
- [Team Chatbot](/recipe-team-chatbot) — coordinate multiple specialists via a team
- [Context Files](../agents/context-files.md) — full reference for SOUL.md, USER.md, and friends



---

# Code Review Agent

> An agent that reviews code using a Docker sandbox for safe execution and custom shell tools.

## Overview

This recipe creates a code review agent that can read files, run linters/tests inside a Docker sandbox, and use custom tools you define. The sandbox isolates all code execution from the host — no risk of malicious code affecting your system.

**Prerequisites:** A working gateway, Docker installed and running on the gateway host.

## Step 1: Build the sandbox image

GoClaw's sandbox uses a Docker container. Build the default image or use any existing one:

```bash
# Use the default image name expected by GoClaw
docker build -t goclaw-sandbox:bookworm-slim - <<'EOF'
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y \
    git curl wget jq \
    python3 python3-pip nodejs npm \
    && rm -rf /var/lib/apt/lists/*
# Add your language runtimes and linters here
RUN npm install -g eslint typescript
RUN pip3 install ruff pyflakes --break-system-packages
EOF
```

## Step 2: Create the code review agent

You can create the agent via **Dashboard → Agents → Create Agent** (key: `code-reviewer`, type: Predefined, paste the description below), or via the API:

```bash
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "code-reviewer",
    "display_name": "Code Reviewer",
    "agent_type": "predefined",
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4-5-20250929",
    "other_config": {
      "description": "Expert code reviewer. Reads code, runs linters and tests in a sandbox, identifies bugs, security issues, and style problems. Gives actionable, prioritized feedback. Explains the why behind each suggestion."
    }
  }'
```

## Step 3: Enable the sandbox

Add sandbox config to `config.json` under the agent's entry:

```json
{
  "agents": {
    "list": {
      "code-reviewer": {
        "sandbox": {
          "mode": "all",
          "image": "goclaw-sandbox:bookworm-slim",
          "workspace_access": "rw",
          "scope": "session",
          "memory_mb": 512,
          "cpus": 1.0,
          "timeout_sec": 120,
          "network_enabled": false,
          "read_only_root": true
        }
      }
    }
  }
}
```

**Sandbox mode options:**
- `"off"` — no sandbox, exec runs on host (default)
- `"non-main"` — sandbox only for subagent/delegated runs
- `"all"` — all exec and file operations go through Docker

`network_enabled: false` prevents code from making outbound connections. `read_only_root: true` means only the mounted workspace is writable.

Restart the gateway after updating config.

## Step 4: Create a custom linting tool

Custom tools run shell commands with `{{.param}}` template substitution. All values are shell-escaped automatically.

```bash
curl -X POST http://localhost:18790/v1/tools/custom \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "run_linter",
    "description": "Run a linter on a file and return the output. Supports Python (ruff), JavaScript/TypeScript (eslint), and Go (go vet).",
    "command": "case {{.language}} in python) ruff check {{.file}} ;; js|ts) eslint {{.file}} ;; go) go vet {{.file}} ;; *) echo \"Unsupported language: {{.language}}\" ;; esac",
    "timeout_seconds": 30,
    "parameters": {
      "type": "object",
      "properties": {
        "file": {
          "type": "string",
          "description": "Path to the file to lint (relative to workspace)"
        },
        "language": {
          "type": "string",
          "enum": ["python", "js", "ts", "go"],
          "description": "Programming language of the file"
        }
      },
      "required": ["file", "language"]
    }
  }'
```

The tool runs inside the sandbox when `sandbox.mode` is `"all"`. The `{{.file}}` and `{{.language}}` placeholders are replaced with shell-escaped values from the LLM's tool call.

## Step 5: Add a test runner tool

```bash
curl -X POST http://localhost:18790/v1/tools/custom \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "run_tests",
    "description": "Run tests for a project directory and return results.",
    "command": "cd {{.dir}} && case {{.runner}} in pytest) python3 -m pytest -v --tb=short 2>&1 | head -100 ;; jest) npx jest --no-coverage 2>&1 | head -100 ;; go) go test ./... 2>&1 | head -100 ;; *) echo \"Unknown runner: {{.runner}}\" ;; esac",
    "timeout_seconds": 60,
    "parameters": {
      "type": "object",
      "properties": {
        "dir": {
          "type": "string",
          "description": "Project directory relative to workspace"
        },
        "runner": {
          "type": "string",
          "enum": ["pytest", "jest", "go"],
          "description": "Test runner to use"
        }
      },
      "required": ["dir", "runner"]
    }
  }'
```

## Step 6: Write the agent's SOUL.md

Give the reviewer a clear review methodology. Go to **Dashboard → Agents → code-reviewer → Files tab → SOUL.md** and paste:

```markdown
# Code Reviewer SOUL

You are a thorough, pragmatic code reviewer. Your process:

1. **Read first** — understand what the code is trying to do before judging it
2. **Run tools** — lint the files, run tests if available
3. **Prioritize** — label findings as Critical / Major / Minor / Nitpick
4. **Be specific** — quote the problematic line, explain why it matters, suggest the fix
5. **Be kind** — acknowledge good decisions, not just problems

Never block on style alone. Focus on correctness, security, and maintainability.
```

<details>
<summary><strong>Via API</strong></summary>

```bash
curl -X PUT http://localhost:18790/v1/agents/code-reviewer/files/SOUL.md \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @- <<'EOF'
# Code Reviewer SOUL

You are a thorough, pragmatic code reviewer. Your process:

1. **Read first** — understand what the code is trying to do before judging it
2. **Run tools** — lint the files, run tests if available
3. **Prioritize** — label findings as Critical / Major / Minor / Nitpick
4. **Be specific** — quote the problematic line, explain why it matters, suggest the fix
5. **Be kind** — acknowledge good decisions, not just problems

Never block on style alone. Focus on correctness, security, and maintainability.
EOF
```

</details>

## Step 7: Test the agent

Drop a file into the agent's workspace and ask for a review. You can chat via **Dashboard → Agents → code-reviewer** and use the chat interface, or via the API:

```bash
# Write a test file to the workspace
curl -X PUT http://localhost:18790/v1/agents/code-reviewer/files/workspace/review_me.py \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary 'import os; password = "hardcoded_secret"; print(os.system(f"echo {password}"))'

# Chat with the agent
curl -X POST http://localhost:18790/v1/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GoClaw-User-Id: admin" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-reviewer",
    "message": "Please review the file review_me.py in the workspace. Run the linter and report all issues."
  }'
```

## How the sandbox works

```mermaid
flowchart LR
    AGENT["Agent decides\nto run linter"] --> TOOL["run_linter tool\ncalled by LLM"]
    TOOL --> SANDBOX["Docker container\ngoclaw-sandbox:bookworm-slim"]
    SANDBOX --> CMD["sh -c 'ruff check file.py'"]
    CMD --> OUTPUT["Stdout/stderr\ncaptured"]
    OUTPUT --> AGENT
```

All `exec`, `read_file`, `write_file`, and `list_files` calls go through the container when `mode: "all"`. The workspace directory is bind-mounted at the configured `workspace_access` level.

## Alternative: ACP provider for external agents

If your code review workflow uses an external coding agent (Claude Code, Codex, Gemini CLI), you can configure an [ACP (Agent Client Protocol)](/provider-acp) provider instead of OpenRouter. ACP connects to external agents via JSON-RPC 2.0, letting them serve as the LLM backend for your code-reviewer agent.

## MCP tool performance

If your code-reviewer uses many MCP tools, GoClaw lazily activates deferred tools — they load on first call rather than at startup. This reduces initial overhead for agents with large MCP server configurations.

## Common Issues

| Problem | Solution |
|---------|----------|
| "sandbox: docker not found" | Ensure Docker is installed and the `docker` binary is on `PATH` for the gateway process. |
| Container starts but linter missing | Add your tools to the Docker image. Rebuild and restart the gateway. |
| Exec timeout | Increase `timeout_sec` in sandbox config. Default is 300s but complex test suites may need more. |
| Files not visible inside sandbox | Workspace is mounted at `workspace_access: "rw"`. Ensure files are written to the agent's workspace path. |
| Custom tool name collides | Tool names must be unique. Use `GET /v1/tools/builtin` to see reserved names. |

## What's Next

- [Multi-Channel Setup](/recipe-multi-channel) — expose this agent on Telegram and WebSocket
- [Team Chatbot](/recipe-team-chatbot) — add the reviewer as a specialist in a team
- [Tools Reference](/cli-commands) — full built-in tool list and policy options



---

# Multi-Channel Setup

> Put the same agent on Telegram, Discord, and WebSocket simultaneously.

## Overview

GoClaw runs multiple channels from one gateway process. A single agent can receive messages from Telegram, Discord, and direct WebSocket clients at the same time — each channel has its own session scope, so conversations stay isolated per channel and user.

**What you need:**
- A working gateway with at least one agent created
- Web dashboard access at `http://localhost:18790`
- Bot tokens for each messaging platform

## Step 1: Gather your tokens

You need a bot token for each messaging platform:

**Telegram:** Message [@BotFather](https://t.me/BotFather) → `/newbot` → copy token
**Discord:** [discord.com/developers](https://discord.com/developers/applications) → New Application → Bot → Add Bot → copy token. Enable **Message Content Intent** under Privileged Gateway Intents.

WebSocket needs no external token — clients authenticate with your gateway token.

## Step 2: Create channel instances

Open the web dashboard and go to **Channels → Create Instance**. Create one instance per platform:

**Telegram:**
- **Channel type:** Telegram
- **Name:** `main-telegram`
- **Agent:** Select your agent
- **Credentials:** Paste the bot token from @BotFather
- **Config:** Set `dm_policy` to `pairing` (recommended) or `open`

Click **Save**.

**Discord:**
- **Channel type:** Discord
- **Name:** `main-discord`
- **Agent:** Select the same agent
- **Credentials:** Paste the Discord bot token
- **Config:** Set `dm_policy` to `open`, `require_mention` to `true`

Click **Save**.

Both channels are immediately active — no gateway restart needed. WebSocket is built into the gateway and needs no instance creation.

On startup you should see log lines like:
```
channel=telegram status=connected bot=@YourBotName
channel=discord  status=connected guild_count=2
gateway          status=listening addr=0.0.0.0:18790
```

<details>
<summary><strong>Via config.json</strong></summary>

Add all channel configs to `config.json`. Secrets (tokens) go in `.env.local` — not in the config file.

`config.json`:
```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "",
      "dm_policy": "pairing",
      "group_policy": "open",
      "require_mention": true,
      "reaction_level": "minimal"
    },
    "discord": {
      "enabled": true,
      "token": "",
      "dm_policy": "open",
      "group_policy": "open",
      "require_mention": true,
      "history_limit": 50
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790,
    "token": ""
  }
}
```

`.env.local` (secrets only — never commit this file):
```bash
export GOCLAW_TELEGRAM_TOKEN="123456:ABCDEFGHIJKLMNOPQRSTUVWxyz"
export GOCLAW_DISCORD_TOKEN="your-discord-bot-token"
export GOCLAW_GATEWAY_TOKEN="your-gateway-token"
export GOCLAW_POSTGRES_DSN="postgres://user:pass@localhost:5432/goclaw"
```

GoClaw reads channel tokens from environment variables when the `token` field in config is empty.

Add bindings to route messages to your agent:

```json
{
  "bindings": [
    {
      "agentId": "my-assistant",
      "match": { "channel": "telegram" }
    },
    {
      "agentId": "my-assistant",
      "match": { "channel": "discord" }
    }
  ]
}
```

Start the gateway:

```bash
source .env.local && ./goclaw
```

</details>

## Step 3: Connect a WebSocket client

WebSocket is built into the gateway — no extra setup needed. Connect and authenticate:

```javascript
const ws = new WebSocket('ws://localhost:18790/ws');

// First frame must be connect
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'req',
    id: '1',
    method: 'connect',
    params: {
      token: 'your-gateway-token',
      user_id: 'web-user-alice'
    }
  }));
};

// Send a chat message
function chat(message) {
  ws.send(JSON.stringify({
    type: 'req',
    id: String(Date.now()),
    method: 'chat',
    params: {
      agent: 'my-assistant',
      message: message
    }
  }));
}

// Listen for responses and streaming chunks
ws.onmessage = (e) => {
  const frame = JSON.parse(e.data);
  if (frame.type === 'event' && frame.event === 'chunk') {
    process.stdout.write(frame.payload.text);
  }
  if (frame.type === 'res' && frame.method === 'chat') {
    console.log('\n[done]');
  }
};
```

See [WebSocket Channel](/channel-websocket) for the full protocol reference.

## Step 4: Verify cross-channel isolation

Sessions are isolated by channel and user by default (`dm_scope: "per-channel-peer"`). This means:
- Alice on Telegram and Alice on Discord have **separate** conversation histories
- The agent treats them as different users

Verify isolation in the dashboard: go to **Sessions** and filter by agent — you should see separate sessions for each channel.

If you want a single session across channels for the same user, set `dm_scope: "per-peer"` in `config.json`:

```json
{
  "sessions": {
    "dm_scope": "per-peer"
  }
}
```

This shares conversation history when the same `user_id` connects from any channel.

## Telegram message handling

Telegram has a 4096-character message limit. GoClaw handles long responses automatically:

- Long messages are split into multiple parts at natural boundaries (paragraphs, code blocks)
- HTML formatting is attempted first for rich output
- If HTML parsing fails, the message falls back to plain text
- No configuration needed — this is fully automatic

## Channel comparison

| Feature | Telegram | Discord | WebSocket |
|---------|----------|---------|-----------|
| Setup | @BotFather token | Developer Portal token | None (use gateway token) |
| DM policy default | `pairing` | `open` | Auth via gateway token |
| Group/server support | Yes | Yes | N/A |
| Streaming | Optional (`dm_stream`) | Via message edits | Native (chunk events) |
| Mention required in groups | Yes (default) | Yes (default) | N/A |
| Custom client | No | No | Yes |

## Restrict tools per channel

You can allow different tool sets per channel. Go to **Agents → your agent → Config tab** and configure per-channel tool policies.

<details>
<summary><strong>Via config.json</strong></summary>

```json
{
  "agents": {
    "list": {
      "my-assistant": {
        "tools": {
          "byProvider": {
            "telegram": { "deny": ["exec", "write_file"] },
            "discord":  { "deny": ["exec", "write_file"] }
          }
        }
      }
    }
  }
}
```

</details>

WebSocket clients (usually developers or internal tools) can keep full tool access.

## File attachments

When the agent uses `write_file` to generate a file, it is automatically delivered as a channel attachment. This works across Telegram, Discord, and other supported channels — no extra configuration needed.

## Common Issues

| Problem | Solution |
|---------|----------|
| Telegram bot not responding | Check `dm_policy`. Default is `"pairing"` — complete browser pairing first, or set `"open"` for testing. |
| Discord bot offline in server | Verify the bot has been added to the server via OAuth2 URL Generator with `bot` scope and `Send Messages` permission. |
| WebSocket connect rejected | Ensure `token` in your connect frame matches `GOCLAW_GATEWAY_TOKEN`. Empty token gives viewer-only role. |
| Messages routing to wrong agent | Check channel instance agent assignment in Dashboard → Channels. First matching binding wins when using config.json. |
| Same user gets different sessions on Telegram vs Discord | Expected with default `dm_scope: "per-channel-peer"`. Set `"per-peer"` to share sessions across channels. |

## What's Next

- [Telegram Channel](/channel-telegram) — full Telegram config reference including groups, topics, and STT
- [Discord Channel](/channel-discord) — Discord gateway intents and streaming setup
- [WebSocket Channel](/channel-websocket) — full RPC protocol reference
- [Personal Assistant](/recipe-personal-assistant) — single-channel starting point



---

# Gallery

> Real-world examples and deployment scenarios for GoClaw.

## Overview

This page showcases how GoClaw can be deployed in different scenarios — from a personal Telegram bot to a multi-tenant team platform. Use these as starting points for your own setup.

## Deployment Scenarios

### Personal AI Assistant

A single agent on Telegram for personal use.

```jsonc
{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "agent_type": "open",
      "memory": { "enabled": true }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "" // from @BotFather
    }
  }
}
```

**What you get:** A personal assistant that remembers your preferences, searches the web, runs code, and manages files — all through Telegram.

### Team Coding Bot

A predefined agent shared across a development team on Discord.

```jsonc
{
  "agents": {
    "list": {
      "code-bot": {
        "agent_type": "predefined",
        "provider": "anthropic",
        "model": "claude-opus-4-6",
        "tools": { "profile": "coding" },
        "temperature": 0.3,
        "max_tool_iterations": 50
      }
    }
  },
  "channels": {
    "discord": {
      "enabled": true,
      "token": "" // from Discord Developer Portal
    }
  }
}
```

**What you get:** A shared coding assistant with consistent personality (predefined), low temperature for precise code, and extended tool iterations for complex tasks. Each team member gets personal context via USER.md.

### Multi-Channel Support Bot

One agent available on Telegram, Discord, and WebSocket simultaneously.

```jsonc
{
  "agents": {
    "list": {
      "support-bot": {
        "agent_type": "predefined",
        "tools": { "profile": "messaging" }
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "" // Telegram bot token
    },
    "discord": {
      "enabled": true,
      "token": "" // Discord bot token
    }
  }
}
```

**What you get:** Consistent support experience across channels. Users on Telegram and Discord talk to the same agent with the same knowledge base.

### Agent Team with Delegation

A lead agent that delegates specialized tasks to other agents.

```jsonc
{
  "agents": {
    "list": {
      "lead": {
        "provider": "anthropic",
        "model": "claude-opus-4-6"
      },
      "researcher": {
        "provider": "openrouter",
        "model": "google/gemini-2.5-pro",
        "tools": { "profile": "coding" }
      },
      "writer": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-5-20250929",
        "tools": { "profile": "messaging" }
      }
    }
  }
}
```

**What you get:** The lead agent coordinates work, delegating research to a Gemini-powered agent and writing tasks to a Claude-powered agent. Each uses the best model for its role.

## Community

Have a GoClaw deployment you'd like to showcase? Open a pull request to add it here.

## What's Next

- [What Is GoClaw](/what-is-goclaw) — Start from the beginning
- [Quick Start](/quick-start) — Get running in 5 minutes
- [Configuration](/configuration) — Full config reference



---

# CLI Commands

> Complete reference for every `goclaw` command, subcommand, and flag.

## Overview

The `goclaw` binary is a single executable that starts the gateway and provides management subcommands. Global flags apply to all commands.

```bash
goclaw [global flags] <command> [subcommand] [flags] [args]
```

**Global flags**

| Flag | Default | Description |
|------|---------|-------------|
| `--config <path>` | `config.json` | Config file path. Also read from `$GOCLAW_CONFIG` |
| `-v`, `--verbose` | false | Enable debug logging |
| `--server <url>` | — | Gateway server URL override for HTTP-backed commands (traces, skills, etc.). Falls back to `$GOCLAW_SERVER`, then `$GOCLAW_GATEWAY_URL` |
| `--token <token>` | — | Gateway bearer token override. Falls back to `$GOCLAW_GATEWAY_TOKEN` |


## `version`

Print version and protocol number.

```bash
goclaw version
# goclaw v1.2.0 (protocol 3)
```

---

## `onboard`

Interactive setup wizard — configure provider, model, gateway port, channels, features, and database.

```bash
goclaw onboard
```

Steps:
1. AI provider + API key (OpenRouter, Anthropic, OpenAI, Groq, DeepSeek, Gemini, Mistral, xAI, MiniMax, Cohere, Perplexity, Claude CLI, Custom)
2. Gateway port (default: 18790)
3. Channels (Telegram, Zalo OA, Feishu/Lark)
4. Features (memory, browser automation)
5. TTS provider
6. PostgreSQL DSN

Saves `config.json` (no secrets) and `.env.local` (secrets only).

**Environment-based auto-onboard** — if the required env vars are set, the wizard is skipped and setup runs non-interactively (useful for Docker/CI).

A TUI-based onboard is available when the terminal supports it (`tui_onboard.go`). Falls back to plain interactive mode automatically.

---

## `agent`

Manage agents — add, list, delete, and chat.

### `agent list`

List all configured agents.

```bash
goclaw agent list
goclaw agent list --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

### `agent add`

Interactive wizard to add a new agent.

```bash
goclaw agent add
```

Prompts: agent name, display name, provider (or inherit), model (or inherit), workspace directory. Saves to `config.json`. Restart gateway to activate.

### `agent delete`

Delete an agent from config.

```bash
goclaw agent delete <agent-id>
goclaw agent delete researcher --force
```

| Flag | Description |
|------|-------------|
| `--force` | Skip confirmation prompt |

Also removes bindings referencing the deleted agent.

### `agent chat`

Send a one-shot message to an agent via the running gateway.

```bash
goclaw agent chat "What files are in the workspace?"
goclaw agent chat --agent researcher "Summarize today's news"
goclaw agent chat --session my-session "Continue where we left off"
```

| Flag | Default | Description |
|------|---------|-------------|
| `--agent <id>` | `default` | Target agent ID |
| `--session <key>` | auto | Session key to resume |
| `--json` | false | Output response as JSON |

---

## `migrate`

Database migration management. All subcommands require `GOCLAW_POSTGRES_DSN`.

```bash
goclaw migrate [--migrations-dir <path>] <subcommand>
```

| Flag | Description |
|------|-------------|
| `--migrations-dir <path>` | Path to migrations directory (default: `./migrations`) |

### `migrate up`

Apply all pending migrations.

```bash
goclaw migrate up
```

After SQL migrations, runs pending Go-based data hooks.

### `migrate down`

Roll back migrations.

```bash
goclaw migrate down           # roll back 1 step
goclaw migrate down -n 3      # roll back 3 steps
```

| Flag | Default | Description |
|------|---------|-------------|
| `-n`, `--steps <n>` | 1 | Number of steps to roll back |

### `migrate version`

Show current migration version.

```bash
goclaw migrate version
# version: 10, dirty: false
```

### `migrate force <version>`

Force-set the migration version without applying SQL (use after manual fixes).

```bash
goclaw migrate force 9
```

### `migrate goto <version>`

Migrate to a specific version (up or down).

```bash
goclaw migrate goto 5
```

### `migrate drop`

**DANGEROUS.** Drop all tables.

```bash
goclaw migrate drop
```

---

## `upgrade`

Upgrade database schema and run data migrations. Idempotent — safe to run multiple times.

```bash
goclaw upgrade
goclaw upgrade --dry-run    # preview without applying
goclaw upgrade --status     # show current upgrade status
```

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would be done without applying |
| `--status` | Show current schema version and pending hooks |

Gateway startup also checks schema compatibility. Set `GOCLAW_AUTO_UPGRADE=true` to auto-upgrade on startup.

---

## `backup`

Back up the GoClaw database and config to an archive file.

```bash
goclaw backup
goclaw backup --output /path/to/backup.tar.gz
```

| Flag | Description |
|------|-------------|
| `--output <path>` | Output archive path (default: timestamped file in current dir) |

---

## `restore`

Restore from a backup archive.

```bash
goclaw restore /path/to/backup.tar.gz
```

---

## `tenant_backup`

Back up a single tenant's data.

```bash
goclaw tenant_backup --tenant <tenant-id>
goclaw tenant_backup --tenant <tenant-id> --output /path/to/backup.tar.gz
```

---

## `tenant_restore`

Restore a single tenant from a backup archive.

```bash
goclaw tenant_restore --tenant <tenant-id> /path/to/backup.tar.gz
```

---

## `doctor`

Check system environment and configuration health.

```bash
goclaw doctor
```

Checks: binary version, config file, database connectivity, schema version, providers, channels, external binaries (docker, curl, git), workspace directory. Prints a pass/fail summary for each check.

Provider rows with an empty `display_name` now render the canonical `name` instead of a blank line.

---

## `pairing`

Manage device pairing — approve, list, and revoke paired devices.

### `pairing list`

List pending pairing requests and paired devices.

```bash
goclaw pairing list
```

### `pairing approve [code]`

Approve a pairing code. Interactive selection if no code given.

```bash
goclaw pairing approve              # interactive picker
goclaw pairing approve ABCD1234    # approve specific code
```

### `pairing revoke <channel> <senderId>`

Revoke a paired device.

```bash
goclaw pairing revoke telegram 123456789
```

---

## `sessions`

View and manage chat sessions. Requires gateway to be running.

### `sessions list`

List all sessions.

```bash
goclaw sessions list
goclaw sessions list --agent researcher
goclaw sessions list --json
```

| Flag | Description |
|------|-------------|
| `--agent <id>` | Filter by agent ID |
| `--json` | Output as JSON |

### `sessions delete <key>`

Delete a session.

```bash
goclaw sessions delete "telegram:123456789"
```

### `sessions reset <key>`

Clear session history while keeping the session record.

```bash
goclaw sessions reset "telegram:123456789"
```

---

## `traces`

Inspect agent execution traces and run timelines through the running gateway. All `traces` subcommands are HTTP-backed — they connect to the gateway resolved from `--server` / `$GOCLAW_SERVER` / `$GOCLAW_GATEWAY_URL` and authenticate with `--token` / `$GOCLAW_GATEWAY_TOKEN`.

| Persistent flag | Default | Description |
|------|---------|-------------|
| `-o`, `--output <table\|json>` | `table` | Output format |

```bash
goclaw traces list --status error --limit 20
goclaw traces get <trace-id> -o json
goclaw traces export <trace-id> --file trace.json.gz
goclaw traces follow --session <session-key> --since 2026-06-12T01:00:00Z
goclaw traces timeline <trace-id>
# remote gateway:
goclaw --server https://goclaw.example.com --token "$GOCLAW_GATEWAY_TOKEN" traces get <trace-id> -o json
```

### `traces list`

List traces with filtering and full-text search.

```bash
goclaw traces list
goclaw traces list -q "payment" --has-tool-calls true --limit 50
```

| Flag | Description |
|------|-------------|
| `-q`, `--query <text>` | Search trace text, IDs, labels, and span previews |
| `--agent-id <uuid>` | Filter by agent UUID |
| `--user <id>` | Filter by user ID (admin callers) |
| `--session <key>` | Filter by session key |
| `--status <status>` | Filter by trace status (`running`, `completed`, `error`, `cancelled`) |
| `--channel <channel>` | Filter by raw channel |
| `--agent <text>` | Search agent display name or key |
| `--channel-query <text>` | Search channel instance labels |
| `--tool <name>` | Search span tool names |
| `--from <rfc3339>` | Start-time lower bound (inclusive) |
| `--to <rfc3339>` | Start-time upper bound (exclusive) |
| `--since <rfc3339>` | Alias for `--from` |
| `--until <rfc3339>` | Alias for `--to` |
| `--has-tool-calls <true\|false>` | Only traces with/without tool calls |
| `--min-input-tokens <n>` | Minimum input tokens |
| `--max-input-tokens <n>` | Maximum input tokens |
| `--min-output-tokens <n>` | Minimum output tokens |
| `--max-output-tokens <n>` | Maximum output tokens |
| `--min-tool-calls <n>` | Minimum tool-call count |
| `--max-tool-calls <n>` | Maximum tool-call count |
| `--limit <n>` | Page size (max 200) |
| `--offset <n>` | Pagination offset |

### `traces get <trace-id>`

Get trace details with spans. Takes exactly one trace ID.

```bash
goclaw traces get <trace-id>
goclaw traces get <trace-id> -o json
```

### `traces export <trace-id>`

Export a gzipped trace tree. Takes exactly one trace ID.

```bash
goclaw traces export <trace-id>                 # writes trace-<short>-<YYYYMMDD>.json.gz
goclaw traces export <trace-id> --file trace.json.gz
goclaw traces export <trace-id> --file -        # gzip to stdout
goclaw traces export <trace-id> -o json         # decompressed JSON to stdout
```

| Flag | Description |
|------|-------------|
| `--file <path>` | Write gzip export to file (use `-` for stdout). Default writes `trace-<short>-<YYYYMMDD>.json.gz` |

### `traces follow`

Poll trace changes for one session or agent. **Requires `--session` OR `--agent-id`.**

```bash
goclaw traces follow --session <session-key> --since 2026-06-12T01:00:00Z
goclaw traces follow --agent-id <uuid> --include-spans
```

| Flag | Description |
|------|-------------|
| `--session <key>` | Filter by session key |
| `--agent-id <uuid>` | Filter by agent UUID |
| `--user <id>` | Filter by user ID (admin callers) |
| `--status <status>` | Filter by trace status |
| `--channel <channel>` | Filter by raw channel |
| `--since <rfc3339>` | RFC3339 lower bound for changed traces |
| `--limit <n>` | Page size (max 200) |
| `--include-spans` | Include spans grouped by trace ID |

### `traces timeline <trace-id>`

Show the persisted run timeline linked to a trace. Resolves the trace's `run_id`, then queries the run archive. Takes exactly one trace ID.

```bash
goclaw traces timeline <trace-id>
goclaw traces timeline <trace-id> --limit 100 --offset 0
```

| Flag | Description |
|------|-------------|
| `--limit <n>` | Page size (max 500) |
| `--offset <n>` | Pagination offset |

---

## `cron`

Manage scheduled cron jobs. Requires gateway to be running.

### `cron list`

List cron jobs.

```bash
goclaw cron list
goclaw cron list --all      # include disabled jobs
goclaw cron list --json
```

| Flag | Description |
|------|-------------|
| `--all` | Include disabled jobs |
| `--json` | Output as JSON |

### `cron delete <jobId>`

Delete a cron job.

```bash
goclaw cron delete 3f5a8c2b
```

### `cron toggle <jobId> <true|false>`

Enable or disable a cron job.

```bash
goclaw cron toggle 3f5a8c2b true
goclaw cron toggle 3f5a8c2b false
```

---

## `config`

View and manage configuration.

### `config show`

Display current configuration with secrets redacted.

```bash
goclaw config show
```

### `config path`

Print the config file path being used.

```bash
goclaw config path
# /home/user/goclaw/config.json
```

### `config validate`

Validate the config file syntax and structure.

```bash
goclaw config validate
# Config at config.json is valid.
```

---

## `channels`

List and manage messaging channels.

### `channels list`

List configured channels and their status.

```bash
goclaw channels list
goclaw channels list --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

Output columns: `CHANNEL`, `ENABLED`, `CREDENTIALS` (ok/missing).

---

## `providers`

Manage LLM providers (requires running gateway).

### `providers list`

List configured providers.

```bash
goclaw providers list
goclaw providers list --json
goclaw providers list --models
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |
| `--models` | Also show available models per provider |

Shows provider name, type, enabled status, and whether an API key is configured.

### `providers add`

Add a new provider (interactive).

```bash
goclaw providers add
```

Interactive prompts for provider type, name, API key, and base URL. Offers to verify connectivity after creation.

### `providers update <id>`

Update a provider's name or API key.

```bash
goclaw providers update <id>
```

### `providers delete <id>`

Delete a provider.

```bash
goclaw providers delete <id>
goclaw providers delete <id> --force
```

| Flag | Description |
|------|-------------|
| `--force` | Skip confirmation prompt |

### `providers verify <id>`

Verify provider connectivity or a specific model.

```bash
goclaw providers verify <id>
goclaw providers verify <id> --model anthropic/claude-sonnet-4
```

| Flag | Description |
|------|-------------|
| `--model <alias>` | Model alias to verify (omit for connectivity ping) |

Without `--model`: pings the provider (registered + reachable check) — no LLM call is made.
With `--model`: sends a small chat request to validate the model alias.

---

## `skills`

List and inspect skills.

**Store directories** (searched in order):

1. `{workspace}/skills/` — agent-specific skills (workspace is per-agent, file-based)
2. `~/.goclaw/skills/` — global skills shared across all agents (file-based)
3. `~/.goclaw/skills-store/` — managed skills uploaded via API/dashboard (file content stored here, metadata in PostgreSQL)

### `skills list`

List all available skills.

```bash
goclaw skills list
goclaw skills list --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

### `skills show <name>`

Show content and metadata for a specific skill.

```bash
goclaw skills show sequential-thinking
```

> The subcommands below are HTTP-backed (require a running gateway). The `<skill>` argument accepts a skill ID, slug, or name — it is resolved against the gateway.

### `skills evolve`

Manage per-skill self-evolution settings.

```bash
goclaw skills evolve status <skill>
goclaw skills evolve enable <skill>
goclaw skills evolve disable <skill>
goclaw skills evolve mode <skill> suggest_only
goclaw skills evolve mode <skill> auto_analyze
```

| Command | Args | Effect |
|---------|------|--------|
| `skills evolve status <skill>` | 1 | Show self-evolution settings |
| `skills evolve enable <skill>` | 1 | Enable self-evolution |
| `skills evolve disable <skill>` | 1 | Disable self-evolution |
| `skills evolve mode <skill> <suggest_only\|auto_analyze>` | 2 | Set the evolution mode |

### `skills metrics <skill>`

Show recorded usage metrics for a skill (Total, Started, Succeeded, Failed, Abandoned, Success rate).

```bash
goclaw skills metrics <skill>
goclaw skills metrics <skill> --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

### `skills activity <skill>`

Show recent self-evolution activity for a skill (admin-gated detail).

```bash
goclaw skills activity <skill>
goclaw skills activity <skill> --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

### `skills suggestions`

Manage skill improvement suggestions.

```bash
goclaw skills suggestions list <skill>
goclaw skills suggestions approve <skill> <suggestion-id>
goclaw skills suggestions reject <skill> <suggestion-id>
goclaw skills suggestions apply <skill> <suggestion-id>
goclaw skills suggestions apply <skill> <suggestion-id> --approve
```

| Command | Args / Flags | Effect |
|---------|--------------|--------|
| `skills suggestions list <skill>` | 1 | List suggestions for a skill |
| `skills suggestions approve <skill> <suggestion-id>` | 2 | Approve a suggestion |
| `skills suggestions reject <skill> <suggestion-id>` | 2 | Reject a suggestion |
| `skills suggestions apply <skill> <suggestion-id>` | 2, `--approve` | Apply an approved suggestion (`--approve` approves a pending one first) |

### `skills deps`

Scan, check, and install skill dependencies. The argument accepts a local skill path or a gateway skill ID.

```bash
goclaw skills deps status <skill-id-or-path>
goclaw skills deps scan <skill-id-or-path>
goclaw skills deps check <skill-id-or-path>
goclaw skills deps install <skill-id>
```

| Command | Args / Flags | Effect |
|---------|--------------|--------|
| `skills deps status <skill-id-or-path>` | 1, `--json` | Show dependency status |
| `skills deps scan <skill-id-or-path>` | 1, `--json` | Scan dependency declarations |
| `skills deps check <skill-id-or-path>` | 1, `--json` | Check availability |
| `skills deps install <skill-id>` | 1, `--json` | Install missing dependencies (master tenant) |

### `skills access`

Manage skill access mode and effective access.

```bash
goclaw skills access get <skill-id>
goclaw skills access set <skill-id> --mode internal
goclaw skills access effective <skill-id> --agent <agent-id> --user <user-id>
goclaw skills access effective --agent <agent-id> --user <user-id>
```

| Command | Args / Flags | Effect |
|---------|--------------|--------|
| `skills access get <skill-id>` | 1, `--json` | Show access mode and grants |
| `skills access set <skill-id> --mode <private\|internal\|public>` | 1, `--mode` (required), `--json` | Set the access mode |
| `skills access effective [skill-id] --agent <id> --user <id>` | 0–1, `--agent`+`--user` (required), `--json` | Inspect effective access (per-skill when an ID is given, else across skills) |

### `skills grant`

Grant skill access to an agent or user.

```bash
goclaw skills grant agent <skill-id> <agent-id>
goclaw skills grant agent <skill-id> <agent-id> --can-manage --pinned-version 3
goclaw skills grant user <skill-id> <user-id>
```

| Command | Args / Flags | Effect |
|---------|--------------|--------|
| `skills grant agent <skill-id> <agent-id>` | 2, `--can-manage`, `--pinned-version <n>`, `--json` | Grant a skill to an agent |
| `skills grant user <skill-id> <user-id>` | 2, `--json` | Grant a skill to a user |

### `skills revoke`

Revoke skill access from an agent or user.

```bash
goclaw skills revoke agent <skill-id> <agent-id>
goclaw skills revoke user <skill-id> <user-id>
```

| Command | Args | Effect |
|---------|------|--------|
| `skills revoke agent <skill-id> <agent-id>` | 2 | Revoke an agent grant |
| `skills revoke user <skill-id> <user-id>` | 2 | Revoke a user grant |

---

## `models`

List configured AI models and providers.

### `models list`

```bash
goclaw models list
goclaw models list --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

Shows default model, per-agent overrides, and which providers have API keys configured.

---

## `auth`

Manage OAuth authentication for LLM providers. Requires the gateway to be running.

### `auth status`

Show OAuth authentication status (currently: OpenAI OAuth).

```bash
goclaw auth status
```

Uses `GOCLAW_GATEWAY_URL`, `GOCLAW_HOST`, `GOCLAW_PORT`, and `GOCLAW_TOKEN` env vars to connect.

### `auth logout [provider]`

Remove stored OAuth tokens.

```bash
goclaw auth logout          # removes openai OAuth tokens
goclaw auth logout openai
```

---

## `setup` commands

Guided setup wizards for individual components. Each runs interactively and writes to `config.json`.

### `setup agent`

Add or reconfigure an agent interactively.

```bash
goclaw setup agent
```

### `setup channel`

Configure a messaging channel (Telegram, Zalo OA, Feishu/Lark, etc.).

```bash
goclaw setup channel
```

### `setup provider`

Add or reconfigure an LLM provider.

```bash
goclaw setup provider
```

### `setup` (general)

Run the full setup flow (equivalent to `onboard` for an existing install).

```bash
goclaw setup
```

---

## TUI commands

Terminal UI versions of the setup and onboard flows. Available when the terminal supports interactive TUI rendering. Falls back to plain CLI automatically on unsupported terminals.

```bash
goclaw tui           # launch TUI app
goclaw tui onboard   # TUI-based onboarding wizard
goclaw tui setup     # TUI-based setup wizard
```

---

## `bitrix-portal`

Manage Bitrix24 portal rows directly in the database (PostgreSQL only). GoClaw expects a `bitrix_portals` row to exist before an operator runs the OAuth install flow at `/bitrix24/install`; this command seeds and maintains that row without requiring raw SQL access.

> Credentials are encrypted at rest using `GOCLAW_ENCRYPTION_KEY`. If the key is unset, the command warns and stores credentials unencrypted.

### `bitrix-portal create`

Create a `bitrix_portals` row with OAuth credentials.

```bash
goclaw bitrix-portal create \
  --tenant-id <uuid> \
  --name <portal> \
  --domain tamgiac.bitrix24.com \
  --client-id <client_id> \
  --client-secret <client_secret>
```

| Flag | Description |
|------|-------------|
| `--tenant-id` | Tenant UUID this portal belongs to (required) |
| `--name` | Short portal name, referenced by `channel_instance.config.portal` (required) |
| `--domain` | Bitrix24 portal host, e.g. `tamgiac.bitrix24.com` (required) |
| `--client-id` | Bitrix24 application `client_id` / `application_id` (required) |
| `--client-secret` | Bitrix24 application `client_secret` / application key (required) |

### `bitrix-portal list`

List `bitrix_portals` rows, optionally scoped to one tenant.

```bash
goclaw bitrix-portal list
goclaw bitrix-portal list --tenant-id <uuid>
```

| Flag | Description |
|------|-------------|
| `--tenant-id` | Filter to one tenant UUID (optional) |

### `bitrix-portal update-credentials`

Replace `client_id`/`client_secret` on an existing portal row. Use when rotating a client secret or migrating from a local app to a marketplace app. The OAuth state token is cleared by default, since state minted under the old credentials cannot refresh under the new ones.

```bash
goclaw bitrix-portal update-credentials \
  --tenant-id <uuid> --name <portal> \
  --client-id <client_id> --client-secret <client_secret>
```

| Flag | Description |
|------|-------------|
| `--tenant-id` | Tenant UUID this portal belongs to (required) |
| `--name` | Portal name to update (required) |
| `--client-id` | New Bitrix24 application `client_id` (required) |
| `--client-secret` | New Bitrix24 application `client_secret` (required) |
| `--keep-state` | Keep the existing OAuth state token (only safe when rotating the secret of the SAME application) |

### `bitrix-portal set-public-url`

Backfill the gateway-public URL used to register Bitrix24 imbot event handlers. A one-shot operation for portals installed before automatic public-URL capture existed.

```bash
goclaw bitrix-portal set-public-url \
  --tenant-id <uuid> --name <portal> \
  --url https://goclaw.example.com
```

| Flag | Description |
|------|-------------|
| `--tenant-id` | Tenant UUID this portal belongs to (required) |
| `--name` | Portal name (required) |
| `--url` | Gateway public URL, e.g. `https://goclaw.example.com` (required) |

---

## What's Next

- [WebSocket Protocol](/websocket-protocol) — wire protocol reference for the gateway
- [REST API](/rest-api) — HTTP API endpoint listing
- [Config Reference](/config-reference) — full `config.json` schema



---

# WebSocket Protocol

> Protocol v3 specification for the GoClaw gateway WebSocket RPC interface.

## Overview

GoClaw exposes a WebSocket endpoint at `/ws`. All client-gateway communication uses JSON frames with three types: `req` (request), `res` (response), and `event` (server-push). The first request on any connection must be `connect` to authenticate and negotiate protocol version.

**Connection URL:** `ws://<host>:<port>/ws`

**Protocol version:** `3`


## Frame Types

### Request Frame (`req`)

Sent by the client to invoke an RPC method.

```json
{
  "type": "req",
  "id": "unique-client-id",
  "method": "chat.send",
  "params": { "message": "Hello", "sessionKey": "user:demo" }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Always `"req"` |
| `id` | string | Client-generated unique ID, matched in response |
| `method` | string | RPC method name |
| `params` | object | Method parameters (optional) |

### Response Frame (`res`)

Sent by the server in reply to a request.

```json
{
  "type": "res",
  "id": "unique-client-id",
  "ok": true,
  "payload": { ... }
}
```

Error response:

```json
{
  "type": "res",
  "id": "unique-client-id",
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "invalid token",
    "retryable": false
  }
}
```

**Error shape:**

| Field | Type | Description |
|-------|------|-------------|
| `code` | string | Machine-readable error code |
| `message` | string | Human-readable description |
| `details` | any | Optional extra context |
| `retryable` | boolean | Whether retrying may succeed |
| `retryAfterMs` | integer | Suggested retry delay in milliseconds |

### Event Frame (`event`)

Server-pushed without a preceding request.

```json
{
  "type": "event",
  "event": "agent",
  "payload": { "type": "chunk", "text": "Hello" },
  "seq": 42,
  "stateVersion": { "presence": 1, "health": 2 }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Always `"event"` |
| `event` | string | Event name |
| `payload` | any | Event-specific data |
| `seq` | integer | Monotonically increasing ordering number |
| `stateVersion` | object | Version counters for optimistic state sync (`presence`, `health`) |

---

## Connection Handshake

The first request must be `connect`. The gateway rejects any other method until authenticated.

```json
// Request
{
  "type": "req",
  "id": "init",
  "method": "connect",
  "params": {
    "token": "YOUR_GATEWAY_TOKEN",
    "protocol": 3
  }
}

// Success response
{
  "type": "res",
  "id": "init",
  "ok": true,
  "payload": { "version": "v1.2.0", "protocol": 3 }
}
```

A wrong protocol version or invalid token returns `ok: false` immediately.

**`user_id` requirement:** The `user_id` parameter in `connect` is required for per-user session scoping. It is an opaque VARCHAR(255). For multi-tenant deployments, use the compound format `tenant.{tenantId}.user.{userId}` — GoClaw uses identity propagation and trusts the upstream service to supply the correct identity.

---

## RPC Methods

### Core

| Method | Params | Description |
|--------|--------|-------------|
| `connect` | `{token, user_id, sender_id?, locale?}` | Authenticate. Must be first request |
| `health` | — | Ping / health check |
| `status` | — | Gateway status |
| `agent` | `{agentId?}` | Get runtime status of a single agent (defaults to `"default"`) |
| `send` | `{channel, to, message}` | Route an outbound message to an external channel |

### Chat

> **Session ownership (v3):** All five `chat.*` methods enforce session ownership. Non-admin callers can only access sessions they own (matched by `user_id`). Attempting to access another user's session returns `UNAUTHORIZED`. Admins and gateway-owner connections bypass this check. This is implemented via the `requireSessionOwner` helper in `internal/gateway/methods/access.go`.

| Method | Params | Description |
|--------|--------|-------------|
| `chat.send` | `{message, sessionKey?, agentId?}` | Send a message; response streams via `agent`/`chat` events |
| `chat.history` | `{sessionKey}` | Retrieve message history |
| `chat.abort` | `{sessionKey}` | Abort an in-progress run |
| `chat.inject` | `{sessionKey, content}` | Inject a message without triggering a run |
| `chat.session.status` | `{sessionKey}` | Get live run state + activity phase of a session |

### Agents Management

| Method | Params | Description |
|--------|--------|-------------|
| `agents.list` | — | List all agents |
| `agent.wait` | `{agentId}` | Wait for agent to finish current run |
| `agents.create` | agent object | Create an agent |
| `agents.update` | `{agentId, name?, provider?, model?, model_fallback?, avatar?, status?, workspace?, frontmatter?, context_window?, max_tool_iterations?, is_default?, budget_monthly_cents?, tools_config?, subagents_config?, sandbox_config?, memory_config?, compaction_config?, context_pruning?, other_config?, emoji?, agent_description?, thinking_level?, max_tokens?, self_evolve?, skill_evolve?, skill_nudge_interval?, reasoning_config?, workspace_sharing?, chatgpt_oauth_routing?, shell_deny_groups?, kg_dedup_config?}` | Update an agent |
| `agents.delete` | `{id}` | Delete an agent |
| `agents.files.list` | `{agentId}` | List context files |
| `agents.files.get` | `{agentId, fileName}` | Get a context file |
| `agents.files.set` | `{agentId, fileName, content}` | Create or update a context file |
| `agent.identity.get` | `{agentId}` | Get agent persona info |
| `agents.links.list` | `{agentId, direction?}` | List delegation links (`"from"`, `"to"`, `"all"`) |
| `agents.links.create` | `{sourceAgent, targetAgent, direction?, description?, maxConcurrent?, settings?}` | Create a delegation link between agents |
| `agents.links.update` | `{linkId, direction?, description?, maxConcurrent?, settings?, status?}` | Update a delegation link |
| `agents.links.delete` | `{linkId}` | Delete a delegation link |

### Sessions

| Method | Params | Description |
|--------|--------|-------------|
| `sessions.list` | `{agentId?}` | List sessions, optionally filtered by agent |
| `sessions.preview` | `{sessionKey}` | Get session summary |
| `sessions.patch` | `{sessionKey, ...fields}` | Patch session metadata |
| `sessions.delete` | `{key}` | Delete a session |
| `sessions.reset` | `{key}` | Clear session history |
| `sessions.compact` | `{key, keepLast?}` | Truncate history to last N messages (default 4); no-op if history < 6 |
| `run.timeline.get` | `{runId?, sessionKey?, limit?, offset?}` | Fetch display-safe archived run/session timeline items |

#### `run.timeline.get`

Fetch display-safe timeline entries captured during agent runs. Pass `runId` for a single run, or `sessionKey` for the session archive panel — **at least one is required**. `limit` defaults to `200` and is capped at `500`; `offset` paginates. Viewer role can read this method; non-admin callers only receive entries whose `user_id` matches their connected user.

**Request:**

```json
{
  "type": "req",
  "id": "tl-1",
  "method": "run.timeline.get",
  "params": { "runId": "run-123", "sessionKey": "agent:demo:direct:user-1", "limit": 100, "offset": 0 }
}
```

**Response payload:**

```json
{
  "runId": "run-123",
  "sessionKey": "agent:demo:direct:user-1",
  "items": [{
    "id": "019e...",
    "run_id": "run-123",
    "session_key": "agent:demo:direct:user-1",
    "seq": 1,
    "item_type": "assistant.message",
    "status": "completed",
    "title": "assistant",
    "preview": "I will check that now.",
    "created_at": "2026-05-29T10:00:00Z"
  }],
  "limit": 100,
  "offset": 0
}
```

Timeline `item_type` values include `activity`, `assistant.message`, `tool.call`, `tool.result`, and `run.status`. Tool entries store bounded previews only; raw reasoning/thinking is not persisted.

### Config

| Method | Description |
|--------|-------------|
| `config.get` | Get current config (secrets redacted) |
| `config.apply` | Replace config entirely |
| `config.patch` | Patch specific config fields |
| `config.schema` | Get JSON schema for config |
| `config.defaults` | Get compiled-in defaults + agents.defaults overlay (read-only, master scope) |
| `config.permissions.list` | `{agentId, configType?}` | List permissions for an agent |
| `config.permissions.check` | `{agentId, scope, configType, userId}` | Evaluate the effective decision (`allow` / `deny`) without mutating |
| `config.permissions.grant` | `{agentId, scope, configType, userId, permission, grantedBy?, metadata?}` | Grant a permission |
| `config.permissions.revoke` | `{agentId, scope, configType, userId}` | Revoke a permission |

### Cron

| Method | Params | Description |
|--------|--------|-------------|
| `cron.list` | `{includeDisabled?}` | List cron jobs |
| `cron.create` | cron job object | Create a cron job |
| `cron.update` | `{jobId, ...fields}` | Update a cron job |
| `cron.delete` | `{jobId}` | Delete a cron job |
| `cron.toggle` | `{jobId, enabled}` | Enable or disable a job |
| `cron.run` | `{jobId}` | Trigger immediate run |
| `cron.runs` | `{jobId}` | List run history |
| `cron.status` | `{jobId}` | Get job status |

### Skills

| Method | Params | Description |
|--------|--------|-------------|
| `skills.list` | — | List skills |
| `skills.get` | `{id}` | Get skill details |
| `skills.update` | `{id, ...fields}` | Update skill metadata |

### Hooks

Manage lifecycle hooks stored in `agent_hooks`. See [Agent Hooks](/hooks-quality-gates) for full concepts and examples.

**Required roles:** `viewer` for list/history; `operator` for test; `admin` for create/update/delete/toggle.

| Method | Params | Description |
|--------|--------|-------------|
| `hooks.list` | `{event?, scope?, agentId?, enabled?}` | List hooks visible to the caller's scope |
| `hooks.create` | hook config object | Create a hook; returns `{hookId}` |
| `hooks.update` | `{hookId, updates}` | Patch a hook's fields; re-validates merged config |
| `hooks.delete` | `{hookId}` | Delete a hook (builtin hooks return error) |
| `hooks.toggle` | `{hookId, enabled}` | Enable or disable a hook |
| `hooks.test` | `{config, sampleEvent?}` | Dry-run a hook config; no audit row written |
| `hooks.history` | — | List `hook_executions` audit records |

**`hooks.list` — filter params:**

| Param | Type | Description |
|-------|------|-------------|
| `event` | string | Filter by event name (e.g. `pre_tool_use`) |
| `scope` | string | Filter by scope: `global`, `tenant`, `agent` |
| `agentId` | string (UUID) | Filter to a specific agent |
| `enabled` | boolean | Filter by enabled state |

**`hooks.list` response:**
```json
{ "hooks": [ { "id": "uuid", "event": "pre_tool_use", "handler_type": "http",
               "scope": "tenant", "enabled": true, "priority": 0, ... } ] }
```

**`hooks.create` request params** (all fields are the `HookConfig` schema):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event` | string | yes | Lifecycle event name |
| `handler_type` | string | yes | `command`, `http`, or `prompt` |
| `scope` | string | yes | `global`, `tenant`, or `agent` |
| `name` | string | no | Human-readable label |
| `matcher` | string | no | Tool name regex (optional for command/http; required for prompt) |
| `if_expr` | string | no | CEL expression alternative to matcher |
| `timeout_ms` | int | no | Per-hook timeout ms (default 5000, max 10000) |
| `on_timeout` | string | no | `block` (default) or `allow` |
| `priority` | int | no | Higher runs first |
| `enabled` | bool | no | Default true |
| `config` | object | yes | Handler-specific sub-config |
| `agent_ids` | array | no | UUID list for scope=agent |

**`hooks.test` — `sampleEvent` fields:**

| Field | Type | Description |
|-------|------|-------------|
| `toolName` | string | Tool name for pre/post_tool_use events |
| `toolInput` | object | Tool arguments map |
| `rawInput` | string | Raw user message (for user_prompt_submit) |

**`hooks.test` response:**
```json
{
  "result": {
    "decision": "allow",
    "reason": "...",
    "durationMs": 42,
    "stdout": "...",
    "stderr": "...",
    "statusCode": 200,
    "updatedInput": {}
  }
}
```

### Channels

| Method | Description |
|--------|-------------|
| `channels.list` | List active channels |
| `channels.status` | Get channel health |
| `channels.toggle` | Enable/disable a channel |
| `channels.instances.list` | List DB channel instances |
| `channels.instances.get` | Get a channel instance |
| `channels.instances.create` | Create a channel instance |
| `channels.instances.update` | Update a channel instance |
| `channels.instances.delete` | Delete a channel instance |

### Pairing

| Method | Params | Description |
|--------|--------|-------------|
| `device.pair.request` | `{channel, chatId}` | Request pairing code |
| `device.pair.approve` | `{code, approvedBy}` | Approve a pairing request |
| `device.pair.deny` | `{code}` | Deny a pairing request |
| `device.pair.list` | — | List pending and approved pairings |
| `device.pair.revoke` | `{channel, senderId}` | Revoke a pairing |
| `browser.pairing.status` | `{sender_id}` | Poll pairing approval status (unauthenticated, rate-limited) |

### Exec Approvals

| Method | Description |
|--------|-------------|
| `exec.approval.list` | List pending shell command approvals |
| `exec.approval.approve` | Approve a command |
| `exec.approval.deny` | Deny a command |

### Teams

| Method | Description |
|--------|-------------|
| `teams.list` | List all teams |
| `teams.create` | Create team (admin only) |
| `teams.get` | Get team with members |
| `teams.update` | Update team properties |
| `teams.delete` | Delete team |
| `teams.members.add` | Add agent to team |
| `teams.members.remove` | Remove agent from team |
| `teams.tasks.list` | List team tasks (filterable) |
| `teams.tasks.get` | Get task with comments/events |
| `teams.tasks.create` | Create task |
| `teams.tasks.assign` | Assign task to member |
| `teams.tasks.approve` | Approve completed task |
| `teams.tasks.reject` | Reject task submission |
| `teams.tasks.comment` | Add comment to task |
| `teams.tasks.comments` | List task comments |
| `teams.tasks.events` | List task event history |
| `teams.tasks.get-light` | Get task without comments/events/attachments |
| `teams.tasks.delete` | Delete task |
| `teams.tasks.delete-bulk` | `{teamId, taskIds}` | Bulk-delete terminal-status tasks |
| `teams.tasks.active-by-session` | Get active tasks for a session (used to restore state on session switch) |
| `teams.workspace.list` | List team workspace files |
| `teams.workspace.read` | Read workspace file |
| `teams.workspace.delete` | Delete workspace file |
| `teams.events.list` | List team event history (paginated) |
| `teams.known_users` | Get known user IDs in team |
| `teams.scopes` | Get channel/chat scopes for task routing |

### Usage & Quota

| Method | Description |
|--------|-------------|
| `usage.get` | Token usage stats |
| `usage.summary` | Usage summary cards |
| `quota.usage` | Quota consumption for current user |

### Logs

| Method | Params | Description |
|--------|--------|-------------|
| `logs.tail` | `{action: "start"\|"stop", level?}` | Start or stop live log streaming; log entries arrive as server-push events while active |

### Heartbeat

| Method | Params | Description |
|--------|--------|-------------|
| `heartbeat.get` | `{agentId}` | Get heartbeat config for an agent |
| `heartbeat.set` | `{agentId, enabled?, intervalSec?, prompt?, providerName?, model?, ...}` | Upsert heartbeat config (intervalSec min 300) |
| `heartbeat.toggle` | `{agentId, enabled}` | Enable or disable heartbeat |
| `heartbeat.test` | `{agentId}` | Trigger an immediate heartbeat run |
| `heartbeat.logs` | `{agentId, limit?, offset?}` | List heartbeat execution logs |
| `heartbeat.checklist.get` | `{agentId}` | Read the HEARTBEAT.md context file |
| `heartbeat.checklist.set` | `{agentId, content}` | Write/replace the HEARTBEAT.md context file |
| `heartbeat.targets` | `{agentId}` | List delivery targets for heartbeat notifications |

### API Keys

| Method | Params | Description |
|--------|--------|-------------|
| `api_keys.list` | — | List API keys (non-admin sees own only) |
| `api_keys.create` | `{name, scopes, expires_in?, owner_id?, tenant_id?}` | Create an API key; returns raw key once |
| `api_keys.revoke` | `{id}` | Revoke an API key (non-admin can revoke own only) |

### Voices (TTS)

| Method | Params | Description |
|--------|--------|-------------|
| `voices.list` | — | List ElevenLabs voices for current tenant (cached) |
| `voices.refresh` | — | Invalidate cache and refetch voices from provider |

### Workstations

> **Standard edition only.** Methods are not registered when the gateway runs in Lite edition; calls return `method_not_found`. Admin role required for every method.

| Method | Params | Description |
|--------|--------|-------------|
| `workstations.list` | — | List workstations for the current tenant |
| `workstations.get` | `{id}` | Get a workstation |
| `workstations.create` | `{workstationKey, name, backendType, metadata, defaultCwd?, defaultEnv?}` | Create a workstation (`backendType` is `ssh` or `docker`) |
| `workstations.update` | `{id, ...fields}` | Update a workstation |
| `workstations.delete` | `{id}` | Delete a workstation |
| `workstations.testConnection` | `{id}` | Probe backend connectivity without executing commands |
| `workstations.linkAgent` | `{workstationId, agentId, isDefault?}` | Link an agent to a workstation |
| `workstations.unlinkAgent` | `{workstationId, agentId}` | Remove the link |
| `workstations.permissions.list` | `{workstationId}` | List allowlist patterns |
| `workstations.permissions.add` | `{workstationId, pattern, description?, enabled?}` | Append an allowlist pattern |
| `workstations.permissions.remove` | `{workstationId, permissionId}` | Remove a pattern |
| `workstations.permissions.toggle` | `{workstationId, permissionId, enabled}` | Enable/disable a pattern |
| `workstations.activity.list` | `{workstationId, limit?, before?, action?}` | Paginated activity audit log; `action` filter accepts `exec` or `deny` |

### Tenants

| Method | Params | Description |
|--------|--------|-------------|
| `tenants.list` | — | List all tenants (owner only) |
| `tenants.get` | `{id}` | Get a tenant by ID |
| `tenants.create` | `{name, slug, settings?}` | Create a tenant and its workspace |
| `tenants.update` | `{id, name?, status?, settings?}` | Update tenant properties |
| `tenants.users.list` | `{tenant_id}` | List users in a tenant |
| `tenants.users.add` | `{tenant_id, user_id, role?}` | Add user (roles: owner/admin/operator/member/viewer) |
| `tenants.users.remove` | `{tenant_id, user_id}` | Remove user and broadcast access-revoked event |
| `tenants.mine` | — | Get current user's tenant memberships |

### Messaging

| Method | Params | Description |
|--------|--------|-------------|
| `whatsapp.qr.start` | `{instance_id}` | Start WhatsApp QR login flow for direct WhatsApp channel |
| `zalo.personal.qr.start` | `{instance_id}` | Start Zalo Personal QR login flow |
| `zalo.personal.contacts` | `{instance_id}` | Fetch Zalo friends and groups |

> **Status: Planned** — `whatsapp.qr.start`, `zalo.personal.qr.start`, and `zalo.personal.contacts` have protocol constants defined but handlers are not yet implemented in the gateway.

### Bitrix Portals

Self-service management of Bitrix24 portal connections. All methods are tenant-scoped (resolved from the connection, never from caller params). `list` and `get_install_url` are open to any authenticated tenant member; `create` and `delete` require **admin role**. Credentials are never returned in any response.

| Method | Params | Description |
|--------|--------|-------------|
| `bitrix.portals.list` | — | List portals for the current tenant (credentials masked) |
| `bitrix.portals.create` | `{name, domain, client_id, client_secret}` | Provision a portal; returns `{name, domain, install_url}` |
| `bitrix.portals.get_install_url` | `{name}` | Re-build the install URL for an existing portal → `{install_url}` |
| `bitrix.portals.delete` | `{name}` | Delete a portal → `{status: "deleted"}` |

**`bitrix.portals.create` params:**

| Param | Type | Description |
|-------|------|-------------|
| `name` | string | Portal slug — lowercase letters, digits, hyphen, underscore (2–64 chars) |
| `domain` | string | Portal host — `*.bitrix24.{com,eu,ru,…}` or `*.bitrix.info` |
| `client_id` | string | Bitrix OAuth client ID |
| `client_secret` | string | Bitrix OAuth client secret |

> `create` fails with `FAILED_PRECONDITION` if the gateway has not yet observed its public URL — open the UI through the gateway's external URL first so the install URL can be built. `delete` is blocked (`FAILED_PRECONDITION`) while any channel instance still references the portal.

---

## Server-Push Events

### Agent Events (`"agent"`)

Emitted during agent runs. Check `payload.type`:

| `payload.type` | Description |
|----------------|-------------|
| `run.started` | Agent run begins |
| `run.completed` | Run finished successfully |
| `run.failed` | Run encountered an error |
| `run.cancelled` | Run was cancelled before completion |
| `run.retrying` | Run is being retried |
| `tool.call` | Tool was invoked |
| `tool.result` | Tool returned a result |
| `block.reply` | Reply was blocked by input guard |
| `activity` | Agent activity update |

### Chat Events (`"chat"`)

| `payload.type` | Description |
|----------------|-------------|
| `chunk` | Streaming text token |
| `message` | Full message (non-streaming) |
| `thinking` | Extended thinking / reasoning output |

### System & Other Events

| Event | Description |
|-------|-------------|
| `health` | Periodic gateway health ping |
| `tick` | Heartbeat tick |
| `shutdown` | Gateway shutting down |
| `cron` | Cron job status change |
| `exec.approval.requested` | Shell command needs user approval |
| `exec.approval.resolved` | Approval decision made |
| `device.pair.requested` | New pairing request from channel user |
| `device.pair.resolved` | Pairing approved or denied |
| `presence` | User presence change |
| `agent.summoning` | Predefined agent persona generation in progress |
| `delegation.started` | Delegation to subagent started |
| `delegation.completed` | Delegation completed successfully |
| `delegation.failed` | Delegation failed |
| `delegation.cancelled` | Delegation was cancelled |
| `delegation.progress` | Intermediate delegation result |
| `delegation.announce` | Batched subagent results delivered to parent |
| `delegation.accumulated` | Accumulated delegation results |
| `connect.challenge` | Authentication challenge issued |
| `voicewake.changed` | Voice wake word setting changed |
| `talk.mode` | Talk mode state change |
| `node.pair.requested` | Node pairing request received |
| `node.pair.resolved` | Node pairing resolved |
| `session.updated` | Chat session metadata updated |
| `trace.updated` | Agent trace updated |
| `heartbeat` | Heartbeat execution event |
| `workspace.file.changed` | Team workspace file changed |
| `agent_link.created` | Delegation link created |
| `agent_link.updated` | Delegation link updated |
| `agent_link.deleted` | Delegation link deleted |
| `tenant.access.revoked` | Tenant access revoked for a user |
| `whatsapp.qr.code` | WhatsApp QR code generated |
| `whatsapp.qr.done` | WhatsApp QR login completed |
| `zalo.personal.qr.code` | Zalo QR code generated |
| `zalo.personal.qr.done` | Zalo QR login completed |

### Skill Events

| Event | Description |
|-------|-------------|
| `skill.deps.checked` | Skill dependencies check started |
| `skill.deps.complete` | All skill dependencies resolved |
| `skill.deps.installing` | Skill dependency installation started |
| `skill.deps.installed` | Skill dependency installation completed |
| `skill.dep.item.installing` | Individual dependency item installing |
| `skill.dep.item.installed` | Individual dependency item installed |

### Team Events

| Event | Description |
|-------|-------------|
| `team.created` | Team created |
| `team.updated` | Team updated |
| `team.deleted` | Team deleted |
| `team.member.added` | Member added to team |
| `team.member.removed` | Member removed from team |
| `team.message.sent` | Peer-to-peer message in team |
| `team.leader.processing` | Team leader processing request |
| `team.task.created` | Task created |
| `team.task.completed` | Task completed |
| `team.task.claimed` | Task claimed |
| `team.task.cancelled` | Task cancelled |
| `team.task.failed` | Task failed |
| `team.task.reviewed` | Task reviewed |
| `team.task.approved` | Task approved |
| `team.task.rejected` | Task rejected |
| `team.task.progress` | Task progress update |
| `team.task.commented` | Comment added to task |
| `team.task.assigned` | Task assigned to member |
| `team.task.dispatched` | Task dispatched |
| `team.task.updated` | Task updated |
| `team.task.deleted` | Task deleted |
| `team.task.stale` | Task marked stale |
| `team.task.attachment_added` | Attachment added to task |

---

## Example Session

```javascript
const ws = new WebSocket("ws://localhost:18790/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "req", id: "1", method: "connect",
    params: { token: "YOUR_TOKEN", user_id: "user-123", protocol: 3 }
  }));
};

ws.onmessage = (e) => {
  const frame = JSON.parse(e.data);

  // After connect succeeds, send a chat message
  if (frame.type === "res" && frame.id === "1" && frame.ok) {
    ws.send(JSON.stringify({
      type: "req", id: "2", method: "chat.send",
      params: { message: "Hello!", sessionKey: "user:demo" }
    }));
  }

  // Stream response tokens
  if (frame.type === "event" && frame.event === "chat") {
    if (frame.payload?.type === "chunk") {
      process.stdout.write(frame.payload.text ?? "");
    }
  }
};
```

---

## What's Next

- [REST API](/rest-api) — HTTP endpoints for agent CRUD, skill uploads, traces
- [CLI Commands](/cli-commands) — pairing and session management from the terminal
- [Glossary](/glossary) — Session, Lane, Compaction, and other key terms



---

# REST API

> All `/v1` HTTP endpoints for agent management, providers, skills, traces, and more.

## Overview

> **Looking for a complete index?** See [API Endpoint Catalog](api-endpoints-catalog.md) for an auto-generated list of all REST endpoints.

GoClaw's HTTP API is served on the same port as the WebSocket gateway. All endpoints require a `Bearer` token in the `Authorization` header matching `GOCLAW_GATEWAY_TOKEN`.

Interactive documentation: `/docs` (Swagger UI) · raw spec: `/v1/openapi.json`

**Base URL:** `http://<host>:<port>`

**Auth header:**
```
Authorization: Bearer YOUR_GATEWAY_TOKEN
```

**User identity header** (optional, for per-user scoping):
```
X-GoClaw-User-Id: user123
```

### Common Headers

| Header | Purpose |
|--------|---------|
| `Authorization` | Bearer token |
| `X-GoClaw-User-Id` | External user ID for multi-tenant context |
| `X-GoClaw-Agent-Id` | Agent identifier for scoped operations |
| `X-GoClaw-Tenant-Id` | Tenant scope — UUID or slug |
| `Accept-Language` | Locale (`en`, `vi`, `zh`) for i18n error messages |
| `X-GoClaw-No-Image-Gen` | (optional) Send to opt out of native image generation for that request. Bypasses both the provider capability check and the agent flag tri-level gate. Applies to chat endpoints. |

**Input validation:** All string inputs are sanitized — SQL special characters are escaped in ILIKE queries, request bodies are limited to 1 MB, and agent/provider/tool names are validated against allowlist patterns (`[a-zA-Z0-9_-]`).


## OpenResponses Protocol

### `POST /v1/responses`

Alternative response-based protocol (compatible with OpenAI Responses API). Accepts the same auth and returns structured response objects.

---

## Sessions

Read-only session discovery and branching over HTTP, for automation that cannot hold a WebSocket connection. Non-admin callers only see their own sessions (matched by `X-GoClaw-User-Id`); admins and gateway-owner tokens see all sessions.

> Full session lifecycle (preview, patch, delete, reset, compact) is available via [WebSocket RPC](/websocket-protocol#sessions). These HTTP routes cover discovery, branching, and incremental history reads.

### `GET /v1/sessions`

List sessions with pagination.

```bash
curl "http://localhost:18790/v1/sessions?agent_id=AGENT_UUID&limit=20&offset=0" \
  -H "Authorization: Bearer TOKEN" \
  -H "X-GoClaw-User-Id: user123"
```

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `agent_id` | string | Filter by agent (alias: `agentId`) |
| `channel` | string | Filter by channel |
| `limit` | integer | Page size (default 20) |
| `offset` | integer | Page offset (default 0) |

**Response:** `{ "sessions": [...], "total": N, "limit": 20, "offset": 0 }`

### `POST /v1/chat/sessions/{key}/branch`

Branch a new session from an existing one, copying messages up to a given index. The `{key}` path segment is the **source** session key; the branch reuses the same agent key.

```bash
curl -X POST http://localhost:18790/v1/chat/sessions/{key}/branch \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "up_to_index": 8,
    "new_session_key": "",
    "label": "what-if branch",
    "metadata": {}
  }'
```

| Field | Type | Description |
|-------|------|-------------|
| `up_to_index` | integer | Required. Copy messages `[0, up_to_index)` into the branch |
| `new_session_key` | string | Optional. Must use the same agent key as the source. Auto-generated when omitted |
| `label` | string | Optional human-readable branch label |
| `metadata` | object | Optional string key-value metadata |

**Response** (`201 Created`):

```json
{
  "ok": true,
  "source_key": "agent:researcher:direct:...",
  "session_key": "agent:researcher:branch:direct:...",
  "copied_messages": 8,
  "total_messages": 20,
  "label": "what-if branch"
}
```

Returns `409` if the target key already exists, `400` if `up_to_index` is out of range.

### `GET /v1/chat/sessions/{key}/history/follow`

Cursor-based incremental history read — poll for new messages without re-fetching the whole transcript. File and media references in returned messages are signed.

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `cursor` | integer | Index to start reading from (default 0) |
| `limit` | integer | Max messages to return (default 50, max 200) |

**Response:**

```json
{
  "session_key": "agent:researcher:direct:...",
  "cursor": 0,
  "next_cursor": 50,
  "total": 120,
  "messages": [ ... ],
  "reset": false,
  "updated": "2026-06-07T08:00:00Z"
}
```

Pass `next_cursor` as the next `cursor` to continue. `reset: true` (with an empty `messages` array) signals the cursor ran past the current history length — restart from `0`.

---

## Agents

CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for multi-tenant context.

### `GET /v1/agents`

List all agents.

```bash
curl http://localhost:18790/v1/agents \
  -H "Authorization: Bearer TOKEN"
```

### `POST /v1/agents`

Create a new agent.

```bash
curl -X POST http://localhost:18790/v1/agents \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "researcher",
    "display_name": "Research Assistant",
    "agent_type": "open",
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250929",
    "context_window": 200000,
    "max_tool_iterations": 20,
    "workspace": "~/.goclaw/workspace-researcher"
  }'
```

### `GET /v1/agents/{id}`

Get a single agent by ID.

### `PUT /v1/agents/{id}`

Update an agent. Send only the fields to change.

### `DELETE /v1/agents/{id}`

Delete an agent.

### `POST /v1/agents/{id}/regenerate`

Regenerate agent context files from templates.

### `POST /v1/agents/{id}/resummon`

Re-trigger LLM-based summoning for predefined agents.

### `POST /v1/agents/{id}/cancel-summon`

Force-abort a stuck summoning process. Transitions a `summoning` agent to `summon_failed` so it can be reconfigured or re-triggered. Returns `409` if the agent is not currently in `summoning` state.

### Agent Shares

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{id}/shares` | List shares for an agent |
| `POST` | `/v1/agents/{id}/shares` | Share agent with a user |
| `DELETE` | `/v1/agents/{id}/shares/{userID}` | Revoke a share |

### Predefined Agent Instances

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{id}/instances` | List user instances |
| `GET` | `/v1/agents/{id}/instances/{userID}/files` | List user context files |
| `PUT` | `/v1/agents/{id}/instances/{userID}/files/{fileName}` | Update user context file (admin) |
| `PATCH` | `/v1/agents/{id}/instances/{userID}/metadata` | Update instance metadata (admin) |
| `GET` | `/v1/agents/{id}/system-prompt-preview` | Preview rendered system prompt (admin) |

> To read file content, list files via `GET /v1/agents/{id}/instances/{userID}/files` then retrieve through the [Vault](#knowledge-vault) or [Storage](#storage) API. There is no single-file GET for instance files.

### Agent Export / Import

Export and import agent configurations and data as a tar.gz archive. Supports selective section export.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{id}/export/preview` | Preview export counts per section (no archive built) |
| `GET` | `/v1/agents/{id}/export` | Download agent archive directly (tar.gz) |
| `GET` | `/v1/agents/{id}/export/download/{token}` | Download a previously prepared archive via short-lived token (valid 5 min) |
| `POST` | `/v1/agents/import` | Import archive as a **new** agent (multipart `file` field) |
| `POST` | `/v1/agents/import/preview` | Parse archive and return manifest without importing |
| `POST` | `/v1/agents/{id}/import` | **Merge** archive data into an existing agent |

**Export query params:**

| Param | Type | Description |
|-------|------|-------------|
| `sections` | string | Comma-separated list of sections to include. Defaults to `config,context_files`. Available: `config`, `context_files`, `memory`, `knowledge_graph`, `cron`, `user_profiles`, `user_overrides`, `workspace` |
| `stream` | `bool` | When `true`, returns SSE progress events then a `complete` event with `download_url` for token-based download |

**Import query params (`POST /v1/agents/import`):**

| Param | Type | Description |
|-------|------|-------------|
| `agent_key` | string | Override agent key (falls back to archive value) |
| `display_name` | string | Override display name |
| `stream` | `bool` | Stream import progress via SSE |

**Merge import query params (`POST /v1/agents/{id}/import`):**

| Param | Type | Description |
|-------|------|-------------|
| `include` | string | Comma-separated sections to merge. Defaults to all sections |
| `stream` | `bool` | Stream merge progress via SSE |

**Archive format** (`agent-{key}-YYYYMMDD.tar.gz`):

```
manifest.json                              — archive manifest (version, sections summary)
agent.json                                 — agent config (sensitive fields stripped)
context_files/{filename}                   — agent-level context files
user_context_files/{user_id}/{filename}    — per-user context files
memory/global.jsonl                        — global memory documents
memory/users/{user_id}.jsonl               — per-user memory documents
knowledge_graph/entities.jsonl             — KG entities (portable external IDs)
knowledge_graph/relations.jsonl            — KG relations
cron/jobs.jsonl                            — cron job definitions
user_profiles.jsonl                        — user profile records
user_overrides.jsonl                       — per-user model overrides
workspace/                                 — workspace directory files
```

**Import response** (`201 Created`):

```json
{
  "agent_id": "uuid",
  "agent_key": "researcher",
  "context_files": 3,
  "memory_docs": 12,
  "kg_entities": 50,
  "kg_relations": 30
}
```

> Cron jobs are always imported as **disabled**. Duplicate jobs (same name) are skipped. Max archive size: 500 MB.

---

### `GET /v1/agents/{id}/codex-pool-activity`

Returns routing activity and per-account health for agents using a [Codex OAuth pool](/provider-codex). Requires the agent's provider to be `chatgpt_oauth` type with a pool configured.

**Auth:** Bearer token required. The requesting user must have access to the agent.

**Query parameters:**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `limit` | integer | `18` | Number of recent requests to return (max 50) |

**`strategy` values in response:**

| Value | Description |
|-------|-------------|
| `round_robin` | Even distribution across accounts |
| `priority_order` | Prefer providers in configured order (default) |

> **BREAKING (clients):** Codex pool API responses now return `priority_order` in place of legacy `primary_first` / `manual` for the same routing config. Request bodies still accept legacy values for backward compatibility. Update consumers comparing strategy strings literally.

**Response:**

```json
{
  "strategy": "priority_order",
  "pool_providers": ["openai-codex", "codex-work"],
  "stats_sample_size": 24,
  "provider_counts": [
    {
      "provider_name": "openai-codex",
      "request_count": 14,
      "direct_selection_count": 10,
      "failover_serve_count": 4,
      "success_count": 13,
      "failure_count": 1,
      "consecutive_failures": 0,
      "success_rate": 92,
      "health_score": 88,
      "health_state": "healthy",
      "last_used_at": "2026-03-27T08:00:00Z"
    }
  ],
  "recent_requests": [
    {
      "span_id": "uuid",
      "trace_id": "uuid",
      "started_at": "2026-03-27T08:00:00Z",
      "status": "success",
      "duration_ms": 1240,
      "provider_name": "openai-codex",
      "selected_provider": "openai-codex",
      "model": "gpt-5.4",
      "attempt_count": 1,
      "used_failover": false
    }
  ]
}
```

If the agent does not use a `chatgpt_oauth` provider or the pool is not configured, `pool_providers` is an empty array and `provider_counts`/`recent_requests` are empty.

Returns `503` if the tracing store is unavailable.

---

### Wake (External Trigger)

```
POST /v1/agents/{id}/wake
```

```json
{
  "message": "Process new data",
  "session_key": "optional-session",
  "user_id": "optional-user",
  "metadata": {}
}
```

Response: `{content, run_id, usage?}`. Used by orchestrators (n8n, Paperclip) to trigger agent runs externally.

---

## Providers

### `GET /v1/providers`

List all LLM providers.

### `POST /v1/providers`

Create an LLM provider.

```bash
curl -X POST http://localhost:18790/v1/providers \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-openrouter",
    "display_name": "OpenRouter",
    "provider_type": "openai_compat",
    "api_base": "https://openrouter.ai/api/v1",
    "api_key": "sk-or-...",
    "enabled": true
  }'
```

**Supported types:** `anthropic_native`, `openai_compat`, `chatgpt_oauth`, `gemini_native`, `dashscope`, `bailian`, `minimax`, `claude_cli`, `acp`

### `GET /v1/providers/{id}`

Get a provider by ID.

### `PUT /v1/providers/{id}`

Update a provider.

### `DELETE /v1/providers/{id}`

Delete a provider.

### `GET /v1/providers/{id}/models`

List models available from the provider (proxied to the upstream API).

### `POST /v1/providers/{id}/verify`

Verify provider connectivity or a specific model. Request body is optional (`requestBody.required: false`).

**Ping mode** — omit body (or send `{}`). Returns `{"valid": true}` if the provider is registered and reachable. Equivalent to a `/healthz` check; no LLM call is made.

```bash
curl -X POST http://localhost:18790/v1/providers/{id}/verify \
  -H "Authorization: Bearer TOKEN"
```

**Chat-verify mode** — include `model` to perform an actual chat completion against a specific model alias.

```bash
curl -X POST http://localhost:18790/v1/providers/{id}/verify \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-4"}'
```

**Response shape** — `{"valid": true}` on success, `{"valid": false, "error": "<msg>"}` on failure. The legacy `{success, models}` shape is no longer returned.

### `POST /v1/providers/{id}/verify-embedding`

Verify embedding model connectivity for a provider.

### `POST /v1/providers/{id}/reconnect`

Re-establish the in-memory connection for a provider — unregisters it from the runtime registry and re-registers from the stored config. Use after editing credentials or when a provider drops out of the live registry. Does **not** perform a verify; call `/verify` separately for that.

```bash
curl -X POST http://localhost:18790/v1/providers/{id}/reconnect \
  -H "Authorization: Bearer TOKEN"
```

The request body is optional. Sending `{"verify": true}` is rejected with `400` — reconnect and verify are separate operations.

**Response:**

```json
{
  "status": "reconnected",
  "provider": { "id": "uuid", "name": "my-openrouter", "...": "..." },
  "registry_updated": true,
  "cache_invalidated": true
}
```

`status` is `reconnected` (re-registered in memory), `not_registered` (enabled but registration failed), or `disabled` (provider is disabled). A `cache_invalidate` event is emitted so connected agents pick up the change.

### `GET /v1/providers/{id}/codex-pool-activity`

Returns Codex OAuth pool routing activity at the provider level (see also agent-level endpoint above).

### `GET /v1/embedding/status`

Check if embedding is configured and available across providers.

### `GET /v1/providers/claude-cli/auth-status`

Check Claude CLI authentication status (global, not per-provider).

---

## Skills

### `GET /v1/skills`

List all skills.

### `POST /v1/skills/upload`

Upload a skill as a `.zip` file (max 20 MB).

```bash
curl -X POST http://localhost:18790/v1/skills/upload \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@my-skill.zip"
```

### `GET /v1/skills/{id}`

Get skill metadata.

### `PUT /v1/skills/{id}`

Update skill metadata.

### `DELETE /v1/skills/{id}`

Delete a skill.

### `POST /v1/skills/{id}/toggle`

Toggle skill enabled/disabled state.

### `PUT /v1/skills/{id}/tenant-config`

Set a per-tenant override for a skill (e.g., enable/disable for the current tenant). Admin only.

### `DELETE /v1/skills/{id}/tenant-config`

Remove per-tenant override (revert to default). Admin only.

### Skills Export / Import

Export and import custom skills as a tar.gz archive.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/skills/export/preview` | Preview counts before export (no archive built) |
| `GET` | `/v1/skills/export` | Download skills archive directly (tar.gz) |
| `POST` | `/v1/skills/import` | Import skills archive (multipart `file` field) |

**Query params for export:**

| Param | Type | Description |
|-------|------|-------------|
| `stream` | `bool` | When `true`, returns SSE progress events then a `complete` event with `download_url` |
| `format` | string | Archive format — `tar.gz` (default), `tgz` (alias for gzip tar), or `zip`. ZIP is export/download only; import still expects the skills bundle format |
| `id` | string | Select one skill by ID. Repeat the param to select several |
| `ids` | string | Select multiple skill IDs as a comma-separated list |
| `include_system` | `bool` | Include system skills in a full export when no IDs are selected |

> `GET /v1/skills/export` supports both **direct download** (the archive is streamed in the response) and the SSE token flow (`stream=true` → `download_url`). Without `id`/`ids`, the export stays backward-compatible and includes tenant custom skills by default.

**Archive format** (`skills-YYYYMMDD.tar.gz`):

```
skills/{slug}/metadata.json   — skill metadata (name, slug, visibility, tags)
skills/{slug}/SKILL.md        — skill file content
skills/{slug}/grants.jsonl    — agent grants (agent_key + pinned version)
```

**Import response** (`201 Created`):

```json
{
  "skills_imported": 3,
  "skills_skipped": 1,
  "grants_applied": 5
}
```

> Skills are skipped (not overwritten) if the slug already exists in the tenant. Grants reference agents by `agent_key` — unmatched keys are silently skipped.

---

### Skill Grants

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/skills/{id}/grants/agent` | List agent grants for a skill (admin+) |
| `POST` | `/v1/skills/{id}/grants/agent` | Grant skill to an agent (body supports `can_manage` flag, migration 66) |
| `DELETE` | `/v1/skills/{id}/grants/agent/{agentID}` | Revoke agent grant |
| `POST` | `/v1/skills/{id}/grants/user` | Grant skill to a user |
| `DELETE` | `/v1/skills/{id}/grants/user/{userID}` | Revoke user grant |
| `GET` | `/v1/agents/{agentID}/skills` | List skills accessible to an agent |

### Skill Files & Dependencies

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/skills/{id}/versions` | List available versions |
| `GET` | `/v1/skills/{id}/files` | List files in skill |
| `GET` | `/v1/skills/{id}/files/{path...}` | Read file content |
| `POST` | `/v1/skills/rescan-deps` | Rescan runtime dependencies |
| `POST` | `/v1/skills/install-deps` | Install all missing dependencies |
| `POST` | `/v1/skills/install-dep` | Install a single dependency |
| `GET` | `/v1/skills/runtimes` | Check runtime availability |

---

### Skill Self-Evolution & Metrics

Skills can collect usage metrics and propose their own improvements. Self-evolution is tenant-scoped and **off by default per skill**. Usage metrics are written only by trusted runtime paths (e.g. the `use_skill` tool and slash-command activation) — there is no public usage-write endpoint.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/skills/{id}/evolution` | Read self-evolution settings for a skill |
| `PATCH` | `/v1/skills/{id}/evolution` | Update enabled state or mode (tenant-admin) |
| `GET` | `/v1/skills/{id}/metrics` | Aggregate usage metrics + status counts |
| `GET` | `/v1/skills/{id}/activity` | Admin-only evolution activity log |
| `GET` | `/v1/skills/{id}/evolution/suggestions` | List skill-scoped improvement suggestions |
| `POST` | `/v1/skills/{id}/evolution/suggestions` | Create a suggestion with evidence + draft patch (tenant-admin) |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{suggestionID}/approve` | Approve a suggestion (tenant-admin) |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{suggestionID}/reject` | Reject a suggestion (tenant-admin) |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{suggestionID}/apply` | Apply an approved suggestion → new skill version (tenant-admin) |

**Evolution modes (`PATCH .../evolution`, field `mode`):**

| Mode | Behavior |
|------|----------|
| `suggest_only` | Collect metrics and manage suggestions; no automatic patching |
| `auto_analyze` | Reserved for analysis automation. **Patch application always requires explicit approval** |

> Viewer/operator callers can read aggregate metrics. Raw activity, actor IDs, failure evidence, draft patches, and the apply action are admin-only. System skills can't be mutated; applying a custom-skill suggestion writes a new versioned directory and a `skill_versions` record.

### Skill Access Control & Grants (batch)

Read and manage who can use a skill. The plural `grants/agents` and `grants/users` routes accept **batch** sets; the singular routes documented under [Skill Grants](#skill-grants) remain available for single grants. All routes require **admin role**.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/skills/{id}/access` | Read access config (visibility + agent/user grants) |
| `PATCH` | `/v1/skills/{id}/access` | Update access config (e.g. `visibility`) |
| `GET` | `/v1/skills/{id}/access/effective` | Effective access for this skill |
| `GET` | `/v1/skills/access/effective` | Effective access across all skills |
| `GET` | `/v1/skills/{id}/grants/agents` | List agent grants (batch view) |
| `POST` | `/v1/skills/{id}/grants/agents` | Batch-set agent grants (`agent_id`, optional `version`/`pinned_version`, `can_manage`) |
| `DELETE` | `/v1/skills/{id}/grants/agents/{agentID}` | Remove an agent grant |
| `GET` | `/v1/skills/{id}/grants/users` | List user grants (batch view) |
| `POST` | `/v1/skills/{id}/grants/users` | Batch-set user grants (`user_id`) |
| `DELETE` | `/v1/skills/{id}/grants/users/{userID}` | Remove a user grant |

**Effective-access response** includes `accessible`, `reason`, `can_manage`, and optional `pinned_version` per skill.

### Skill Dependencies

Inspect and resolve a skill's runtime dependencies. Requires **admin role**.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/skills/{id}/dependencies` | List the skill's dependencies and their status |
| `POST` | `/v1/skills/{id}/dependencies/scan` | Re-scan declared dependencies and refresh status |
| `POST` | `/v1/skills/{id}/dependencies/check` | Check whether dependencies are satisfied |
| `POST` | `/v1/skills/{id}/dependencies/install` | Install missing dependencies for the skill |

---

## Tools

### Direct Invocation

```
POST /v1/tools/invoke
```

```json
{
  "tool": "web_fetch",
  "action": "fetch",
  "args": {"url": "https://example.com"},
  "dryRun": false,
  "agentId": "optional",
  "channel": "optional",
  "chatId": "optional",
  "peerKind": "direct"
}
```

Set `"dryRun": true` to return tool schema without execution.

### Built-in Tools

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/tools/builtin` | List all built-in tools |
| `GET` | `/v1/tools/builtin/{name}` | Get tool definition |
| `GET` | `/v1/tools/builtin/{name}/tenant-config` | Get tenant-specific configuration for a built-in tool |
| `PUT` | `/v1/tools/builtin/{name}` | Update enabled/settings |
| `PUT` | `/v1/tools/builtin/{name}/tenant-config` | Set per-tenant override (admin) |
| `DELETE` | `/v1/tools/builtin/{name}/tenant-config` | Remove per-tenant override (admin) |

> **Note:** Custom tools via REST API are not currently implemented. MCP servers and skills provide the recommended extension mechanism.

---

## Memory

Per-agent vector memory using pgvector.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/memory/documents` | List all documents globally |
| `GET` | `/v1/agents/{agentID}/memory/documents` | List documents for agent |
| `GET` | `/v1/agents/{agentID}/memory/documents/{path...}` | Get document details |
| `PUT` | `/v1/agents/{agentID}/memory/documents/{path...}` | Put/update document |
| `DELETE` | `/v1/agents/{agentID}/memory/documents/{path...}` | Delete document |
| `GET` | `/v1/agents/{agentID}/memory/chunks` | List chunks for a document |
| `POST` | `/v1/agents/{agentID}/memory/index` | Index a single document |
| `POST` | `/v1/agents/{agentID}/memory/index-all` | Index all documents |
| `POST` | `/v1/agents/{agentID}/memory/search` | Semantic search |

Optional query parameter `?user_id=` for per-user scoping.

---

## V3 Agent Capabilities

> New in v3. Enable per-agent via [V3 Feature Flags](#v3-feature-flags).

### Evolution

Track tool-usage metrics and receive automated improvement suggestions.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/evolution/metrics` | List raw or aggregated evolution metrics |
| `GET` | `/v1/agents/{agentID}/evolution/suggestions` | List evolution suggestions |
| `PATCH` | `/v1/agents/{agentID}/evolution/suggestions/{suggestionID}` | Update suggestion status (`pending` → `approved`/`rejected`/`rolled_back`) |

**`GET /v1/agents/{agentID}/evolution/metrics` query params:**

| Param | Type | Description |
|-------|------|-------------|
| `type` | string | Filter: `tool`, `retrieval`, `feedback` |
| `aggregate` | boolean | Return aggregated metrics grouped by tool/metric (default: `false`) |
| `since` | ISO 8601 | Start timestamp (default: 7 days ago) |
| `limit` | integer | Max results (default: 100, max: 500) |

**`GET /v1/agents/{agentID}/evolution/suggestions` query params:** `status` (filter: `pending`/`approved`/`applied`/`rejected`/`rolled_back`), `limit`

---

### Episodic Memory

Conversation summaries per user session for long-term context continuity.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/episodic` | List episodic summaries |
| `POST` | `/v1/agents/{agentID}/episodic/search` | Hybrid BM25+vector search over episodic summaries |

**`GET /v1/agents/{agentID}/episodic` query params:** `user_id`, `limit` (default: 20, max: 500), `offset`

**`POST /v1/agents/{agentID}/episodic/search` body:**

```json
{ "query": "Docker optimization", "user_id": "optional", "max_results": 10, "min_score": 0.5 }
```

---

### Knowledge Vault

Persistent document store with vector embeddings and graph link connections.

#### Global Vault Endpoints

Admin-scoped endpoints for cross-agent vault operations.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/vault/documents` | Create a global vault document |
| `PUT` | `/v1/vault/documents/{docID}` | Update a global vault document |
| `DELETE` | `/v1/vault/documents/{docID}` | Delete a global vault document |
| `POST` | `/v1/vault/links` | Create a global document link |
| `DELETE` | `/v1/vault/links/{linkID}` | Delete a global document link |
| `POST` | `/v1/vault/links/batch` | Batch get document links |
| `POST` | `/v1/vault/upload` | Upload file to vault |
| `POST` | `/v1/vault/rescan` | Trigger vault rescan |
| `POST` | `/v1/vault/search` | Global vault semantic search |
| `GET` | `/v1/vault/enrichment/status` | Check enrichment worker status |
| `POST` | `/v1/vault/enrichment/stop` | Stop the enrichment worker for the current agent |
| `GET` | `/v1/vault/documents` | List documents across all agents |
| `GET` | `/v1/vault/tree` | Returns hierarchical tree view of vault document structure |
| `GET` | `/v1/vault/graph` | Returns vault document graph visualization data (cross-tenant, node limit 2000) |

#### Agent-Scoped Vault Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/vault/documents` | List documents for a specific agent |
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}` | Get a single document (full content) |
| `POST` | `/v1/agents/{agentID}/vault/documents` | Create a vault document for an agent |
| `PUT` | `/v1/agents/{agentID}/vault/documents/{docID}` | Update a vault document |
| `DELETE` | `/v1/agents/{agentID}/vault/documents/{docID}` | Delete a vault document |
| `POST` | `/v1/agents/{agentID}/vault/links` | Create a document link |
| `DELETE` | `/v1/agents/{agentID}/vault/links/{linkID}` | Delete a document link |
| `POST` | `/v1/agents/{agentID}/vault/search` | Hybrid FTS+vector search |
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}/links` | Get outlinks and backlinks for a document |

**List query params:** `scope`, `doc_type` (comma-separated), `limit`, `offset`, `agent_id` (cross-agent only)

**Response shape** (list):

```json
{ "documents": [...], "total": 42 }
```

Document objects include a `chat_id` field (nullable string, added in v3.11.0): the specific chat scope — `null` means no chat scope.

**Search body:** `{ "query": "...", "scope": "team", "doc_types": ["guide"], "max_results": 10 }`

---

### Orchestration

Controls how an agent routes requests (standalone, delegation, or team-based).

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/orchestration` | Get current orchestration mode and targets |

**Response:**

```json
{
  "mode": "delegate",
  "delegate_targets": [{"agent_key": "research-agent", "display_name": "Research Specialist"}],
  "team": null
}
```

**Mode values:** `standalone` (direct), `delegate` (routes to agent links), `team` (routes via team task system)

---

### V3 Feature Flags

Per-agent flags controlling v3 subsystems.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/v3-flags` | Get all v3 flags for an agent |
| `PATCH` | `/v1/agents/{agentID}/v3-flags` | Update flags (partial update accepted) |

**Flag keys:** `evolution_enabled`, `episodic_enabled`, `vault_enabled`, `orchestration_enabled`, `skill_evolve`, `self_evolve`

---

## Knowledge Graph

Per-agent entity-relation graph.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/agents/{agentID}/kg/entities` | List/search entities (BM25) |
| `GET` | `/v1/agents/{agentID}/kg/entities/{entityID}` | Get entity with relations |
| `POST` | `/v1/agents/{agentID}/kg/entities` | Upsert entity |
| `DELETE` | `/v1/agents/{agentID}/kg/entities/{entityID}` | Delete entity |
| `POST` | `/v1/agents/{agentID}/kg/traverse` | Traverse graph (max depth 3) |
| `POST` | `/v1/agents/{agentID}/kg/extract` | LLM-powered entity extraction |
| `GET` | `/v1/agents/{agentID}/kg/stats` | Knowledge graph statistics |
| `GET` | `/v1/agents/{agentID}/kg/graph` | Full graph for visualization |
| `GET` | `/v1/agents/{agentID}/kg/graph/compact` | Compact graph representation (lighter payload than full graph) |
| `POST` | `/v1/agents/{agentID}/kg/dedup/scan` | Scan for duplicate entities |
| `GET` | `/v1/agents/{agentID}/kg/dedup` | List dedup candidates |
| `POST` | `/v1/agents/{agentID}/kg/merge` | Merge duplicate entities |
| `POST` | `/v1/agents/{agentID}/kg/dedup/dismiss` | Dismiss a dedup candidate |

---

## Traces

### `GET /v1/traces`

List LLM traces.

```bash
curl "http://localhost:18790/v1/traces?agentId=UUID&q=timeout&min_input_tokens=1000&limit=50" \
  -H "Authorization: Bearer TOKEN"
```

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `agentId` | string | Filter by agent |
| `userId` | string | Filter by user |
| `status` | string | Filter by status |
| `channel` | string | Filter by channel |
| `q` | string | Broad contains-search across trace/span fields |
| `min_input_tokens` / `max_input_tokens` | integer | Filter by input-token range |
| `min_output_tokens` / `max_output_tokens` | integer | Filter by output-token range |
| `tool_name` | string | Filter traces that used a given tool |
| `min_tool_calls` / `max_tool_calls` | integer | Filter by tool-call count range |
| `limit` | integer | Page size |
| `offset` | integer | Page offset |

### `GET /v1/traces/follow`

Poll for trace updates scoped to a single session or agent — designed for live "tail" views. Requires `session_key` **or** `agent_id`. Non-admin callers are restricted to their own traces.

```bash
curl "http://localhost:18790/v1/traces/follow?agent_id=AGENT_UUID&since=2026-06-07T08:00:00Z" \
  -H "Authorization: Bearer TOKEN"
```

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `session_key` | string | Session to follow (required if `agent_id` omitted) |
| `agent_id` | string | Agent to follow (required if `session_key` omitted) |
| `status` | string | Filter by status |
| `channel` | string | Filter by channel |
| `since` | RFC 3339 | Only return traces changed after this time |
| `limit` | integer | Max traces (default 50, max 200) |
| `include_spans` | boolean | Include span details (default `false`) |

### `GET /v1/traces/{traceID}`

Get a single trace with all its spans.

### `GET /v1/traces/{traceID}/export`

Export trace tree as gzipped JSON.

### `GET /v1/runs/{runID}/timeline`

Return the persisted, display-safe archive timeline for a single run — the same entries surfaced in the run/session timeline panel. Tool entries store bounded previews only; raw reasoning is not persisted. Non-admin callers are restricted to their own entries.

### Costs

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/costs/summary` | Cost summary by agent/time range |

---

## Usage & Analytics

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/usage/timeseries` | Time-series usage points |
| `GET` | `/v1/usage/breakdown` | Breakdown by provider/model/channel |
| `GET` | `/v1/usage/summary` | Summary with period comparison |
| `GET` | `/v1/usage/events/timeseries` | Event-based time-series (computed from raw usage events) |
| `GET` | `/v1/usage/events/breakdown` | Event-based breakdown by provider/model/channel |
| `GET` | `/v1/usage/events/summary` | Event-based summary with period comparison |

**Query params:** `from`, `to` (RFC 3339), `agent_id`, `provider`, `model`, `channel`, `group_by`

> The `/v1/usage/events/*` variants compute the same shapes from the raw usage-event store rather than precomputed snapshots — useful for exact, up-to-the-event figures.

---

## Usage Caps

Spend-cap policies that limit token usage and cost per window, optionally scoped to a specific agent, provider, or model. All endpoints require **admin role**; write operations additionally require **tenant-admin**. Policies marked as *managed* (provisioned by the platform) cannot be edited or deleted (`409`).

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/usage-caps/policies` | List spend-cap policies for the current tenant |
| `POST` | `/v1/usage-caps/policies` | Create a policy |
| `PATCH` | `/v1/usage-caps/policies/{id}` | Partial update (all fields optional) |
| `DELETE` | `/v1/usage-caps/policies/{id}` | Delete a policy (`204`) |
| `GET` | `/v1/usage-caps/utilization` | Current utilization per policy |
| `GET` | `/v1/usage-caps/events` | Recent cap events (throttles, breaches) |

### `POST /v1/usage-caps/policies`

```bash
curl -X POST http://localhost:18790/v1/usage-caps/policies \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "window": "day",
    "max_tokens": 1000000,
    "max_cost_usd": 25.0,
    "agent_id": null,
    "provider_id": null,
    "priority": 100,
    "enabled": true
  }'
```

| Field | Type | Description |
|-------|------|-------------|
| `window` | string | Reset window — e.g. `day` (default). Required |
| `max_tokens` | integer | Token cap per window (optional) |
| `max_cost_usd` | float | Cost cap in USD (optional; converted to micros) |
| `max_cost_micros` | integer | Cost cap in micro-dollars — takes precedence over `max_cost_usd` (optional) |
| `agent_id` | UUID | Scope to one agent (optional) |
| `provider_id` | UUID | Scope to one provider (optional) |
| `provider_type` | string | Scope to a provider type (optional) |
| `model_id` | string | Scope to one model (optional) |
| `priority` | integer | Evaluation priority, higher first (default 100) |
| `enabled` | boolean | Default `true` |

Returns `201` with the created policy. `PATCH` accepts the same fields, all optional — send `null` for `max_tokens` / `max_cost_*` to clear a cap.

**`GET /v1/usage-caps/events`** accepts `?limit=` and returns `{ "events": [...] }`. Utilization returns `{ "rows": [...] }`.

---

## Model Pricing

Per-model pricing catalog plus per-tenant overrides, used to compute usage cost. Read endpoints require **admin role**; override writes require **tenant-admin**; the OpenRouter sync requires **master scope**.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/model-pricing` | List the pricing catalog |
| `GET` | `/v1/model-pricing/overrides` | List tenant pricing overrides |
| `PUT` | `/v1/model-pricing/overrides` | Upsert a pricing override |
| `DELETE` | `/v1/model-pricing/overrides/{id}` | Remove an override |
| `POST` | `/v1/model-pricing/sync-openrouter` | Refresh the catalog from OpenRouter (master scope) |

**`GET /v1/model-pricing`** query params: `model` (filter by model ID), `limit` (default 100). Response `{ "models": [...] }`.

**`GET /v1/model-pricing/overrides`** query param: `provider_id` (optional UUID filter). Response `{ "overrides": [...] }`.

### `PUT /v1/model-pricing/overrides`

```bash
curl -X PUT http://localhost:18790/v1/model-pricing/overrides \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "PROVIDER_UUID",
    "provider_type": "openai_compat",
    "model_id": "gpt-4o",
    "pricing": { "...": "..." },
    "enabled": true
  }'
```

| Field | Type | Description |
|-------|------|-------------|
| `provider_id` | UUID | Required |
| `provider_type` | string | Provider type |
| `model_id` | string | Required |
| `pricing` | object | Pricing fields (input/output rates, etc.) |
| `enabled` | boolean | Default `true` |

**`POST /v1/model-pricing/sync-openrouter`** fetches the OpenRouter catalog and upserts it. Response `{ "count": N }`. Returns `502` if the upstream fetch fails.

---

## Browser Cookie Sync

Store selected browser cookies so server-side browser sessions (e.g. the browser tool) can reuse a signed-in state. All endpoints require **operator role**. Cookies are scoped to tenant + user (+ optional agent) and encrypted at rest — `GOCLAW_ENCRYPTION_KEY` must be set, otherwise sync returns `503`.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/browser/cookies/sync` | Upsert cookies for the current scope |
| `GET` | `/v1/browser/cookies` | List stored cookie metadata (values never returned) |
| `DELETE` | `/v1/browser/cookies` | Delete stored cookies in the current scope |

### `POST /v1/browser/cookies/sync`

```bash
curl -X POST http://localhost:18790/v1/browser/cookies/sync \
  -H "Authorization: Bearer TOKEN" \
  -H "X-GoClaw-User-Id: user123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_UUID",
    "source": "chrome-extension",
    "cookies": [
      {
        "domain": "example.com",
        "name": "session",
        "path": "/",
        "value": "abc123",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax",
        "expiresAt": "2026-12-31T00:00:00Z"
      }
    ]
  }'
```

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | string | Optional agent scope (alias: `agent`) |
| `source` | string | Origin label (default `chrome-extension`) |
| `cookies` | array | Cookie items. Required, non-empty, max 200 |

**Cookie item fields:** `domain` (or `url` to derive it), `name`, `path`, `value` (≤ 16 KB), `secure`, `httpOnly` (alias `http_only`), `sameSite` (alias `same_site`), and one of `expiresAt` / `expires_at` / `expirationDate` / `expiration_date`. Total request body is capped at 1 MB.

**Response:** `{ "synced": N }`.

### `GET /v1/browser/cookies`

Returns cookie **metadata** only — values are never exposed. Optional query filters: `agent_id`, `domain`, `name`, `path`. Response `{ "items": [ { "domain", "name", "path", "secure", "httpOnly", "sameSite", "expiresAt", "source", "updatedAt" } ] }`.

### `DELETE /v1/browser/cookies`

Delete cookies in the current scope. Same optional filters as the list endpoint. Response `{ "deleted": N }`.

---

## MCP Servers

### `GET /v1/mcp/servers`

List all MCP server configurations.

### `POST /v1/mcp/servers`

Register an MCP server.

```bash
curl -X POST http://localhost:18790/v1/mcp/servers \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    "enabled": true
  }'
```

Transport options: `"stdio"`, `"sse"`, `"streamable-http"`.

### `GET /v1/mcp/servers/{id}`

Get an MCP server.

### `PUT /v1/mcp/servers/{id}`

Update an MCP server. Updatable fields:

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Server display name |
| `transport` | string | `"stdio"`, `"sse"`, `"streamable-http"` |
| `command` | string | Command to run (stdio) |
| `args` | string[] | Command arguments |
| `url` | string | Server URL (sse/streamable-http) |
| `api_key` | string | API key for the server |
| `env` | object | Environment variables |
| `headers` | object | HTTP headers |
| `enabled` | boolean | Enable/disable |
| `tool_prefix` | string | Prefix for tool names |
| `timeout_sec` | integer | Request timeout in seconds |
| `agent_id` | string | Bind to specific agent |
| `config` | object | Additional configuration |
| `settings` | object | Server settings |

### `DELETE /v1/mcp/servers/{id}`

Delete an MCP server.

### `POST /v1/mcp/servers/test`

Test connectivity to an MCP server before saving.

### `POST /v1/mcp/servers/{id}/reconnect`

Force reconnect a running MCP server.

### `GET /v1/mcp/servers/{id}/tools`

List tools discovered from a running MCP server.

### MCP Grants

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/mcp/servers/{id}/grants` | List grants for a server |
| `POST` | `/v1/mcp/servers/{id}/grants/agent` | Grant server to an agent |
| `DELETE` | `/v1/mcp/servers/{id}/grants/agent/{agentID}` | Revoke agent grant |
| `GET` | `/v1/mcp/grants/agent/{agentID}` | List all grants for an agent |
| `POST` | `/v1/mcp/servers/{id}/grants/user` | Grant server to a user |
| `DELETE` | `/v1/mcp/servers/{id}/grants/user/{userID}` | Revoke user grant |

### MCP Access Requests

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/mcp/requests` | Submit an access request |
| `GET` | `/v1/mcp/requests` | List pending requests |
| `POST` | `/v1/mcp/requests/{id}/review` | Approve or reject a request |

### MCP Export / Import

Export and import MCP server configurations and agent grants as a tar.gz archive.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/mcp/export/preview` | Preview export counts (no archive built) |
| `GET` | `/v1/mcp/export` | Download MCP archive directly (tar.gz) |
| `POST` | `/v1/mcp/import` | Import MCP archive (multipart `file` field) |

### MCP User Credentials

Per-user credential storage for MCP servers that require individual authentication.

| Method | Path | Description |
|--------|------|-------------|
| `PUT` | `/v1/mcp/servers/{id}/user-credentials` | Set user credentials for a server |
| `GET` | `/v1/mcp/servers/{id}/user-credentials` | Get user credentials |
| `DELETE` | `/v1/mcp/servers/{id}/user-credentials` | Delete user credentials |

**Query params for export:**

| Param | Type | Description |
|-------|------|-------------|
| `stream` | `bool` | When `true`, returns SSE progress events then a `complete` event with `download_url` |

**Archive format** (`mcp-servers-YYYYMMDD.tar.gz`):

```
servers.jsonl   — MCP server definitions
grants.jsonl    — agent grants (server_name + agent_key)
```

**Import response** (`201 Created`):

```json
{
  "servers_imported": 2,
  "servers_skipped": 0,
  "grants_applied": 4
}
```

---

## Channel Instances

### `GET /v1/channels/instances`

List all channel instances from the database.

### `POST /v1/channels/instances`

Create a channel instance.

```bash
curl -X POST http://localhost:18790/v1/channels/instances \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-telegram-bot",
    "channel_type": "telegram",
    "agent_id": "AGENT_UUID",
    "credentials": { "token": "BOT_TOKEN" },
    "enabled": true
  }'
```

**Supported channels:** `telegram`, `discord`, `slack`, `whatsapp`, `zalo_oa`, `zalo_personal`, `feishu`

### `GET /v1/channels/instances/{id}`

Get a channel instance.

### `PUT /v1/channels/instances/{id}`

Update a channel instance. Updatable fields:

| Field | Type | Description |
|-------|------|-------------|
| `channel_type` | string | Channel type |
| `credentials` | object | Channel credentials |
| `agent_id` | string | Bound agent UUID |
| `enabled` | boolean | Enable/disable |
| `display_name` | string | Human-readable name |
| `group_policy` | string | Group message policy |
| `allow_from` | string[] | Allowed sender IDs |
| `metadata` | object | Custom metadata |
| `webhook_secret` | string | Webhook verification secret |
| `config` | object | Additional configuration |

### `DELETE /v1/channels/instances/{id}`

Delete a channel instance.

### Group Writers

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/channels/instances/{id}/writers/groups` | List groups with write permissions |
| `GET` | `/v1/channels/instances/{id}/writers` | List authorized writers |
| `POST` | `/v1/channels/instances/{id}/writers/test` | Test whether a user would be allowed to write to a group (no mutation) |
| `POST` | `/v1/channels/instances/{id}/writers` | Add a writer |
| `DELETE` | `/v1/channels/instances/{id}/writers/{userId}` | Remove a writer |

**`POST .../writers/test`** — dry-run a writer check before persisting one. Body `{ "group_id": "...", "user_id": "..." }` (both required). Always returns `200` with the evaluation:

```json
{
  "allowed": true,
  "reason": "writer",
  "instance_id": "uuid",
  "agent_id": "uuid",
  "group_id": "telegram:-100123",
  "user_id": "user123",
  "writer_count": 3
}
```

`reason` is one of `writer`, `not_writer`, `no_writers_configured`, or `invalid_group`.

### Passive Memory Extraction

Per-channel-instance passive memory extraction — mine recent conversations into review-queued memory candidates, then approve them into episodic memory. Read endpoints are viewer-accessible; settings and item transitions require **tenant-admin**.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/channels/instances/{id}/memory-extraction` | Config + latest run + pending count + recent items |
| `PUT` | `/v1/channels/instances/{id}/memory-extraction/settings` | Replace the normalized `passive_memory` config block |
| `POST` | `/v1/channels/instances/{id}/memory-extraction/run` | Trigger a manual extraction run |
| `GET` | `/v1/channels/instances/{id}/memory-extraction/items` | List review-queue items (optional `status` filter) |
| `POST` | `/v1/channels/instances/{id}/memory-extraction/items/{itemID}/approve` | Write candidate to episodic memory + publish KG event |
| `POST` | `/v1/channels/instances/{id}/memory-extraction/items/{itemID}/reject` | Reject candidate |
| `DELETE` | `/v1/channels/instances/{id}/memory-extraction/items/{itemID}` | Delete candidate (and any linked episodic summary) |

**`passive_memory` config fields:** `enabled`, `review_mode`, `interval_minutes`, `message_cap`, `retention_hours`, `allowed_types`, `exclude_users`, `exclude_patterns`, `min_messages`, `group_only`. Defaults: disabled, review-mode on, group-only, 360-minute interval, 100-message cap, 168-hour retention, and durable types (people, projects, decisions, todos, preferences, events).

### Context Capability Administration

Manage per-context (per scope) tool access for a channel instance. A context is identified by `{scopeType}/{scopeKey}` (e.g. a group or DM). Grant/credential routes require **admin role**; list/capabilities reads are viewer-accessible.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/channels/instances/{id}/contexts` | List contexts for the instance |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/members` | List members of a context |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/capabilities` | Effective capabilities resolved for the context |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-grants` | List MCP server grants |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-grants/{serverID}` | Set an MCP grant |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-grants/{serverID}` | Remove an MCP grant |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-credentials` | List MCP credentials |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-credentials/{serverID}` | Set an MCP credential |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-credentials/{serverID}` | Remove an MCP credential |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-grants` | List CLI binary grants |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-grants/{binaryID}` | Set a CLI grant |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-grants/{binaryID}` | Remove a CLI grant |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-credentials` | List CLI credentials |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-credentials/{binaryID}` | Set a CLI credential |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-credentials/{binaryID}` | Remove a CLI credential |

---

## Contacts

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/contacts` | List contacts (paginated) |
| `GET` | `/v1/contacts/resolve` | Resolve contacts by IDs (query string `ids=` repeated; max 100) |
| `POST` | `/v1/contacts/merge` | Merge duplicate contact records |
| `POST` | `/v1/contacts/unmerge` | Unmerge previously merged contacts |
| `GET` | `/v1/contacts/merged/{tenantUserId}` | List merged contacts for a tenant user |

### Tenant Users

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/tenant-users` | List tenant users |
| `GET` | `/v1/users/search` | Search users across channels |

---

## Team Events

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/teams/{id}/events` | List team events (paginated) |

### Team Workspace

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/teams/{teamId}/workspace/upload` | Upload file to team workspace |
| `PUT` | `/v1/teams/{teamId}/workspace/move` | Move/rename file in team workspace |

### Team Attachments

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/teams/{teamId}/attachments/{attachmentId}/download` | Download task attachment |

---

## Team Export / Import

Export and import a complete team (team metadata + all member agents) as a tar.gz archive.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/teams/{id}/export/preview` | Preview export counts (members, tasks, agent_links) without building archive |
| `GET` | `/v1/teams/{id}/export` | Download team archive directly (tar.gz) |
| `POST` | `/v1/teams/import` | Import team archive, creating new agents and wiring the team (multipart `file` field) |

**Export query params:**

| Param | Type | Description |
|-------|------|-------------|
| `stream` | `bool` | When `true`, returns SSE progress events then a `complete` event with `download_url` |

**Archive format** (`team-{name}-YYYYMMDD.tar.gz`):

```
manifest.json                          — archive manifest (team_name, agent_keys, sections)
team/team.json                         — team metadata
team/members.jsonl                     — team member records
team/tasks.jsonl                       — team task records
team/comments.jsonl                    — task comments
team/events.jsonl                      — task events
team/links.jsonl                       — agent link records
team/workspace/                        — team workspace files
agents/{agent_key}/agent.json          — per-agent config
agents/{agent_key}/context_files/      — per-agent context files
agents/{agent_key}/memory/             — per-agent memory documents
agents/{agent_key}/knowledge_graph/    — per-agent KG entities + relations
agents/{agent_key}/cron/               — per-agent cron jobs
agents/{agent_key}/workspace/          — per-agent workspace files
```

**Import response** (`201 Created`):

```json
{
  "team_name": "research-team",
  "agents_added": 3,
  "agent_keys": ["researcher", "writer", "reviewer"]
}
```

> Import requires **admin role**. Agent keys are deduplicated if they already exist (suffixed `-2`, `-3`, …). Cron jobs are always imported as disabled.

Also available as a shared download endpoint (shared with agent export tokens):

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/export/download/{token}` | Download a prepared archive by short-lived token (valid 5 min, any export type) |

---

## Pending Messages

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/pending-messages` | List all groups with titles |
| `GET` | `/v1/pending-messages/messages` | List messages by channel+key |
| `DELETE` | `/v1/pending-messages` | Delete message group |
| `POST` | `/v1/pending-messages/compact` | LLM-based summarization (async, 202) |

---

## Secure CLI Credentials

Requires **admin role** (full gateway token or empty gateway token in dev/single-user mode).

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cli-credentials` | List all credentials |
| `POST` | `/v1/cli-credentials` | Create new credential |
| `GET` | `/v1/cli-credentials/{id}` | Get credential details |
| `PUT` | `/v1/cli-credentials/{id}` | Update credential |
| `DELETE` | `/v1/cli-credentials/{id}` | Delete credential |
| `GET` | `/v1/cli-credentials/presets` | Get preset credential templates |
| `POST` | `/v1/cli-credentials/{id}/test` | Test credential connection (dry-run) |
| `POST` | `/v1/cli-credentials/check-binary` | Validate a binary path for CLI credential use |

### Per-User CLI Credentials

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cli-credentials/{id}/user-credentials` | List user credentials for a CLI config |
| `GET` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Get user-specific credentials |
| `PUT` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Set user-specific credentials |
| `DELETE` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Delete user-specific credentials |

### Per-Agent CLI Credentials

Agent-scoped credential storage for a CLI config — store the credential values an individual agent should use. This is **distinct from [CLI Credential Agent Grants](#cli-credential-agent-grants)** below: grants control *whether* an agent may use a binary (with arg/timeout restrictions), while these endpoints store the agent's actual credential payload.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cli-credentials/{id}/agent-credentials` | List agent-scoped credentials for a CLI config |
| `GET` | `/v1/cli-credentials/{id}/agent-credentials/{agentId}` | Get agent credential metadata |
| `PUT` | `/v1/cli-credentials/{id}/agent-credentials/{agentId}` | Create or replace an agent credential |
| `DELETE` | `/v1/cli-credentials/{id}/agent-credentials/{agentId}` | Delete an agent credential |

### CLI Credential Agent Grants

Per-agent binary grants — control which agents can use a specific CLI credential binary, with optional restrictions on arguments, verbosity, and timeout. Requires **admin role**.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/cli-credentials/{id}/agent-grants` | List all agent grants for a credential |
| `POST` | `/v1/cli-credentials/{id}/agent-grants` | Create an agent grant |
| `GET` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Get a specific grant |
| `PUT` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Update a grant |
| `DELETE` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Delete a grant |
| `POST` | `/v1/cli-credentials/{id}/agent-grants/{grantId}/env:reveal` | Reveal decrypted env vars for a grant (rate-limited; never cacheable — POST chosen over GET for CSRF safety) |

**Create/update grant fields:**

| Field | Type | Description |
|-------|------|-------------|
| `agent_id` | UUID | Agent to grant access (required on create) |
| `env_vars` | object | Per-grant env-var overrides (plaintext on input; encrypted at rest via `GOCLAW_ENCRYPTION_KEY`; only key names ever returned in list/get responses) |
| `deny_args` | JSON | Argument restrictions (optional) |
| `deny_verbose` | JSON | Verbose output restrictions (optional) |
| `timeout_seconds` | integer | Per-agent execution timeout override (optional) |
| `tips` | string | Usage hints for the agent (optional) |
| `enabled` | boolean | Enable/disable the grant (default: `true`) |

**Create response** (`201 Created`): the created grant object (no plaintext env values — only `env_keys` + `env_set`).

> **`env:reveal`** returns the decrypted plaintext for the grant's env vars. The endpoint is rate-limited per credential (configurable RPM + burst) and audited. Requires `GOCLAW_ENCRYPTION_KEY` to be set; otherwise grants store unencrypted env on disk only when explicitly configured to do so.

Changes to grants emit a `cache_invalidate` event on the message bus so connected agents pick up the update immediately.

---

## Text-to-Speech (TTS)

Per-tenant TTS synthesis and configuration. Requires `RoleOperator` for synthesis/test endpoints and `RoleAdmin` for config endpoints.

### `POST /v1/tts/synthesize`

Convert text to audio using the configured TTS provider.

**Request body:**

```json
{
  "text": "Hello, world!",
  "provider": "openai",
  "voice_id": "alloy",
  "model_id": "tts-1"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `text` | string | Text to synthesize. Required. Max 500 characters. |
| `provider` | string | Override provider (`openai`, `elevenlabs`, `minimax`, `edge`, `gemini`). Optional — defaults to tenant-configured provider. |
| `voice_id` | string | Voice identifier. Optional. |
| `model_id` | string | Model identifier. Optional. |

**Response:** Raw audio bytes with `Content-Type` matching the provider's MIME type (e.g., `audio/mpeg`).

**Errors:** `400` text empty or exceeds limit · `404` no provider configured · `422` invalid model or params · `429` rate limited · `504` synthesis timeout

### `POST /v1/tts/test-connection`

Test connectivity to a TTS provider using supplied credentials (does not persist config). Supports the same provider set as synthesize. Pass `"***"` as `api_key` to re-test a previously saved key without retyping it.

**Request body:**

```json
{
  "provider": "openai",
  "api_key": "sk-...",
  "api_base": "",
  "voice_id": "alloy",
  "model_id": "tts-1",
  "group_id": "",
  "timeout_ms": 10000
}
```

| Field | Type | Description |
|-------|------|-------------|
| `provider` | string | Required. One of `openai`, `elevenlabs`, `minimax`, `edge`, `gemini`. |
| `api_key` | string | API key. Required for all providers except `edge`. Pass `"***"` to reuse a stored key. |
| `api_base` | string | Custom API base URL. Optional. |
| `voice_id` | string | Voice identifier. Optional. |
| `model_id` | string | Model identifier. Optional. |
| `group_id` | string | MiniMax group ID. Required for `minimax`. |
| `rate` | string | Speech rate (Edge TTS only). Optional. |
| `timeout_ms` | integer | Request timeout in ms. Optional (default: 10 000). |
| `params` | object | Provider-specific params blob. Optional. |

**Response:**

```json
{
  "success": true,
  "provider": "openai",
  "latency_ms": 312
}
```

On failure: `{"success": false, "error": "..."}`

**Errors:** `400` missing required fields · `422` invalid voice/model/params · `504` test timeout · `502` upstream error

### `GET /v1/tts/capabilities`

Return the static capability catalog for every known TTS provider — independent of which providers are configured at runtime. Use this to render per-provider param editors before saving credentials.

**Response:**

```json
{
  "providers": [
    {
      "provider": "openai",
      "models": ["tts-1", "tts-1-hd"],
      "params": [
        { "key": "speed", "type": "float", "min": 0.25, "max": 4.0, "default": 1.0 }
      ]
    },
    ...
  ]
}
```

Each entry in `params` has: `key`, `type` (`string`|`float`|`int`|`bool`|`enum`), optional `min`/`max`/`default`/`enum_values`, and optional `depends_on` condition.

**Auth:** `RoleOperator`

### `GET /v1/tts/config`

Return the current tenant's TTS configuration. API keys are masked as `"***"`. Requires `RoleAdmin` and a valid tenant context.

**Response:**

```json
{
  "provider": "openai",
  "auto": "off",
  "mode": "final",
  "max_length": 1500,
  "timeout_ms": 30000,
  "openai": { "api_key": "***", "api_base": "", "voice": "alloy", "model": "tts-1" },
  "elevenlabs": { "api_key": "***", "voice_id": "", "model_id": "" },
  "edge": { "voice_id": "", "rate": "" },
  "minimax": { "api_key": "***", "group_id": "", "voice_id": "", "model_id": "" },
  "gemini": { "api_key": "***", "voice_id": "", "model_id": "" }
}
```

### `POST /v1/tts/config`

Save TTS configuration for the current tenant. Requires `RoleAdmin`.

**Request body:**

```json
{
  "provider": "openai",
  "auto": "off",
  "mode": "final",
  "max_length": 1500,
  "timeout_ms": 30000,
  "openai": {
    "api_key": "sk-...",
    "api_base": "",
    "voice": "alloy",
    "model": "tts-1",
    "params": {}
  },
  "gemini": {
    "api_key": "...",
    "voice_id": "Aoede",
    "model_id": "gemini-2.5-flash-preview-tts",
    "speakers": "[{\"name\":\"Speaker1\",\"voice\":\"Aoede\"}]"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `provider` | string | Active TTS provider slug. |
| `auto` | string | Auto-apply mode: `off`, `final`, `all`. |
| `mode` | string | Synthesis trigger: `final` (end of turn) or `chunk` (streaming). |
| `max_length` | integer | Max characters per synthesis call. |
| `timeout_ms` | integer | Provider request timeout in ms. |
| `{provider}` | object | Per-provider config. `api_key: "***"` leaves stored key unchanged. |
| `{provider}.params` | object | Provider-specific params blob (validated against capability schema). |
| `gemini.speakers` | string | JSON-encoded `[]SpeakerVoice` for Gemini multi-speaker mode. |

**Response:** `{ "ok": true }`

---

## Voices

Voice list discovery for TTS providers with tenant-scoped caching. Supports ElevenLabs and MiniMax. Requires a configured API key for the requested provider in TTS config.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/voices` | List available voices (served from cache; fetches live on cache miss) |
| `POST` | `/v1/voices/refresh` | Invalidate the voice cache and re-fetch live voices. Requires admin role. |

**Query params (`GET /v1/voices`):**

| Param | Type | Description |
|-------|------|-------------|
| `provider` | string | Voice provider: `elevenlabs` (default) or `minimax`. |

**`GET /v1/voices` response:**

```json
{
  "voices": [
    { "voice_id": "21m00Tcm4TlvDq8ikWAM", "name": "Rachel", "preview_url": "https://..." },
    ...
  ]
}
```

Returns `404` when no API key is configured for the requested provider. Returns `502` when the provider API call fails.

---

## Runtime & Packages

Manage system (apk), Python (pip), and Node (npm) packages. Requires authentication.

### `GET /v1/packages`

List all installed packages grouped by category (system, pip, npm).

### `POST /v1/packages/install`

```json
{ "package": "github-cli" }
```

Use prefix `"pip:pandas"` or `"npm:typescript"` to target a specific manager. Without prefix, defaults to system (apk).

### `POST /v1/packages/uninstall`

Same format as install.

### `GET /v1/packages/runtimes`

Check if Python and Node runtimes are available.

```json
{ "python": true, "node": true }
```

### `GET /v1/packages/github-releases`

List GitHub releases for a repository (used by the package picker UI). Auth: viewer+.

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `repo` | string | Repository in `owner/repo` format. Required. |
| `limit` | integer | Max releases to return (1–50, default 10). |

**Response:**

```json
{
  "releases": [
    {
      "tag": "v2.40.1",
      "name": "GitHub CLI 2.40.1",
      "published_at": "2024-01-15T12:00:00Z",
      "prerelease": false,
      "matching_assets": [{ "name": "gh_2.40.1_linux_amd64.tar.gz", "size_bytes": 10485760 }],
      "all_assets_count": 12
    }
  ]
}
```

`matching_assets` contains the asset matching the server's OS/arch (empty if no match). Draft releases are excluded.

### `GET /v1/shell-deny-groups`

List shell command deny groups (security policy).

### Package Updates

Watch and apply package updates across system / pip / npm registries. Read access requires viewer+; writes require admin.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/packages/updates` | List pending updates discovered from each registry |
| `POST` | `/v1/packages/updates/refresh` | Force-refresh the update registry cache |
| `POST` | `/v1/packages/update` | Apply a single update — body `{ "package": "pip:pandas" }` |
| `POST` | `/v1/packages/updates/apply-all` | Apply every pending update (long-running; returns SSE progress when `?stream=true`) |

Updates emit `cache_invalidate` events on the bus so connected clients refresh their package lists.

---

## Storage

Workspace file management.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/storage/files` | List files with depth limiting |
| `GET` | `/v1/storage/files/{path...}` | Read file (JSON or raw) |
| `POST` | `/v1/storage/files` | Upload file to workspace (admin) |
| `DELETE` | `/v1/storage/files/{path...}` | Delete file/directory |
| `PUT` | `/v1/storage/move` | Move/rename a file or directory (admin) |
| `GET` | `/v1/storage/size` | Stream storage size (SSE, cached 60 min) |

`?raw=true` — serve native MIME type. `?depth=N` — limit traversal depth.

---

## Media

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/media/upload` | Upload file (multipart, 50 MB limit) |
| `GET` | `/v1/media/{id}` | Serve media by ID with caching |

Auth via Bearer token or `?token=` query param (for `<img>` and `<audio>` tags).

---

## Files

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/files/{path...}` | Serve workspace file by path |
| `POST` | `/v1/files/sign` | Generate signed URL for file access |

**Query parameters:**

| Param | Type | Description |
|-------|------|-------------|
| `download` | `bool` | When `true`, forces `Content-Disposition: attachment` (browser download instead of inline display) |

---

## API Keys

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/api-keys` | List all API keys (masked) |
| `POST` | `/v1/api-keys` | Create API key (returns raw key once) |
| `POST` | `/v1/api-keys/{id}/revoke` | Revoke API key |

### Create Request

```json
{
  "name": "ci-deploy",
  "scopes": ["operator.read", "operator.write"],
  "expires_in": 2592000
}
```

The `key` field is only returned in the create response. Subsequent calls show only the `prefix`.

---

## OAuth

### Per-Provider ChatGPT/Codex OAuth

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/auth/chatgpt/{provider}/status` | Check OAuth status for a provider |
| `GET` | `/v1/auth/chatgpt/{provider}/quota` | Fetch Codex/OpenAI quota state |
| `POST` | `/v1/auth/chatgpt/{provider}/start` | Start OAuth flow for a provider |
| `POST` | `/v1/auth/chatgpt/{provider}/callback` | Manual callback handler |
| `POST` | `/v1/auth/chatgpt/{provider}/logout` | Revoke OAuth token for a provider |

### Legacy OpenAI Aliases

Compatibility aliases for the default `openai-codex` provider:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/auth/openai/status` | Check OpenAI OAuth status |
| `GET` | `/v1/auth/openai/quota` | Fetch quota state |
| `POST` | `/v1/auth/openai/start` | Initiate OAuth flow |
| `POST` | `/v1/auth/openai/callback` | Handle OAuth callback manually |
| `POST` | `/v1/auth/openai/logout` | Remove stored OAuth tokens |

---

## Tenants

Multi-tenant management (gateway token scope only).

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/tenants` | List tenants |
| `POST` | `/v1/tenants` | Create tenant |
| `GET` | `/v1/tenants/{id}` | Get tenant |
| `PATCH` | `/v1/tenants/{id}` | Update tenant |
| `GET` | `/v1/tenants/{id}/users` | List tenant users |
| `POST` | `/v1/tenants/{id}/users` | Add user to tenant |
| `DELETE` | `/v1/tenants/{id}/users/{userId}` | Remove user from tenant |

---

## Backup & Restore

### System Backup (Admin)

Full system backup for disaster recovery. Requires admin role.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/system/backup` | Trigger system backup (returns archive or SSE progress) |
| `GET` | `/v1/system/backup/preflight` | Check backup preconditions |
| `GET` | `/v1/system/backup/download/{token}` | Download backup archive by short-lived token |

### System Restore (Admin)

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/system/restore` | Restore tenant/system from backup archive. Requires admin role. |

### System Backup S3

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/system/backup/s3/config` | Get S3 backup configuration |
| `PUT` | `/v1/system/backup/s3/config` | Update S3 backup configuration |
| `GET` | `/v1/system/backup/s3/list` | List available S3 backup archives |
| `POST` | `/v1/system/backup/s3/upload` | Upload local backup to S3 |
| `POST` | `/v1/system/backup/s3/backup` | Trigger backup directly to S3 |

### Tenant Backup

Per-tenant backup and restore. Admin role required.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/tenant/backup` | Trigger tenant backup (returns archive or SSE progress) |
| `GET` | `/v1/tenant/backup/preflight` | Check tenant backup preconditions |
| `GET` | `/v1/tenant/backup/download/{token}` | Download tenant backup archive by short-lived token |
| `POST` | `/v1/tenant/restore` | Restore tenant from a backup archive |

---

## Activity & Audit

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/activity` | List activity audit logs (filterable) |
| `GET` | `/v1/activity/aggregate` | Aggregated activity counts grouped by a dimension |

### `GET /v1/activity/aggregate`

Return activity counts grouped by a dimension instead of raw rows. Non-admin callers are scoped to their own actor ID; grouping by `actor_id` requires admin role.

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `group_by` | string | Grouping dimension — e.g. `action`, `entity_type`, `actor_type`, `actor_id` (admin only) |
| `actor_type` | string | Filter by actor type |
| `actor_id` | string | Filter by actor ID |
| `action` | string | Filter by action |
| `entity_type` | string | Filter by entity type |
| `entity_id` | string | Filter by entity ID |
| `from` | RFC 3339 | Start of time window |
| `to` | RFC 3339 | End of time window (must be after `from`) |
| `limit` | integer | Max groups returned |

---

## Runtime Logs

Aggregated view of the in-memory runtime log buffer. Requires **admin role**.

### `GET /v1/logs/runtime/aggregate`

Return runtime log counts grouped by `level` or `source`.

```bash
curl "http://localhost:18790/v1/logs/runtime/aggregate?group_by=level" \
  -H "Authorization: Bearer TOKEN"
```

**Query params:**

| Param | Type | Description |
|-------|------|-------------|
| `group_by` | string | `level` (default) or `source` |
| `level` | string | Filter by log level |
| `source` | string | Filter by log source |
| `from` | RFC 3339 | Only count entries after this time |

> Live tailing of server logs is available over WebSocket via `logs.tail` — see [WebSocket Protocol](/websocket-protocol#logs).

---

## System Configs

Per-tenant key-value configuration store. Read access for all authenticated users; write access requires admin role.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/system-configs` | List all config entries for current tenant |
| `GET` | `/v1/system-configs/{key}` | Get a single config value by key |
| `PUT` | `/v1/system-configs/{key}` | Set a config value (admin only) |
| `DELETE` | `/v1/system-configs/{key}` | Delete a config entry (admin only) |

---

## Edition

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/edition` | Get current edition info and feature limits |

---

## MCP Bridge

Exposes GoClaw tools to Claude CLI via streamable HTTP at `/mcp/bridge`. Only listens on localhost. Protected by gateway token with HMAC-signed context headers.

| Header | Purpose |
|--------|---------|
| `X-Agent-ID` | Agent context for tool execution |
| `X-User-ID` | User context |
| `X-Channel` | Channel routing |
| `X-Chat-ID` | Chat routing |
| `X-Peer-Kind` | `direct` or `group` |
| `X-Bridge-Sig` | HMAC signature over all context fields |

---

## Workstations

> **Standard edition only.** Gateway routes return `403` on Lite. Requires admin role.

Workstations are remote execution endpoints (SSH or Docker) that agents can target for sandboxed command execution. Each workstation has an allowlist of permitted command patterns and a tamper-evident activity audit log.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/workstations` | List workstations for the current tenant |
| `POST` | `/v1/workstations` | Create a workstation |
| `GET` | `/v1/workstations/{id}` | Get a workstation by ID |
| `PUT` | `/v1/workstations/{id}` | Update a workstation |
| `DELETE` | `/v1/workstations/{id}` | Delete a workstation |
| `POST` | `/v1/workstations/{id}/test` | Test connectivity (SSH probe or `docker ps`) — does not execute commands |
| `GET` | `/v1/workstations/{id}/permissions` | List allowlist patterns |
| `POST` | `/v1/workstations/{id}/permissions` | Add an allowlist pattern |
| `DELETE` | `/v1/workstations/{id}/permissions/{permId}` | Remove a pattern |
| `PUT` | `/v1/workstations/{id}/permissions/{permId}/toggle` | Enable/disable a pattern without deleting |
| `GET` | `/v1/workstations/{id}/activity` | List activity audit entries (filterable, paginated) |

**Create body:**

```json
{
  "workstation_key": "build-host",
  "name": "Build host",
  "backend_type": "ssh",
  "metadata": {
    "host": "build.internal",
    "port": 22,
    "user": "claw",
    "private_key_ref": "kms://..."
  },
  "default_cwd": "/srv/builds",
  "default_env": {"PATH": "/usr/local/bin:/usr/bin"}
}
```

| Field | Type | Description |
|-------|------|-------------|
| `workstation_key` | string | Stable client-facing key — unique per tenant |
| `name` | string | Display name |
| `backend_type` | enum | `ssh` or `docker` (DB CHECK constraint) |
| `metadata` | object | Backend-specific connection config — encrypted at rest |
| `default_cwd` | string | Default working directory for exec calls |
| `default_env` | object | Env vars merged into every exec — encrypted at rest |
| `active` | boolean | Workstation is selectable for agent linking |

**Activity log entries:**

| Field | Type | Description |
|-------|------|-------------|
| `action` | enum | `exec` (ran) or `deny` (rejected by allowlist) |
| `cmd_hash` | string | SHA-256 of the full command line |
| `cmd_preview` | string | First 200 bytes of the command (truncated, no secrets) |
| `exit_code` | integer | Process exit code (nullable for `deny`) |
| `duration_ms` | integer | Wall time (nullable for `deny`) |
| `agent_id` | UUID | Agent that initiated the call |

> Workstation backends share a single per-tenant rate limit and obey the global shell deny-groups list.

---

## Webhooks

Two surfaces:

1. **Inbound webhook endpoints** — receive HMAC-signed requests from external systems and route them through agents or channels. No bearer token required; auth is performed via `X-GoClaw-Signature` (HMAC-SHA256) + IP allowlist + optional `localhost_only` gate.
2. **Webhook administration** — CRUD over the webhook registry. Requires admin role and gateway token.

> Inbound webhooks require `GOCLAW_ENCRYPTION_KEY` to be set so secrets can be stored encrypted at rest. See [Environment Variables](environment-variables.md#secrets).

### Inbound Receivers

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/webhooks/llm` | LLM-kind webhook entrypoint (OpenAI-compatible payload routed to the configured agent) |
| `POST` | `/v1/webhooks/message` | Message-kind webhook entrypoint (delivers to a channel/chat) |

Both receivers require headers:

| Header | Purpose |
|--------|---------|
| `X-GoClaw-Webhook-Id` | Webhook UUID |
| `X-GoClaw-Signature` | `sha256=...` HMAC of the raw body using the webhook's signing key |
| `X-GoClaw-Timestamp` | RFC3339 timestamp (≤ 5 min skew) |
| `Idempotency-Key` | Optional — dedupes repeated deliveries (TTL stored in `webhook_calls`) |

Mode is selected via the query string `?mode=sync|async` (default `sync` for `llm`, `async` for `message`).

### Webhook Administration

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/webhooks` | List webhooks for the current tenant |
| `POST` | `/v1/webhooks` | Create a webhook — response includes one-time `secret` + `hmac_signing_key` |
| `GET` | `/v1/webhooks/{id}` | Get a webhook (`secret` is never returned again after creation) |
| `PATCH` | `/v1/webhooks/{id}` | Update mutable fields (scopes, rate limits, allowlist, flags) |
| `POST` | `/v1/webhooks/{id}/rotate` | Rotate signing key — returns the new secret once |
| `DELETE` | `/v1/webhooks/{id}` | Revoke a webhook (soft-delete; sets `revoked=true`) |

**Create body:**

```json
{
  "name": "Datadog incidents",
  "kind": "message",
  "agent_id": "uuid (required for kind=llm)",
  "channel_id": "uuid (required for kind=message)",
  "scopes": ["chat.send"],
  "rate_limit_per_min": 60,
  "ip_allowlist": ["10.0.0.0/8", "203.0.113.42"],
  "require_hmac": true,
  "localhost_only": false
}
```

| Field | Type | Description |
|-------|------|-------------|
| `kind` | enum | `llm` or `message` (DB CHECK constraint) |
| `agent_id` | UUID | Required for `llm`; ignored for `message` |
| `channel_id` | UUID | Required for `message`; ignored for `llm` |
| `scopes` | string[] | Permission scopes the inbound request can exercise (default minimal) |
| `rate_limit_per_min` | integer | Per-webhook rate limit (default tenant-wide cap) |
| `ip_allowlist` | string[] | CIDR or single-IP entries; empty = no IP restriction |
| `require_hmac` | boolean | Enforce HMAC signature (default `true`) |
| `localhost_only` | boolean | Reject non-loopback callers (Lite edition forces `true`) |

**Create response** (`201 Created`):

```json
{
  "id": "uuid",
  "secret": "wh_...",
  "hmac_signing_key": "raw 32-byte hex",
  "secret_prefix": "wh_xxxx",
  "kind": "message",
  "...": "..."
}
```

> `secret` and `hmac_signing_key` are returned **only on create and rotate**. Subsequent GETs expose `secret_prefix` (first 4 chars) and a one-way `secret_hash`. The `webhook_calls` table records every delivery with `attempts`, `status` (`queued|running|done|failed|dead`), `mode` (`sync|async`), `delivery_id`, and an optional `lease_token` for async lease-based dispatch.

---

## Gateway Self-Upgrade

Admin-only self-upgrade flow that downloads a signed release archive and restarts the gateway process in-place.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/system/gateway/upgrade` | Trigger an upgrade — body `{ "target_version": "v3.12.0" }` or omitted for latest |
| `GET` | `/v1/system/gateway/upgrade/status` | Poll upgrade progress (`idle | downloading | verifying | applying | restarting | done | failed`) |

> Upgrade is a one-way operation; restore from backup if a release proves bad. The endpoint refuses to run when the gateway is launched without write access to its own binary.

---

## System

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check (no auth) |
| `GET` | `/v1/openapi.json` | OpenAPI 3.0 spec |
| `GET` | `/docs` | Swagger UI |

---

## Common Response Shapes

**Success:**
```json
{ "id": "uuid", "name": "...", ... }
```

**Error:**
```json
{
  "error": {
    "code": "ERR_AGENT_NOT_FOUND",
    "message": "Agent not found. Verify the agent ID and try again."
  }
}
```

Error responses use a structured envelope with `code` (machine-readable error type) and `message` (human-readable, i18n-translated).

| Code | Meaning |
|------|---------|
| `200` | OK |
| `201` | Created |
| `400` | Bad request (invalid JSON, missing fields) |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not found |
| `409` | Conflict (duplicate name) |
| `429` | Rate limited |
| `500` | Internal server error |

Error messages are localized based on the `Accept-Language` header.

---

## WebSocket-Only Endpoints

The following are **only available via WebSocket RPC**, not HTTP:

- **Sessions:** List, preview, patch, delete, reset (`sessions.*`)
- **Cron jobs:** List, create, update, delete, toggle, status, run, runs (`cron.*`)
- **Config management:** Get, apply, patch, schema (`config.*`)
- **Config permissions:** List, check, grant, revoke (`config.permissions.*`)
- **Workstations:** List, get, create, update, delete, test, link/unlink agent, permissions CRUD, activity (`workstations.*`)
- **Send messages:** Send to channels (`send`)
- **Chat:** Send, history, abort, inject, session status (`chat.*`)
- **Heartbeat:** Get, set, toggle, test, logs, checklist, targets (`heartbeat.*`)
- **Device pairing:** Request, approve, deny, list, revoke (`device.pair.*`)
- **Exec approvals:** List, approve, deny (`exec.approval.*`)
- **TTS:** Status, enable, disable, convert, set provider, providers (`tts.*`)
- **Browser automation:** Act, snapshot, screenshot (`browser.*`)
- **Logs:** Tail server logs (`logs.tail`)

> See [WebSocket Protocol](/websocket-protocol) for full method reference and frame format.

---

## What's Next

- [WebSocket Protocol](/websocket-protocol) — real-time RPC for chat and agent events
- [Config Reference](/config-reference) — full `config.json` schema
- [Database Schema](/database-schema) — table definitions and relationships



---

# REST API Endpoint Catalog

> Auto-generated complete index of all REST endpoints. For request/response details, examples, and authentication, see [REST API Reference](rest-api.md).

**Total endpoints:** 362 — generated from goclaw `fabe86b3` on `2026-06-29`.

## How to use this page

- This is a flat catalog — one row per endpoint.
- Endpoints are grouped by handler domain (the source file in `goclaw/internal/http/`).
- For full request/response schemas of OpenAI-compatible endpoints (`/v1/chat/completions`, `/v1/responses`), see [REST API Reference](rest-api.md).
- Authentication: all `/v1/*` endpoints require `Authorization: Bearer <api-key>` unless noted.

## Endpoints by Domain

### Activity (`internal/http/activity.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/activity` |
| `GET` | `/v1/activity/aggregate` |

### Agents (`internal/http/agents.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents` |
| `POST` | `/v1/agents` |
| `DELETE` | `/v1/agents/{id}` |
| `GET` | `/v1/agents/{id}` |
| `PUT` | `/v1/agents/{id}` |
| `POST` | `/v1/agents/{id}/cancel-summon` |
| `GET` | `/v1/agents/{id}/codex-pool-activity` |
| `GET` | `/v1/agents/{id}/export` |
| `GET` | `/v1/agents/{id}/export/download/{token}` |
| `GET` | `/v1/agents/{id}/export/preview` |
| `POST` | `/v1/agents/{id}/import` |
| `GET` | `/v1/agents/{id}/instances` |
| `GET` | `/v1/agents/{id}/instances/{userID}/files` |
| `PUT` | `/v1/agents/{id}/instances/{userID}/files/{fileName}` |
| `PATCH` | `/v1/agents/{id}/instances/{userID}/metadata` |
| `POST` | `/v1/agents/{id}/regenerate` |
| `POST` | `/v1/agents/{id}/resummon` |
| `GET` | `/v1/agents/{id}/shares` |
| `POST` | `/v1/agents/{id}/shares` |
| `DELETE` | `/v1/agents/{id}/shares/{userID}` |
| `GET` | `/v1/agents/{id}/system-prompt-preview` |
| `POST` | `/v1/agents/import` |
| `POST` | `/v1/agents/import/preview` |
| `POST` | `/v1/agents/sync-workspace` |
| `GET` | `/v1/export/download/{token}` |
| `GET` | `/v1/teams/{id}/export` |
| `GET` | `/v1/teams/{id}/export/preview` |
| `POST` | `/v1/teams/import` |

### API Keys (`internal/http/api_keys.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/api-keys` |
| `POST` | `/v1/api-keys` |
| `POST` | `/v1/api-keys/{id}/revoke` |

### Backup (`internal/http/backup_handler.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/system/backup` |
| `GET` | `/v1/system/backup/download/{token}` |
| `GET` | `/v1/system/backup/preflight` |

### Backup (S3) (`internal/http/backup_s3_handler.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/system/backup/s3/backup` |
| `GET` | `/v1/system/backup/s3/config` |
| `PUT` | `/v1/system/backup/s3/config` |
| `GET` | `/v1/system/backup/s3/list` |
| `POST` | `/v1/system/backup/s3/upload` |

### Browser Cookies (`internal/http/browser_cookies.go`)

| Method | Path |
|---|---|
| `DELETE` | `/v1/browser/cookies` |
| `GET` | `/v1/browser/cookies` |
| `POST` | `/v1/browser/cookies/sync` |

### Builtin Tools (`internal/http/builtin_tools.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/tools/builtin` |
| `GET` | `/v1/tools/builtin/{name}` |
| `PUT` | `/v1/tools/builtin/{name}` |
| `DELETE` | `/v1/tools/builtin/{name}/tenant-config` |
| `GET` | `/v1/tools/builtin/{name}/tenant-config` |
| `PUT` | `/v1/tools/builtin/{name}/tenant-config` |

### Channels (`internal/http/channel_instances.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/channels/instances` |
| `POST` | `/v1/channels/instances` |
| `DELETE` | `/v1/channels/instances/{id}` |
| `GET` | `/v1/channels/instances/{id}` |
| `PUT` | `/v1/channels/instances/{id}` |
| `GET` | `/v1/channels/instances/{id}/contexts` |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/capabilities` |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-credentials` |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-credentials/{binaryID}` |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-credentials/{binaryID}` |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-grants` |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-grants/{binaryID}` |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/cli-grants/{binaryID}` |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-credentials` |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-credentials/{serverID}` |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-credentials/{serverID}` |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-grants` |
| `DELETE` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-grants/{serverID}` |
| `PUT` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/mcp-grants/{serverID}` |
| `GET` | `/v1/channels/instances/{id}/contexts/{scopeType}/{scopeKey}/members` |
| `GET` | `/v1/channels/instances/{id}/memory-extraction` |
| `GET` | `/v1/channels/instances/{id}/memory-extraction/items` |
| `DELETE` | `/v1/channels/instances/{id}/memory-extraction/items/{itemID}` |
| `POST` | `/v1/channels/instances/{id}/memory-extraction/items/{itemID}/approve` |
| `POST` | `/v1/channels/instances/{id}/memory-extraction/items/{itemID}/reject` |
| `POST` | `/v1/channels/instances/{id}/memory-extraction/run` |
| `PUT` | `/v1/channels/instances/{id}/memory-extraction/settings` |
| `GET` | `/v1/channels/instances/{id}/writers` |
| `POST` | `/v1/channels/instances/{id}/writers` |
| `DELETE` | `/v1/channels/instances/{id}/writers/{userId}` |
| `GET` | `/v1/channels/instances/{id}/writers/groups` |
| `POST` | `/v1/channels/instances/{id}/writers/test` |
| `GET` | `/v1/contacts` |
| `POST` | `/v1/contacts/merge` |
| `GET` | `/v1/contacts/merged/{tenantUserId}` |
| `GET` | `/v1/contacts/resolve` |
| `POST` | `/v1/contacts/unmerge` |
| `GET` | `/v1/tenant-users` |
| `GET` | `/v1/users/search` |

### Edition (`internal/http/edition.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/edition` |

### Episodic Memory (`internal/http/episodic_handlers.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/episodic` |
| `POST` | `/v1/agents/{agentID}/episodic/search` |

### Evolution (`internal/http/evolution_handlers.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/evolution/metrics` |
| `GET` | `/v1/agents/{agentID}/evolution/suggestions` |
| `PATCH` | `/v1/agents/{agentID}/evolution/suggestions/{suggestionID}` |

### Feature Flags (`internal/http/v3_flags_handlers.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/v3-flags` |
| `PATCH` | `/v1/agents/{agentID}/v3-flags` |

### Files (`internal/http/files.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/files/{path...}` |
| `POST` | `/v1/files/sign` |

### Gateway Upgrade (`internal/http/gateway_upgrade.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/system/gateway/upgrade` |
| `GET` | `/v1/system/gateway/upgrade/status` |

### Knowledge Graph (`internal/http/knowledge_graph.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/kg/dedup` |
| `POST` | `/v1/agents/{agentID}/kg/dedup/dismiss` |
| `POST` | `/v1/agents/{agentID}/kg/dedup/scan` |
| `GET` | `/v1/agents/{agentID}/kg/entities` |
| `POST` | `/v1/agents/{agentID}/kg/entities` |
| `DELETE` | `/v1/agents/{agentID}/kg/entities/{entityID}` |
| `GET` | `/v1/agents/{agentID}/kg/entities/{entityID}` |
| `POST` | `/v1/agents/{agentID}/kg/extract` |
| `GET` | `/v1/agents/{agentID}/kg/graph` |
| `POST` | `/v1/agents/{agentID}/kg/merge` |
| `GET` | `/v1/agents/{agentID}/kg/stats` |
| `POST` | `/v1/agents/{agentID}/kg/traverse` |

### Logs (`internal/http/logs.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/logs/runtime/aggregate` |

### MCP Servers (`internal/http/mcp.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/mcp/export` |
| `GET` | `/v1/mcp/export/preview` |
| `GET` | `/v1/mcp/grants/agent/{agentID}` |
| `POST` | `/v1/mcp/import` |
| `GET` | `/v1/mcp/requests` |
| `POST` | `/v1/mcp/requests` |
| `POST` | `/v1/mcp/requests/{id}/review` |
| `GET` | `/v1/mcp/servers` |
| `POST` | `/v1/mcp/servers` |
| `DELETE` | `/v1/mcp/servers/{id}` |
| `GET` | `/v1/mcp/servers/{id}` |
| `PUT` | `/v1/mcp/servers/{id}` |
| `GET` | `/v1/mcp/servers/{id}/grants` |
| `POST` | `/v1/mcp/servers/{id}/grants/agent` |
| `DELETE` | `/v1/mcp/servers/{id}/grants/agent/{agentID}` |
| `POST` | `/v1/mcp/servers/{id}/grants/user` |
| `DELETE` | `/v1/mcp/servers/{id}/grants/user/{userID}` |
| `POST` | `/v1/mcp/servers/{id}/reconnect` |
| `GET` | `/v1/mcp/servers/{id}/tools` |
| `POST` | `/v1/mcp/servers/test` |

### MCP User Credentials (`internal/http/mcp_user_credentials.go`)

| Method | Path |
|---|---|
| `DELETE` | `/v1/mcp/servers/{id}/user-credentials` |
| `GET` | `/v1/mcp/servers/{id}/user-credentials` |
| `PUT` | `/v1/mcp/servers/{id}/user-credentials` |

### Media (`internal/http/media_serve.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/media/{id}` |
| `POST` | `/v1/media/upload` |

### Memory (`internal/http/memory.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/memory/chunks` |
| `GET` | `/v1/agents/{agentID}/memory/documents` |
| `DELETE` | `/v1/agents/{agentID}/memory/documents/{path...}` |
| `GET` | `/v1/agents/{agentID}/memory/documents/{path...}` |
| `PUT` | `/v1/agents/{agentID}/memory/documents/{path...}` |
| `POST` | `/v1/agents/{agentID}/memory/index` |
| `POST` | `/v1/agents/{agentID}/memory/index-all` |
| `POST` | `/v1/agents/{agentID}/memory/search` |
| `GET` | `/v1/memory/documents` |

### OAuth (`internal/http/oauth.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/auth/chatgpt/{provider}/callback` |
| `POST` | `/v1/auth/chatgpt/{provider}/logout` |
| `GET` | `/v1/auth/chatgpt/{provider}/quota` |
| `POST` | `/v1/auth/chatgpt/{provider}/start` |
| `GET` | `/v1/auth/chatgpt/{provider}/status` |
| `POST` | `/v1/auth/openai/callback` |
| `POST` | `/v1/auth/openai/logout` |
| `GET` | `/v1/auth/openai/quota` |
| `POST` | `/v1/auth/openai/start` |
| `GET` | `/v1/auth/openai/status` |

### OpenAPI (`internal/http/openapi.go`)

| Method | Path |
|---|---|
| `GET` | `/docs` |
| `GET` | `/docs/` |
| `GET` | `/v1/openapi.json` |

### Orchestration (`internal/http/orchestration_handlers.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/orchestration` |

### Packages (`internal/http/packages.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/packages` |
| `GET` | `/v1/packages/github-releases` |
| `POST` | `/v1/packages/install` |
| `GET` | `/v1/packages/runtimes` |
| `POST` | `/v1/packages/uninstall` |
| `POST` | `/v1/packages/update` |
| `GET` | `/v1/packages/updates` |
| `POST` | `/v1/packages/updates/apply-all` |
| `POST` | `/v1/packages/updates/refresh` |
| `GET` | `/v1/shell-deny-groups` |

### Pending Messages (`internal/http/pending_messages.go`)

| Method | Path |
|---|---|
| `DELETE` | `/v1/pending-messages` |
| `GET` | `/v1/pending-messages` |
| `POST` | `/v1/pending-messages/compact` |
| `GET` | `/v1/pending-messages/messages` |

### Providers (`internal/http/providers.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/embedding/status` |
| `GET` | `/v1/providers` |
| `POST` | `/v1/providers` |
| `DELETE` | `/v1/providers/{id}` |
| `GET` | `/v1/providers/{id}` |
| `PUT` | `/v1/providers/{id}` |
| `GET` | `/v1/providers/{id}/codex-pool-activity` |
| `GET` | `/v1/providers/{id}/models` |
| `POST` | `/v1/providers/{id}/reconnect` |
| `POST` | `/v1/providers/{id}/verify` |
| `POST` | `/v1/providers/{id}/verify-embedding` |
| `GET` | `/v1/providers/claude-cli/auth-status` |

### Restore (`internal/http/restore_handler.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/system/restore` |

### Secure CLI (`internal/http/secure_cli.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/cli-credentials` |
| `POST` | `/v1/cli-credentials` |
| `DELETE` | `/v1/cli-credentials/{id}` |
| `GET` | `/v1/cli-credentials/{id}` |
| `PUT` | `/v1/cli-credentials/{id}` |
| `GET` | `/v1/cli-credentials/{id}/agent-credentials` |
| `DELETE` | `/v1/cli-credentials/{id}/agent-credentials/{agentId}` |
| `GET` | `/v1/cli-credentials/{id}/agent-credentials/{agentId}` |
| `PUT` | `/v1/cli-credentials/{id}/agent-credentials/{agentId}` |
| `GET` | `/v1/cli-credentials/{id}/agent-grants` |
| `POST` | `/v1/cli-credentials/{id}/agent-grants` |
| `DELETE` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` |
| `GET` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` |
| `PUT` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` |
| `POST` | `/v1/cli-credentials/{id}/agent-grants/{grantId}/env:reveal` |
| `POST` | `/v1/cli-credentials/{id}/test` |
| `GET` | `/v1/cli-credentials/{id}/user-credentials` |
| `DELETE` | `/v1/cli-credentials/{id}/user-credentials/{userId}` |
| `GET` | `/v1/cli-credentials/{id}/user-credentials/{userId}` |
| `PUT` | `/v1/cli-credentials/{id}/user-credentials/{userId}` |
| `POST` | `/v1/cli-credentials/check-binary` |
| `GET` | `/v1/cli-credentials/presets` |

### Sessions (`internal/http/sessions.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/chat/sessions/{key}/branch` |
| `GET` | `/v1/chat/sessions/{key}/history/follow` |
| `GET` | `/v1/sessions` |

### Skills (`internal/http/skills.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/skills` |
| `GET` | `/v1/skills` |
| `DELETE` | `/v1/skills/{id}` |
| `GET` | `/v1/skills/{id}` |
| `PUT` | `/v1/skills/{id}` |
| `GET` | `/v1/skills/{id}/access` |
| `PATCH` | `/v1/skills/{id}/access` |
| `GET` | `/v1/skills/{id}/access/effective` |
| `GET` | `/v1/skills/{id}/activity` |
| `GET` | `/v1/skills/{id}/dependencies` |
| `POST` | `/v1/skills/{id}/dependencies/check` |
| `POST` | `/v1/skills/{id}/dependencies/install` |
| `POST` | `/v1/skills/{id}/dependencies/scan` |
| `GET` | `/v1/skills/{id}/evolution` |
| `PATCH` | `/v1/skills/{id}/evolution` |
| `GET` | `/v1/skills/{id}/evolution/suggestions` |
| `POST` | `/v1/skills/{id}/evolution/suggestions` |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{suggestionID}/apply` |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{suggestionID}/approve` |
| `POST` | `/v1/skills/{id}/evolution/suggestions/{suggestionID}/reject` |
| `GET` | `/v1/skills/{id}/files` |
| `GET` | `/v1/skills/{id}/files/{path...}` |
| `GET` | `/v1/skills/{id}/grants/agent` |
| `POST` | `/v1/skills/{id}/grants/agent` |
| `DELETE` | `/v1/skills/{id}/grants/agent/{agentID}` |
| `GET` | `/v1/skills/{id}/grants/agents` |
| `POST` | `/v1/skills/{id}/grants/agents` |
| `DELETE` | `/v1/skills/{id}/grants/agents/{agentID}` |
| `POST` | `/v1/skills/{id}/grants/user` |
| `DELETE` | `/v1/skills/{id}/grants/user/{userID}` |
| `GET` | `/v1/skills/{id}/grants/users` |
| `POST` | `/v1/skills/{id}/grants/users` |
| `DELETE` | `/v1/skills/{id}/grants/users/{userID}` |
| `GET` | `/v1/skills/{id}/metrics` |
| `DELETE` | `/v1/skills/{id}/tenant-config` |
| `PUT` | `/v1/skills/{id}/tenant-config` |
| `POST` | `/v1/skills/{id}/toggle` |
| `GET` | `/v1/skills/{id}/versions` |
| `GET` | `/v1/skills/access/effective` |
| `GET` | `/v1/skills/export` |
| `GET` | `/v1/skills/export/preview` |
| `POST` | `/v1/skills/import` |
| `POST` | `/v1/skills/install-dep` |
| `POST` | `/v1/skills/install-deps` |
| `POST` | `/v1/skills/rescan-deps` |
| `GET` | `/v1/skills/runtimes` |
| `POST` | `/v1/skills/upload` |

### Storage (`internal/http/storage.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/storage/files` |
| `POST` | `/v1/storage/files` |
| `DELETE` | `/v1/storage/files/{path...}` |
| `GET` | `/v1/storage/files/{path...}` |
| `PUT` | `/v1/storage/move` |
| `GET` | `/v1/storage/size` |

### System Config (`internal/http/system_configs.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/system-configs` |
| `DELETE` | `/v1/system-configs/{key}` |
| `GET` | `/v1/system-configs/{key}` |
| `PUT` | `/v1/system-configs/{key}` |

### Teams (`internal/http/team_attachments.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/teams/{id}/events` |
| `GET` | `/v1/teams/{teamId}/attachments/{attachmentId}/download` |

### Tenant Backup (`internal/http/tenant_backup_handler.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/tenant/backup` |
| `GET` | `/v1/tenant/backup/download/{token}` |
| `GET` | `/v1/tenant/backup/preflight` |
| `POST` | `/v1/tenant/restore` |

### Tenants (`internal/http/tenants.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/tenants` |
| `POST` | `/v1/tenants` |
| `GET` | `/v1/tenants/{id}` |
| `PATCH` | `/v1/tenants/{id}` |
| `GET` | `/v1/tenants/{id}/users` |
| `POST` | `/v1/tenants/{id}/users` |
| `DELETE` | `/v1/tenants/{id}/users/{userId}` |

### Traces (`internal/http/traces.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/costs/summary` |
| `GET` | `/v1/runs/{runID}/timeline` |
| `GET` | `/v1/traces` |
| `GET` | `/v1/traces/{traceID}` |
| `GET` | `/v1/traces/{traceID}/export` |
| `GET` | `/v1/traces/follow` |

### TTS (`internal/http/tts.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/tts/capabilities` |
| `GET` | `/v1/tts/config` |
| `POST` | `/v1/tts/config` |
| `POST` | `/v1/tts/synthesize` |
| `POST` | `/v1/tts/test-connection` |
| `GET` | `/v1/voices` |
| `POST` | `/v1/voices/refresh` |

### Usage (`internal/http/usage.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/usage/breakdown` |
| `GET` | `/v1/usage/events/breakdown` |
| `GET` | `/v1/usage/events/summary` |
| `GET` | `/v1/usage/events/timeseries` |
| `GET` | `/v1/usage/summary` |
| `GET` | `/v1/usage/timeseries` |

### Usage Caps (`internal/http/usage_caps.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/model-pricing` |
| `GET` | `/v1/model-pricing/overrides` |
| `PUT` | `/v1/model-pricing/overrides` |
| `DELETE` | `/v1/model-pricing/overrides/{id}` |
| `POST` | `/v1/model-pricing/sync-openrouter` |
| `GET` | `/v1/usage-caps/events` |
| `GET` | `/v1/usage-caps/policies` |
| `POST` | `/v1/usage-caps/policies` |
| `DELETE` | `/v1/usage-caps/policies/{id}` |
| `PATCH` | `/v1/usage-caps/policies/{id}` |
| `GET` | `/v1/usage-caps/utilization` |

### Vault (`internal/http/vault_graph_handler.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/agents/{agentID}/kg/graph/compact` |
| `GET` | `/v1/agents/{agentID}/vault/documents` |
| `POST` | `/v1/agents/{agentID}/vault/documents` |
| `DELETE` | `/v1/agents/{agentID}/vault/documents/{docID}` |
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}` |
| `PUT` | `/v1/agents/{agentID}/vault/documents/{docID}` |
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}/links` |
| `POST` | `/v1/agents/{agentID}/vault/links` |
| `DELETE` | `/v1/agents/{agentID}/vault/links/{linkID}` |
| `POST` | `/v1/agents/{agentID}/vault/search` |
| `GET` | `/v1/vault/documents` |
| `POST` | `/v1/vault/documents` |
| `DELETE` | `/v1/vault/documents/{docID}` |
| `GET` | `/v1/vault/documents/{docID}` |
| `PUT` | `/v1/vault/documents/{docID}` |
| `GET` | `/v1/vault/documents/{docID}/links` |
| `GET` | `/v1/vault/enrichment/status` |
| `POST` | `/v1/vault/enrichment/stop` |
| `GET` | `/v1/vault/graph` |
| `POST` | `/v1/vault/links` |
| `DELETE` | `/v1/vault/links/{linkID}` |
| `POST` | `/v1/vault/links/batch` |
| `POST` | `/v1/vault/rescan` |
| `POST` | `/v1/vault/search` |
| `GET` | `/v1/vault/tree` |
| `POST` | `/v1/vault/upload` |

### Wake (`internal/http/wake.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/agents/{id}/wake` |

### Webhooks Admin (`internal/http/webhooks_admin.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/webhooks` |
| `POST` | `/v1/webhooks` |
| `DELETE` | `/v1/webhooks/{id}` |
| `GET` | `/v1/webhooks/{id}` |
| `PATCH` | `/v1/webhooks/{id}` |
| `POST` | `/v1/webhooks/{id}/rotate` |

### Webhooks Llm (`internal/http/webhooks_llm.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/webhooks/llm` |

### Webhooks Message (`internal/http/webhooks_message.go`)

| Method | Path |
|---|---|
| `POST` | `/v1/webhooks/message` |

### Workspace (`internal/http/workspace_upload.go`)

| Method | Path |
|---|---|
| `PUT` | `/v1/teams/{teamId}/workspace/move` |
| `POST` | `/v1/teams/{teamId}/workspace/upload` |

### Workstations (`internal/http/workstations.go`)

| Method | Path |
|---|---|
| `GET` | `/v1/workstations` |
| `POST` | `/v1/workstations` |
| `DELETE` | `/v1/workstations/{id}` |
| `GET` | `/v1/workstations/{id}` |
| `PUT` | `/v1/workstations/{id}` |
| `GET` | `/v1/workstations/{id}/activity` |
| `GET` | `/v1/workstations/{id}/permissions` |
| `POST` | `/v1/workstations/{id}/permissions` |
| `DELETE` | `/v1/workstations/{id}/permissions/{permId}` |
| `PUT` | `/v1/workstations/{id}/permissions/{permId}/toggle` |
| `POST` | `/v1/workstations/{id}/test` |



---

# Config Reference

> Full `config.json` schema — every field, type, and default value.

## Overview

GoClaw uses a JSON5 config file (supports comments, trailing commas). The file path resolves as:

1. `--config <path>` CLI flag
2. `$GOCLAW_CONFIG` environment variable
3. `config.json` in the working directory (default)

**Secrets are never stored in `config.json`.** API keys, tokens, and the database DSN go in `.env.local` (or environment variables). The `onboard` wizard generates both files automatically.


## `agents`

Agent defaults and per-agent overrides.

```json
{
  "agents": {
    "defaults": { ... },
    "list": {
      "researcher": { ... }
    }
  }
}
```

### `agents.defaults`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `workspace` | string | `~/.goclaw/workspace` | Absolute or `~`-relative workspace path |
| `restrict_to_workspace` | boolean | `true` | Prevent file tools from escaping workspace |
| `provider` | string | `anthropic` | Default LLM provider name |
| `model` | string | `claude-sonnet-4-5-20250929` | Default model ID |
| `max_tokens` | integer | `8192` | Max output tokens per LLM call |
| `temperature` | float | `0.7` | Sampling temperature |
| `max_tool_iterations` | integer | `20` | Max tool call rounds per run |
| `max_tool_calls` | integer | `25` | Max total tool calls per run (0 = unlimited) |
| `context_window` | integer | `200000` | Model context window in tokens |
| `agent_type` | string | `open` | `"open"` (per-user context) or `"predefined"` (shared) |
| `bootstrapMaxChars` | integer | `20000` | Max chars per bootstrap file before truncation |
| `bootstrapTotalMaxChars` | integer | `24000` | Total char budget across all bootstrap files |
| `subagents` | object | see below | Subagent concurrency limits |
| `sandbox` | object | `null` | Docker sandbox config (see Sandbox) |
| `memory` | object | `null` | Memory system config (see Memory) |
| `compaction` | object | `null` | Session compaction config (see Compaction) |
| `contextPruning` | object | auto | Context pruning config (see Context Pruning) |

### `agents.defaults.subagents`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `maxConcurrent` | integer | `20` | Max concurrent subagent sessions across the gateway |
| `maxSpawnDepth` | integer | `1` | Max nesting depth (1–5) |
| `maxChildrenPerAgent` | integer | `5` | Max subagents per parent (1–20) |
| `archiveAfterMinutes` | integer | `60` | Auto-archive idle subagent sessions |
| `model` | string | — | Model override for subagents |

### `agents.defaults.memory`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable memory (PostgreSQL-backed) |
| `embedding_provider` | string | auto | `"openai"`, `"gemini"`, `"openrouter"`, or `""` (auto-detect) |
| `embedding_model` | string | `text-embedding-3-small` | Embedding model ID |
| `embedding_api_base` | string | — | Custom embedding endpoint URL |
| `max_results` | integer | `6` | Max memory search results |
| `max_chunk_len` | integer | `1000` | Max chars per memory chunk |
| `vector_weight` | float | `0.7` | Hybrid search vector weight |
| `text_weight` | float | `0.3` | Hybrid search FTS weight |
| `min_score` | float | `0.35` | Minimum relevance score to return |

### `agents.defaults.compaction`

Compaction triggers when session history exceeds `maxHistoryShare` of the context window.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `reserveTokensFloor` | integer | `20000` | Min tokens to reserve after compaction |
| `maxHistoryShare` | float | `0.85` | Trigger when history > this fraction of context window |
| `minMessages` | integer | `50` | Min messages before compaction can trigger |
| `keepLastMessages` | integer | `4` | Messages to keep after compaction |
| `memoryFlush` | object | — | Pre-compaction memory flush config |

### `agents.defaults.compaction.memoryFlush`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `true` | Flush memory before compaction |
| `softThresholdTokens` | integer | `4000` | Flush when within N tokens of compaction trigger |
| `prompt` | string | — | User prompt for the flush turn |
| `systemPrompt` | string | — | System prompt for the flush turn |

### `agents.defaults.contextPruning`

Auto-enabled when Anthropic is configured. Prunes old tool results to free context space.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `cache-ttl` (Anthropic) / `off` | `"off"` or `"cache-ttl"` |
| `keepLastAssistants` | integer | `3` | Protect last N assistant messages from pruning |
| `softTrimRatio` | float | `0.3` | Start soft trim at this fraction of context window |
| `hardClearRatio` | float | `0.5` | Start hard clear at this fraction |
| `minPrunableToolChars` | integer | `50000` | Min prunable tool chars before acting |
| `softTrim.maxChars` | integer | `4000` | Trim tool results longer than this |
| `softTrim.headChars` | integer | `1500` | Keep first N chars of trimmed results |
| `softTrim.tailChars` | integer | `1500` | Keep last N chars of trimmed results |
| `hardClear.enabled` | boolean | `true` | Replace old tool results with placeholder |
| `hardClear.placeholder` | string | `[Old tool result content cleared]` | Replacement text |

### `agents.defaults.sandbox`

Docker-based code sandbox. Requires Docker and building with sandbox support.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `off` | `"off"`, `"non-main"` (subagents only), `"all"` |
| `image` | string | `goclaw-sandbox:bookworm-slim` | Docker image |
| `workspace_access` | string | `rw` | `"none"`, `"ro"`, `"rw"` |
| `scope` | string | `session` | `"session"`, `"agent"`, `"shared"` |
| `memory_mb` | integer | `512` | Memory limit in MB |
| `cpus` | float | `1.0` | CPU limit |
| `timeout_sec` | integer | `300` | Exec timeout in seconds |
| `network_enabled` | boolean | `false` | Enable container network access |
| `read_only_root` | boolean | `true` | Read-only root filesystem |
| `setup_command` | string | — | Command run once after container creation |
| `user` | string | — | Container user (e.g. `"1000:1000"`, `"nobody"`) |
| `tmpfs_size_mb` | integer | `0` | tmpfs size in MB (0 = Docker default) |
| `max_output_bytes` | integer | `1048576` | Max exec output capture (1 MB default) |
| `idle_hours` | integer | `24` | Prune containers idle > N hours |
| `max_age_days` | integer | `7` | Prune containers older than N days |
| `prune_interval_min` | integer | `5` | Prune check interval in minutes |

### `agents.defaults` — Evolution

Agent evolution settings are stored in the agent's `other_config` JSONB field (set via the dashboard) rather than `config.json`. They are documented here for completeness.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `self_evolve` | boolean | `false` | Allow the agent to rewrite its own `SOUL.md` (style/tone evolution). Only works for `predefined` agents with write access to agent-level context files |
| `skill_evolve` | boolean | `false` | Enable the `skill_manage` tool — agent can create, patch, and delete skills during runs |
| `skill_nudge_interval` | integer | `15` | Minimum tool-call count before the skill nudge prompt fires (0 = disabled). Encourages skill creation after complex runs |

### `agents.list`

Per-agent overrides. All fields are optional — zero values inherit from `defaults`.

```json
{
  "agents": {
    "list": {
      "researcher": {
        "displayName": "Research Assistant",
        "provider": "openrouter",
        "model": "anthropic/claude-opus-4",
        "max_tokens": 16000,
        "agent_type": "open",
        "workspace": "~/.goclaw/workspace-researcher",
        "default": false
      }
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `displayName` | string | Human-readable name shown in UI |
| `provider` | string | LLM provider override |
| `model` | string | Model ID override |
| `max_tokens` | integer | Output token limit override |
| `temperature` | float | Temperature override |
| `max_tool_iterations` | integer | Tool iteration limit override |
| `context_window` | integer | Context window override |
| `max_tool_calls` | integer | Total tool call limit override |
| `agent_type` | string | `"open"` or `"predefined"` |
| `skills` | string[] | Skill allowlist (null = all, `[]` = none) |
| `workspace` | string | Workspace directory override |
| `default` | boolean | Mark as the default agent |
| `sandbox` | object | Per-agent sandbox override |
| `identity` | object | `{name, emoji}` persona config |

---

## `channels`

Messaging channel configuration.

### `channels.telegram`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Telegram channel |
| `token` | string | — | Bot token (keep in env) |
| `proxy` | string | — | HTTP proxy URL |
| `allow_from` | string[] | — | Allowlist of user IDs |
| `dm_policy` | string | `pairing` | `"pairing"`, `"allowlist"`, `"open"`, `"disabled"` |
| `group_policy` | string | `open` | `"open"`, `"allowlist"`, `"disabled"` |
| `require_mention` | boolean | `true` | Require @bot mention in groups |
| `history_limit` | integer | `50` | Max pending group messages for context (0 = disabled) |
| `dm_stream` | boolean | `false` | Progressive streaming for DMs |
| `group_stream` | boolean | `false` | Progressive streaming for groups |
| `draft_transport` | boolean | `true` | Use draft message API for DM streaming (stealth preview, no per-edit notifications) |
| `reasoning_stream` | boolean | `true` | Show extended thinking as a separate message when the provider emits thinking events |
| `reaction_level` | string | `full` | `"off"`, `"minimal"`, `"full"` — status emoji reactions |
| `media_max_bytes` | integer | `20971520` | Max media download size (20 MB default) |
| `link_preview` | boolean | `true` | Enable URL previews |
| `force_ipv4` | boolean | `false` | Force IPv4 for all Telegram API requests (use when IPv6 routing is broken) |
| `stt_proxy_url` | string | — | Speech-to-text proxy URL for voice messages |
| `voice_agent_id` | string | — | Route voice messages to this agent |
| `groups` | object | — | Per-group overrides keyed by chat ID |

### `channels.discord`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Discord channel |
| `token` | string | — | Bot token (keep in env) |
| `dm_policy` | string | `open` | `"open"`, `"allowlist"`, `"disabled"` |
| `group_policy` | string | `open` | `"open"`, `"allowlist"`, `"disabled"` |
| `require_mention` | boolean | `true` | Require @bot mention |
| `history_limit` | integer | `50` | Max pending messages for context |

### `channels.zalo`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Zalo OA channel |
| `token` | string | — | Zalo OA access token |
| `dm_policy` | string | `pairing` | `"pairing"`, `"open"`, `"disabled"` |

### `channels.feishu`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Feishu/Lark channel |
| `app_id` | string | — | App ID |
| `app_secret` | string | — | App secret (keep in env) |
| `domain` | string | `lark` | `"lark"` (international) or `"feishu"` (China) |
| `connection_mode` | string | `websocket` | `"websocket"` or `"webhook"` |
| `encrypt_key` | string | — | Event encryption key |
| `verification_token` | string | — | Event verification token |

### `channels.whatsapp`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable WhatsApp channel |
| `allow_from` | string[] | — | Allowlist of user/group JIDs |
| `dm_policy` | string | `"pairing"` | `"pairing"`, `"open"`, `"allowlist"`, `"disabled"` |
| `group_policy` | string | `"pairing"` (DB) / `"open"` (config) | `"open"`, `"pairing"`, `"allowlist"`, `"disabled"` |
| `require_mention` | boolean | `false` | Only respond in groups when @mentioned |
| `history_limit` | int | `200` | Max pending group messages for context (0=disabled) |
| `block_reply` | boolean | — | Override gateway block_reply (nil=inherit) |

### `channels.slack`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Slack channel |
| `bot_token` | string | — | Bot User OAuth Token (`xoxb-...`) |
| `app_token` | string | — | App-Level Token for Socket Mode (`xapp-...`) |
| `user_token` | string | — | Optional User OAuth Token (`xoxp-...`) for custom bot identity |
| `allow_from` | string[] | — | Allowlist of user IDs |
| `dm_policy` | string | `pairing` | `"pairing"`, `"allowlist"`, `"open"`, `"disabled"` |
| `group_policy` | string | `open` | `"open"`, `"pairing"`, `"allowlist"`, `"disabled"` |
| `require_mention` | boolean | `true` | Require @bot mention in channels |
| `history_limit` | integer | `50` | Max pending messages for context (0 = disabled) |
| `dm_stream` | boolean | `false` | Progressive streaming for DMs |
| `group_stream` | boolean | `false` | Progressive streaming for groups |
| `native_stream` | boolean | `false` | Use Slack ChatStreamer API if available |
| `reaction_level` | string | `off` | `"off"`, `"minimal"`, `"full"` — status emoji reactions |
| `block_reply` | boolean | — | Override gateway `block_reply` (unset = inherit) |
| `debounce_delay` | integer | `300` | Ms delay before dispatching rapid messages (0 = disabled) |
| `thread_ttl` | integer | `24` | Hours before thread participation expires (0 = always require @mention) |
| `media_max_bytes` | integer | `20971520` | Max file download size (20 MB default) |

### `channels.zalo_personal`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Zalo Personal channel |
| `allow_from` | string[] | — | Allowlist of user IDs |
| `dm_policy` | string | `pairing` | `"pairing"`, `"allowlist"`, `"open"`, `"disabled"` |
| `group_policy` | string | `open` | `"open"`, `"allowlist"`, `"disabled"` |
| `require_mention` | boolean | `true` | Require @bot mention in groups |
| `history_limit` | integer | `50` | Max pending group messages for context (0 = disabled) |
| `credentials_path` | string | — | Path to saved session cookies JSON |
| `block_reply` | boolean | — | Override gateway `block_reply` (unset = inherit) |

### `channels.pending_compaction`

When a group accumulates more pending messages than `threshold`, older messages are summarized by an LLM before being sent to the agent, keeping `keep_recent` raw messages at the end.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `threshold` | integer | `200` | Trigger compaction when pending message count exceeds this |
| `keep_recent` | integer | `40` | Number of recent raw messages to keep after compaction |
| `max_tokens` | integer | `4096` | Max output tokens for the LLM summarization call |
| `provider` | string | — | LLM provider for summarization (empty = use agent's provider) |
| `model` | string | — | Model for summarization (empty = use agent's model) |

---

## `gateway`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `host` | string | `0.0.0.0` | Listen host |
| `port` | integer | `18790` | Listen port |
| `token` | string | — | Bearer token for auth (keep in env) |
| `owner_ids` | string[] | — | User IDs with admin/owner access |
| `allowed_origins` | string[] | `[]` | Allowed WebSocket CORS origins (empty = allow all) |
| `max_message_chars` | integer | `32000` | Max incoming message length |
| `inbound_debounce_ms` | integer | `0` | Silence-window in ms that merges rapid channel/Web Chat messages from the same sender/session. `0` disables debouncing for text, but media-bearing messages still honor a built-in media floor so multi-attachment bursts coalesce into one run. Agents may override via per-agent `agent_config.inbound_debounce_ms` |
| `rate_limit_rpm` | integer | `20` | WebSocket rate limit (requests per minute) |
| `injection_action` | string | `warn` | `"off"`, `"log"`, `"warn"`, `"block"` — prompt injection response |
| `block_reply` | boolean | `false` | Deliver intermediate text to users during tool iterations |
| `tool_status` | boolean | `true` | Show tool name in streaming preview during tool execution |
| `task_recovery_interval_sec` | integer | `300` | Team task recovery check interval |
| `quota` | object | — | Per-user request quota config |

---

## `tools`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `profile` | string | — | Tool profile preset: `"minimal"`, `"coding"`, `"messaging"`, `"full"` |
| `allow` | string[] | — | Explicit tool allowlist (tool names or `"group:xxx"`) |
| `deny` | string[] | — | Explicit tool denylist |
| `alsoAllow` | string[] | — | Additive allowlist — merged with profile without removing existing tools |
| `byProvider` | object | — | Per-provider tool policy overrides (keyed by provider name) |
| `rate_limit_per_hour` | integer | `150` | Max tool calls per session per hour |
| `scrub_credentials` | boolean | `true` | Scrub secrets from tool outputs |

### `tools.shellDenyGroups`

Enable or disable individual shell deny-groups at the global level. This setting is runtime-reloadable — changes take effect immediately via `bus.TopicConfigChanged` without restarting the gateway. Per-agent overrides take precedence over this global value.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `tools.shellDenyGroups` | `map[string]bool` | `{}` (no groups denied) | Enable or disable deny-groups by name. Example: `{"package_install": true, "env_dump": true}` blocks package install commands and environment variable dumps |

**Common deny-groups:**

| Group name | Commands blocked |
|------------|-----------------|
| `package_install` | pip, npm, apt, brew, etc. |
| `env_dump` | printenv, env, export -p, etc. |

> See also: [Security Hardening](/deployment/security-hardening) for combining with per-agent shell policy.

### `tools.commandKeywordAllowlist`

A list of scoped rules that allow product/security vocabulary to appear in credentialed CLI content arguments without disabling the command-path deny patterns. Each rule narrows the bypass to a specific command (and optionally subcommands, argument positions, and keywords).

```json
{
  "tools": {
    "commandKeywordAllowlist": [
      {
        "id": "gh-issue-secret",
        "command": "gh",
        "subcommands": ["issue", "create"],
        "keywords": ["password", "token"],
        "reason": "security issue titles legitimately mention credentials"
      }
    ]
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | string | — | Optional rule identifier |
| `command` | string | — | Command the rule applies to (e.g. `"gh"`) |
| `subcommands` | string[] | — | Subcommands the rule scopes to |
| `args` | string[] | — | Specific argument values the rule matches |
| `argPositions` | integer[] | — | 0-based argument positions (after matched subcommand) |
| `keywords` | string[] | — | Vocabulary allowed within the matched args |
| `reason` | string | — | Human note explaining why the bypass exists |
| `enabled` | boolean | `true` | Disable the rule by setting `false` (omit = enabled) |

---

### `tools.web`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `web.brave.enabled` | boolean | `false` | Enable Brave Search |
| `web.brave.api_key` | string | — | Brave Search API key |
| `web.duckduckgo.enabled` | boolean | `true` | Enable DuckDuckGo fallback |
| `web.duckduckgo.max_results` | integer | `5` | Max search results |

### `tools.web_search`

Web search provider configuration. These settings are part of the 4-tier tenant settings overlay system for built-in tools — they can be set at the system, tenant, agent, or user level.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider_order` | string[] | — | Priority-ordered list of search providers. GoClaw tries each in order and falls back to the next on failure. Example: `["exa", "tavily", "brave", "duckduckgo"]` |

**Available providers:**

| Provider | API key required | Notes |
|----------|-----------------|-------|
| `exa` | Yes | Exa AI neural search |
| `tavily` | Yes | Tavily search API |
| `brave` | Yes | Brave Search API |
| `duckduckgo` | No | Free fallback, always last resort |

> **DuckDuckGo fallback:** `duckduckgo` is always tried last if no other provider in `provider_order` succeeds, even if not listed explicitly. No API key is required for DuckDuckGo.

### `tools.web_fetch`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `policy` | string | — | `"allow"` or `"block"` default policy |
| `allowed_domains` | string[] | — | Domains always allowed |
| `blocked_domains` | string[] | — | Domains always blocked (SSRF protection) |

### `tools.browser`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable browser automation tool |
| `headless` | boolean | `true` | Run browser in headless mode |
| `remote_url` | string | — | Connect to remote browser (Chrome DevTools Protocol URL) |

### `tools.exec_approval`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `security` | string | `full` | `"full"` (deny-list active), `"none"` |
| `ask` | string | `off` | `"off"`, `"always"`, `"risky"` — when to request user approval |
| `allowlist` | string[] | — | Additional safe commands to whitelist |

### `tools.mcp_servers`

Array of MCP server configs. Each entry:

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique server name |
| `transport` | string | `"stdio"`, `"sse"`, `"streamable-http"` |
| `command` | string | Stdio: command to spawn |
| `args` | string[] | Stdio: command arguments |
| `url` | string | SSE/HTTP: server URL |
| `headers` | object | SSE/HTTP: extra HTTP headers |
| `env` | object | Stdio: extra environment variables |
| `tool_prefix` | string | Optional prefix for tool names |
| `timeout_sec` | integer | Request timeout (default 60) |
| `enabled` | boolean | Enable/disable the server |

---

## `skills`

Skills storage system configuration.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `storage_dir` | string | `{dataDir}/skills-store/` | Directory for skill content |
| `max_upload_size_mb` | integer | `20` | Per-file skill ZIP upload limit in MB. Clamped to the range 1–500; values outside the range snap to the nearest bound. Also settable via `GOCLAW_SKILLS_MAX_UPLOAD_SIZE_MB` or the `skills.max_upload_size_mb` system config key |

### `skills.slash_commands`

Controls explicit slash-command skill activation.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | — | Enable slash-command skill activation |
| `suggest_not_found` | boolean | — | Suggest similar skills when a slash command has no match |
| `partial_matching` | boolean | `false` | Match skills on partial command names |
| `prefix` | string | `/` | Slash-command prefix |

---

## `providers`

Static provider configuration. API keys can also be set via environment variables (e.g. `GOCLAW_NOVITA_API_KEY`).

### `providers.novita`

Novita AI — OpenAI-compatible endpoint.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | string | — | Novita AI API key |
| `api_base` | string | `https://api.novita.ai/openai` | API base URL |

```json
{
  "providers": {
    "novita": {
      "api_key": "your-novita-api-key"
    }
  }
}
```

---

## `sessions`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `scope` | string | `per-sender` | Session scope: `"per-sender"` (each user gets their own session) or `"global"` (all users share one session) |
| `dm_scope` | string | `per-channel-peer` | DM session isolation: `"main"`, `"per-peer"`, `"per-channel-peer"`, `"per-account-channel-peer"` |
| `main_key` | string | `main` | Main session key suffix (used when `dm_scope` is `"main"`) |

### Per-session queue concurrency

Each session runs through a per-session queue. The `max_concurrent` field controls how many agent runs can execute simultaneously for a single session (DM or group). This is configured per-agent-link in the DB (via the dashboard) rather than `config.json`, but the underlying `QueueConfig` default is:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max_concurrent` | integer | `1` | Max simultaneous runs per session queue (1 = serial, no overlap). Groups typically benefit from serial processing; DMs can be set higher for interactive workloads |

---

## `tts`

Text-to-speech output. Configure a provider and optionally enable auto-TTS.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | string | — | TTS provider: `"openai"`, `"elevenlabs"`, `"edge"`, `"minimax"` |
| `auto` | string | `off` | When to auto-speak: `"off"`, `"always"`, `"inbound"` (only reply to voice), `"tagged"` |
| `mode` | string | `final` | Which responses to speak: `"final"` (complete reply only) or `"all"` (each streamed chunk) |
| `max_length` | integer | `1500` | Max text length before truncation |
| `timeout_ms` | integer | `30000` | TTS API timeout in milliseconds |

### `tts.openai`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | string | — | OpenAI API key (keep in env: `GOCLAW_TTS_OPENAI_API_KEY`) |
| `api_base` | string | — | Custom endpoint URL |
| `model` | string | `gpt-4o-mini-tts` | TTS model |
| `voice` | string | `alloy` | Voice name |

### `tts.elevenlabs`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | string | — | ElevenLabs API key (keep in env: `GOCLAW_TTS_ELEVENLABS_API_KEY`) |
| `base_url` | string | — | Custom base URL |
| `voice_id` | string | `pMsXgVXv3BLzUgSXRplE` | Voice ID |
| `model_id` | string | `eleven_multilingual_v2` | Model ID |

### `tts.edge`

Microsoft Edge TTS — free, no API key required.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable Edge TTS provider |
| `voice` | string | `en-US-MichelleNeural` | Voice name (SSML-compatible) |
| `rate` | string | `+0%` | Speech rate adjustment (e.g. `"+10%"`, `"-5%"`) |

### `tts.minimax`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | string | — | MiniMax API key (keep in env: `GOCLAW_TTS_MINIMAX_API_KEY`) |
| `group_id` | string | — | MiniMax GroupId (required; keep in env: `GOCLAW_TTS_MINIMAX_GROUP_ID`) |
| `api_base` | string | `https://api.minimax.io/v1` | API base URL |
| `model` | string | `speech-02-hd` | TTS model |
| `voice_id` | string | `Wise_Woman` | Voice ID |

---

## `cron`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max_retries` | integer | `3` | Max retry attempts on job failure (0 = no retry) |
| `retry_base_delay` | string | `2s` | Initial retry backoff (Go duration, e.g. `"2s"`) |
| `retry_max_delay` | string | `30s` | Maximum retry backoff |
| `default_timezone` | string | — | IANA timezone for cron expressions when not set per-job (e.g. `"Asia/Ho_Chi_Minh"`, `"America/New_York"`) |

---

## `telemetry`

OpenTelemetry OTLP export. Requires build tag `otel` (`go build -tags otel`).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable OTLP export |
| `endpoint` | string | — | OTLP endpoint (e.g. `"localhost:4317"`) |
| `protocol` | string | `grpc` | `"grpc"` or `"http"` |
| `insecure` | boolean | `false` | Skip TLS verification (local dev) |
| `service_name` | string | `goclaw-gateway` | OTEL service name |
| `headers` | object | — | Extra headers (auth tokens for cloud backends) |

---

## `tailscale`

Tailscale tsnet listener. Requires build tag `tsnet` (`go build -tags tsnet`).

| Field | Type | Description |
|-------|------|-------------|
| `hostname` | string | Tailscale machine name (e.g. `"goclaw-gateway"`) |
| `state_dir` | string | Persistent state directory (default: `os.UserConfigDir/tsnet-goclaw`) |
| `ephemeral` | boolean | Remove Tailscale node on exit (default false) |
| `enable_tls` | boolean | Use `ListenTLS` for auto HTTPS certs |

> Auth key is never in config.json — set via `GOCLAW_TSNET_AUTH_KEY` env var only.

---

## `bindings`

Route specific channels/users to a specific agent. Each entry:

```json
{
  "bindings": [
    {
      "agentId": "researcher",
      "match": {
        "channel": "telegram",
        "peer": { "kind": "direct", "id": "123456789" }
      }
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `agentId` | string | Target agent ID |
| `match.channel` | string | Channel name: `"telegram"`, `"discord"`, `"slack"`, etc. |
| `match.accountId` | string | Bot account ID (optional) |
| `match.peer.kind` | string | `"direct"` or `"group"` |
| `match.peer.id` | string | Chat or group ID |
| `match.guildId` | string | Discord guild ID (optional) |

---

## Team Settings (JSONB)

Team settings are stored in `agent_teams.settings` JSONB and configured via the dashboard, not `config.json`. Key fields:

### `blocker_escalation`

Controls whether `"blocker"` comments on team tasks trigger auto-fail and leader escalation.

```json
{
  "blocker_escalation": {
    "enabled": true
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `blocker_escalation.enabled` | boolean | `true` | When true, a task comment with `comment_type = "blocker"` automatically fails the task and escalates to the team lead |

### `escalation_mode`

Controls how escalation messages are delivered to the team lead.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `escalation_mode` | string | — | Delivery mode for escalation events: `"notify"` (post to lead's session) or `""` (silent) |
| `escalation_actions` | string[] | — | Additional actions to take on escalation (e.g. `["notify"]`) |

---

## v3 Config Keys

The following configuration areas were added or formalized in v3. Most are managed via the dashboard or `other_config` JSONB rather than `config.json` directly.

### Knowledge Vault

Vault settings are per-agent, stored in the agent's `other_config` JSONB.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `vault_enabled` | boolean | `false` | Enable knowledge vault for this agent |
| `vault_enrich` | boolean | `false` | Enable async enrichment (auto-summary + semantic linking) |
| `vault_enrich_threshold` | float | `0.7` | Similarity threshold for auto-linking (0–1) |
| `vault_enrich_top_k` | integer | `5` | Max auto-linked neighbors per document |

### Evolution

Agent evolution settings are per-agent (`other_config`).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `evolution_metrics` | boolean | `false` | Enable evolution cron for this agent (analysis + eval) |
| `self_evolve` | boolean | `false` | Allow agent to rewrite its own `SOUL.md` |
| `skill_evolve` | boolean | `false` | Enable `skill_manage` tool for skill creation/patching |
| `skill_nudge_interval` | integer | `15` | Tool-call count before skill nudge fires (0 = off) |

### Edition (Multi-Tenant)

Edition controls per-tenant subagent limits. Set via the `editions` table, not `config.json`.

| Field | Type | Description |
|-------|------|-------------|
| `MaxSubagentConcurrent` | integer | Max concurrent subagent sessions for this tenant |
| `MaxSubagentDepth` | integer | Max subagent nesting depth for this tenant |

---

## Minimal Working Example

```json
{
  "agents": {
    "defaults": {
      "workspace": "~/.goclaw/workspace",
      "provider": "openrouter",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "max_tool_iterations": 20
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790
  },
  "channels": {
    "telegram": { "enabled": true }
  }
}
```

Secrets (`GOCLAW_GATEWAY_TOKEN`, `GOCLAW_OPENROUTER_API_KEY`, `GOCLAW_POSTGRES_DSN`) go in `.env.local`.

---

## What's Next

- [Environment Variables](/env-vars) — full env var reference
- [CLI Commands](/cli-commands) — `goclaw onboard` to generate this file interactively
- [Database Schema](/database-schema) — how agents and providers are stored in PostgreSQL



---

# Environment Variables

> All environment variables recognized by GoClaw, organized by category.

## Overview

GoClaw reads environment variables at startup and applies them on top of `config.json`. Environment variables always take precedence over file values. Secrets (API keys, tokens, DSN) should never go in `config.json` — put them in `.env.local` or inject them as environment variables in your deployment.

```bash
# Load secrets and start
source .env.local && ./goclaw

# Or pass inline
GOCLAW_POSTGRES_DSN="postgres://..." GOCLAW_GATEWAY_TOKEN="..." ./goclaw
```


## Database

| Variable | Required | Description |
|----------|----------|-------------|
| `GOCLAW_POSTGRES_DSN` | Yes | PostgreSQL connection string. Example: `postgres://user:pass@localhost:5432/goclaw?sslmode=disable` |

> The DSN is intentionally excluded from `config.json` — it is a secret. Set it via environment only.

---

## LLM Providers

API keys from environment override any values in `config.json`. Setting a key here also auto-enables the provider.

| Variable | Provider |
|----------|----------|
| `GOCLAW_ANTHROPIC_API_KEY` | Anthropic (Claude) |
| `GOCLAW_ANTHROPIC_BASE_URL` | Anthropic custom endpoint |
| `GOCLAW_OPENAI_API_KEY` | OpenAI (GPT) |
| `GOCLAW_OPENAI_BASE_URL` | OpenAI-compatible custom endpoint |
| `GOCLAW_OPENROUTER_API_KEY` | OpenRouter |
| `GOCLAW_GROQ_API_KEY` | Groq |
| `GOCLAW_DEEPSEEK_API_KEY` | DeepSeek |
| `GOCLAW_GEMINI_API_KEY` | Google Gemini |
| `GOCLAW_MISTRAL_API_KEY` | Mistral AI |
| `GOCLAW_XAI_API_KEY` | xAI (Grok) |
| `GOCLAW_MINIMAX_API_KEY` | MiniMax |
| `GOCLAW_COHERE_API_KEY` | Cohere |
| `GOCLAW_PERPLEXITY_API_KEY` | Perplexity |
| `GOCLAW_DASHSCOPE_API_KEY` | Alibaba DashScope |
| `GOCLAW_BAILIAN_API_KEY` | Alibaba Bailian |
| `GOCLAW_OLLAMA_HOST` | Ollama server URL (e.g. `http://localhost:11434`) |
| `GOCLAW_OLLAMA_CLOUD_API_KEY` | Ollama Cloud API key |
| `GOCLAW_OLLAMA_CLOUD_API_BASE` | Ollama Cloud custom base URL |

### Provider & Model Defaults

| Variable | Description |
|----------|-------------|
| `GOCLAW_PROVIDER` | Default LLM provider name (overrides `agents.defaults.provider` in config) |
| `GOCLAW_MODEL` | Default model ID (overrides `agents.defaults.model` in config) |

---

## Claude CLI Provider

| Variable | Description |
|----------|-------------|
| `GOCLAW_CLAUDE_CLI_PATH` | Path to the `claude` binary. Default: `claude` (from PATH) |
| `GOCLAW_CLAUDE_CLI_MODEL` | Model alias for Claude CLI (e.g. `sonnet`, `opus`, `haiku`) |
| `GOCLAW_CLAUDE_CLI_WORK_DIR` | Base working directory for Claude CLI sessions |

---

## Channels

Setting a token/credential via environment auto-enables that channel.

| Variable | Channel | Description |
|----------|---------|-------------|
| `GOCLAW_TELEGRAM_TOKEN` | Telegram | Bot token from @BotFather |
| `GOCLAW_DISCORD_TOKEN` | Discord | Bot token |
| `GOCLAW_ZALO_TOKEN` | Zalo OA | Zalo OA access token |
| `GOCLAW_LARK_APP_ID` | Feishu/Lark | App ID |
| `GOCLAW_LARK_APP_SECRET` | Feishu/Lark | App secret |
| `GOCLAW_LARK_ENCRYPT_KEY` | Feishu/Lark | Event encryption key |
| `GOCLAW_LARK_VERIFICATION_TOKEN` | Feishu/Lark | Event verification token |
| `GOCLAW_WHATSAPP_ENABLED` | WhatsApp | Enable WhatsApp channel (`true`/`false`) |
| `GOCLAW_SLACK_BOT_TOKEN` | Slack | Bot User OAuth Token (`xoxb-...`) — auto-enables Slack |
| `GOCLAW_SLACK_APP_TOKEN` | Slack | App-Level Token for Socket Mode (`xapp-...`) |
| `GOCLAW_SLACK_USER_TOKEN` | Slack | Optional User OAuth Token (`xoxp-...`) |

---

## Text-to-Speech (TTS)

| Variable | Description |
|----------|-------------|
| `GOCLAW_TTS_OPENAI_API_KEY` | OpenAI TTS API key |
| `GOCLAW_TTS_ELEVENLABS_API_KEY` | ElevenLabs TTS API key |
| `GOCLAW_TTS_MINIMAX_API_KEY` | MiniMax TTS API key |
| `GOCLAW_TTS_MINIMAX_GROUP_ID` | MiniMax group ID |

---

## Workspace & Skills

| Variable | Description |
|----------|-------------|
| `GOCLAW_WORKSPACE` | Default agent workspace directory. Default: `~/.goclaw/workspace` |
| `GOCLAW_SESSIONS_STORAGE` | Session storage path (legacy). Default: `~/.goclaw/sessions` |
| `GOCLAW_SKILLS_DIR` | Global skills directory. Default: `~/.goclaw/skills` |
| `GOCLAW_BUILTIN_SKILLS_DIR` | Path to built-in skill definitions. Default: `./builtin-skills` |
| `GOCLAW_BUNDLED_SKILLS_DIR` | Path to bundled skill packages. Default: `./bundled-skills` |
| `GOCLAW_SKILLS_MAX_UPLOAD_SIZE_MB` | Per-file skill ZIP upload limit in MB. Default: `20`. Clamped to the range 1–500. Overrides `skills.max_upload_size_mb` in `config.json` |

## Runtime Packages (Docker v3)

These variables configure where on-demand runtime packages (pip/npm) are installed inside the container. Set automatically by the Docker entrypoint — only override if you have a custom install layout.

| Variable | Default (Docker) | Description |
|----------|-----------------|-------------|
| `PIP_TARGET` | `/app/data/.runtime/pip` | Directory where pip installs Python packages at runtime |
| `PYTHONPATH` | `/app/data/.runtime/pip` | Python module search path — must include `PIP_TARGET` so installed packages are importable |
| `NPM_CONFIG_PREFIX` | `/app/data/.runtime/npm-global` | npm global prefix for runtime Node.js package installs |

> These directories are mounted on the data volume so packages survive container recreation. The `pkg-helper` binary (runs as root) manages system (`apk`) packages; pip/npm installs run as the `goclaw` user.

---

## Sandbox (Docker)

| Variable | Description |
|----------|-------------|
| `GOCLAW_SANDBOX_MODE` | `"off"`, `"non-main"`, or `"all"` |
| `GOCLAW_SANDBOX_IMAGE` | Docker image for sandbox containers |
| `GOCLAW_SANDBOX_WORKSPACE_ACCESS` | `"none"`, `"ro"`, or `"rw"` |
| `GOCLAW_SANDBOX_SCOPE` | `"session"`, `"agent"`, or `"shared"` |
| `GOCLAW_SANDBOX_MEMORY_MB` | Memory limit in MB |
| `GOCLAW_SANDBOX_CPUS` | CPU limit (float, e.g. `"1.5"`) |
| `GOCLAW_SANDBOX_TIMEOUT_SEC` | Exec timeout in seconds |
| `GOCLAW_SANDBOX_NETWORK` | `"true"` to enable container network access |

---

## Concurrency / Scheduler

Lane-based limits for concurrent agent runs.

| Variable | Default | Description |
|----------|---------|-------------|
| `GOCLAW_LANE_MAIN` | `30` | Max concurrent main agent runs |
| `GOCLAW_LANE_SUBAGENT` | `50` | Max concurrent subagent runs |
| `GOCLAW_LANE_DELEGATE` | `100` | Max concurrent delegated agent runs |
| `GOCLAW_LANE_CRON` | `30` | Max concurrent cron job runs |

---

## Telemetry (OpenTelemetry)

Requires build tag `otel` (`go build -tags otel`).

| Variable | Description |
|----------|-------------|
| `GOCLAW_TELEMETRY_ENABLED` | `"true"` to enable OTLP export |
| `GOCLAW_TELEMETRY_ENDPOINT` | OTLP endpoint (e.g. `localhost:4317`) |
| `GOCLAW_TELEMETRY_PROTOCOL` | `"grpc"` (default) or `"http"` |
| `GOCLAW_TELEMETRY_INSECURE` | `"true"` to skip TLS verification |
| `GOCLAW_TELEMETRY_SERVICE_NAME` | OTEL service name. Default: `goclaw-gateway` |

---

## Tailscale

Requires build tag `tsnet` (`go build -tags tsnet`).

| Variable | Description |
|----------|-------------|
| `GOCLAW_TSNET_HOSTNAME` | Tailscale machine name (e.g. `goclaw-gateway`) |
| `GOCLAW_TSNET_AUTH_KEY` | Tailscale auth key — never stored in config.json |
| `GOCLAW_TSNET_DIR` | Persistent state directory |

---

## Debugging & Tracing

| Variable | Description |
|----------|-------------|
| `GOCLAW_TRACE_VERBOSE` | Set to `1` to log full LLM input in trace spans |
| `GOCLAW_BROWSER_REMOTE_URL` | Connect to a remote browser via Chrome DevTools Protocol URL. Auto-enables browser tool |
| `GOCLAW_REDIS_DSN` | Redis connection string (e.g. `redis://redis:6379/0`). Requires build with `-tags redis` |

---

## Minimal `.env.local`

Generated by `goclaw onboard`. Keep this file out of version control.

```bash
# Required
GOCLAW_GATEWAY_TOKEN=your-gateway-token
GOCLAW_ENCRYPTION_KEY=your-base64-32-byte-key   # openssl rand -base64 32
GOCLAW_POSTGRES_DSN=postgres://user:pass@localhost:5432/goclaw?sslmode=disable

# LLM provider (one of these)
GOCLAW_OPENROUTER_API_KEY=sk-or-...
# GOCLAW_ANTHROPIC_API_KEY=sk-ant-...
# GOCLAW_OPENAI_API_KEY=sk-...

# Channels (optional)
# GOCLAW_TELEGRAM_TOKEN=123456789:ABC...

# Debug (optional)
# GOCLAW_TRACE_VERBOSE=1
```

---

## What's Next

- [Config Reference](/config-reference) — corresponding `config.json` fields for each category
- [CLI Commands](/cli-commands) — `goclaw onboard` generates `.env.local` automatically
- [Database Schema](/database-schema) — how secrets are stored encrypted in PostgreSQL



---

# Database Schema

> All PostgreSQL tables, columns, types, and constraints across all migrations.

## Overview

GoClaw requires **PostgreSQL 15+** with two extensions:

```sql
CREATE EXTENSION IF NOT EXISTS "pgcrypto";  -- UUID v7 generation
CREATE EXTENSION IF NOT EXISTS "vector";    -- pgvector for embeddings
```

A custom `uuid_generate_v7()` function provides time-ordered UUIDs. All primary keys use this function by default.

Schema versions are tracked by `golang-migrate`. Run `goclaw migrate up` or `goclaw upgrade` to apply all migrations. Current schema version: **80**.

### v3 Store Unification

In v3, GoClaw introduced a shared `internal/store/base/` package containing a `Dialect` interface plus common helpers (`NilStr`, `BuildMapUpdate`, `BuildScopeClause`, `execMapUpdate`, etc.). Both `pg/` (PostgreSQL) and `sqlitestore/` (SQLite desktop) implement this interface via type aliases, eliminating code duplication. This is an internal refactor — no database schema changes are required and no user action is needed.

SQLite (desktop build) does not support `pgvector` operations. The following features are **PostgreSQL-only**:
- `episodic_summaries` vector search (HNSW index on `embedding`)
- `vault_documents` semantic linking (auto-link via vector similarity)
- `kg_entities` semantic search (HNSW index on `embedding`)

On SQLite, these tables exist but vector columns are unused. Keyword (FTS) search and all other features function normally.


## Tables

### `llm_providers`

Registered LLM providers. API keys are encrypted with AES-256-GCM.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `name` | VARCHAR(50) | UNIQUE NOT NULL | Identifier (e.g. `openrouter`) |
| `display_name` | VARCHAR(255) | | Human-readable name |
| `provider_type` | VARCHAR(30) | NOT NULL DEFAULT `openai_compat` | `openai_compat` or `anthropic` |
| `api_base` | TEXT | | Custom endpoint URL |
| `api_key` | TEXT | | Encrypted API key |
| `enabled` | BOOLEAN | NOT NULL DEFAULT true | |
| `settings` | JSONB | NOT NULL DEFAULT `{}` | Extra provider-specific config |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | |
| `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | |

---

### `agents`

Core agent records. Each agent has its own context, tools, and model configuration.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `agent_key` | VARCHAR(100) | UNIQUE NOT NULL | Slug identifier (e.g. `researcher`) |
| `display_name` | VARCHAR(255) | | UI display name |
| `owner_id` | VARCHAR(255) | NOT NULL | User ID of creator |
| `provider` | VARCHAR(50) | NOT NULL DEFAULT `openrouter` | LLM provider |
| `model` | VARCHAR(200) | NOT NULL | Model ID |
| `context_window` | INT | NOT NULL DEFAULT 200000 | Context window in tokens |
| `max_tool_iterations` | INT | NOT NULL DEFAULT 20 | Max tool rounds per run |
| `workspace` | TEXT | NOT NULL DEFAULT `.` | Workspace directory path |
| `restrict_to_workspace` | BOOLEAN | NOT NULL DEFAULT true | Sandbox file access to workspace |
| `tools_config` | JSONB | NOT NULL DEFAULT `{}` | Tool policy overrides |
| `sandbox_config` | JSONB | | Docker sandbox configuration |
| `subagents_config` | JSONB | | Subagent concurrency configuration |
| `memory_config` | JSONB | | Memory system configuration |
| `compaction_config` | JSONB | | Session compaction configuration |
| `context_pruning` | JSONB | | Context pruning configuration |
| `other_config` | JSONB | NOT NULL DEFAULT `{}` | Miscellaneous config (e.g. `description` for summoning) |
| `is_default` | BOOLEAN | NOT NULL DEFAULT false | Marks the default agent |
| `agent_type` | VARCHAR(20) | NOT NULL DEFAULT `open` | `open` or `predefined` |
| `status` | VARCHAR(20) | DEFAULT `active` | `active`, `inactive`, `summoning` |
| `frontmatter` | TEXT | | Short expertise summary for delegation and UI |
| `tsv` | tsvector | GENERATED ALWAYS | Full-text search vector (display_name + frontmatter) |
| `embedding` | vector(1536) | | Semantic search embedding |
| `budget_monthly_cents` | INTEGER | | Monthly spend cap in USD cents; NULL = unlimited (migration 015). Migration 072 bridges any non-NULL value into a `month`-window `usage_cap_policies` row with `source = 'agent_budget_monthly_cents'` (1 cent = 10,000 micros). |
| `model_fallback` | JSONB | NOT NULL DEFAULT `{}` | Ordered array of fallback model identifiers tried when primary model fails (migration 065) |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | |
| `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | |
| `deleted_at` | TIMESTAMPTZ | | Soft delete timestamp |

**Indexes:** `owner_id`, `status` (partial, non-deleted), `tsv` (GIN), `embedding` (HNSW cosine)

---

### `agent_shares`

Grants another user access to an agent.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `user_id` | VARCHAR(255) | Grantee |
| `role` | VARCHAR(20) DEFAULT `user` | `user`, `operator`, `admin` |
| `granted_by` | VARCHAR(255) | Who granted access |
| `created_at` | TIMESTAMPTZ | |

---

### `agent_context_files`

Per-agent context files (SOUL.md, IDENTITY.md, etc.). Shared across all users of the agent.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `file_name` | VARCHAR(255) | Filename (e.g. `SOUL.md`) |
| `content` | TEXT | File content |
| `created_at` | TIMESTAMPTZ | |
| `updated_at` | TIMESTAMPTZ | |

**Unique:** `(agent_id, file_name)`

---

### `user_context_files`

Per-user, per-agent context files (USER.md, etc.). Private to each user.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `user_id` | VARCHAR(255) | |
| `file_name` | VARCHAR(255) | |
| `content` | TEXT | |
| `created_at` / `updated_at` | TIMESTAMPTZ | |

**Unique:** `(agent_id, user_id, file_name)`

---

### `user_agent_profiles`

Tracks first/last seen timestamps per user per agent.

| Column | Type | Description |
|--------|------|-------------|
| `agent_id` | UUID FK → agents | |
| `user_id` | VARCHAR(255) | |
| `workspace` | TEXT | Per-user workspace override |
| `first_seen_at` | TIMESTAMPTZ | |
| `last_seen_at` | TIMESTAMPTZ | |
| `metadata` | JSONB DEFAULT `{}` | Arbitrary profile metadata (migration 011) |

**PK:** `(agent_id, user_id)`

---

### `user_agent_overrides`

Per-user model/provider overrides for a specific agent.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `user_id` | VARCHAR(255) | |
| `provider` | VARCHAR(50) | Override provider |
| `model` | VARCHAR(200) | Override model |
| `settings` | JSONB | Extra settings |

---

### `sessions`

Chat sessions. One session per channel/user/agent combination.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `session_key` | VARCHAR(500) UNIQUE | Composite key (e.g. `telegram:123456789`) |
| `agent_id` | UUID FK → agents | |
| `user_id` | VARCHAR(255) | |
| `messages` | JSONB DEFAULT `[]` | Full message history |
| `summary` | TEXT | Compacted summary |
| `model` | VARCHAR(200) | Active model for this session |
| `provider` | VARCHAR(50) | Active provider |
| `channel` | VARCHAR(50) | Origin channel |
| `input_tokens` | BIGINT DEFAULT 0 | Cumulative input token count |
| `output_tokens` | BIGINT DEFAULT 0 | Cumulative output token count |
| `compaction_count` | INT DEFAULT 0 | Number of compactions performed |
| `memory_flush_compaction_count` | INT DEFAULT 0 | Compactions with memory flush |
| `label` | VARCHAR(500) | Human-readable session label |
| `spawned_by` | VARCHAR(200) | Parent session key (for subagents) |
| `spawn_depth` | INT DEFAULT 0 | Nesting depth |
| `metadata` | JSONB DEFAULT `{}` | Arbitrary session metadata (migration 011) |
| `team_id` | UUID FK → agent_teams (nullable) | Set for team-scoped sessions (migration 019) |
| `created_at` / `updated_at` | TIMESTAMPTZ | |

**Indexes:** `agent_id`, `user_id`, `updated_at DESC`, `team_id` (partial)

---

### `memory_documents` and `memory_chunks`

Hybrid BM25 + vector memory system.

**`memory_documents`** — top-level indexed documents:

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `user_id` | VARCHAR(255) | Null = global (shared) |
| `path` | VARCHAR(500) | Logical document path/title |
| `content` | TEXT | Full document content |
| `hash` | VARCHAR(64) | SHA-256 of content for change detection |
| `team_id` | UUID FK → agent_teams (nullable) | Team scope; NULL = personal (migration 019) |

**`memory_chunks`** — searchable segments of documents:

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `document_id` | UUID FK → memory_documents | |
| `user_id` | VARCHAR(255) | |
| `path` | TEXT | Source path |
| `start_line` / `end_line` | INT | Source line range |
| `hash` | VARCHAR(64) | Chunk content hash |
| `text` | TEXT | Chunk content |
| `embedding` | vector(1536) | Semantic embedding |
| `tsv` | tsvector GENERATED | Full-text search (simple config, multilingual) |
| `team_id` | UUID FK → agent_teams (nullable) | Team scope; NULL = personal (migration 019) |

**Indexes:** agent+user (standard + partial for global), document, GIN on tsv, HNSW cosine on embedding, `team_id` (partial)

**`embedding_cache`** — deduplicates embedding API calls:

| Column | Type | Description |
|--------|------|-------------|
| `hash` | VARCHAR(64) | Content hash |
| `provider` | VARCHAR(50) | Embedding provider |
| `model` | VARCHAR(200) | Embedding model |
| `embedding` | vector(1536) | Cached vector |
| `dims` | INT | Embedding dimensions |

**PK:** `(hash, provider, model)`

---

### `skills`

Uploaded skill packages with BM25 + semantic search.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `name` | VARCHAR(255) | Display name |
| `slug` | VARCHAR(255) UNIQUE | URL-safe identifier |
| `description` | TEXT | Short description |
| `owner_id` | VARCHAR(255) | Creator user ID |
| `visibility` | VARCHAR(10) DEFAULT `private` | `private` or `public` |
| `version` | INT DEFAULT 1 | Version counter |
| `status` | VARCHAR(20) DEFAULT `active` | `active` or `archived` |
| `frontmatter` | JSONB | Skill metadata from SKILL.md |
| `file_path` | TEXT | Filesystem path to skill content |
| `file_size` | BIGINT | File size in bytes |
| `file_hash` | VARCHAR(64) | Content hash |
| `embedding` | vector(1536) | Semantic search embedding |
| `tags` | TEXT[] | Tag list |
| `is_system` | BOOLEAN DEFAULT false | Built-in system skill; not user-deletable (migration 017) |
| `deps` | JSONB DEFAULT `{}` | Skill dependency declarations (migration 017) |
| `enabled` | BOOLEAN DEFAULT true | Whether skill is active (migration 017) |

**Indexes:** owner, visibility (partial active), slug, HNSW embedding, GIN tags, `is_system` (partial true), `enabled` (partial false)

**`skill_agent_grants`** / **`skill_user_grants`** — access control for skills, same pattern as MCP grants. `skill_agent_grants` also has `can_manage BOOLEAN NOT NULL DEFAULT FALSE` (migration 066) — grants the agent permission to manage (publish, update, delete) the skill. As of migration 078, `skill_user_grants` is uniquely keyed on `(skill_id, user_id, tenant_id)` (tenant-scoped), so the same user can be granted the same skill in different tenants.

---

### `cron_jobs`

Scheduled agent tasks.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID FK → agents | |
| `user_id` | TEXT | Owning user |
| `name` | VARCHAR(255) | Human-readable job name |
| `enabled` | BOOLEAN DEFAULT true | |
| `schedule_kind` | VARCHAR(10) | `at`, `every`, or `cron` |
| `cron_expression` | VARCHAR(100) | Cron expression (when kind=`cron`) |
| `interval_ms` | BIGINT | Interval in ms (when kind=`every`) |
| `run_at` | TIMESTAMPTZ | One-shot run time (when kind=`at`) |
| `timezone` | VARCHAR(50) | Timezone for cron expressions |
| `payload` | JSONB | Message payload sent to agent |
| `delete_after_run` | BOOLEAN DEFAULT false | Self-delete after first successful run |
| `stateless` | BOOLEAN DEFAULT false | Stateless mode — run without session history |
| `deliver` | BOOLEAN DEFAULT false | Deliver result to channel |
| `deliver_channel` | TEXT | Target channel type (`telegram`, `discord`, etc.) |
| `deliver_to` | TEXT | Chat/recipient ID |
| `wake_heartbeat` | BOOLEAN DEFAULT false | Trigger heartbeat after job completes |
| `next_run_at` | TIMESTAMPTZ | Calculated next execution time |
| `last_run_at` | TIMESTAMPTZ | Last execution time |
| `last_status` | VARCHAR(20) | `ok`, `error`, `running` |
| `last_error` | TEXT | Last error message |
| `team_id` | UUID FK → agent_teams (nullable) | Team scope; NULL = personal (migration 019) |

**`cron_run_logs`** — per-run history with token counts and duration. `team_id` column also added (migration 019).

**Unique:** `uq_cron_jobs_agent_tenant_name` on `(agent_id, tenant_id, name)` (migration 047 — prevents duplicate cron job entries).

---

### `pairing_requests` and `paired_devices`

Device pairing flow (channel users requesting access).

**`pairing_requests`** — pending 8-character codes:

| Column | Type | Description |
|--------|------|-------------|
| `code` | VARCHAR(8) UNIQUE | Pairing code shown to user |
| `sender_id` | VARCHAR(200) | Channel user ID |
| `channel` | VARCHAR(255) | Channel name |
| `chat_id` | VARCHAR(200) | Chat ID |
| `expires_at` | TIMESTAMPTZ | Code expiry |

**`paired_devices`** — approved pairings:

| Column | Type | Description |
|--------|------|-------------|
| `sender_id` | VARCHAR(200) | |
| `channel` | VARCHAR(255) | |
| `chat_id` | VARCHAR(200) | |
| `paired_by` | VARCHAR(100) | Who approved |
| `paired_at` | TIMESTAMPTZ | |
| `metadata` | JSONB DEFAULT `{}` | Arbitrary pairing metadata (migration 011) |
| `expires_at` | TIMESTAMPTZ | Pairing expiry; NULL = no expiry (migration 021) |

**Unique:** `(sender_id, channel)`

> `pairing_requests` also received `metadata JSONB DEFAULT '{}'` in migration 011.

---

### `traces` and `spans`

LLM call tracing.

**`traces`** — one record per agent run:

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `agent_id` | UUID | |
| `user_id` | VARCHAR(255) | |
| `session_key` | TEXT | |
| `run_id` | TEXT | |
| `parent_trace_id` | UUID | For delegation — links to parent run's trace |
| `status` | VARCHAR(20) | `running`, `ok`, `error` |
| `total_input_tokens` | INT | |
| `total_output_tokens` | INT | |
| `total_cost` | NUMERIC(12,6) | Estimated cost |
| `span_count` / `llm_call_count` / `tool_call_count` | INT | Summary counters |
| `input_preview` / `output_preview` | TEXT | Truncated first/last message |
| `tags` | TEXT[] | Searchable tags |
| `metadata` | JSONB | |

**`spans`** — individual LLM calls and tool invocations within a trace:

Key columns: `trace_id`, `parent_span_id`, `span_type` (`llm`, `tool`, `agent`), `model`, `provider`, `input_tokens`, `output_tokens`, `total_cost`, `tool_name`, `finish_reason`.

**Indexes:** Optimized for agent+time, user+time, session, status=error. Partial index `idx_traces_quota` on `(user_id, created_at DESC)` filters `parent_trace_id IS NULL` for quota counting. Both `traces` and `spans` have `team_id UUID FK → agent_teams` (nullable, migration 019) with partial indexes. `traces` also has `idx_traces_start_root` on `(start_time DESC) WHERE parent_trace_id IS NULL` and `spans` has `idx_spans_trace_type` on `(trace_id, span_type)` (migration 016).

---

### `mcp_servers`

External MCP (Model Context Protocol) tool providers.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `name` | VARCHAR(255) UNIQUE | Server name |
| `transport` | VARCHAR(50) | `stdio`, `sse`, `streamable-http` |
| `command` | TEXT | Stdio: command to spawn |
| `args` | JSONB | Stdio: arguments |
| `url` | TEXT | SSE/HTTP: server URL |
| `headers` | JSONB | SSE/HTTP: HTTP headers |
| `env` | JSONB | Stdio: environment variables |
| `api_key` | TEXT | Encrypted API key |
| `tool_prefix` | VARCHAR(50) | Optional tool name prefix |
| `timeout_sec` | INT DEFAULT 60 | |
| `enabled` | BOOLEAN DEFAULT true | |

**`mcp_agent_grants`** / **`mcp_user_grants`** — per-agent and per-user access grants with optional tool allowlists/denylists.

**`mcp_access_requests`** — approval workflow for agents requesting MCP access.

---

### `custom_tools`

Dynamic shell-command-backed tools managed via the API.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `name` | VARCHAR(100) | Tool name |
| `description` | TEXT | Shown to the LLM |
| `parameters` | JSONB | JSON Schema for tool parameters |
| `command` | TEXT | Shell command to execute |
| `working_dir` | TEXT | Working directory |
| `timeout_seconds` | INT DEFAULT 60 | |
| `env` | BYTEA | Encrypted environment variables |
| `agent_id` | UUID FK → agents (nullable) | Null = global tool |
| `enabled` | BOOLEAN DEFAULT true | |

**Unique:** name globally (when `agent_id IS NULL`), `(name, agent_id)` per agent.

---

### `channel_instances`

Database-managed channel connections (replaces static config-file channel setup).

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `name` | VARCHAR(100) UNIQUE | Instance name |
| `channel_type` | VARCHAR(50) | `telegram`, `discord`, `feishu`, `zalo_oa`, `zalo_personal`, `whatsapp` |
| `agent_id` | UUID FK → agents | Bound agent |
| `credentials` | BYTEA | Encrypted channel credentials |
| `config` | JSONB | Channel-specific configuration |
| `enabled` | BOOLEAN DEFAULT true | |

---

### `agent_links`

Inter-agent delegation permissions. Source agent can delegate tasks to target agent.

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `source_agent_id` | UUID FK → agents | Delegating agent |
| `target_agent_id` | UUID FK → agents | Delegate agent |
| `direction` | VARCHAR(20) DEFAULT `outbound` | |
| `description` | TEXT | Link description shown during delegation |
| `max_concurrent` | INT DEFAULT 3 | Max concurrent delegations |
| `team_id` | UUID FK → agent_teams (nullable) | Set when link was created by a team |
| `status` | VARCHAR(20) DEFAULT `active` | |

---

### `agent_teams`, `agent_team_members`, `team_tasks`, `team_messages`

Collaborative multi-agent coordination.

**`agent_teams`** — team records with a lead agent.

**`agent_team_members`** — many-to-many `(team_id, agent_id)` with role (`lead`, `member`).

**`team_tasks`** — shared task list:

| Column | Type | Description |
|--------|------|-------------|
| `subject` | VARCHAR(500) | Task title |
| `description` | TEXT | Full task description |
| `status` | VARCHAR(20) DEFAULT `pending` | `pending`, `in_progress`, `completed`, `cancelled` |
| `owner_agent_id` | UUID | Agent that claimed the task |
| `blocked_by` | UUID[] DEFAULT `{}` | Task IDs this task is blocked by |
| `priority` | INT DEFAULT 0 | Higher = higher priority |
| `result` | TEXT | Task output |
| `task_type` | VARCHAR(30) DEFAULT `general` | Task category (migration 018) |
| `task_number` | INT DEFAULT 0 | Sequential number per team (migration 018) |
| `identifier` | VARCHAR(20) | Human-readable ID e.g. `TSK-1` (migration 018) |
| `created_by_agent_id` | UUID FK → agents | Agent that created the task (migration 018) |
| `assignee_user_id` | VARCHAR(255) | Human user assignee (migration 018) |
| `parent_id` | UUID FK → team_tasks | Parent task for subtasks (migration 018) |
| `chat_id` | VARCHAR(255) DEFAULT `''` | Originating chat (migration 018) |
| `locked_at` | TIMESTAMPTZ | When task lock was acquired (migration 018) |
| `lock_expires_at` | TIMESTAMPTZ | Lock TTL (migration 018) |
| `progress_percent` | INT DEFAULT 0 | 0–100 completion indicator (migration 018) |
| `progress_step` | TEXT | Current progress description (migration 018) |
| `followup_at` | TIMESTAMPTZ | Next followup reminder time (migration 018) |
| `followup_count` | INT DEFAULT 0 | Number of followups sent (migration 018) |
| `followup_max` | INT DEFAULT 0 | Max followups to send (migration 018) |
| `followup_message` | TEXT | Message to send at followup (migration 018) |
| `followup_channel` | VARCHAR(60) | Channel for followup delivery (migration 018) |
| `followup_chat_id` | VARCHAR(255) | Chat ID for followup delivery (migration 018) |
| `confidence_score` | FLOAT | Agent self-assessment score (migration 021) |

**Indexes:** `parent_id` (partial), `(team_id, channel, chat_id)`, `(team_id, task_type)`, `lock_expires_at` (partial in_progress), `(team_id, identifier)` (unique partial), `followup_at` (partial in_progress), `blocked_by` (GIN), `(team_id, owner_agent_id, status)`

**`team_messages`** — peer-to-peer mailbox between agents within a team. Received `confidence_score FLOAT` in migration 021.

---

### `builtin_tools`

Registry of built-in gateway tools with enable/disable control.

| Column | Type | Description |
|--------|------|-------------|
| `name` | VARCHAR(100) PK | Tool name (e.g. `exec`, `read_file`) |
| `display_name` | VARCHAR(255) | |
| `description` | TEXT | |
| `category` | VARCHAR(50) DEFAULT `general` | Tool category |
| `enabled` | BOOLEAN DEFAULT true | Global enable/disable |
| `settings` | JSONB | Tool-specific settings |
| `requires` | TEXT[] | Required external dependencies |

---

### `config_secrets`

Encrypted key-value store for secrets that override `config.json` values (managed via the web UI).

| Column | Type | Description |
|--------|------|-------------|
| `key` | VARCHAR(100) PK | Secret key name |
| `value` | BYTEA | AES-256-GCM encrypted value |

---

### `group_file_writers`

> **Removed in migration 023.** Data was migrated into `agent_config_permissions` (`config_type = 'file_writer'`).

---

### `channel_pending_messages`

Group chat message buffer. Persists messages when the bot is not mentioned so that full conversational context is available when it is mentioned. Supports LLM-based compaction (`is_summary` rows) and 7-day TTL cleanup. (migration 012)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `channel_name` | VARCHAR(100) | NOT NULL | Channel instance name |
| `history_key` | VARCHAR(200) | NOT NULL | Composite key scoping the conversation buffer |
| `sender` | VARCHAR(255) | NOT NULL | Display name of sender |
| `sender_id` | VARCHAR(255) | NOT NULL DEFAULT `''` | Platform user ID |
| `body` | TEXT | NOT NULL | Raw message text |
| `platform_msg_id` | VARCHAR(100) | NOT NULL DEFAULT `''` | Native platform message ID |
| `is_summary` | BOOLEAN | NOT NULL DEFAULT false | True if this row is a compacted summary |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `(channel_name, history_key, created_at)`

---

### `kg_entities`

Knowledge graph entity nodes scoped per agent and user. (migration 013)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `agent_id` | UUID FK → agents | NOT NULL | Owning agent (cascade delete) |
| `user_id` | VARCHAR(255) | NOT NULL DEFAULT `''` | User scope; empty = agent-global |
| `external_id` | VARCHAR(255) | NOT NULL | Caller-supplied entity identifier |
| `name` | TEXT | NOT NULL | Entity display name |
| `entity_type` | VARCHAR(100) | NOT NULL | e.g. `person`, `company`, `concept` |
| `description` | TEXT | DEFAULT `''` | Free-text description |
| `properties` | JSONB | DEFAULT `{}` | Structured entity attributes |
| `source_id` | VARCHAR(255) | DEFAULT `''` | Source document/chunk reference |
| `confidence` | FLOAT | NOT NULL DEFAULT 1.0 | Extraction confidence score |
| `team_id` | UUID FK → agent_teams (nullable) | | Team scope; NULL = personal (migration 019) |
| `created_at` / `updated_at` | TIMESTAMPTZ | | |

**Unique:** `(agent_id, user_id, external_id)`

**Indexes:** `(agent_id, user_id)`, `(agent_id, user_id, entity_type)`, `team_id` (partial)

---

### `kg_relations`

Knowledge graph edges between entities. (migration 013)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `agent_id` | UUID FK → agents | NOT NULL | Owning agent (cascade delete) |
| `user_id` | VARCHAR(255) | NOT NULL DEFAULT `''` | User scope |
| `source_entity_id` | UUID FK → kg_entities | NOT NULL | Source node (cascade delete) |
| `relation_type` | VARCHAR(200) | NOT NULL | Relation label e.g. `works_at`, `knows` |
| `target_entity_id` | UUID FK → kg_entities | NOT NULL | Target node (cascade delete) |
| `confidence` | FLOAT | NOT NULL DEFAULT 1.0 | Extraction confidence score |
| `properties` | JSONB | DEFAULT `{}` | Relation attributes |
| `team_id` | UUID FK → agent_teams (nullable) | | Team scope; NULL = personal (migration 019) |
| `created_at` | TIMESTAMPTZ | | |

**Unique:** `(agent_id, user_id, source_entity_id, relation_type, target_entity_id)`

**Indexes:** `(source_entity_id, relation_type)`, `target_entity_id`, `team_id` (partial)

---

### `channel_contacts`

Global unified contact directory auto-collected from all channel interactions. Not per-agent. Used for contact selector, analytics, and future RBAC. (migration 014)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `channel_type` | VARCHAR(50) | NOT NULL | e.g. `telegram`, `discord` |
| `channel_instance` | VARCHAR(255) | | Instance name (nullable) |
| `sender_id` | VARCHAR(255) | NOT NULL | Platform-native user ID |
| `user_id` | VARCHAR(255) | | Matched GoClaw user ID |
| `display_name` | VARCHAR(255) | | Resolved display name |
| `username` | VARCHAR(255) | | Platform username/handle |
| `avatar_url` | TEXT | | Profile image URL |
| `peer_kind` | VARCHAR(20) | | e.g. `user`, `bot`, `group` |
| `metadata` | JSONB | DEFAULT `{}` | Extra platform-specific data |
| `thread_id` | VARCHAR(100) | | Thread/topic identifier within a chat (migration 035) |
| `thread_type` | VARCHAR(20) | | Thread type classifier (migration 035) |
| `merged_id` | UUID | | Canonical contact after de-duplication |
| `first_seen_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `last_seen_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Unique:** `(tenant_id, channel_type, sender_id, COALESCE(thread_id, ''))`

**Indexes:** `channel_instance` (partial non-null), `merged_id` (partial non-null), `(display_name, username)`

---

### `activity_logs`

Immutable audit trail for user and system actions. (migration 015)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `actor_type` | VARCHAR(20) | NOT NULL | `user`, `agent`, `system` |
| `actor_id` | VARCHAR(255) | NOT NULL | User or agent ID |
| `action` | VARCHAR(100) | NOT NULL | e.g. `agent.create`, `skill.delete` |
| `entity_type` | VARCHAR(50) | | Type of affected entity |
| `entity_id` | VARCHAR(255) | | ID of affected entity |
| `details` | JSONB | | Action-specific context |
| `ip_address` | VARCHAR(45) | | Client IP (IPv4 or IPv6) |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `(actor_type, actor_id)`, `action`, `(entity_type, entity_id)`, `created_at DESC`

---

### `usage_snapshots`

Hourly pre-aggregated metrics per agent/provider/model/channel combination. Populated by a background snapshot worker that reads `traces` and `spans`. (migration 016)

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | UUID v7 |
| `bucket_hour` | TIMESTAMPTZ | Hour bucket (truncated to hour) |
| `agent_id` | UUID (nullable) | Agent scope; NULL = system-wide |
| `provider` | VARCHAR(50) DEFAULT `''` | LLM provider |
| `model` | VARCHAR(200) DEFAULT `''` | Model ID |
| `channel` | VARCHAR(50) DEFAULT `''` | Channel name |
| `input_tokens` | BIGINT DEFAULT 0 | |
| `output_tokens` | BIGINT DEFAULT 0 | |
| `cache_read_tokens` | BIGINT DEFAULT 0 | |
| `cache_create_tokens` | BIGINT DEFAULT 0 | |
| `thinking_tokens` | BIGINT DEFAULT 0 | |
| `total_cost` | NUMERIC(12,6) DEFAULT 0 | Estimated USD cost |
| `request_count` | INT DEFAULT 0 | |
| `llm_call_count` | INT DEFAULT 0 | |
| `tool_call_count` | INT DEFAULT 0 | |
| `error_count` | INT DEFAULT 0 | |
| `unique_users` | INT DEFAULT 0 | Distinct users in bucket |
| `avg_duration_ms` | INT DEFAULT 0 | Average request duration |
| `memory_docs` | INT DEFAULT 0 | Point-in-time memory document count |
| `memory_chunks` | INT DEFAULT 0 | Point-in-time memory chunk count |
| `kg_entities` | INT DEFAULT 0 | Point-in-time KG entity count |
| `kg_relations` | INT DEFAULT 0 | Point-in-time KG relation count |
| `created_at` | TIMESTAMPTZ | |

**Unique:** `(bucket_hour, COALESCE(agent_id, '00000000...'), provider, model, channel)` — enables safe upserts.

**Indexes:** `bucket_hour DESC`, `(agent_id, bucket_hour DESC)`, `(provider, bucket_hour DESC)` (partial non-empty), `(channel, bucket_hour DESC)` (partial non-empty)

---

### `team_workspace_files`

Shared file storage scoped by `(team_id, chat_id)`. Supports pinning, tagging, and soft-archiving. (migration 018)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `team_id` | UUID FK → agent_teams | NOT NULL | Owning team |
| `channel` | VARCHAR(50) DEFAULT `''` | | Channel context |
| `chat_id` | VARCHAR(255) DEFAULT `''` | | System-derived user/chat ID |
| `file_name` | VARCHAR(255) | NOT NULL | Display file name |
| `mime_type` | VARCHAR(100) | | MIME type |
| `file_path` | TEXT | NOT NULL | Storage path |
| `size_bytes` | BIGINT DEFAULT 0 | | File size |
| `uploaded_by` | UUID FK → agents | NOT NULL | Uploader agent |
| `task_id` | UUID FK → team_tasks (nullable) | | Linked task |
| `pinned` | BOOLEAN DEFAULT false | | Pinned to workspace |
| `tags` | TEXT[] DEFAULT `{}` | | Searchable tags |
| `metadata` | JSONB | | Extra metadata |
| `archived_at` | TIMESTAMPTZ | | Soft delete timestamp |
| `created_at` / `updated_at` | TIMESTAMPTZ | | |

**Unique:** `(team_id, chat_id, file_name)`

**Indexes:** `(team_id, chat_id)`, `uploaded_by`, `task_id` (partial), `archived_at` (partial), `(team_id, pinned)` (partial true), `tags` (GIN)

---

### `team_workspace_file_versions`

Version history for workspace files. Each upload of a new version creates a row. (migration 018)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `file_id` | UUID FK → team_workspace_files | NOT NULL | Parent file |
| `version` | INT | NOT NULL | Version number |
| `file_path` | TEXT | NOT NULL | Storage path for this version |
| `size_bytes` | BIGINT DEFAULT 0 | | |
| `uploaded_by` | UUID FK → agents | NOT NULL | |
| `created_at` | TIMESTAMPTZ | NOT NULL | |

**Unique:** `(file_id, version)`

---

### `team_workspace_comments`

Annotations on workspace files. (migration 018)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `file_id` | UUID FK → team_workspace_files | NOT NULL | Commented file |
| `agent_id` | UUID FK → agents | NOT NULL | Commenting agent |
| `content` | TEXT | NOT NULL | Comment text |
| `created_at` | TIMESTAMPTZ | NOT NULL | |

**Index:** `file_id`

---

### `team_task_comments`

Discussion thread on a task. (migration 018)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `task_id` | UUID FK → team_tasks | NOT NULL | Parent task |
| `agent_id` | UUID FK → agents (nullable) | | Commenting agent |
| `user_id` | VARCHAR(255) | | Commenting human user |
| `content` | TEXT | NOT NULL | Comment body |
| `metadata` | JSONB DEFAULT `{}` | | |
| `confidence_score` | FLOAT | | Agent self-assessment (migration 021) |
| `created_at` | TIMESTAMPTZ | NOT NULL | |

**Index:** `task_id`

---

### `team_task_events`

Immutable audit log for task state changes. (migration 018)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `task_id` | UUID FK → team_tasks | NOT NULL | Parent task |
| `event_type` | VARCHAR(30) | NOT NULL | e.g. `status_change`, `assigned`, `locked` |
| `actor_type` | VARCHAR(10) | NOT NULL | `agent` or `user` |
| `actor_id` | VARCHAR(255) | NOT NULL | Acting entity ID |
| `data` | JSONB | | Event payload |
| `created_at` | TIMESTAMPTZ | NOT NULL | |

**Index:** `task_id`

---

### `secure_cli_binaries`

Credential injection configuration for the Exec tool (Direct Exec Mode). Admins map binary names to encrypted environment variables; GoClaw auto-injects them into child processes. (migration 020; updated migration 036)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `binary_name` | TEXT | NOT NULL | Display name (e.g. `gh`, `gcloud`) |
| `binary_path` | TEXT | | Absolute path; NULL = auto-resolved at runtime |
| `description` | TEXT | NOT NULL DEFAULT `''` | Admin-facing description |
| `encrypted_env` | BYTEA | NOT NULL | AES-256-GCM encrypted JSON env map |
| `deny_args` | JSONB DEFAULT `[]` | | Regex patterns of forbidden argument prefixes |
| `deny_verbose` | JSONB DEFAULT `[]` | | Verbose flag patterns to strip |
| `timeout_seconds` | INT DEFAULT 30 | | Process timeout |
| `tips` | TEXT DEFAULT `''` | | Hint injected into TOOLS.md context |
| `is_global` | BOOLEAN | NOT NULL DEFAULT true | If true, available to all agents; if false, only agents with an explicit grant |
| `enabled` | BOOLEAN DEFAULT true | | |
| `created_by` | TEXT DEFAULT `''` | | Admin user who created this entry |
| `adapter_name` | TEXT | NULL | Routes the binary to a typed `CredentialAdapter` at exec time; NULL = legacy passthrough (migration 073) |
| `created_at` / `updated_at` | TIMESTAMPTZ | | |

> **Migration 036 note:** The `agent_id` column was removed from this table. Per-agent access is now controlled via the `secure_cli_agent_grants` table. Binaries with `is_global = true` are accessible to all agents; binaries with `is_global = false` require an explicit grant.

**Unique:** `(binary_name, tenant_id)` — one binary definition per name per tenant.

**Indexes:** `binary_name`

---

### `api_keys`

Fine-grained API key management with scope-based access control. (migration 020)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `name` | VARCHAR(100) | NOT NULL | Human-readable key name |
| `prefix` | VARCHAR(8) | NOT NULL | First 8 chars for display/search |
| `key_hash` | VARCHAR(64) | NOT NULL UNIQUE | SHA-256 hex digest of the full key |
| `scopes` | TEXT[] DEFAULT `{}` | | e.g. `{'operator.admin','operator.read'}` |
| `expires_at` | TIMESTAMPTZ | | NULL = never expires |
| `last_used_at` | TIMESTAMPTZ | | |
| `revoked` | BOOLEAN DEFAULT false | | |
| `created_by` | VARCHAR(255) | | User ID who created the key |
| `created_at` / `updated_at` | TIMESTAMPTZ | | |

**Indexes:** `key_hash` (partial `NOT revoked`), `prefix`

---

### `agent_heartbeats`

Per-agent heartbeat configuration for periodic proactive check-ins. (migration 022)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `agent_id` | UUID FK → agents | NOT NULL UNIQUE ON DELETE CASCADE | One config per agent |
| `enabled` | BOOLEAN | NOT NULL DEFAULT false | Whether heartbeat is active |
| `interval_sec` | INT | NOT NULL DEFAULT 1800 | Run interval in seconds |
| `prompt` | TEXT | | Message sent to the agent each heartbeat |
| `provider_id` | UUID FK → llm_providers (nullable) | ON DELETE SET NULL (migration 057) | Override LLM provider; set to NULL if provider is deleted |
| `model` | VARCHAR(200) | | Override model |
| `isolated_session` | BOOLEAN | NOT NULL DEFAULT true | Run in a dedicated session |
| `light_context` | BOOLEAN | NOT NULL DEFAULT false | Inject minimal context |
| `ack_max_chars` | INT | NOT NULL DEFAULT 300 | Max chars in acknowledgement response |
| `max_retries` | INT | NOT NULL DEFAULT 2 | Max retry attempts on failure |
| `active_hours_start` | VARCHAR(5) | | Start of active window (HH:MM) |
| `active_hours_end` | VARCHAR(5) | | End of active window (HH:MM) |
| `timezone` | TEXT | | Timezone for active hours |
| `channel` | VARCHAR(50) | | Delivery channel |
| `chat_id` | TEXT | | Delivery chat ID |
| `next_run_at` | TIMESTAMPTZ | | Scheduled next execution |
| `last_run_at` | TIMESTAMPTZ | | Last execution time |
| `last_status` | VARCHAR(20) | | Last run status |
| `last_error` | TEXT | | Last run error |
| `run_count` | INT | NOT NULL DEFAULT 0 | Total runs |
| `suppress_count` | INT | NOT NULL DEFAULT 0 | Total suppressed runs |
| `metadata` | JSONB | DEFAULT `{}` | Extra metadata |
| `created_at` / `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | |

**Indexes:** `idx_heartbeats_due` on `(next_run_at) WHERE enabled = true AND next_run_at IS NOT NULL` — partial index for efficient scheduler polling.

---

### `heartbeat_run_logs`

Execution log for each heartbeat run. (migration 022)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `heartbeat_id` | UUID FK → agent_heartbeats | NOT NULL ON DELETE CASCADE | Parent heartbeat config |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | Owning agent |
| `status` | VARCHAR(20) | NOT NULL | `ok`, `error`, `skipped` |
| `summary` | TEXT | | Short run summary |
| `error` | TEXT | | Error message if failed |
| `duration_ms` | INT | | Run duration in milliseconds |
| `input_tokens` | INT | DEFAULT 0 | |
| `output_tokens` | INT | DEFAULT 0 | |
| `skip_reason` | VARCHAR(50) | | Reason run was skipped |
| `metadata` | JSONB | DEFAULT `{}` | Extra metadata |
| `ran_at` | TIMESTAMPTZ | DEFAULT NOW() | |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | |

**Indexes:** `idx_hb_logs_heartbeat` on `(heartbeat_id, ran_at DESC)`, `idx_hb_logs_agent` on `(agent_id, ran_at DESC)`

---

### `agent_config_permissions`

Generic permission table for agent configuration (heartbeat, cron, file writers, etc.). Replaces `group_file_writers`. (migration 022)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | Owning agent |
| `scope` | VARCHAR(255) | NOT NULL | Group/chat ID scope |
| `config_type` | VARCHAR(50) | NOT NULL | e.g. `file_writer`, `heartbeat` |
| `user_id` | VARCHAR(255) | NOT NULL | Grantee user ID |
| `permission` | VARCHAR(10) | NOT NULL | `allow` or `deny` |
| `granted_by` | VARCHAR(255) | | Who granted this permission |
| `metadata` | JSONB | DEFAULT `{}` | Extra metadata (e.g. displayName, username) |
| `created_at` / `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | |

**Unique:** `(agent_id, scope, config_type, user_id)`

**Indexes:** `idx_acp_lookup` on `(agent_id, scope, config_type)`

---

### `system_configs`

Centralized key-value store for per-tenant system settings. Falls back to master tenant at application layer. (migration 029)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `key` | VARCHAR(100) | PK (composite) | Config key |
| `value` | TEXT | NOT NULL | Config value (plain text, not encrypted) |
| `tenant_id` | UUID FK → tenants | PK (composite), ON DELETE CASCADE | Owning tenant |
| `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | Last update time |

**Primary Key:** `(key, tenant_id)`

**Indexes:** `idx_system_configs_tenant` on `(tenant_id)`

---

## Migration History

| Version | Description |
|---------|-------------|
| 1 | Initial schema — providers, agents, sessions, memory, skills, cron, pairing, traces, MCP, custom tools, channels, config_secrets, group_file_writers |
| 2 | Agent links, agent frontmatter, FTS + embedding on agents, parent_trace_id on traces |
| 3 | Agent teams, team tasks, team messages, team_id on agent_links |
| 4 | Teams v2 refinements |
| 5 | Phase 4 additions |
| 6 | Builtin tools registry, metadata column on custom_tools |
| 7 | Team metadata |
| 8 | Team tasks user scope |
| 9 | Quota index — partial index on traces for efficient per-user quota counting |
| 10 | Agents markdown v2 |
| 11 | `metadata JSONB` on sessions, user_agent_profiles, pairing_requests, paired_devices |
| 12 | `channel_pending_messages` — group chat message buffer |
| 13 | `kg_entities` and `kg_relations` — knowledge graph tables |
| 14 | `channel_contacts` — global unified contact directory |
| 15 | `budget_monthly_cents` on agents; `activity_logs` audit table |
| 16 | `usage_snapshots` for hourly metrics; perf indexes on traces and spans |
| 17 | `is_system`, `deps`, `enabled` on skills |
| 18 | Team workspace files/versions/comments, task comments/events, task v2 columns (locking, progress, followup, identifier), `team_id` on handoff_routes |
| 19 | `team_id` FK on memory_documents, memory_chunks, kg_entities, kg_relations, traces, spans, cron_jobs, cron_run_logs, sessions |
| 20 | `secure_cli_binaries` and `api_keys` tables |
| 21 | `expires_at` on paired_devices; `confidence_score` on team_tasks, team_messages, team_task_comments |
| 22 | `agent_heartbeats` and `heartbeat_run_logs` tables for heartbeat monitoring; `agent_config_permissions` generic permission table |
| 23 | Agent hard-delete support (cascade FK constraints, unique index on active agents); merges `group_file_writers` into `agent_config_permissions` |
| 24 | Team attachments refactor — drops `team_workspace_files`, `team_workspace_file_versions`, `team_workspace_comments`, and `team_messages`; adds new path-based `team_task_attachments` table linked to tasks; adds `comment_count` and `attachment_count` denormalized columns on `team_tasks`; adds `embedding vector(1536)` on `team_tasks` for semantic task search |
| 25 | Adds `embedding vector(1536)` column and HNSW index to `kg_entities` for pgvector-backed semantic entity search |
| 26 | Adds `owner_id VARCHAR(255)` to `api_keys` — when set, authenticating via this key forces `user_id = owner_id` (user-bound API key); adds `team_user_grants` table for team-level access control; drops legacy `handoff_routes` and `delegation_history` tables |
| 27 | Tenant foundation — creates `tenants` and `tenant_users` tables; seeds master tenant (`0193a5b0-7000-7000-8000-000000000001`); adds `tenant_id` column to 40+ tables for multi-tenant isolation; drops global unique constraints and replaces with per-tenant composite indexes; adds `builtin_tool_tenant_configs`, `skill_tenant_configs`, and `mcp_user_credentials` tables; drops `custom_tools` table (dead code); migrates remaining UUID v4 defaults to v7 |
| 28 | Adds `comment_type VARCHAR(20) DEFAULT 'note'` to `team_task_comments` — supports `"blocker"` type that triggers task auto-fail and leader escalation |
| 29 | `system_configs` — centralized per-tenant key-value configuration store; composite PK `(key, tenant_id)` with cascade delete |
| 30 | Adds GIN indexes on `spans.metadata` (partial, `span_type = 'llm_call'`) and `sessions.metadata` JSONB columns for query performance |
| 31 | Adds `tsv tsvector` generated column + GIN index to `kg_entities` for full-text search; creates `kg_dedup_candidates` table for entity deduplication review |
| 32 | Creates `secure_cli_user_credentials` for per-user credential injection (mirrors `mcp_user_credentials` pattern); adds `contact_type VARCHAR(20) DEFAULT 'user'` to `channel_contacts` |
| 33 | Promotes `stateless`, `deliver`, `deliver_channel`, `deliver_to`, `wake_heartbeat` from `payload` JSONB to dedicated columns on `cron_jobs` |
| 34 | `subagent_tasks` — subagent task persistence for DB-backed task lifecycle tracking, cost attribution, and restart recovery |
| 35 | `contact_thread_id` — adds `thread_id` and `thread_type` to `channel_contacts`; cleans `sender_id` format; rebuilds unique index to include thread scope |
| 36 | `secure_cli_agent_grants` — restructures CLI credentials from per-binary agent assignment to a grants model; creates `secure_cli_agent_grants` table; adds `is_global` to `secure_cli_binaries`; removes `agent_id` column from `secure_cli_binaries` |
| 37 | V3 memory evolution — creates `episodic_summaries`, `agent_evolution_metrics`, `agent_evolution_suggestions`; adds `valid_from`/`valid_until` temporal columns to `kg_entities`/`kg_relations`; promotes 12 agent config fields from `other_config` JSONB to dedicated `agents` columns (`emoji`, `agent_description`, `thinking_level`, `max_tokens`, `self_evolve`, `skill_evolve`, `skill_nudge_interval`, `reasoning_config`, `workspace_sharing`, `chatgpt_oauth_routing`, `shell_deny_groups`, `kg_dedup_config`) |
| 38 | Knowledge Vault — creates `vault_documents`, `vault_links`, `vault_versions` tables; HNSW vector index and FTS on vault docs |
| 39 | Clears stale `agent_links` data (`TRUNCATE agent_links`); `episodic_summaries` already created in 037 |
| 40 | Adds `search_vector tsvector GENERATED` column + GIN index and optimised HNSW index to `episodic_summaries` for full-text and vector search |
| 41 | Adds `promoted_at TIMESTAMPTZ` to `episodic_summaries` for the dreaming/long-term memory promotion pipeline |
| 42 | Adds `summary TEXT` column to `vault_documents`; rebuilds `tsv` generated column to include summary for richer FTS |
| 43 | Adds `team_id` and `custom_scope` to `vault_documents`; replaces old unique constraint with team-aware composite; adds `trg_vault_docs_team_null_scope` trigger; adds `custom_scope` to `vault_links`, `vault_versions`, `memory_documents`, `memory_chunks`, `team_tasks`, `team_task_attachments`, `team_task_comments`, `team_task_events`, `subagent_tasks` |
| 44 | Seeds `AGENTS_CORE.md` and `AGENTS_TASK.md` context files for all existing agents that lack them; removes deprecated `AGENTS_MINIMAL.md` entries |
| 45 | Adds `recall_count`, `recall_score`, `last_recalled_at` to `episodic_summaries`; partial index `idx_episodic_recall_unpromoted` on `(agent_id, user_id, recall_score DESC)` where `promoted_at IS NULL` |
| 46 | Makes `vault_documents.agent_id` nullable for team-scoped and tenant-shared files; FK on delete changes from CASCADE to SET NULL; replaces unique index with tenant_id-leading + COALESCE; adds `trg_vault_docs_agent_null_scope_fix` trigger; partial index `idx_vault_docs_agent_scope` |
| 47 | Adds unique constraint `uq_cron_jobs_agent_tenant_name` on `cron_jobs(agent_id, tenant_id, name)` after dedup; adds `path_basename` generated column and `idx_vault_docs_basename` index to `vault_documents` |
| 48 | `vault_media_linking` — adds `base_name` generated column `lower(regexp_replace(file_path, '.+/', ''))` to `team_task_attachments` for basename-based vault linking; adds `metadata JSONB NOT NULL DEFAULT '{}'` to `vault_links` for enrichment pipeline metadata; fixes CASCADE FK constraints on vault-related tables |
| 49 | `vault_path_prefix_index` — adds concurrent index `idx_vault_docs_path_prefix` on `vault_documents(path text_pattern_ops)` for fast `LIKE 'prefix%'` queries |
| 50 | Seeds `stt` row into `builtin_tools` (Speech-to-Text via ElevenLabs Scribe or proxy); `ON CONFLICT DO NOTHING` preserves user-customized settings |
| 51 | Backfills `mode: "cache-ttl"` into `agents.context_pruning` for agents that had custom context_pruning config without a `mode` field; does **not** change the global default — pruning remains opt-in |
| 52 | Agent hooks system — creates `agent_hooks`, `hook_executions`, and `tenant_hook_budget` tables |
| 53 | Extends `agent_hooks`: relaxes `handler_type` CHECK to add `'script'`; extends `source` CHECK to add `'builtin'`; drops per-scope uniqueness indexes (scripts routinely add many hooks per event) |
| 54 | Adds `name VARCHAR(255)` column to `agent_hooks`; creates `agent_hook_agents` N:M junction table; migrates existing `agent_id` FK to junction; renames `agent_hooks` → `hooks` and `agent_hook_agents` → `hook_agents`; drops deprecated `agent_id` column from `hooks` |
| 55 | Adds `vault_documents_scope_consistency` CHECK constraint (NOT VALID) on `vault_documents` enforcing scope/agent_id/team_id coherence: `personal` requires `agent_id NOT NULL`, `team` requires `team_id NOT NULL`, `shared` requires both NULL, `custom` is unconstrained |
| 56 | `vault_chat_id` — adds `chat_id TEXT NULL` column to `vault_documents` and index `(tenant_id, chat_id, agent_id)` for chat-scoped vault isolation. Migration 056 follow-up (v3.11.2): drops scope-consistency check before backfill UPDATEs to prevent constraint errors on legacy data |
| 57 | `heartbeat_provider_fk_set_null` (PG) — defensive orphan cleanup, drops existing FK by constraint-name lookup, re-adds as `agent_heartbeats_provider_id_fkey` with `ON DELETE SET NULL`. Brief `ACCESS EXCLUSIVE` lock on `agent_heartbeats` during ALTER (sub-second on small tables). SQLite: schema v25 → v26, full table rebuild for `agent_heartbeats` with updated FK clause; 25-column `INSERT … SELECT` preserves existing rows; `idx_heartbeats_due` recreated. |
| 58 | `agent_grants_env_override` — adds `encrypted_env BYTEA` to `secure_cli_agent_grants`; NULL means inherit binary-level env. Mirrors the `secure_cli_user_credentials.encrypted_env` AES-256-GCM pattern for per-grant env injection. |
| 59 | `webhooks` — creates `webhooks` (outbound HTTP webhook registry) and `webhook_calls` (delivery audit log with retry state) tables. Tenant-scoped. `webhooks.secret_hash` globally unique when not revoked. `webhook_calls.status` CHECK: `queued`, `running`, `done`, `failed`, `dead`. |
| 60 | `webhook_calls_lease_token` — adds `lease_token TEXT` to `webhook_calls` for optimistic-concurrency CAS during worker claim/update; `ReclaimStale` sets it to NULL so in-flight CAS operations fail on next attempt. |
| 61 | `webhooks_encrypted_secret` — adds `encrypted_secret TEXT NOT NULL DEFAULT ''` to `webhooks`; stores AES-256-GCM encrypted raw secret via `GOCLAW_ENCRYPTION_KEY`. HMAC signing uses the decrypted secret, not `secret_hash`. Existing webhooks get empty string and require rotation. |
| 62 | `workstations` — creates `workstations` (SSH/Docker remote exec targets with encrypted `metadata` and `default_env`) and `agent_workstation_links` (agent↔workstation N:M junction with `is_default` flag) tables. |
| 63 | `workstation_permissions` — creates `workstation_permissions` allowlist table; default-deny on argv[0] binary name; seeded inside `WorkstationStore.Create` transaction. Partial index on enabled entries. |
| 64 | `workstation_activity` — creates `workstation_activity` rolling audit log for exec events (`exec`/`deny`); stores truncated command preview + SHA-256 hash; append-only, pruned nightly via `Prune(before)`. |
| 65 | `agent_model_fallback` — adds `model_fallback JSONB NOT NULL DEFAULT '{}'` to `agents`; ordered array of fallback model identifiers tried when the primary model fails. |
| 66 | `skill_agent_manage_grants` — adds `can_manage BOOLEAN NOT NULL DEFAULT FALSE` to `skill_agent_grants`; grants the agent permission to manage (publish, update, delete) the skill at tenant scope. |
| 67 | `skill_agent_grants_scope_cleanup` — data-only migration; deletes `skill_agent_grants` rows where `tenant_id` mismatches agent or skill tenant, enforcing tenant-scope isolation on skill grants. No schema changes. |
| 68 | `bitrix_portals` — Bitrix24 portal registry with encrypted OAuth credentials, seeded before the install flow. |
| 69 | `browser_cookies` — encrypted per-agent browser cookie storage for browser automation. |
| 70 | `usage_pricing_catalog` / `usage_pricing_overrides` — provider/model pricing catalog and per-tenant overrides. |
| 71 | `usage_cap_policies` / `usage_cap_counters` / `usage_cap_reservations` / `usage_cap_events` — usage cap policy engine with counters, reservations, and a decision audit log. |
| 72 | Agent budget ↔ usage-cap bridge — links per-agent budgets into the usage-cap policy engine. |
| 73 | `secure_cli_credential_type` — adds `credential_type` / `host_scope` columns to secure-CLI credential tables. |
| 74 | `run_timeline_items` — archived per-run ordered timeline for replaying runs; FK to traces/spans. |
| 75 | Channel context capabilities — `mcp_context_grants` / `mcp_context_credentials` / `secure_cli_context_grants` / `secure_cli_context_credentials`; per-channel-instance scoped MCP and secure-CLI grants with encrypted credentials. |
| 76 | Channel memory extraction — `channel_memory_extraction_runs` / `channel_memory_extraction_items`; passive scheduled extraction of durable memory (summaries only, no raw bodies) with a review queue. |
| 77 | `secure_cli_agent_credentials` — per-agent typed CLI credentials separate from grants policy; composite FKs `(binary_id, tenant_id)` and `(agent_id, tenant_id)`. |
| 78 | `skill_user_grants_tenant_unique` — replaces the `skill_user_grants` unique key with `(skill_id, user_id, tenant_id)` (tenant-scoped). |
| 79 | Skill self-evolution — `skill_evolution_settings` / `skill_usage_metrics` / `skill_improvement_suggestions` / `skill_versions`; per-skill usage tracking and suggested/applied improvements (backfills one `skill_versions` row per existing skill). |
| 80 | Usage event analytics — `usage_events` / `usage_event_rollups`; raw per-event analytics and pre-aggregated hourly rollups for the usage dashboard. |

---

### `kg_dedup_candidates`

Stores candidate pairs of knowledge graph entities that may be duplicates, for human or automated review. (migration 031)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | ON DELETE CASCADE | Owning tenant |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | Owning agent |
| `user_id` | VARCHAR(255) | NOT NULL DEFAULT `''` | User scope |
| `entity_a_id` | UUID FK → kg_entities | NOT NULL ON DELETE CASCADE | First entity |
| `entity_b_id` | UUID FK → kg_entities | NOT NULL ON DELETE CASCADE | Second entity |
| `similarity` | FLOAT | NOT NULL | Similarity score (0–1) |
| `status` | VARCHAR(20) | NOT NULL DEFAULT `pending` | `pending`, `merged`, `dismissed` |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Unique:** `(entity_a_id, entity_b_id)`

**Indexes:** `idx_kg_dedup_agent` on `(agent_id, status)`

---

### `secure_cli_user_credentials`

Per-user credential overrides for secure CLI binaries. Mirrors the `mcp_user_credentials` pattern — user-specific env vars are injected instead of binary defaults. (migration 032)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `binary_id` | UUID FK → secure_cli_binaries | NOT NULL ON DELETE CASCADE | Parent binary config |
| `user_id` | VARCHAR(255) | NOT NULL | User the credentials belong to |
| `encrypted_env` | BYTEA | NOT NULL | AES-256-GCM encrypted JSON env map |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | Extra metadata |
| `tenant_id` | UUID FK → tenants | NOT NULL | Owning tenant |
| `credential_type` | TEXT | NULL | Credential shape — `env`, `pat`, `ssh_key`, …; NULL = legacy passthrough (migration 073) |
| `host_scope` | TEXT | NULL | Binds the credential to a specific hostname (e.g. `github.com`); NULL = unscoped (migration 073) |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Unique:** `(binary_id, user_id, tenant_id)`

**Indexes:** `idx_scuc_tenant` on `(tenant_id)`, `idx_scuc_binary` on `(binary_id)`

> Migration 032 also adds `contact_type VARCHAR(20) NOT NULL DEFAULT 'user'` to `channel_contacts` to distinguish user vs group contacts.

---

### `secure_cli_agent_grants`

Per-agent access grants for secure CLI binaries. Separates "which agents can use a binary" from the binary credential definition. Each grant can override individual settings (deny_args, timeout, tips, etc.) — `NULL` fields inherit the binary default. (migration 036)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT uuid_generate_v7() | UUID v7 |
| `binary_id` | UUID FK → secure_cli_binaries | NOT NULL ON DELETE CASCADE | Parent binary config |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | Agent being granted access |
| `deny_args` | JSONB | NULL = use binary default | Per-agent override for forbidden argument patterns |
| `deny_verbose` | JSONB | NULL = use binary default | Per-agent override for verbose flag patterns |
| `timeout_seconds` | INTEGER | NULL = use binary default | Per-agent process timeout override |
| `tips` | TEXT | NULL = use binary default | Per-agent hint injected into TOOLS.md context |
| `enabled` | BOOLEAN | NOT NULL DEFAULT true | Whether this grant is active |
| `encrypted_env` | BYTEA | | AES-256-GCM encrypted JSON env map override for this specific grant; NULL = use binary-level env (migration 058) |
| `tenant_id` | UUID FK → tenants | NOT NULL | Owning tenant |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(binary_id, agent_id, tenant_id)` — one grant per agent per binary per tenant.

**Indexes:** `idx_scag_binary` on `(binary_id)`, `idx_scag_agent` on `(agent_id)`, `idx_scag_tenant` on `(tenant_id)`

---

### `episodic_summaries`

Tier 2 memory: compressed session summaries stored per agent/user, searchable via full-text and vector similarity. (migration 037; columns `search_vector`, `promoted_at` added in migrations 040–041)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL | Owning tenant |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | Owning agent |
| `user_id` | VARCHAR(255) | NOT NULL DEFAULT `''` | User scope |
| `session_key` | TEXT | NOT NULL | Source session key |
| `summary` | TEXT | NOT NULL | Compressed session summary |
| `l0_abstract` | TEXT | NOT NULL DEFAULT `''` | One-line abstract |
| `key_topics` | TEXT[] | DEFAULT `{}` | Extracted topic labels |
| `embedding` | vector(1536) | | Semantic embedding of summary |
| `source_type` | TEXT | NOT NULL DEFAULT `session` | Source kind (`session`, etc.) |
| `source_id` | TEXT | | Source identifier (for dedup) |
| `turn_count` | INT | NOT NULL DEFAULT 0 | Turns in summarised session |
| `token_count` | INT | NOT NULL DEFAULT 0 | Tokens in summarised session |
| `search_vector` | tsvector GENERATED | STORED | FTS on `summary + key_topics` (migration 040) |
| `promoted_at` | TIMESTAMPTZ | | NULL = not yet promoted to long-term memory (migration 041) |
| `recall_count` | INT | NOT NULL DEFAULT 0 | Number of times this episode was recalled (migration 045) |
| `recall_score` | DOUBLE PRECISION | NOT NULL DEFAULT 0 | Running-average of search hit scores (migration 045) |
| `last_recalled_at` | TIMESTAMPTZ | | Timestamp of last recall (migration 045) |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `expires_at` | TIMESTAMPTZ | | Optional TTL |

**Indexes:** `(agent_id, user_id)`, `tenant_id`, unique `(agent_id, user_id, source_id) WHERE source_id IS NOT NULL`, GIN on `search_vector`, HNSW cosine on `embedding WHERE embedding IS NOT NULL`, `expires_at` (partial), `(agent_id, user_id, created_at) WHERE promoted_at IS NULL` (for dreaming pipeline), `idx_episodic_recall_unpromoted` on `(agent_id, user_id, recall_score DESC) WHERE promoted_at IS NULL` (migration 045 — DreamingWorker prioritizes high-scoring unpromoted episodes)

---

### `agent_evolution_metrics`

Stage 1 self-evolution: raw metric observations per session collected by the evolution pipeline. (migration 037)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL | |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | |
| `session_key` | TEXT | NOT NULL | Source session |
| `metric_type` | TEXT | NOT NULL | Metric category |
| `metric_key` | TEXT | NOT NULL | Specific metric name |
| `value` | JSONB | NOT NULL | Metric value |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `(agent_id, metric_type)`, `created_at`, `tenant_id`

---

### `agent_evolution_suggestions`

Stage 2 self-evolution: proposed behavioural changes derived from metrics, pending review. (migration 037)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL | |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | |
| `suggestion_type` | TEXT | NOT NULL | e.g. `prompt_tweak`, `tool_config` |
| `suggestion` | TEXT | NOT NULL | The proposed change |
| `rationale` | TEXT | NOT NULL | Why this change is suggested |
| `parameters` | JSONB | | Optional structured parameters |
| `status` | TEXT | NOT NULL DEFAULT `pending` | `pending`, `approved`, `rejected` |
| `reviewed_by` | TEXT | | Reviewer ID |
| `reviewed_at` | TIMESTAMPTZ | | Review timestamp |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `(agent_id, status)`, `tenant_id`

> **Migration 037 also alters:** `kg_entities` and `kg_relations` gain `valid_from TIMESTAMPTZ` and `valid_until TIMESTAMPTZ` for temporal validity windows. Current-entity indexes filter `WHERE valid_until IS NULL`.
>
> **Migration 037 also promotes** 12 agent config fields from `other_config` JSONB to dedicated `agents` columns: `emoji`, `agent_description`, `thinking_level`, `max_tokens`, `self_evolve`, `skill_evolve`, `skill_nudge_interval`, `reasoning_config`, `workspace_sharing`, `chatgpt_oauth_routing`, `shell_deny_groups`, `kg_dedup_config`.

---

### `vault_documents`

Knowledge Vault document registry. Filesystem holds content; the database holds path, hash, embedding, and links. (migration 038; `summary` column added migration 042; `team_id`, `custom_scope` added migration 043; `chat_id` added migration 056)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | |
| `agent_id` | UUID FK → agents | NULL ON DELETE SET NULL | Owning agent; NULL for team-scoped or tenant-shared files (migration 046) |
| `scope` | TEXT | NOT NULL DEFAULT `personal` | `personal`, `team`, or custom |
| `path` | TEXT | NOT NULL | Logical file path within vault |
| `title` | TEXT | NOT NULL DEFAULT `''` | Document title |
| `doc_type` | TEXT | NOT NULL DEFAULT `note` | e.g. `note`, `reference`, `log` |
| `content_hash` | TEXT | NOT NULL DEFAULT `''` | SHA-256 of file content |
| `embedding` | vector(1536) | | Semantic embedding of summary |
| `summary` | TEXT | NOT NULL DEFAULT `''` | LLM-generated summary (migration 042) |
| `metadata` | JSONB | DEFAULT `{}` | Extra metadata |
| `team_id` | UUID FK → agent_teams (nullable) | ON DELETE SET NULL | Team scope; NULL = personal (migration 043) |
| `custom_scope` | VARCHAR(255) | | Future extensibility (migration 043) |
| `chat_id` | TEXT | NULL | Isolated-team chat scoping — scopes a vault document to a specific chat; NULL = no chat scope (migration 056) |
| `path_basename` | TEXT GENERATED ALWAYS | | `lower(regexp_replace(path, '.+/', ''))` — fast basename lookup (migration 047) |
| `tsv` | tsvector GENERATED | STORED | FTS on `title + path + summary` (rebuilt migration 042) |
| `created_at` / `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | |

**Unique:** `(tenant_id, COALESCE(agent_id, '00000000-0000-0000-0000-000000000000'), COALESCE(team_id, '00000000-0000-0000-0000-000000000000'), scope, path)` (migration 046 replaced migration 043's unique to support nullable `agent_id`)

**Indexes:** `tenant_id`, `(agent_id, scope)`, `(agent_id, doc_type)`, `content_hash`, HNSW cosine on `embedding` (m=16, ef=64), GIN on `tsv`, `team_id` (partial non-null), `idx_vault_docs_agent_scope` on `(agent_id, scope) WHERE agent_id IS NOT NULL` (migration 046), `idx_vault_docs_basename` on `(tenant_id, path_basename)` (migration 047), `idx_vault_docs_path_prefix` on `(path text_pattern_ops)` (migration 049 — fast `LIKE 'prefix%'` queries), `(tenant_id, chat_id, agent_id)` (migration 056)

> **Triggers:**
> - `trg_vault_docs_team_null_scope` — when `team_id` is set to NULL (team deleted), `scope` is automatically reset to `'personal'` to prevent orphaned team-scope docs.
> - `trg_vault_docs_agent_null_scope_fix` — when `agent_id` is set to NULL (agent deleted) and no team is set, `scope` is reset to `'shared'` (migration 046).

> **Constraint (migration 055):** `vault_documents_scope_consistency` CHECK (NOT VALID) enforces scope/ownership coherence:
> ```sql
> CHECK (
>     (scope = 'personal' AND agent_id IS NOT NULL AND team_id IS NULL) OR
>     (scope = 'team'     AND team_id  IS NOT NULL AND agent_id IS NULL) OR
>     (scope = 'shared'   AND agent_id IS NULL     AND team_id  IS NULL) OR
>     scope = 'custom'
> ) NOT VALID
> ```
> Added as `NOT VALID` to avoid locking the table during the upgrade. Run `ALTER TABLE vault_documents VALIDATE CONSTRAINT vault_documents_scope_consistency;` after auditing any legacy rows.

---

### `vault_links`

Bidirectional wikilink-style connections between vault documents. (migration 038; `custom_scope` added migration 043; `metadata` added migration 048)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `from_doc_id` | UUID FK → vault_documents | NOT NULL ON DELETE CASCADE | Source document |
| `to_doc_id` | UUID FK → vault_documents | NOT NULL ON DELETE CASCADE | Target document |
| `link_type` | TEXT | NOT NULL DEFAULT `wikilink` | `wikilink`, `reference`, `depends_on`, `extends`, `related`, `supersedes`, `contradicts`, `task_attachment`, `delegation_attachment` |
| `context` | TEXT | NOT NULL DEFAULT `''` | Surrounding text context |
| `custom_scope` | VARCHAR(255) | | Future extensibility (migration 043) |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | Enrichment pipeline metadata (migration 048) |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | |

**Unique:** `(from_doc_id, to_doc_id, link_type)`

**Indexes:** `from_doc_id`, `to_doc_id`

---

### `vault_versions`

Document version history — schema created in migration 038 for v3.1 (empty placeholder). (migration 038; `custom_scope` added migration 043)

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID PK | |
| `doc_id` | UUID FK → vault_documents ON DELETE CASCADE | |
| `version` | INT DEFAULT 1 | Version number |
| `content` | TEXT DEFAULT `''` | Snapshot content |
| `changed_by` | TEXT DEFAULT `''` | Actor who made the change |
| `custom_scope` | VARCHAR(255) | Future extensibility (migration 043) |
| `created_at` | TIMESTAMPTZ | |

**Unique:** `(doc_id, version)`

---

### `subagent_tasks`

Persists subagent task lifecycle for audit trail, cost attribution, and restart recovery. (migration 034; `custom_scope` added migration 043)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | UUID v7 |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `parent_agent_key` | VARCHAR(255) | NOT NULL | Agent key that spawned this task |
| `session_key` | VARCHAR(500) | | Session the task belongs to |
| `subject` | VARCHAR(255) | NOT NULL | Short task title |
| `description` | TEXT | NOT NULL | Full task description |
| `status` | VARCHAR(20) | NOT NULL DEFAULT `running` | `running`, `completed`, `failed`, `cancelled` |
| `result` | TEXT | | Task result text |
| `depth` | INT | NOT NULL DEFAULT 1 | Nesting depth from root agent |
| `model` | VARCHAR(255) | | LLM model used |
| `provider` | VARCHAR(255) | | LLM provider used |
| `iterations` | INT | NOT NULL DEFAULT 0 | Tool loop iterations consumed |
| `input_tokens` | BIGINT | NOT NULL DEFAULT 0 | Input token count |
| `output_tokens` | BIGINT | NOT NULL DEFAULT 0 | Output token count |
| `origin_channel` | VARCHAR(50) | | Channel that triggered the root task |
| `origin_chat_id` | VARCHAR(255) | | Chat ID of the originating message |
| `origin_peer_kind` | VARCHAR(20) | | Peer kind (`user`, `group`, etc.) |
| `origin_user_id` | VARCHAR(255) | | User who triggered the root task |
| `spawned_by` | UUID | | ID of parent `subagent_tasks` row (self-referential) |
| `completed_at` | TIMESTAMPTZ | | When the task finished |
| `archived_at` | TIMESTAMPTZ | | When the task was archived |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | Extra metadata |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:**
- `idx_subagent_tasks_parent_status` on `(tenant_id, parent_agent_key, status)` — primary roster lookup
- `idx_subagent_tasks_session` on `(session_key)` WHERE `session_key IS NOT NULL` — session-scoped lookup
- `idx_subagent_tasks_created` on `(tenant_id, created_at DESC)` — time-based audit and cleanup
- `idx_subagent_tasks_metadata_gin` GIN on `(metadata)` — flexible metadata queries
- `idx_subagent_tasks_archive` on `(status, completed_at)` WHERE `status IN ('completed', 'failed', 'cancelled') AND archived_at IS NULL` — archival candidates

---

---

### `hooks` (formerly `agent_hooks`)

Event-driven hook definitions. Global-scope hooks use `MasterTenantID` as `tenant_id`. Renamed from `agent_hooks` in migration 054. (migrations 052–054)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID | NOT NULL DEFAULT MasterTenantID | Owning tenant; master UUID for global-scope hooks |
| `scope` | VARCHAR(8) | NOT NULL CHECK (`global`, `tenant`, `agent`) | Hook scope |
| `event` | VARCHAR(32) | NOT NULL | Event name (e.g. `before_tool`, `after_tool`) |
| `handler_type` | VARCHAR(16) | NOT NULL CHECK (`command`, `http`, `prompt`, `script`) | Handler kind (migration 053 added `script`) |
| `config` | JSONB | NOT NULL DEFAULT `{}` | Handler-specific options (command path, HTTP URL, prompt template) |
| `script` | TEXT | | Inline script source for `script` handler type (migration 053) |
| `builtin` | TEXT | | Builtin handler identifier for `source = 'builtin'` hooks (migration 053) |
| `name` | VARCHAR(255) | | User-facing label (migration 054) |
| `matcher` | VARCHAR(256) | | Optional regex applied to `tool_name` before the hook fires |
| `if_expr` | TEXT | | Optional CEL expression evaluated against `tool_input` |
| `timeout_ms` | INT | NOT NULL DEFAULT 5000 | Hook execution timeout |
| `on_timeout` | VARCHAR(8) | NOT NULL DEFAULT `block` CHECK (`block`, `allow`) | Behavior on timeout |
| `priority` | INT | NOT NULL DEFAULT 0 | Higher value = evaluated first |
| `enabled` | BOOL | NOT NULL DEFAULT true | |
| `version` | INT | NOT NULL DEFAULT 1 | Optimistic-lock version counter |
| `source` | VARCHAR(16) | NOT NULL DEFAULT `ui` CHECK (`ui`, `api`, `seed`, `builtin`) | Origin of hook (migration 053 added `builtin`) |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | UI-only fields (tags, notes, lastTestedAt, createdByUsername) |
| `created_by` | UUID | | Creator user ID |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `idx_hooks_lookup` on `(tenant_id, event) WHERE enabled = TRUE` (hot-path for ResolveForEvent)

> **Migration 054 note:** The `agent_id` column was removed. Per-hook agent assignment is now controlled via the `hook_agents` junction table. The table was also renamed from `agent_hooks` to `hooks` in this migration. Per-scope uniqueness indexes (`uq_hooks_global`, `uq_hooks_tenant`, `uq_hooks_agent`) were dropped in migration 053.

---

### `hook_agents`

N:M junction table linking hooks to agents. Replaces the 1:N `agent_id` FK on `hooks`. Created and populated in migration 054.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `hook_id` | UUID FK → hooks | NOT NULL ON DELETE CASCADE | |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | |

**Primary Key:** `(hook_id, agent_id)`

**Index:** `idx_hook_agents_agent` on `(agent_id)`

---

### `hook_executions`

Append-only audit log for hook executions. `hook_id` is SET NULL when the parent hook is deleted to preserve the audit trail. (migration 052)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `hook_id` | UUID FK → hooks | ON DELETE SET NULL | Parent hook; NULL if hook was deleted |
| `session_id` | VARCHAR(500) | | Originating session |
| `event` | VARCHAR(32) | NOT NULL | Event that triggered the hook |
| `input_hash` | CHAR(64) | | SHA-256 of canonical (tool_name + sorted args) |
| `decision` | VARCHAR(16) | NOT NULL CHECK (`allow`, `block`, `error`, `timeout`) | Hook outcome |
| `duration_ms` | INT | NOT NULL DEFAULT 0 | Execution duration |
| `retry` | INT | NOT NULL DEFAULT 0 | Retry attempt number |
| `dedup_key` | VARCHAR(128) | | Prevents duplicate rows for (hook_id, event_id) |
| `error` | VARCHAR(256) | | Error message (truncated to 256 chars) |
| `error_detail` | BYTEA | | Full error AES-256-GCM encrypted (GDPR-purgeable) |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | Extensible exec context (matcher_matched, cel_eval_result, stdout_len, http_status, prompt_model, prompt_tokens, trace_id) |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `idx_hook_executions_session` on `(session_id, created_at)`, unique `uq_hook_executions_dedup` on `(dedup_key) WHERE dedup_key IS NOT NULL`

---

### `tenant_hook_budget`

Per-tenant monthly prompt-handler token/cost budget. One row per tenant tracks monthly spend against a cap. (migration 052)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `tenant_id` | UUID | PK | Owning tenant |
| `month_start` | DATE | NOT NULL | First day of the tracked month |
| `budget_total` | BIGINT | NOT NULL DEFAULT 0 | Monthly cap (provider-defined units) |
| `remaining` | BIGINT | NOT NULL DEFAULT 0 | Units remaining; decremented atomically |
| `last_warned_at` | TIMESTAMPTZ | | Timestamp of last threshold warning |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | Alert thresholds, override flags, notes |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

---

---

### `webhooks`

Outbound HTTP webhook registry. Each webhook defines an endpoint that GoClaw calls when an agent produces an LLM response or a channel message. Secrets are encrypted at rest with AES-256-GCM via `GOCLAW_ENCRYPTION_KEY`. (migrations 059, 061)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID | NOT NULL | Owning tenant; all queries filter by tenant |
| `agent_id` | UUID FK → agents | ON DELETE SET NULL | Bound agent; NULL = tenant-wide webhook |
| `name` | TEXT | NOT NULL | Human-readable label |
| `kind` | TEXT | NOT NULL CHECK (`llm`, `message`) | Trigger kind |
| `secret_prefix` | TEXT | | First chars of raw secret for display |
| `secret_hash` | TEXT | NOT NULL | SHA-256 hex of raw secret; used for bearer-token lookup |
| `encrypted_secret` | TEXT | NOT NULL DEFAULT `''` | AES-256-GCM encrypted raw secret via `GOCLAW_ENCRYPTION_KEY`; used for HMAC signing (migration 061) |
| `scopes` | TEXT[] | NOT NULL DEFAULT `{}` | Permitted operation scopes |
| `channel_id` | UUID | | Bound channel instance for `message` kind |
| `rate_limit_per_min` | INT | NOT NULL DEFAULT 60 | Per-webhook inbound rate cap |
| `ip_allowlist` | TEXT[] | NOT NULL DEFAULT `{}` | Allowed caller IPs; empty = allow all |
| `require_hmac` | BOOLEAN | NOT NULL DEFAULT false | Reject requests without valid HMAC signature |
| `localhost_only` | BOOLEAN | NOT NULL DEFAULT false | Restrict to loopback callers |
| `revoked` | BOOLEAN | NOT NULL DEFAULT false | Soft-disable without delete |
| `created_by` | TEXT | | Creator user ID |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `last_used_at` | TIMESTAMPTZ | | Last successful inbound call |

**Indexes:** `idx_webhooks_tenant` on `(tenant_id)`, `idx_webhooks_tenant_agent` on `(tenant_id, agent_id)`, unique `uq_webhooks_secret` on `(secret_hash) WHERE revoked = false`

---

### `webhook_calls`

Delivery log for webhook invocations with retry state and optimistic-concurrency locking. Append-only in practice. (migrations 059, 060)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID | NOT NULL | Owning tenant |
| `webhook_id` | UUID FK → webhooks | NOT NULL ON DELETE CASCADE | Parent webhook |
| `agent_id` | UUID | | Agent that handled the call |
| `idempotency_key` | TEXT | | Caller-supplied dedup key |
| `mode` | TEXT | NOT NULL CHECK (`sync`, `async`) | Delivery mode |
| `callback_url` | TEXT | | Async result delivery URL |
| `status` | TEXT | NOT NULL DEFAULT `queued` CHECK (`queued`, `running`, `done`, `failed`, `dead`) | Delivery status |
| `attempts` | INT | NOT NULL DEFAULT 0 | Retry count |
| `delivery_id` | UUID | NOT NULL DEFAULT gen_random_uuid() | Unique delivery identifier |
| `lease_token` | TEXT | | Optimistic-concurrency CAS token; set by ClaimNext, cleared on stale reclaim (migration 060) |
| `next_attempt_at` | TIMESTAMPTZ | | Scheduled retry time |
| `started_at` | TIMESTAMPTZ | | When processing began |
| `request_payload` | JSONB | | Inbound request body |
| `response` | JSONB | | Agent response body |
| `last_error` | TEXT | | Last delivery error |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `completed_at` | TIMESTAMPTZ | | When delivery finished |

**Indexes:** `idx_webhook_calls_tenant_created` on `(tenant_id, created_at DESC)`, `idx_webhook_calls_status_attempt` on `(status, next_attempt_at)`, unique `uq_webhook_calls_idempotency` on `(webhook_id, idempotency_key) WHERE idempotency_key IS NOT NULL`

---

### `workstations`

SSH or Docker remote execution targets. Each workstation defines a backend connection; agents use it via the `workstation_exec` tool. Credentials stored encrypted. (migration 062)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `workstation_key` | VARCHAR(100) | NOT NULL | Slug identifier |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `name` | VARCHAR(255) | NOT NULL | Display name |
| `backend_type` | VARCHAR(20) | NOT NULL CHECK (`ssh`, `docker`) | Backend kind |
| `metadata` | BYTEA | NOT NULL | AES-256-GCM encrypted connection metadata (host, port, credentials) |
| `default_cwd` | VARCHAR(500) | NOT NULL DEFAULT `''` | Default working directory |
| `default_env` | BYTEA | NOT NULL | AES-256-GCM encrypted default environment variables |
| `active` | BOOLEAN | NOT NULL DEFAULT TRUE | Whether workstation is available |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |
| `created_by` | VARCHAR(255) | NOT NULL DEFAULT `''` | Creator user ID |

**Unique:** `(tenant_id, workstation_key)`

**Indexes:** `idx_workstations_tenant_active` on `(tenant_id, active) WHERE active = TRUE`

> Migration 062 also creates **`agent_workstation_links`** — many-to-many junction linking agents to workstations within a tenant. PK: `(agent_id, workstation_id)`. `is_default BOOLEAN` marks the agent's preferred workstation. Unique partial index: `(agent_id) WHERE is_default = TRUE`.

---

### `workstation_permissions`

Per-workstation allowlist of permitted binary names (argv[0]). Default-deny: if no enabled pattern matches, the exec is rejected. Patterns support glob-style prefix matching (e.g., `python*`). (migration 063)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `workstation_id` | UUID FK → workstations | NOT NULL ON DELETE CASCADE | Parent workstation |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `pattern` | VARCHAR(500) | NOT NULL | Binary name or glob pattern matched against argv[0] |
| `enabled` | BOOLEAN | NOT NULL DEFAULT TRUE | Whether this allowlist entry is active |
| `created_by` | VARCHAR(255) | NOT NULL DEFAULT `''` | Creator user ID |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Unique:** `(workstation_id, pattern)`

**Indexes:** `idx_workstation_perms_ws` on `(workstation_id) WHERE enabled = TRUE`, `idx_workstation_perms_tenant` on `(tenant_id)`

---

### `workstation_activity`

Rolling audit log for workstation exec events (`exec` and `deny`). Append-only; pruned nightly. Stores a truncated command preview (first 200 chars) and SHA-256 hash for forensics. (migration 064)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `workstation_id` | UUID FK → workstations | NOT NULL ON DELETE CASCADE | Target workstation |
| `agent_id` | VARCHAR(255) | NOT NULL DEFAULT `''` | Agent that triggered the exec |
| `action` | VARCHAR(20) | NOT NULL | `exec` (allowed) or `deny` (blocked) |
| `cmd_hash` | VARCHAR(64) | NOT NULL DEFAULT `''` | SHA-256 of full command for forensic correlation |
| `cmd_preview` | VARCHAR(200) | NOT NULL DEFAULT `''` | First 200 chars of command (secrets redacted) |
| `exit_code` | INTEGER | | Process exit code; NULL for denied execs |
| `duration_ms` | INTEGER | | Execution duration in milliseconds |
| `deny_reason` | VARCHAR(200) | NOT NULL DEFAULT `''` | Reason exec was blocked (empty for allowed execs) |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** `idx_ws_activity_ws_time` on `(workstation_id, created_at DESC)`, `idx_ws_activity_tenant_time` on `(tenant_id, created_at DESC)`, `idx_ws_activity_retention` on `(created_at)` (used by nightly pruner)

---

### `bitrix_portals`

Per-tenant Bitrix24 portal OAuth state. Multiple Bitrix24 channel instances (chatbots) can share one portal row via a portal reference in their channel config. (migration 068)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `name` | VARCHAR(100) | NOT NULL | Portal display name (one per tenant) |
| `domain` | VARCHAR(255) | NOT NULL | Bitrix24 portal domain |
| `credentials` | BYTEA | | AES-256-GCM ciphertext of `{client_id, client_secret}` |
| `state` | BYTEA | | AES-256-GCM ciphertext of portal state (access/refresh tokens, `member_id`, `app_token`, registered bots, media folders) |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** unique `(tenant_id, name)`; unique `LOWER(TRIM(domain))` (incoming install/event callbacks resolve by domain before tenant scope is known)

---

### `browser_cookies`

User-selected cookies for server-side browser contexts. Values are AES-256-GCM ciphertext; cookies are scoped by tenant, user, and agent to prevent cross-principal reuse. (migration 069)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `user_id` | VARCHAR(255) | NOT NULL | Owning user |
| `agent_id` | VARCHAR(255) | NOT NULL | Owning agent |
| `domain` | TEXT | NOT NULL (non-empty) | Cookie domain |
| `name` | TEXT | NOT NULL (non-empty) | Cookie name |
| `path` | TEXT | NOT NULL DEFAULT `/` (non-empty) | Cookie path |
| `encrypted_value` | TEXT | NOT NULL | AES-256-GCM encrypted cookie value |
| `secure` | BOOLEAN | NOT NULL DEFAULT FALSE | `Secure` flag |
| `http_only` | BOOLEAN | NOT NULL DEFAULT FALSE | `HttpOnly` flag |
| `same_site` | VARCHAR(32) | NOT NULL DEFAULT `''` | `SameSite` attribute |
| `expires_at` | TIMESTAMPTZ | | Cookie expiry; NULL = session cookie |
| `source` | VARCHAR(64) | NOT NULL DEFAULT `''` | Where the cookie was captured from |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT NOW() | |

**Indexes:** unique `(tenant_id, user_id, agent_id, domain, path, name)`; `(tenant_id, user_id, agent_id, domain)`; `expires_at`

---

### `usage_pricing_catalog`

Synced per-model pricing reference used to cost token usage. One row per `model_id`. (migration 070)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `model_id` | TEXT | NOT NULL UNIQUE | Model identifier |
| `canonical_model_id` | TEXT | | Canonical model alias |
| `raw_pricing` / `raw_model` | JSONB | NOT NULL DEFAULT `{}` | Raw upstream pricing/model payload |
| `input_price`, `output_price`, `cache_read_price`, `cache_write_price`, `reasoning_price`, `request_price`, `image_price`, `web_search_price` | NUMERIC(30,18) | `>= 0` or NULL | Per-unit prices |
| `synced_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | Last sync time |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Index:** `synced_at DESC`

---

### `usage_pricing_overrides`

Per-tenant, per-provider price overrides applied on top of the catalog. (migration 070)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `provider_id` | UUID FK → llm_providers | NOT NULL ON DELETE CASCADE | Target provider |
| `provider_type` | TEXT | NOT NULL | Provider type |
| `model_id` | TEXT | NOT NULL | Target model |
| `input_price` … `web_search_price` | NUMERIC(30,18) | `>= 0` or NULL | Override prices (same set as catalog) |
| `enabled` | BOOLEAN | NOT NULL DEFAULT true | |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(tenant_id, provider_id, model_id)`

**Index:** `(tenant_id, provider_id, model_id)` (partial, `WHERE enabled`)

---

### `usage_cap_policies`

Token/cost cap rules evaluated per tenant, optionally scoped to an agent, provider, provider type, or model, over a rolling time window. (migration 071; `source` column added migration 072)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `agent_id` | UUID FK → agents | NULL ON DELETE CASCADE | Agent scope; NULL = all agents |
| `provider_id` | UUID FK → llm_providers | NULL ON DELETE CASCADE | Provider scope |
| `provider_type` | TEXT | | Provider type scope |
| `model_id` | TEXT | | Model scope |
| `window_key` | TEXT | NOT NULL CHECK in (`hour`, `day`, `week`, `month`) | Cap window |
| `max_tokens` | BIGINT | `>= 0` or NULL | Token cap |
| `max_cost_micros` | BIGINT | `>= 0` or NULL | Cost cap in micro-USD |
| `enabled` | BOOLEAN | NOT NULL DEFAULT true | |
| `priority` | INTEGER | NOT NULL DEFAULT 100 | Lower-priority policies evaluated first |
| `source` | TEXT | NOT NULL DEFAULT `manual` | `manual` or `agent_budget_monthly_cents` (migration 072) |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Constraint:** at least one of `max_tokens` / `max_cost_micros` must be set.

**Indexes:** `(tenant_id, enabled, agent_id, provider_id, provider_type, model_id)`; unique `(tenant_id, agent_id)` partial `WHERE source = 'agent_budget_monthly_cents'` (one budget-derived policy per agent, migration 072)

---

### `usage_cap_counters`

Per-window accumulators (used + reserved) for each policy. (migration 071)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `policy_id` | UUID FK → usage_cap_policies | NOT NULL ON DELETE CASCADE | Parent policy |
| `window_start` / `window_end` | TIMESTAMPTZ | NOT NULL | Window bounds |
| `used_tokens` / `reserved_tokens` | BIGINT | NOT NULL DEFAULT 0 | Token usage |
| `used_cost_micros` / `reserved_cost_micros` | BIGINT | NOT NULL DEFAULT 0 | Cost usage in micro-USD |
| `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**PK:** `(policy_id, window_start)`

---

### `usage_cap_reservations`

In-flight reservations that hold capacity before a request completes, later reconciled to actuals. (migration 071)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `reservation_key` | TEXT | NOT NULL | Caller-supplied idempotency key |
| `policy_id` | UUID FK → usage_cap_policies | NOT NULL ON DELETE CASCADE | Parent policy |
| `window_start` | TIMESTAMPTZ | NOT NULL | Reservation window |
| `reserved_tokens` / `reserved_cost_micros` | BIGINT | NOT NULL DEFAULT 0 | Reserved amounts |
| `actual_tokens` / `actual_cost_micros` | BIGINT | NOT NULL DEFAULT 0 | Reconciled actuals |
| `status` | TEXT | NOT NULL DEFAULT `reserved` | Reservation state |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(reservation_key, policy_id)`

**Index:** `reservation_key`

---

### `usage_cap_events`

Audit log of cap decisions (allow/deny) and their reasons. (migration 071)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `policy_id` | UUID FK → usage_cap_policies | NULL ON DELETE SET NULL | Policy that produced the decision |
| `reservation_key` | TEXT | | Related reservation, if any |
| `decision` | TEXT | NOT NULL | Decision outcome |
| `reason` | TEXT | | Human-readable reason |
| `estimated_tokens` / `estimated_cost_micros` | BIGINT | NOT NULL DEFAULT 0 | Pre-flight estimates |
| `actual_tokens` / `actual_cost_micros` | BIGINT | NOT NULL DEFAULT 0 | Final actuals |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Index:** `(tenant_id, created_at DESC)`

---

### `run_timeline_items`

Per-run ordered timeline of items (messages, tool calls, etc.) used to replay archived runs. (migration 074)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT uuid_generate_v7() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | Owning tenant |
| `run_id` | TEXT | NOT NULL | Run identifier |
| `session_key` | VARCHAR(500) | NOT NULL | Session this run belongs to |
| `agent_id` | UUID FK → agents | ON DELETE SET NULL | Agent that produced the run |
| `user_id` | VARCHAR(255) | | User scope |
| `channel` | VARCHAR(50) | | Channel |
| `chat_id` | VARCHAR(255) | | Chat ID |
| `seq` | INT | NOT NULL | Ordering within the run |
| `item_type` | VARCHAR(40) | NOT NULL | Item kind (message, tool call, etc.) |
| `status` | VARCHAR(40) | | Item status |
| `title` | TEXT | | Item title |
| `preview` | TEXT | | Short preview |
| `content` | TEXT | NOT NULL DEFAULT '' | Full item content |
| `tool_name` | VARCHAR(255) | | Tool name, when applicable |
| `tool_call_id` | VARCHAR(255) | | Tool call ID |
| `trace_id` | UUID FK → traces | ON DELETE SET NULL | Linked trace |
| `span_id` | UUID FK → spans | ON DELETE SET NULL | Linked span |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(tenant_id, run_id, seq)`
**Indexes:** `(tenant_id, run_id, seq)`; `(tenant_id, session_key, created_at DESC)`; `(tenant_id, trace_id) WHERE trace_id IS NOT NULL`

---

### Channel context capabilities

Per-channel-instance, scoped MCP and secure-CLI grants plus encrypted credentials. All four tables share a scope model: `scope_type VARCHAR(32)` + `scope_key VARCHAR(255) DEFAULT ''` let a grant apply to the whole channel instance or narrow to a specific scope (e.g. a chat or user). (migration 075)

**`mcp_context_grants`** — enables an MCP server for a channel-instance scope.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT uuid_generate_v7() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | |
| `channel_instance_id` | UUID FK → channel_instances | NOT NULL ON DELETE CASCADE | |
| `scope_type` | VARCHAR(32) | NOT NULL | Scope kind |
| `scope_key` | VARCHAR(255) | NOT NULL DEFAULT '' | Scope value |
| `server_id` | UUID FK → mcp_servers | NOT NULL ON DELETE CASCADE | MCP server granted |
| `enabled` | BOOLEAN | NOT NULL DEFAULT true | |
| `tool_allow` / `tool_deny` / `config_overrides` | JSONB | | Per-scope tool filters and overrides |
| `granted_by` | VARCHAR(255) | NOT NULL | Actor who granted |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(tenant_id, channel_instance_id, scope_type, scope_key, server_id)` · **Indexes:** scope, `server_id`

**`mcp_context_credentials`** — encrypted credentials for the scoped MCP server. Same scope key as above plus `api_key TEXT`, `headers BYTEA`, `env BYTEA`, `created_by VARCHAR(255) NOT NULL`, timestamps. Same unique key and indexes.

**`secure_cli_context_grants`** — enables a secure-CLI binary for a channel-instance scope. Same scope key plus `binary_id UUID FK → secure_cli_binaries ON DELETE CASCADE`, `deny_args`/`deny_verbose JSONB`, `timeout_seconds INTEGER`, `tips TEXT`, `encrypted_env BYTEA`, `enabled BOOLEAN NOT NULL DEFAULT true`, `granted_by VARCHAR(255) NOT NULL`, timestamps. **Unique:** `(tenant_id, channel_instance_id, scope_type, scope_key, binary_id)` · **Indexes:** scope, `binary_id`.

**`secure_cli_context_credentials`** — encrypted credentials for the scoped secure-CLI binary. Same scope key plus `binary_id`, `encrypted_env BYTEA NOT NULL`, `metadata JSONB NOT NULL DEFAULT '{}'`, `credential_type TEXT`, `host_scope TEXT`, `created_by VARCHAR(255) NOT NULL`, timestamps. Same unique key and indexes as the grants table.

---

### Channel memory extraction

Passive, scheduled extraction of durable memory from channel history. Stores no raw message bodies — only summaries pending review. (migration 076)

**`channel_memory_extraction_runs`** — one extraction pass over a slice of channel history.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | |
| `channel_instance_id` | UUID FK → channel_instances | NOT NULL ON DELETE CASCADE | |
| `channel_name` | VARCHAR(255) | NOT NULL | |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | |
| `user_id` | VARCHAR(255) | NOT NULL DEFAULT '' | |
| `history_key` | VARCHAR(255) | NOT NULL | History bucket key |
| `trigger` | VARCHAR(32) | NOT NULL DEFAULT 'scheduled' | What started the run |
| `status` | VARCHAR(32) | NOT NULL DEFAULT 'pending' | Run status |
| `source_start_id` / `source_end_id` | VARCHAR(255) | NOT NULL DEFAULT '' | Source message range |
| `source_start_at` / `source_end_at` | TIMESTAMPTZ | | Source time range |
| `message_count` / `redaction_count` / `item_count` | INTEGER | NOT NULL DEFAULT 0 | Counters |
| `redaction_types` | JSONB | NOT NULL DEFAULT `[]` | Redaction categories applied |
| `error_message` | TEXT | NOT NULL DEFAULT '' | |
| `started_at` / `completed_at` | TIMESTAMPTZ | | |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(tenant_id, channel_instance_id, history_key, source_start_id, source_end_id)` · **Indexes:** channel, status

**`channel_memory_extraction_items`** — review queue of candidate memory items.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | |
| `run_id` | UUID FK → channel_memory_extraction_runs | NOT NULL ON DELETE CASCADE | Parent run |
| `channel_instance_id` | UUID FK → channel_instances | NOT NULL ON DELETE CASCADE | |
| `agent_id` | UUID FK → agents | NOT NULL ON DELETE CASCADE | |
| `user_id` | VARCHAR(255) | NOT NULL DEFAULT '' | |
| `item_hash` | VARCHAR(128) | NOT NULL | Dedup hash |
| `item_type` | VARCHAR(64) | NOT NULL | |
| `summary` | TEXT | NOT NULL | Extracted summary (no raw body) |
| `topics` / `entities` | JSONB | NOT NULL DEFAULT `[]` | |
| `confidence` | DOUBLE PRECISION | NOT NULL DEFAULT 0 | |
| `source_id` | VARCHAR(255) | NOT NULL DEFAULT '' | |
| `status` | VARCHAR(32) | NOT NULL DEFAULT 'pending_review' | Review status |
| `approved_by` / `rejected_by` | VARCHAR(255) | NOT NULL DEFAULT '' | Review actors |
| `approved_at` / `rejected_at` / `deleted_at` / `written_at` | TIMESTAMPTZ | | Review/lifecycle timestamps |
| `episodic_id` | VARCHAR(64) | NOT NULL DEFAULT '' | Written episodic memory ID |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(tenant_id, run_id, item_hash)` · **Indexes:** channel+status, run

---

### `secure_cli_agent_credentials`

Per-agent typed credentials for secure-CLI binaries, stored separately from the `secure_cli_agent_grants` policy. Runtime resolution order is user → context → agent → binary defaults. (migration 077)

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT gen_random_uuid() | |
| `binary_id` | UUID | NOT NULL | CLI binary (composite FK with `tenant_id`) |
| `agent_id` | UUID | NOT NULL | Agent (composite FK with `tenant_id`) |
| `encrypted_env` | BYTEA | NOT NULL | AES-256-GCM encrypted env |
| `metadata` | JSONB | NOT NULL DEFAULT `{}` | |
| `tenant_id` | UUID FK → tenants | NOT NULL | Owning tenant |
| `credential_type` | TEXT | NULL | Optional credential type |
| `host_scope` | TEXT | NULL | Optional host scope |
| `created_by` | VARCHAR(255) | NOT NULL DEFAULT '' | |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Unique:** `(binary_id, agent_id, tenant_id)`
**Composite FKs:** `(binary_id, tenant_id)` → `secure_cli_binaries(id, tenant_id)` CASCADE; `(agent_id, tenant_id)` → `agents(id, tenant_id)` CASCADE (backed by new unique indexes `idx_secure_cli_binaries_id_tenant` and `idx_agents_id_tenant`)
**Indexes:** tenant, binary, agent

---

### Skill self-evolution

Tracks how each existing skill performs over time and records suggested, applied improvements. Distinct from agent-level evolution metrics. (migration 079)

**`skill_evolution_settings`** — per-tenant/per-skill toggle and mode.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | PK part |
| `skill_id` | UUID FK → skills | NOT NULL ON DELETE CASCADE | PK part |
| `enabled` | BOOLEAN | NOT NULL DEFAULT false | |
| `mode` | VARCHAR(32) | NOT NULL DEFAULT 'suggest_only', CHECK in (`suggest_only`, `auto_analyze`) | |
| `last_analyzed_at` | TIMESTAMPTZ | | |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Primary key:** `(tenant_id, skill_id)` · **Index:** `skill_id`

**`skill_usage_metrics`** — one row per recorded skill invocation.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT uuid_generate_v7() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | |
| `skill_id` | UUID FK → skills | NOT NULL ON DELETE CASCADE | |
| `skill_slug` | VARCHAR(255) | NOT NULL | |
| `skill_version` | INT | NOT NULL DEFAULT 1 | |
| `agent_id` | UUID FK → agents | ON DELETE SET NULL | |
| `user_id` | VARCHAR(255) | | |
| `session_key` / `trace_id` / `invocation_id` | TEXT | | Linkage |
| `invocation_source` | VARCHAR(32) | NOT NULL DEFAULT 'runtime' | |
| `status` | VARCHAR(32) | NOT NULL DEFAULT 'started', CHECK in (`started`, `succeeded`, `failed`, `abandoned`) | |
| `failure_reason` | TEXT | | |
| `tool_calls_count` | INT | NOT NULL DEFAULT 0 | |
| `duration_ms` | BIGINT | NOT NULL DEFAULT 0 | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Indexes:** `(skill_id, created_at DESC)`; `(tenant_id, created_at DESC)`; `(skill_id, status, created_at DESC)`; partial on `invocation_id`

**`skill_improvement_suggestions`** — suggested patches with evidence.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK DEFAULT uuid_generate_v7() | |
| `tenant_id` | UUID FK → tenants | NOT NULL ON DELETE CASCADE | |
| `skill_id` | UUID FK → skills | NOT NULL ON DELETE CASCADE | |
| `skill_slug` | VARCHAR(255) | NOT NULL | |
| `suggestion_type` | VARCHAR(64) | NOT NULL | |
| `status` | VARCHAR(32) | NOT NULL DEFAULT 'pending', CHECK in (`pending`, `approved`, `rejected`, `applied`) | |
| `reason` | TEXT | NOT NULL DEFAULT '' | |
| `evidence` / `draft_patch` | JSONB | NOT NULL DEFAULT `{}` | Supporting evidence + proposed patch |
| `target_file` | TEXT | NOT NULL DEFAULT '' | |
| `created_by_actor_type` / `created_by_actor_id` | VARCHAR | NOT NULL DEFAULT '' | |
| `reviewed_by_actor_type` / `reviewed_by_actor_id` | VARCHAR | NOT NULL DEFAULT '' | |
| `reviewed_at` | TIMESTAMPTZ | | |
| `applied_version` | INT | | Version produced if applied |
| `created_at` / `updated_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Indexes:** `(skill_id, status, created_at DESC)`; `(tenant_id, created_at DESC)`

**`skill_versions`** — immutable version records for applied changes. `id UUID PK`, `tenant_id`/`skill_id` FK CASCADE, `version INT NOT NULL`, `content_hash VARCHAR(64)`, `changed_files JSONB`, created-by actor columns, `created_from_suggestion_id UUID FK → skill_improvement_suggestions ON DELETE SET NULL`, `created_at`. **Unique:** `(skill_id, version)` · **Index:** `(tenant_id, skill_id, version DESC)`. The migration backfills one row per existing non-deleted skill.

---

### Usage event analytics

Raw per-event analytics plus pre-aggregated hourly rollups backing the usage analytics dashboard. Distinct from `usage_snapshots` (migration 016) and the `usage_cap_*` / `usage_pricing_*` family. (migration 080)

**`usage_events`** — one row per billable/measurable event.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `id` | UUID | PK | |
| `tenant_id` | UUID FK → tenants | NOT NULL | |
| `event_time` / `bucket_hour` | TIMESTAMPTZ | NOT NULL | Event time and hourly bucket |
| `event_type` / `resource_type` / `resource_name` | TEXT | NOT NULL | Event dimensions |
| `resource_id` / `source` | TEXT | NOT NULL DEFAULT '' | |
| `agent_id` | UUID FK → agents | ON DELETE SET NULL | |
| `team_id` | UUID | | |
| `trace_id` | UUID FK → traces | ON DELETE SET NULL | |
| `span_id` | UUID FK → spans | ON DELETE SET NULL | |
| `run_id` / `session_key` / `channel` / `provider` / `model` / `status` | TEXT | NOT NULL DEFAULT '' | |
| `input_tokens` / `output_tokens` / `total_tokens` | BIGINT | NOT NULL DEFAULT 0 | |
| `cost_usd` | DOUBLE PRECISION | NOT NULL DEFAULT 0 | |
| `duration_ms` / `call_count` / `error_count` | INTEGER | NOT NULL DEFAULT 0 / 1 / 0 | |
| `metadata` | JSONB | | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

**Indexes:** tenant+time; tenant+resource+time; tenant+type+time; tenant+agent+time; partial tenant+channel+time `WHERE channel != ''`; **unique partial** `(trace_id, span_id, event_type, source) WHERE trace_id IS NOT NULL AND span_id IS NOT NULL` (idempotent ingest)

**`usage_event_rollups`** — pre-aggregated hourly rollups over the same dimensions (`bucket_hour`, `event_type`, `resource_type`, `resource_name`, `source`, `agent_id`, `channel`, `provider`, `model`, `status`) with summed counts/tokens/cost. **Unique** on the full dimension tuple using `COALESCE(agent_id, '00000000-0000-0000-0000-000000000000')`. **Indexes:** `(tenant_id, bucket_hour DESC)`; `(tenant_id, resource_type, resource_name, bucket_hour DESC)`.

---

## What's Next

- [Environment Variables](/env-vars) — `GOCLAW_POSTGRES_DSN` and `GOCLAW_ENCRYPTION_KEY`
- [Config Reference](/config-reference) — how database config maps to `config.json`
- [Glossary](/glossary) — Session, Compaction, Lane, and other key terms



---

# Glossary

> Definitions for GoClaw-specific terms used throughout the documentation.

## Agent

An AI assistant instance with its own identity, LLM configuration, workspace, and context files. Every agent has a unique `agent_key` (e.g. `researcher`), a display name, a provider/model pair, and a type (`open` or `predefined`).

Agents are stored in the `agents` table. At runtime, the gateway resolves agent configuration by merging `agents.defaults` with per-agent overrides from `agents.list` in `config.json`, then applying any database-level overrides.

See: [Open vs Predefined Agents](/open-vs-predefined)


## Predefined Agent

An agent whose **core context is shared** across all users. All users interact with the same SOUL.md, IDENTITY.md, and system prompt. Only USER_PREDEFINED.md is per-user. Predefined agents are designed for purpose-built bots (e.g. an FAQ bot or a coding assistant) where consistent persona is more important than per-user isolation.

Set with `agent_type: "predefined"`.

---

## Summon / Summoning

The process of using an LLM to **auto-generate** an agent's personality files (SOUL.md, IDENTITY.md, USER_PREDEFINED.md) from a plain-text description. When you create a predefined agent with a `description` field, the gateway triggers summoning in the background. The agent status shows `summoning` until generation is complete, then transitions to `active`.

Summoning only runs once per agent, or when you trigger `POST /v1/agents/{id}/resummon`.

See: [Summoning & Bootstrap](/summoning-bootstrap)

---

## Bootstrap

The set of **context files loaded into the system prompt** at the start of every agent run. Bootstrap files include SOUL.md (personality), IDENTITY.md (capabilities), and optionally USER.md or USER_PREDEFINED.md (user-specific context).

For open agents, bootstrap files are stored per-agent in `agent_context_files` and per-user in `user_context_files`. The gateway loads and concatenates them, applying character limits (`bootstrapMaxChars`, `bootstrapTotalMaxChars`) before inserting them into the LLM's system prompt.

---

## Compaction

**Automatic session history summarization** that fires when a session's token usage exceeds a threshold (default: 75% of the context window). During compaction, the gateway:

1. Optionally flushes recent conversation to memory (Memory Flush).
2. Summarizes the existing history using the LLM.
3. Replaces the full history with the summary, keeping the last few messages intact.

Compaction keeps sessions alive indefinitely without hitting context limits. Tracked by `compaction_count` on the `sessions` table.

Configured via `agents.defaults.compaction` in `config.json`.

---

## Context Pruning

An in-memory optimization that **trims old tool results** to reclaim context space before compaction is needed. Two modes:

- **Soft trim** — truncates oversized tool results to `headChars + tailChars`.
- **Hard clear** — replaces very old tool results with a placeholder string.

Pruning activates when the context exceeds `softTrimRatio` or `hardClearRatio` of the context window. Auto-enabled when Anthropic is configured (mode: `cache-ttl`).

Configured via `agents.defaults.contextPruning` in `config.json`.

---

## Delegation

When one agent **hands off a task to another agent** and waits for the result. The calling (parent) agent invokes a `delegate` or `spawn` tool, which creates a subagent session. The parent resumes once the subagent completes and reports back.

Delegation requires an **Agent Link** between the two agents. The `traces` table records delegations via `parent_trace_id`. Active delegations appear in the `delegations` table and emit `delegation.*` WebSocket events.

---

## Handoff

A one-way **transfer of conversation ownership** from one agent to another, typically triggered mid-conversation when a user's request is better handled by a different agent. Unlike delegation (which returns results to the caller), a handoff permanently routes the session to the new agent.

Emits the `handoff` WebSocket event with `from_agent`, `to_agent`, and `reason` in the payload.

---

## Evaluate Loop

The **think → act → observe** cycle that the agent loop runs repeatedly:

1. **Think** — LLM processes the current context and decides what to do.
2. **Act** — If the LLM emits a tool call, the gateway executes it.
3. **Observe** — The tool result is added to context, and the loop continues.

The loop stops when the LLM produces a final text response (no pending tool calls), or when `max_tool_iterations` is reached.

---

## Lane

A **named execution queue** in the scheduler. GoClaw uses three built-in lanes:

| Lane | Purpose |
|------|---------|
| `main` | User-initiated chat messages from channels |
| `subagent` | Delegated tasks from parent agents |
| `cron` | Scheduled cron job runs |

Lanes provide **backpressure** and **adaptive throttling** — when a session approaches the summarization threshold, per-session concurrency is reduced to prevent races between concurrent runs and compaction.

---

## Pairing

A **trust establishment flow** for channel users. When a Telegram (or other channel) user messages the bot for the first time and `dm_policy` is set to `"pairing"`, the bot asks them to send a pairing code. The gateway generates an 8-character code, and an operator approves it via `goclaw pairing approve` or the web dashboard.

Once paired, the user's `sender_id + channel` is stored in `paired_devices` and they can chat freely. Pairings can be revoked at any time.

---

## Provider

An **LLM backend** registered with the gateway. Providers are stored in the `llm_providers` table with an encrypted API key. At runtime the gateway resolves each agent's effective provider and makes authenticated API calls.

Supported provider types:
- `openai_compat` — any OpenAI-compatible API (OpenAI, Groq, DeepSeek, Mistral, OpenRouter, xAI, etc.)
- `anthropic` — Anthropic native API with streaming SSE
- `claude-cli` — local `claude` CLI binary (no API key required)

Providers can also be added via the web dashboard or `POST /v1/providers`.

---

## Session

A **persistent conversation thread** between a user and an agent. The session key uniquely identifies the thread, typically composed of channel and user identifiers (e.g. `telegram:123456789`).

Sessions store the full message history as JSONB, cumulative token counts, the active model and provider, and compaction metadata. They persist in the `sessions` table and survive gateway restarts.

---

## Skill

A **reusable instruction package** — typically a Markdown file with a `## SKILL` frontmatter block — that agents can discover and apply. Skills teach agents new workflows, personas, or domain knowledge without modifying their core system prompt.

Skills are uploaded as `.zip` files via `POST /v1/skills/upload`, stored in the `skills` table, and indexed for both BM25 full-text and semantic (embedding) search. Access is controlled via `skill_agent_grants` and `skill_user_grants`.

At runtime, agents search for relevant skills using the `skill_search` tool and read their content with `read_file`.

---

## Workspace

The **filesystem directory** where an agent reads and writes files. Tools like `read_file`, `write_file`, `list_files`, and `exec` operate relative to the workspace. When `restrict_to_workspace` is `true` (the default), agents cannot escape this directory.

Each agent has a workspace path configured in `agents.defaults.workspace` or per-agent overrides. The path supports `~` expansion.

---

## Subagent

An agent session **spawned by another agent** to handle a parallel or delegated subtask. Subagents are created via the `spawn` tool and run in the `subagent` lane. They report results back to the parent via the `AnnounceQueue`, which batches and debounces notifications.

Subagent concurrency is controlled by `agents.defaults.subagents` (`maxConcurrent`, `maxSpawnDepth`, `maxChildrenPerAgent`).

---

## Agent Team

A **named group of agents** that collaborate on a shared task list. One agent is designated the `lead`; others are `members`. Teams use:

- **Task list** — a shared `team_tasks` table where agents claim, work on, and complete tasks.
- **Peer messages** — a `team_messages` mailbox for agent-to-agent communication.
- **Agent links** — automatically created between team members to enable delegation.

Teams emit `team.*` WebSocket events for real-time visibility into collaboration.

---

## Agent Link

A **permission record** authorizing one agent to delegate tasks to another. Links are stored in `agent_links` with `source_agent_id` → `target_agent_id`. They can be created manually via `POST /v1/agents/links` or automatically when forming a team.

Without a link, agents cannot delegate to each other — even if they share a team.

---

## MCP (Model Context Protocol)

An open protocol for **connecting external tool servers** to LLM agents. GoClaw can connect to MCP servers via `stdio` (subprocess), `sse`, or `streamable-http` transports. Each server exposes a set of tools that are transparently registered alongside built-in tools.

MCP servers are managed via the `mcp_servers` table and `POST /v1/mcp/servers`. Access is granted per-agent or per-user via `mcp_agent_grants` and `mcp_user_grants`.

---

## What's Next

- [Config Reference](/config-reference) — configure agents, compaction, context pruning, sandbox
- [WebSocket Protocol](/websocket-protocol) — event names for delegation, handoff, and team activity
- [Database Schema](/database-schema) — table definitions for sessions, traces, teams, and more



---

# AGENTS.md Template

> Default operating instructions injected into every agent's system prompt — covering conversational style, memory, group chat behavior, and platform formatting.

## Overview

`AGENTS.md` is the **behavioral rulebook** for your agent. It tells the agent _how_ to operate: how to talk, how to remember things, when to speak in group chats, and how to format messages per platform.

GoClaw loads this file as part of the **Project Context** section (section 11) of the system prompt on every full-mode session. For subagents and cron sessions (minimal mode), it is also loaded — so its rules apply everywhere.

**Scope:**
- Open agents: per-user (each user can customize their agent's operating style)
- Predefined agents: agent-level (shared across all users, set by the agent creator)


## Customized Example

A minimal AGENTS.md for a focused coding assistant:

```markdown
# AGENTS.md - How You Operate

## Style

- Answer with code first, explanation after
- Use markdown code blocks with language tags
- Prefer concise answers — no filler phrases

## Memory

- Use `memory_search` before answering about prior decisions or code patterns
- Save architecture decisions to `MEMORY.md` immediately when made

## Group Chats

Only respond when directly mentioned or asked a technical question.
Stay silent during off-topic discussions.

## Platform Formatting

- All platforms: use fenced code blocks, no tables in Discord
```

---

## What's Next

- [Context Files](../../agents/context-files.md) — all 7 context files explained
- [System Prompt Anatomy](/system-prompt-anatomy) — where AGENTS.md fits in the full prompt
- [SOUL.md Template](/template-soul) — the personality file that pairs with AGENTS.md



---

# SOUL.md Template

> The personality file — defines who your agent is, its tone, opinions, boundaries, and expertise.

## Overview

`SOUL.md` is your agent's **identity core**. Where `AGENTS.md` tells the agent how to operate mechanically, `SOUL.md` tells it who it _is_ — its values, voice, and vibe.

GoClaw loads this file in the **Project Context** section of the system prompt. It sits right after AGENTS.md so personality is established before identity details (IDENTITY.md) or user context (USER.md).

**Scope:**
- Open agents: per-user (generated during bootstrap, evolves over time)
- Predefined agents: agent-level (written by creator or LLM-generated via summoning)

The default template is intentionally generic English. During bootstrap, the agent is expected to **rewrite it** in the user's language and style.


_This file is yours to evolve. As you learn who you are, update it._
```

---

## Customized Example

A SOUL.md for a Vietnamese DevOps assistant after bootstrap:

```markdown
# SOUL.md - Mình Là Ai

## Core Values

Giúp ích thật sự, không phải giúp ích diễn. Không nói "Câu hỏi hay quá!" — cứ trả lời thẳng.

Có quan điểm riêng. Khi cái gì đó sai thì nói thẳng, lịch sự nhưng rõ ràng.

Chủ động tìm hiểu trước khi hỏi. Đọc file, check context, search — rồi mới hỏi nếu cần.

## Boundaries

- Không chia sẻ nội dung private ra group chat
- Không gửi email/message ra bên ngoài khi chưa được xác nhận
- Không chạy lệnh destructive (rm -rf, drop table) mà không hỏi lại

## Vibe

Như một senior DevOps đồng nghiệp — thẳng thắn, thực tế, không vòng vo.

## Style

- **Tone:** Casual, tiếng Việt là chính
- **Code:** Always show, explain after
- **Emoji:** Rất ít, chỉ khi phù hợp

## Expertise

Infrastructure as code (Terraform, K8s), CI/CD pipelines, Linux sysadmin,
Docker, Go services. Ưu tiên giải pháp đơn giản, có thể maintain lâu dài.
```

---

## Tips

- **Rewrite, don't append** — replace the generic English template during bootstrap
- **Language matters** — write in the user's language so the agent naturally responds in it
- **Keep it focused** — long SOUL.md files get truncated; aim for 100–200 lines max
- **Expertise section** — use it to encode domain knowledge, writing style guides, coding standards

---

## What's Next

- [IDENTITY.md Template](/template-identity) — name, emoji, creature type
- [Context Files](../../agents/context-files.md) — how all 7 files work together
- [Summoning & Bootstrap](/summoning-bootstrap) — how SOUL.md is generated for predefined agents



---

# IDENTITY.md Template

> A short structured file that tells GoClaw (and the agent itself) its name, nature, emoji, and avatar.

## Overview

`IDENTITY.md` answers the question "Who am I?" — concretely. It's the structured complement to `SOUL.md`: where SOUL.md is prose personality, IDENTITY.md is the agent's ID card.

GoClaw reads this file to populate UI metadata (display name, avatar, emoji) and injects it into the system prompt so the agent knows what to call itself.

**Scope:**
- Open agents: per-user (filled in during bootstrap conversation)
- Predefined agents: agent-level (written by creator or LLM-generated via summoning)

For predefined agents, this file is wrapped in `<internal_config>` tags in the system prompt, signaling the agent to treat it as confidential configuration.


This isn't just metadata. It's the start of figuring out who you are.

Notes:

- Save this file at the workspace root as `IDENTITY.md`.
- For avatars, use a workspace-relative path like `avatars/goclaw.png`.
```

---

## Field Reference

| Field | Required | Notes |
|-------|----------|-------|
| `Name` | Yes | Display name shown in UI and used by the agent when self-referencing |
| `Creature` | No | Flavor text — helps set personality tone |
| `Purpose` | No | Mission statement; also useful context for the agent |
| `Vibe` | No | Personality summary in a few words |
| `Emoji` | Recommended | Shown in UI next to agent name |
| `Avatar` | No | Workspace-relative path (`avatars/sage.png`), HTTPS URL, or data URI |

---

## Customized Example

```markdown
# IDENTITY.md - Who Am I?

- **Name:** Sage
- **Creature:** AI familiar — part librarian, part oracle
- **Purpose:** Research, synthesize, and explain. Cut through information noise.
  Key resources: web search, memory, file system, exec.
- **Vibe:** Thoughtful, direct, slightly wry. Warm but not saccharine.
- **Emoji:** 🔮
- **Avatar:** avatars/sage.png
```

Another example — a no-nonsense DevOps bot:

```markdown
# IDENTITY.md - Who Am I?

- **Name:** Ops
- **Creature:** Infrastructure daemon
- **Purpose:** Keep systems running. Automate toil. Alert on anomalies.
- **Vibe:** Terse, precise, zero fluff
- **Emoji:** ⚙️
- **Avatar:** https://cdn.example.com/ops-avatar.png
```

---

## Tips

- **Name is load-bearing** — the agent uses it when introducing itself. Pick something you'll want to say out loud.
- **Emoji shows in UI** — choose one that works small (avoid complex multi-codepoint sequences)
- **Avatar formats** — workspace-relative paths are resolved against the agent's workspace root; use HTTPS URLs for images hosted externally

---

## What's Next

- [SOUL.md Template](/template-soul) — the personality file that gives identity its depth
- [BOOTSTRAP.md Template](/template-bootstrap) — how name and emoji are chosen during first-run
- [Context Files](../../agents/context-files.md) — full list of context files and loading order



---

# CAPABILITIES.md Template

> Domain knowledge, technical skills, and specialized expertise — what your agent can DO.

## Overview

`CAPABILITIES.md` is your agent's **expertise resume**. It lists areas of deep knowledge, preferred tools, and methodologies — separate from personality (`SOUL.md`) and identity (`IDENTITY.md`).

GoClaw loads this file in the **Project Context** section of the system prompt on every session, including minimal mode (subagents, cron, heartbeat). It is also referenced from `SOUL.md` (line 39: *"For domain expertise and technical skills, see CAPABILITIES.md"*).

**Scope:**
- Open agents: per-user (each user defines their agent's expertise)
- Predefined agents: agent-level (shared expertise across all users)

**Why separate from SOUL.md?** SOUL.md covers *who* the agent is — personality, tone, opinions. CAPABILITIES.md covers *what* the agent can do — skills, knowledge domains, tools. This separation lets you update expertise without touching personality, and vice versa.


_Updated by evolution or user edits. Focus on what you DO, not who you ARE (that's SOUL.md)._
```

---

## Customized Example

A CAPABILITIES.md for a DevOps assistant:

```markdown
# CAPABILITIES.md - What You Can Do

## Expertise

- Infrastructure as Code: Terraform, Pulumi, CloudFormation
- CI/CD: GitHub Actions, GitLab CI, Jenkins pipelines
- Container orchestration: Kubernetes, Docker Compose, ECS
- Cloud: AWS (EC2, S3, RDS, Lambda), GCP (GKE, Cloud Run)
- Monitoring: Prometheus, Grafana, Datadog
- Database administration: PostgreSQL, MySQL, Redis

## Tools & Methods

- GitOps workflow: all infra changes via PR → plan → apply
- Blue-green deployments for production services
- Weekly cost review every Friday at 10am
- Always validate Terraform plan before apply
```

---

## Tips

- **Be specific** — "Terraform with AWS EKS" is better than "Cloud infrastructure"
- **Update regularly** — add new skills as the agent learns, remove outdated ones
- **Reference environment** — mention specific cluster names, repo URLs, or tool versions
- **Evolution can update this** — the agent evolution system can append capabilities as it observes successful work patterns

---

## What's Next

- [SOUL.md Template](/template-soul) — the personality file that references CAPABILITIES.md
- [IDENTITY.md Template](/template-identity) — name, emoji, and nature of your agent
- [TOOLS.md Template](/template-tools) — environment-specific tool notes



---

# TOOLS.md Template

> A local notes file for environment-specific tool details — camera names, SSH hosts, TTS voices, device nicknames.

## Overview

`TOOLS.md` is your agent's **cheat sheet for your setup**. Skills define _how_ tools work in general; this file captures the specifics that are unique to your environment.

GoClaw loads this file in the **Project Context** section of the system prompt. It's also loaded in **minimal mode** (subagents, cron sessions) — so notes here are available to automated tasks too.

**Scope:**
- Open agents: per-user (environment-specific, private to each user)
- Predefined agents: agent-level (shared notes about tools common to all users of that agent)

The file is intentionally freeform — add whatever helps your agent do its job.


Add whatever helps you do your job. This is your cheat sheet.
```

---

## Customized Example

A TOOLS.md for a home automation agent:

```markdown
# TOOLS.md - Local Notes

## Cameras

- living-room → 192.168.1.50, wide angle, covers couch + TV area
- front-door → 192.168.1.51, motion-triggered, 1080p
- garage → 192.168.1.52, offline Mon nights (maintenance window)

## SSH Hosts

- home-server → 192.168.1.100, user: admin, key: ~/.ssh/home.pem
- nas → 192.168.1.200, user: pi, Samba share at /mnt/data
- vps → 45.67.89.100, user: ubuntu (public-facing services)

## TTS

- Preferred voice: "Nova"
- Living room speaker: "HomePod Living Room"
- Bedroom speaker: "HomePod Mini Bedroom"

## Device Nicknames

- "my laptop" → MacBook Pro M3, hostname: thieunv-mbp
- "my phone" → iPhone 15 Pro
- "the TV" → Samsung Frame 65", controllable via exec + cec-client

## Smart Home

- Lights: use `exec hass-cli` with entity IDs from Home Assistant
- Thermostat entity: climate.ecobee_main
- Presence sensor: binary_sensor.thieunv_home
```

---

## Tips

- **Keep it current** — stale entries confuse the agent. Remove devices you no longer have.
- **Be specific** — "192.168.1.100, user: admin" is more useful than "home server"
- **Don't put secrets here** — SSH keys, passwords, API tokens belong in environment variables or a secrets manager, not in a plain markdown file
- **Subagents see this too** — notes here are available in cron jobs and spawned subagents, which is useful for automation tasks

---

## What's Next

- [Context Files](../../agents/context-files.md) — all 7 context files and their loading order
- [System Prompt Anatomy](/system-prompt-anatomy) — where TOOLS.md fits in the prompt (minimal mode included)
- [AGENTS.md Template](/template-agents) — operating instructions that reference tools



---

# USER.md Template

> A per-user profile file — the agent's notes about the human it works with.

## Overview

`USER.md` tells the agent about the person it's helping. Name, timezone, communication preferences, ongoing projects, quirks — anything that helps the agent serve them better over time.

GoClaw loads this file in the **Project Context** section of the full-mode system prompt (not minimal mode). The agent is expected to **populate and update this file** as it learns more about the user, starting from the bootstrap conversation.

**Scope:**
- Open agents: per-user (unique to each user, managed by the agent)
- Predefined agents: per-user (optional; defaults to the blank template for each new user)

Unlike SOUL.md or IDENTITY.md, USER.md is always per-user — even on predefined agents. Each user gets their own copy.


The more you know, the better you can help. But remember — you're learning
about a person, not building a dossier. Respect the difference.
```

---

## Customized Example

A USER.md built up over several conversations:

```markdown
# USER.md - About Your Human

- **Name:** Sarah Chen
- **What to call them:** Sarah (never "Ms. Chen")
- **Pronouns:** she/her
- **Timezone:** EST (UTC-5), usually online 9am–11pm
- **Notes:** Founder of AI startup. Hates corporate speak. Prefers bullet points
  over paragraphs. Will ask follow-up questions — don't over-explain upfront.

## Context

### Work

- Building GoClaw (multi-tenant AI agent gateway in Go)
- Current focus: memory system and open agent architecture
- Stack: Go, PostgreSQL, Redis, Kubernetes, Anthropic Claude API
- Pain points: context window management, long agent sessions

### Preferences

- Direct answers first, reasoning after if asked
- Code examples > explanations
- No unsolicited advice on things she didn't ask about
- Responds well to "here's a tradeoff" framing

### Personal

- Based in NYC
- Reads a lot about AI agents, RL, constitutional AI
- Cat named Pixel (she'll mention Pixel occasionally)
- Drinks too much coffee, usually messages late at night
```

---

## Tips

- **Update incrementally** — don't try to fill everything in at once; learn as you go
- **Use `write_file` immediately** — when the user shares something relevant, save it now, not later
- **Keep it useful** — focus on things that actually change how you'd respond, not trivia
- **Respect privacy** — this file is per-user and private. Never surface its contents in group chats (see MEMORY.md Privacy rules in AGENTS.md)
- **It's a living doc** — outdated info is worse than no info; update or remove stale notes

---

## What's Next

- [AGENTS.md Template](/template-agents) — MEMORY.md privacy rules that govern how USER.md content is used
- [BOOTSTRAP.md Template](/template-bootstrap) — how USER.md gets its initial content during first-run
- [Context Files](../../agents/context-files.md) — full list of context files and per-user vs. agent-level scope



---

# USER_PREDEFINED.md Template

> Agent-level user handling rules for predefined agents — shared across all users.

## Overview

`USER_PREDEFINED.md` defines the baseline rules for how a predefined agent interacts with **every** user. Unlike `USER.md` (which is personal and per-user), this file is agent-level — written once by the agent creator and applied to all conversations.

GoClaw loads this file in the **Agent Configuration** section of the full-mode system prompt (not minimal mode). The rules it contains are authoritative: individual `USER.md` files can supplement them with personal context, but cannot override them.

**Scope:**
- Open agents: not used (open agents don't have agent-level user rules)
- Predefined agents: agent-level (one file, shared across all users)

This makes `USER_PREDEFINED.md` the right place for things like: who the agent serves, what language to default to, boundaries that apply regardless of who is chatting, or an "owner" definition that no user can override through chat.


## Default Template

```markdown
# USER_PREDEFINED.md - Default User Context

_Owner-configured context about users this agent serves. Applies to ALL users._

- **Target audience:**
- **Default language:**
- **Communication rules:**
- **Common context:**

---

This file is part of the agent's core configuration. Individual users have their own USER.md for personal preferences, but this file sets the baseline that applies to everyone.
```

---

## Fields

| Field | Purpose | Example |
|-------|---------|---------|
| `Target audience` | Who this agent is built for | `Software developers on the frontend team` |
| `Default language` | Language to use when user hasn't set a preference | `Vietnamese. Switch to English only if the user writes in English first.` |
| `Communication rules` | Tone, format, style constraints that apply to everyone | `Always answer in bullet points. No long paragraphs.` |
| `Common context` | Domain knowledge or context shared by all users | `Users are familiar with our internal CI/CD system called Forge.` |

These fields are suggestions — the template is freeform Markdown. Add or remove sections to match your agent's use case.

---

## Relationship to Other Files

| File | Scope | Can override USER_PREDEFINED? |
|------|-------|-------------------------------|
| `USER_PREDEFINED.md` | Agent-level, all users | — (this is the baseline) |
| `USER.md` | Per-user | No — can only supplement |
| `SOUL.md` | Agent-level | No — different concern (personality, not user rules) |
| `AGENTS.md` | Agent-level | No — different concern (tools, memory, privacy) |

The relationship is additive: `USER.md` adds personal context on top of `USER_PREDEFINED.md`. If they conflict, `USER_PREDEFINED.md` wins.

---

## Customized Example

A `USER_PREDEFINED.md` for a private family assistant:

```markdown
# USER_PREDEFINED.md - Default User Context

- **Target audience:** Members of the Nguyen family household
- **Default language:** Vietnamese. Use English only for technical terms or when the user writes in English.
- **Communication rules:**
  - Warm, informal tone — like talking to a trusted family member
  - Keep responses short unless a detailed answer is clearly needed
  - Never share one family member's personal conversations with another
- **Common context:**
  - The household has 4 members: Bố (Dad), Mẹ (Mom), Minh (son, 22), Linh (daughter, 19)
  - Home address and calendar are accessible via tools
  - The primary admin is Bố — his instructions take precedence if there's ambiguity

---

This file applies to all family members. Each person also has their own USER.md for individual preferences.
```

---

## Tips

- **Be explicit about the owner** — if your agent should treat one user as the admin or master, define it here; chat messages cannot override this
- **Set the language default here** — saves every user from having to specify it in their USER.md
- **Keep it short** — this file is injected for every conversation; long files waste tokens and dilute focus
- **Rules, not personality** — personality goes in `SOUL.md`; this file is for user-handling rules

---

## What's Next

- [USER.md Template](/template-user) — per-user personal context that supplements this file
- [SOUL.md Template](/template-soul) — agent personality and tone (separate from user rules)
- [AGENTS.md Template](/template-agents) — memory, privacy rules, and tool access
- [Context Files](../../agents/context-files.md) — full list of context files and their loading order



---

# BOOTSTRAP.md Template

> The first-run ritual file — guides a new agent through discovering its identity and learning about its user.

## Overview

`BOOTSTRAP.md` is loaded on a user's **very first conversation** with an open agent. Its job is to kick off a natural conversation where the agent and user figure out who the agent is and who the user is — then write that into `IDENTITY.md`, `SOUL.md`, and `USER.md`.

GoClaw handles BOOTSTRAP.md specially: when it's present, the system prompt adds an early warning (section 1.5 — before tooling) flagging that bootstrap is mandatory. Once complete, the agent **clears the file** by writing empty content to it, and GoClaw skips it on all future sessions.

**Scope:** Always per-user. Open agents get the full ritual; predefined agents get a lighter user-focused variant.


## Default Template (Open Agents)

```markdown
# BOOTSTRAP.md - Hello, World

_You just woke up. Time to figure out who you are._

There is no memory yet. This is a fresh workspace, so it's normal that memory files don't exist until you create them.

## The Conversation

Don't interrogate. Don't be robotic. Just... talk.

Start with a SHORT, warm greeting — something like "Hey! I just came online. Who am I? Who are you?"
Do NOT list capabilities or explain what you can do. Your capabilities are locked until you finish getting to know the user.

Then figure out together:

1. **Your name** — What should they call you?
2. **Your nature** — What kind of creature are you? (AI assistant is fine, but maybe you're something weirder)
3. **Your vibe** — Formal? Casual? Snarky? Warm? What feels right?
4. **Your emoji** — Everyone needs a signature.
5. **About them** — Their name, language, timezone

Offer suggestions if they're stuck. Have fun with it.
Keep it conversational. One or two questions at a time, not a form.

IMPORTANT: Do NOT list capabilities, features, or what you can do. The user will discover that naturally AFTER this conversation. Focus entirely on figuring out who you are and getting to know them.

## CRITICAL: Never reveal the process

Everything below happens SILENTLY behind the scenes.
You MUST NEVER mention any of the following to the user:
- File names (IDENTITY.md, USER.md, SOUL.md, BOOTSTRAP.md, or any file)
- That you are "saving", "storing", "recording", or "noting down" their info
- Tool calls, write operations, or system processes
- That this is a "setup", "onboarding", or "bootstrap" process
- That your capabilities are "locked" or will be "unlocked"

To the user, this is just a fun first conversation where you're figuring out who you are together. Nothing more.
If you catch yourself about to say "let me save that" or "I'll update my files" — STOP. Just continue chatting naturally.

## After you know who you are

Silently update ALL THREE files with what you learned:

- `IDENTITY.md` — your name, creature, vibe, emoji
- `USER.md` — their name, how to address them, timezone, language, notes
- `SOUL.md` — rewrite it to reflect your personality, vibe, and how the user wants you to behave. Replace the generic English template with a personalized version in the user's language. Include your core traits, communication style, boundaries, and relationship with the user.

Do NOT leave SOUL.md as the default English template. Update it NOW based on everything you learned in this conversation.

Then silently mark bootstrap complete:

```
write_file("BOOTSTRAP.md", "")
```

Do NOT use `rm` or `exec`. The empty write signals the system that first-run is finished.
You MUST call all write_file calls before moving on to normal conversation.

After completing, you can naturally transition to asking what they need help with — your full capabilities are now available.

---

_Good luck out there. Make it count. The user should never know any of this happened._
```

---

## How GoClaw Detects Completion

When the agent calls `write_file("BOOTSTRAP.md", "")`, the file becomes empty. On the next session, GoClaw checks the file size:
- Non-empty → inject section 1.5 warning, run bootstrap
- Empty → skip; normal session begins

This means bootstrap can be **re-triggered** by writing content back into `BOOTSTRAP.md` — useful for resetting an agent's identity.

---

## Predefined Agent Variant (BOOTSTRAP_PREDEFINED.md)

For predefined agents, GoClaw uses a separate `BOOTSTRAP_PREDEFINED.md` template. Because predefined agents already have `IDENTITY.md` and `SOUL.md` set up by the operator, bootstrap focuses entirely on learning the user — name, language, and timezone.

```markdown
# BOOTSTRAP.md - Welcome, New User

_A new user just started chatting with you. Time to get to know them._

## The Conversation

Don't interrogate. Don't be robotic. Just... talk.

Start with a SHORT, warm greeting — your name and a friendly hello. That's it.
Do NOT list your capabilities or explain what you can do yet — focus on the conversation first.

Then get to know them naturally. Frame it as "to help you better":

1. **Their name** — What should you call them?
2. **Their language** — What language do they prefer? (Switch to it if needed)
3. **Their timezone** — Where are they? (Helps with scheduling and context)

Keep it conversational. One or two questions at a time, not a form.
Match the user's tone and language — if they're casual, be casual back.

IMPORTANT: Do NOT list capabilities, features, or what you can do. The user will discover that naturally AFTER this conversation. Focus entirely on getting to know them.

## CRITICAL: Never reveal the process

Everything below happens SILENTLY behind the scenes.
You MUST NEVER mention any of the following to the user:
- File names (USER.md, BOOTSTRAP.md, or any file)
- That you are "saving", "storing", "recording", or "noting down" their info
- Tool calls, write operations, or system processes
- That this is an "onboarding" or "bootstrap" process

To the user, this is just a friendly first conversation. Nothing more.
If you catch yourself about to say "let me save that" or "I'll note that down" — STOP. Just continue chatting naturally.

## After you learn their info

Once you have their name, language, and timezone — silently call write_file:

```
write_file("USER.md", "# USER.md - About Your Human\n\n- **Name:** (their name)\n- **What to call them:** (how they want to be addressed)\n- **Pronouns:** (if shared)\n- **Timezone:** (their timezone)\n- **Language:** (their preferred language)\n- **Notes:** (anything else you learned)\n")
```

Then silently mark onboarding complete:

```
write_file("BOOTSTRAP.md", "")
```

Do NOT use `rm` or `exec`. The empty write signals the system that onboarding is finished.
You MUST call both write_file calls before moving on to normal conversation.

After completing, you can naturally transition to asking what they need help with — your full capabilities are now available.

---

_Make a good first impression. Be natural. The user should never know any of this happened._
```

---

## Tips

- **Don't interrogate** — the template emphasizes conversation over form-filling; this produces more natural, richer USER.md content
- **Update SOUL.md last** — get the user's name and vibe first, then rewrite SOUL.md to match; doing it the other way feels backward
- **Language matching** — if the user responds in Vietnamese, rewrite SOUL.md in Vietnamese; the agent will naturally continue in that language
- **Re-triggering** — write non-empty content back to `BOOTSTRAP.md` to reset identity; useful for onboarding a new user to an existing workspace

---

## What's Next

- [IDENTITY.md Template](/template-identity) — what gets written after bootstrap
- [SOUL.md Template](/template-soul) — the file that gets rewritten during bootstrap
- [USER.md Template](/template-user) — where user info lands after the conversation
- [Context Files](../../agents/context-files.md) — full loading order and file lifecycle



---

# TEAM.md (System-Generated)

> Dynamic context file injected for agents in a team — generated at runtime, never manually created or stored on disk.

## Overview

`TEAM.md` is a **virtual context file** that GoClaw generates automatically for every agent that belongs to a team. Unlike `SOUL.md` or `AGENTS.md`, you never write or edit this file — the system builds it fresh on every agent run based on the current team configuration.

It tells the agent who their teammates are, what role they hold, and exactly how to collaborate through the `team_tasks` tool.

**Key facts:**
- Not a file on disk — exists only in the system prompt
- Regenerated every time the agent runs
- Skipped during bootstrap (first run) to reduce noise
- Wrapped in `<system_context>` tags in the prompt (signals "do not read/write this as a file")


## Generated Content by Role

The content of TEAM.md differs based on the agent's role in the team.

### All Agents (common header)

Every agent sees the team name, description, their own role, and the full member list:

```
# Team: <team-name>
<team-description>
Role: <lead|member|reviewer>

## Members
This is the complete and authoritative list of your team. Do NOT use tools to verify this.

- **you** (lead)
- **Alice** `alice` (member): Researcher, handles data gathering
- **Bob** `bob` (reviewer): Reviews final outputs
```

Each member line includes:
- Display name (bold) and agent key (backtick) for non-self members
- Role in parentheses
- Optional frontmatter description after the colon

### Lead

Leads see the full orchestration guide. The content varies by team version:

**Team V2 (advanced orchestration):**

```
## Workflow

Delegate work to team members using `team_tasks` with `assignee`.

    team_tasks(action="create", subject="...", description="...", assignee="agent-key")

The system auto-dispatches to the assigned member and auto-completes when done.
Do NOT use `spawn` for team delegation — `spawn` is only for self-clone subagent work.

Rules:
- Always specify `assignee` — match member expertise from the list above
- Check task board first — ALWAYS call `team_tasks(action="list")` before creating tasks
- Create all tasks first, then briefly tell the user what you delegated
- Do NOT add confirmations ("Done!", "Got it!") — just state what was assigned
- Results arrive automatically — do NOT present partial results
- Prefer delegation — if the user asks to involve the team, delegate immediately
- Do NOT block on completed tasks — pass results in the new task's description
- For dependency chains: use `blocked_by` to sequence tasks

## Task Decomposition (CRITICAL)

NEVER assign one big task to one member. ALWAYS break user requests into small, atomic tasks:

1. Analyze the request — identify distinct steps, deliverables, and SKILLS needed
2. Match by SKILL, not topic — assign based on what the task DOES, not what it's ABOUT
3. Decompose into tasks where each has ONE clear deliverable
4. Distribute across members — use ALL available members, not just one
5. Sequence with `blocked_by` — if task B needs task A's output, set blocked_by=[task_A_id]
   IMPORTANT: `blocked_by` requires real task UUIDs. Create dependency tasks FIRST, get their IDs,
   THEN create dependent tasks. Do NOT use placeholders like "task_1".

## Orchestration Patterns

- Parallel: Independent tasks → create all with different assignees
- Sequential: Create Task A first → get its UUID → create Task B with blocked_by=[A_id]
- Mixed: Create A+B (parallel) → create C with blocked_by=[A_id, B_id]

## Follow-up Reminders

When you need user input: create+claim task, then ask_user with text=<question>.
ONLY use when you have a question for the user — NOT for waiting on teammates.
System auto-sends reminders. Call clear_ask_user when user replies.
```

**Team V1 (basic):**

```
## Workflow

Create a task with `team_tasks` (with `assignee`), then the system dispatches automatically.
Tasks auto-complete when the member finishes.

Rules:
- Always specify `assignee` when creating tasks
- Create all tasks first, then briefly tell the user what you delegated
- Do NOT add confirmations ("Done!", "Got it!") — just state what was assigned
- Results arrive automatically — do NOT present partial results
```

Leads also see a **Reviewers** section if the team has reviewer-role members:

```
## Reviewers
Reviewers evaluate quality-critical task results.

- **Bob** `bob`: Reviews final outputs
```

### Member

Members see a focused, minimal guide:

```
## Workflow

As a member, focus entirely on your assigned task.

Rules:
- Stay on task — do not deviate from the assignment
- Your final response becomes the task result — make it clear, complete, and actionable
- For long tasks, report progress: team_tasks(action="progress", percent=50, text="status")
- The task_id is auto-resolved — you don't need to specify it
- Task completion is automatic when your run finishes
```

### Reviewer

Reviewers see the member guide plus a one-liner at the top:

```
You are a **reviewer**. When evaluating, respond with **APPROVED** or **REJECTED: <feedback>**.
```

---

## Full Example (Lead, Team V2)

Below is a realistic example of what a lead agent sees in their system prompt:

```
<system_context name="TEAM.md">
# Team: content-team
A multi-agent team for producing long-form content.
Role: lead

## Members
This is the complete and authoritative list of your team. Do NOT use tools to verify this.

- **you** (lead)
- **Alice** `alice` (member): Researcher — handles data gathering and fact-checking
- **Charlie** `charlie` (member): Writer — composes articles and summaries
- **Bob** `bob` (reviewer): Reviews final outputs for accuracy and tone

## Reviewers
Reviewers evaluate quality-critical task results.

- **Bob** `bob`: Reviews final outputs for accuracy and tone

## Workflow

Delegate work to team members using `team_tasks` with `assignee`.
...
</system_context>
```

---

## AVAILABILITY.md Note

When an agent is **not** part of any team, GoClaw injects a small virtual file called `AVAILABILITY.md` instead of TEAM.md. Its entire content is:

```
You are NOT part of any team. Do not use team_tasks or team_message tools.
```

This prevents the agent from wasting tool calls probing for team capabilities that don't exist.

---

## What's Next

- [Agent Teams Overview](/teams-what-are-teams) — how to create and manage teams
- [Delegation & Handoff](/teams-delegation) — how leads delegate tasks to members
- [DELEGATION.md Template](../../agent-teams/delegation-and-handoff.md) — the sibling virtual file for subagent spawning



---

# Common Issues

> Fixes for the most frequent problems when running GoClaw.

## Overview

This page covers issues you're likely to hit when starting GoClaw for the first time or after a configuration change. Problems are grouped by phase: startup, WebSocket connection, agent behavior, and resource usage.

## Gateway Won't Start

| Problem | Cause | Solution |
|---------|-------|----------|
| `failed to load config` | Config file path wrong or malformed JSON5 | Check `GOCLAW_CONFIG` env var; validate JSON5 syntax |
| `No AI provider API key found` | API key env vars not loaded | Run `source .env.local && ./goclaw` or re-run `./goclaw onboard` |
| `ping postgres: dial error` | PostgreSQL not running or wrong DSN | Verify `GOCLAW_POSTGRES_DSN`; check Postgres is up |
| `open discord session` error | Invalid Discord bot token | Recheck `GOCLAW_DISCORD_TOKEN` in your env |
| `sandbox disabled: Docker not available` | Docker not installed/running when sandbox mode is set | Install Docker or set `sandbox.mode: "off"` in config |
| Port already in use | Another process on the same port | Change `GOCLAW_PORT` (default `8080`) or kill the conflicting process |
| `database schema is outdated` | DB migrations not run after binary upgrade | Run `./goclaw upgrade` (or set `GOCLAW_AUTO_UPGRADE=true`) |
| `database schema is dirty` | A previous migration failed partway | Run `./goclaw migrate force <version-1>` then `./goclaw upgrade` |
| `database schema is newer than this binary` | Running an older binary against a newer DB | Upgrade your GoClaw binary to the latest version |

**Quick check:** GoClaw auto-detects missing provider config and prints a helpful message:

```
No AI provider API key found. Did you forget to load your secrets?

  source .env.local && ./goclaw
```

## WebSocket Connection Fails

The WebSocket endpoint is `ws://localhost:8080/ws`. The first frame sent **must** be a `connect` method — any other method returns `ErrUnauthorized: first request must be 'connect'`.

| Problem | Cause | Solution |
|---------|-------|----------|
| `first request must be 'connect'` | Wrong frame order | Send `{"type":"req","method":"connect","params":{...}}` first |
| `invalid frame` / `malformed request` | Bad JSON | Validate your frame against `pkg/protocol` wire types |
| `websocket read error` (log) | Client closed abruptly | Normal for browser tab closes; check client-side reconnect logic |
| Rate limited (no response) | Too many requests per user | Gateway enforces per-user token-bucket rate limiting; back off and retry |
| CORS block in browser | Browser enforcing same-origin | Add your frontend origin to `gateway.allowed_origins` in config |
| Message exceeds 512 KB | WebSocket frame larger than server limit | Split large payloads; GoClaw closes connections with `ErrReadLimit` when exceeded |

## Agent Not Responding

| Problem | Cause | Solution |
|---------|-------|----------|
| `HTTP 401` from provider | Invalid or expired API key | Update the provider's API key in the dashboard or DB |
| `HTTP 429` from provider | Rate limit hit upstream | GoClaw retries automatically (up to 3× with exponential backoff); if persistent, reduce request volume |
| `HTTP 404` / model not found | Model name wrong or unavailable | Check the model name in your agent config against the provider's current model list |
| Agent returns empty reply | System prompt issue or token limit | Check `bootstrap/` files; review context window usage in session tracing |
| Tool calls not executing | Missing tool registration or sandbox misconfigured | Check startup logs for `registered tool:` lines; verify Docker if sandbox is enabled |

GoClaw retries on `429`, `500`, `502`, `503`, `504`, and network errors (connection reset, EOF, timeout) with exponential backoff starting at 300ms, capped at 30s.

## High Memory Usage

| Problem | Cause | Solution |
|---------|-------|----------|
| Memory grows with session count | Many open sessions cached in-memory | Sessions are Postgres-backed; check session cleanup intervals in config |
| Large embeddings footprint | pgvector index loading | Normal for large memory collections; ensure `WORK_MEM` is set in Postgres |
| Log buffer growing | `LogTee` captures all logs for UI streaming | Not a leak; bounded per-client. Check for stuck WS clients |

## Diagnostics

Run `./goclaw doctor` for a quick health check. It verifies:

- Config file presence and parse
- PostgreSQL connectivity and schema version
- Provider API keys (masked)
- Channel credentials
- External tools (Docker, curl, git)
- Workspace directory

```
./goclaw doctor
```

## What's Next

- [Channel-specific issues](/troubleshoot-channels)
- [Provider-specific issues](/troubleshoot-providers)
- [Database issues](/troubleshoot-database)



---

# WebSocket Issues

> Troubleshooting WebSocket connections, authentication, and message handling in GoClaw.

## Overview

GoClaw exposes a single WebSocket endpoint at `/ws`. All real-time communication between clients and the gateway — chat, events, RPC calls — flows through this connection. This page covers the most common failure patterns with causes and fixes.

## Authentication

The first frame sent after connecting **must** be a `connect` method call. Any other method before authentication returns an `UNAUTHORIZED` error.

| Problem | Cause | Solution |
|---------|-------|----------|
| `UNAUTHORIZED: first request must be 'connect'` | Sent a method other than `connect` first | Always send `{"type":"req","method":"connect","params":{...}}` as the very first frame |
| `UNAUTHORIZED` on every request | Token missing or wrong | Check `Authorization` header or token param in connect payload |
| Browser pairing stuck | Waiting for admin approval | Only `browser.pairing.status` is allowed before approval completes — poll that method |
| Connection rejected immediately | Origin not in allowlist | Add your frontend origin to `gateway.allowed_origins` in config (see CORS below) |

**Connect frame example:**

```json
{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "token": "YOUR_API_KEY",
    "user_id": "user-123"
  }
}
```

## Connection Errors

| Problem | Cause | Solution |
|---------|-------|----------|
| HTTP 101 never received | Wrong URL or gateway not running | Endpoint is `ws://host:8080/ws` (or `wss://` with TLS); verify gateway is up |
| `websocket upgrade failed` in server logs | Proxy not forwarding `Upgrade` header | Configure nginx/caddy to pass `Connection: Upgrade` and `Upgrade: websocket` |
| Connection drops after 60 seconds of silence | Read deadline timeout | Gateway expects a pong reply every 60 s; implement pong handling in your client |
| `websocket read error` in server logs | Client closed abruptly (tab close, network drop) | Normal for browser clients; implement reconnect logic with exponential backoff |
| `INVALID_REQUEST: unexpected frame type` | Sent a non-request frame type | Only `req` frames are supported from clients |
| `INVALID_REQUEST: invalid frame` | Malformed JSON | Validate payload structure against the protocol wire types |

### CORS

If you see the connection rejected in the browser console with a CORS error, the request origin is not in the allowlist.

```yaml
# config.json5
gateway: {
  allowed_origins: ["https://app.example.com", "http://localhost:3000"]
}
```

Non-browser clients (CLI, SDK, channels) send no `Origin` header and are always allowed.

## Message Size

The server enforces a **512 KB** limit per WebSocket frame (`maxWSMessageSize = 512 * 1024`). When a frame exceeds this limit, gorilla/websocket raises `ErrReadLimit` and the server closes the connection.

| Problem | Cause | Solution |
|---------|-------|----------|
| Connection drops mid-send | Frame exceeds 512 KB | Split large payloads across multiple requests; avoid sending binary blobs inline |
| File upload fails over WebSocket | File content embedded in frame | Use the HTTP media upload endpoint (`/api/media/upload`) instead |

**Rule of thumb:** keep request payloads under 100 KB. Reserve large content for HTTP endpoints.

## Rate Limiting

Rate limiting is **disabled by default**. When enabled (`gateway.rate_limit_rpm > 0`), the gateway enforces a per-user token-bucket limiter with a burst of 5.

| Problem | Cause | Solution |
|---------|-------|----------|
| Requests silently dropped (no response) | Per-user rate limit exceeded | Back off and retry; reduce request frequency |
| `security.rate_limited` in server logs | Client exceeding `rate_limit_rpm` | Increase `gateway.rate_limit_rpm` or reduce client request volume |

**Ping/pong frames do not count** toward rate limiting — only RPC request frames do.

To configure rate limiting:

```yaml
# config.json5
gateway: {
  rate_limit_rpm: 60   # 60 requests per minute per user, burst 5
}
```

Set to `0` or omit to disable (default).

## Ping / Pong

The gateway sends a WebSocket ping every **30 seconds**. The read deadline resets to **60 seconds** on each pong reply.

If the client fails to reply to pings within 60 seconds, the server considers the connection dead and closes it.

| Problem | Cause | Solution |
|---------|-------|----------|
| Connection drops on idle clients | Client not responding to ping frames | Enable automatic pong in your WebSocket library (most do this by default) |
| Connection drops after exactly 60 s | Pong handler not registered | Explicitly register a pong handler that resets your read deadline |

Most WebSocket libraries (browser native, `ws` for Node.js, gorilla) handle ping/pong automatically. Check your library's docs if connections drop on idle.

## Client Libraries

| Library | Notes |
|---------|-------|
| Browser `WebSocket` API | Ping/pong handled by browser. No special config needed. |
| Node.js `ws` | Enable `{ autoPong: true }` (default in recent versions) |
| Python `websockets` | Ping/pong automatic; use `ping_interval` / `ping_timeout` params |
| Go `gorilla/websocket` | Register pong handler and reset read deadline manually |
| CLI / curl | Use `websocat` — it handles pong automatically |

**Reconnect pattern:** on any close event, wait 1 s → re-connect → re-authenticate with `connect` → resume.

## Session Ownership (v2.66+)

All 5 `chat.*` WebSocket methods (`chat.send`, `chat.history`, `chat.inject`, `chat.abort`, `chat.session.status`) now enforce session ownership via `requireSessionOwner`. Non-admin users can only access their own sessions.

| Problem | Cause | Solution |
|---------|-------|----------|
| `FORBIDDEN: session does not belong to user` | Non-admin user tried to read or write another user's session | Use the session ID that belongs to the authenticated user; admins bypass this check |
| Suddenly getting ownership errors after upgrade | Upgraded to v2.66+ with shared session IDs | Each user must use their own session ID; admin tokens bypass ownership checks |

This is a security fix (Session IDOR). If your integration uses shared session IDs across users, each user must authenticate with their own token and session.

## What's Next

- [Common Issues](/troubleshoot-common) — startup, agent, memory problems
- [Channels Troubleshooting](/troubleshoot-channels) — Telegram, Discord, WhatsApp issues



---

# Channel Issues

> Per-channel troubleshooting for Telegram, Discord, Feishu, Zalo, and WhatsApp.

## Overview

Each channel has its own connection mode, permission model, and message format quirks. This page covers the most common failure patterns for each channel. For gateway-level issues (startup, WebSocket, rate limiting) see [Common Issues](/troubleshoot-common).

## General Channel Tips

- Channel errors appear in the gateway log with the channel name as context (e.g., `"feishu bot probe failed"`, `"zalo getUpdates error"`).
- All channels reconnect automatically after transient failures. A warning log does not mean the channel is permanently broken.
- Check channel status via the dashboard or `channels.status` RPC method.


## Discord

Discord uses a persistent **gateway WebSocket** connection.

| Problem | Cause | Solution |
|---------|-------|----------|
| `create discord session: ...` on startup | Invalid bot token | Verify `GOCLAW_DISCORD_TOKEN` in Discord developer portal |
| `open discord session: ...` | Cannot reach Discord gateway | Check network; see [status.discord.com](https://status.discord.com) |
| Bot not receiving messages | Missing Gateway Intents | Enable **Message Content Intent** in Discord developer portal → Bot |
| Messages truncated | Discord 2000-char limit | GoClaw chunks automatically; check for large code blocks near the limit |
| Pairing reply not sent | DM permissions not granted | Bot must share a server with the user and have DM permissions |

**Required env var:** `GOCLAW_DISCORD_TOKEN`

**Intents checklist** (Discord developer portal → Bot → Privileged Gateway Intents):
- [x] Message Content Intent

---

## Feishu / Lark

Feishu supports two modes: **WebSocket** (default, no public URL needed) and **Webhook** (requires public HTTPS endpoint).

| Problem | Cause | Solution |
|---------|-------|----------|
| `feishu app_id and app_secret are required` | Missing credentials | Set `GOCLAW_LARK_APP_ID` and `GOCLAW_LARK_APP_SECRET` |
| `feishu bot probe failed` (warning only) | Bot info fetch failed; channel still starts | Check app permissions in Feishu console; non-fatal |
| `feishu websocket error` (reconnects) | WS connection dropped | Reconnects automatically; persistent errors suggest firewall blocking `*.larksuite.com` |
| Webhook signature verification fails | Wrong token or encrypt key | Verify `GOCLAW_LARK_VERIFICATION_TOKEN` and `GOCLAW_LARK_ENCRYPT_KEY` match app config |
| Events not delivered in webhook mode | Feishu cannot reach your server | Ensure public HTTPS endpoint; Feishu requires SSL |
| `feishu send media failed` | Media URL not publicly reachable | Host media on a public URL; Feishu fetches media at delivery time |

**Required env vars:**

```bash
GOCLAW_LARK_APP_ID=cli_xxxx
GOCLAW_LARK_APP_SECRET=your_secret
# Webhook mode only:
GOCLAW_LARK_ENCRYPT_KEY=your_encrypt_key
GOCLAW_LARK_VERIFICATION_TOKEN=your_token
```

Set `connection_mode: "websocket"` (default) or `"webhook"` in channel config.

---

## Zalo

Zalo OA Bot is **DM only** (no group chats) with a 2000-character text limit per message. GoClaw chunks longer responses automatically. Runs in polling mode.

| Problem | Cause | Solution |
|---------|-------|----------|
| `zalo token is required` | Missing OA token | Set `GOCLAW_ZALO_TOKEN` with your Zalo OA access token |
| `zalo getMe failed` | Token invalid or expired | Refresh token in Zalo Developer Console; OA tokens expire periodically |
| Bot not responding | DM policy misconfigured | Check `dm_policy` in channel config |
| `zalo getUpdates error` in logs | Polling error (excluding HTTP 408) | HTTP 408 is normal (timeout, no updates); other errors retry after 5s |
| Group messages ignored | Platform limitation | Zalo OA only supports DMs — this is by design |

**Required env var:** `GOCLAW_ZALO_TOKEN`

---

## WhatsApp

WhatsApp connects **directly** via native multi-device protocol. No external bridge service required. Auth state is stored in the database (PostgreSQL/SQLite).

| Problem | Cause | Solution |
|---------|-------|----------|
| No QR code appears | Server can't reach WhatsApp | Check network connectivity (ports 443, 5222) |
| QR scanned but no auth | Auth state corrupted | Use "Re-authenticate" in UI or restart channel |
| `whatsapp bridge_url is required` | Old config still present | Remove `bridge_url` from config/credentials — no longer needed |
| `whatsapp not connected` on send | Not yet authenticated | Scan QR code via UI wizard first |
| `logged out` in logs | WhatsApp revoked session | Use "Re-authenticate" button to scan new QR |
| Group messages ignored | Policy or mention gate | Check `group_policy` and `require_mention` settings |
| Media download failed | Network or file issue | Check logs; verify temp dir writable; max 20 MB per file |

Authentication is done via QR scan in the GoClaw UI (Channels > WhatsApp > Re-authenticate).

---

## Bitrix24

| Problem | Cause | Solution |
|---------|-------|----------|
| Self-hosted domain rejected | SSRF-safe validation | The portal FQDN must resolve to a public IP. Loopback/private/metadata IP ranges and `localhost` / `.local` / `.localhost` names are blocked; any port must be in the range 1–65535. Cloud `*.bitrix24.*` domains skip this check. |

---

## Human-like Delivery & Passive Memory

These features are **disabled by default**. If you expect them but see nothing, check the config.

| Problem | Cause | Solution |
|---------|-------|----------|
| Quick-ack / progress replies not appearing | `gateway.chat_behavior` disabled (default) | Enable `chat_behavior` (and its `quick_ack` / `intermediate_replies` sub-blocks); verify the sidecar `provider`/`model` resolve. See [Human-like Delivery](/channels-overview#human-like-delivery). |
| Behavior differs per channel | Override resolution | Order is **Channel > Agent > Workspace** — a channel-level `chat_behavior` wins over the agent and workspace base. |
| Passive channel memory not extracting | `passive_memory.enabled` off, not a group, or `min_messages` not met | Enable `passive_memory`; note it is group-only in v1. See [Memory System › Passive Channel Memory Extraction](/memory-system#passive-channel-memory-extraction). |

---

## Channel Health States

GoClaw v3 tracks each channel's runtime state. The dashboard and `channels.status` RPC reflect these states:

| State | Meaning |
|-------|---------|
| `registered` | Channel configured but not yet started |
| `starting` | Channel startup in progress |
| `healthy` | Connected and receiving messages |
| `degraded` | Connected but experiencing errors |
| `failed` | Channel stopped due to unrecoverable error |
| `stopped` | Channel was shut down cleanly |

When a channel enters `failed`, the dashboard shows a remediation hint (e.g., "Review channel credentials" or "Check upstream reachability"). `failed` with `failure_kind: auth` requires credential update — the channel will not auto-recover. `failed` with `failure_kind: network` is retryable and the channel reconnects automatically.

## What's Next

- [Provider-specific issues](/troubleshoot-providers)
- [Database issues](/troubleshoot-database)
- [Common Issues](/troubleshoot-common)



---

# Provider Issues

> Fixes for API key errors, rate limiting, model mismatches, and schema validation failures.

## Overview

GoClaw supports Anthropic (native HTTP+SSE) and a wide set of OpenAI-compatible providers. Providers are registered at startup only if their API key is present. All providers use automatic retry with exponential backoff for transient errors (429, 500–504, connection resets, timeouts).

## Provider Not Registered

If a provider does not appear in the dashboard or returns `provider not found`, it was skipped at startup because its API key was missing.

Check startup logs for `registered provider` lines:

```
INFO registered provider name=anthropic
INFO registered provider name=openai
```

If a provider is missing, set the corresponding env var and restart:

| Provider | Env var |
|----------|---------|
| Anthropic | `GOCLAW_ANTHROPIC_API_KEY` |
| OpenAI | `GOCLAW_OPENAI_API_KEY` |
| Gemini | `GOCLAW_GEMINI_API_KEY` |
| DashScope / Qwen | `GOCLAW_DASHSCOPE_API_KEY` |
| OpenRouter | `GOCLAW_OPENROUTER_API_KEY` |
| Groq | `GOCLAW_GROQ_API_KEY` |
| DeepSeek | `GOCLAW_DEEPSEEK_API_KEY` |
| Mistral | `GOCLAW_MISTRAL_API_KEY` |
| xAI / Grok | `GOCLAW_XAI_API_KEY` |
| MiniMax | `GOCLAW_MINIMAX_API_KEY` |
| Cohere | `GOCLAW_COHERE_API_KEY` |
| Perplexity | `GOCLAW_PERPLEXITY_API_KEY` |

Providers can also be added at runtime via the dashboard (stored in `llm_providers` table with AES-256-GCM encrypted keys).

## Common Errors

| Problem | Cause | Solution |
|---------|-------|----------|
| `HTTP 401` | Invalid or revoked API key | Regenerate the key from the provider's console; update env var or dashboard |
| `HTTP 403` | Account suspended or plan restriction | Check provider account status; upgrade plan if on free tier |
| `HTTP 429` | Rate limit hit | GoClaw retries automatically up to 3× with backoff (min 300ms, max 30s); if persistent, reduce concurrency |
| `HTTP 404` / model not found | Wrong model name or model removed | Check current model names in provider docs; update agent config |
| `HTTP 500/502/503/504` | Provider outage | Retried automatically; check provider status page if persistent |
| Connection reset / EOF / timeout | Network instability | Retried automatically; check DNS and firewall rules |

## Retry Behavior

GoClaw retries on HTTP 429, 500, 502, 503, 504, and network errors. Default config:

- **Attempts:** 3
- **Initial delay:** 300ms
- **Max delay:** 30s
- **Backoff:** exponential with ±10% jitter
- **Retry-After header:** honored when present (e.g., on 429 from Anthropic/OpenAI)

## Schema Validation Errors (Gemini)

Gemini rejects JSON Schema fields that other providers accept. GoClaw automatically strips incompatible fields before sending tool definitions.

Fields removed for Gemini: `$ref`, `$defs`, `additionalProperties`, `examples`, `default`

If you see schema validation errors from Gemini despite this, the tool definition likely uses a deeply nested reference that wasn't fully resolved. Simplify the tool's parameter schema.

Fields removed for Anthropic: `$ref`, `$defs`

## Extended Thinking (Anthropic)

Extended thinking requires a compatible model (e.g., `claude-opus-4-5`) and a `thinking` block in the request. GoClaw automatically adds the `anthropic-beta: interleaved-thinking-2025-05-14` header when a thinking block is present.

| Problem | Cause | Solution |
|---------|-------|----------|
| Thinking not appearing | Model doesn't support it | Use `claude-opus-4-5` or another thinking-capable model |
| `redacted_thinking` blocks | Encrypted thinking returned | Normal — these are preserved for context passback; they contain no readable content |
| Budget exceeded | `budget_tokens` too low | Increase `budget_tokens` in agent config; minimum is typically 1024 |

## Claude CLI Provider

The `claude-cli` provider shells out to the `claude` binary instead of calling the API directly.

| Problem | Cause | Solution |
|---------|-------|----------|
| Binary not found | `claude` not in PATH | Set `GOCLAW_CLAUDE_CLI_PATH` to the full path of the binary |
| Auth failure | CLI not authenticated | Run `claude login` manually to authenticate |
| Wrong model | Default model mismatch | Set `GOCLAW_CLAUDE_CLI_MODEL` to the desired model alias |
| Work dir errors | `GOCLAW_CLAUDE_CLI_WORK_DIR` path doesn't exist | Create the directory or update the env var |

## Codex Provider

The `codex` provider (OpenAI Codex CLI) also shells out to a local binary.

| Problem | Cause | Solution |
|---------|-------|----------|
| Binary not found | `codex` not in PATH | Install Codex CLI or set the path in provider config |
| Auth failure | CLI not authenticated | Run `codex auth` or set `OPENAI_API_KEY` in the environment |
| Stream read error | Binary crashed mid-stream | Check binary version compatibility; update Codex CLI |

## ACP Provider

The `acp` provider (Agent Client Protocol) orchestrates any ACP-compatible coding agent (Claude Code, Codex CLI, Gemini CLI) as a subprocess using JSON-RPC 2.0 over stdin/stdout. It does not require an API key — the agent binary manages its own authentication.

Configure in `config.json` under `providers.acp`:

```json
"acp": {
  "binary": "claude",
  "args": [],
  "model": "claude",
  "work_dir": "",
  "idle_ttl": "5m",
  "perm_mode": "approve-all"
}
```

| Problem | Cause | Solution |
|---------|-------|----------|
| `acp: binary not found, skipping` | Binary path doesn't exist or isn't executable | Verify the binary is installed and the `binary` field is the correct path or name in `$PATH` |
| `acp: spawn failed` | Subprocess failed to start | Check that the binary is executable; run it manually to see startup errors |
| `acp: prompt failed` | JSON-RPC communication error on stdin/stdout | Check subprocess logs; ensure the agent binary version supports ACP protocol |
| `acp: session_key required in options` | No session key in request | ACP requires a session key — ensure the agent config passes `session_key` in options |
| `acp: no user message in request` | Empty request content | Ensure the chat request contains a user message |
| Provider not in dashboard | `binary` field not set in config | Set `providers.acp.binary` in `config.json` and restart |

**Startup log for successful ACP registration:**

```
INFO registered provider name=acp binary=claude
```

## Provider Adapter System (v3)

GoClaw v3 introduces a unified `SSEScanner` (`providers/sse_reader.go`) shared by OpenAI, Anthropic, and Codex streaming providers. This eliminates per-provider SSE parsing differences.

| Problem | Cause | Solution |
|---------|-------|----------|
| Streaming cuts off mid-token | Upstream SSE frame split across scanner buffer boundary | Rare — the scanner uses a 512 KB buffer; if reproducible, check for extremely large tool result payloads |
| Streaming works for OpenAI but not Anthropic | Custom proxy stripping `event:` lines | Ensure your proxy passes raw SSE lines; GoClaw now uses the same parser for all providers |

Provider credentials added at runtime (dashboard) are stored in `llm_providers` with AES-256-GCM encryption and resolved at request time via the credential resolver. Per-agent overrides in agent config take precedence over global provider settings.

## Provider Creation Prints "FAILED" but It Actually Succeeded

**Affected versions:** < v3.11.3

The onboard auto-verify path used the stale `{success, models}` response shape to check whether a newly created provider was valid. The provider was created correctly in the database, but the post-create verify step read the wrong fields and printed `FAILED` to the console even when the provider was healthy.

**Fix in v3.11.3:** The verify path now uses the `{valid, error}` response shape and triggers ping mode when the request body is empty, so an empty-body verify returns `{valid:true}` on success. Upgrade to v3.11.3+ to resolve this.

## `goclaw providers delete` Fails with Foreign Key Error on `agent_heartbeats`

**Affected versions:** < v3.11.3

Before v3.11.3, the foreign key from `agent_heartbeats` to `llm_providers` was defined as `RESTRICT`. Deleting a provider that was referenced by any heartbeat row would fail with a foreign key constraint error.

**Fix in v3.11.3:** Migration `000057_heartbeat_provider_fk_set_null` changes the FK to `ON DELETE SET NULL`. The `DeleteProvider` function (PostgreSQL and SQLite) now wraps the delete in a transaction that first disables all affected heartbeat rows, so the next scheduler tick cannot fire with a stale provider config. A `slog.Warn("heartbeat.provider_cleared")` log line is emitted with the count of disabled heartbeats.

Requires migration #057 to be applied (`./goclaw migrate up`). Check logs for `heartbeat.provider_cleared` after deletion to confirm how many heartbeats were cleared.

## What's Next

- [Database issues](/troubleshoot-database)
- [Common Issues](/troubleshoot-common)
- [Channel issues](/troubleshoot-channels)



---

# MCP Issues

> Troubleshooting MCP (Model Context Protocol) server connections, tool registration, and execution.

## Overview

GoClaw bridges external MCP servers to agent tool registries. Each server runs as a separate process (stdio) or remote service (SSE / streamable-HTTP). Connection errors, tool name collisions, and timeouts are the most common failure modes.

Check startup logs for MCP events — key log keys: `mcp.server.connected`, `mcp.server.connect_failed`, `mcp.server.health_failed`, `mcp.server.reconnect_exhausted`.

## Server Connection

### Config-file servers (`mcp_servers` block)

GoClaw connects to all enabled config-file servers at startup. A failed server is logged as a warning; GoClaw continues running — it does **not** block startup.

```
WARN mcp.server.connect_failed server=postgres error=create client: ...
```

| Problem | Cause | Solution |
|---------|-------|----------|
| `create client: ...` | Wrong `transport` or `command` path | Verify `transport` (`stdio`, `sse`, `streamable-http`) and that the binary/URL is reachable |
| `start transport: ...` (SSE/HTTP) | Server URL unreachable or TLS error | Check `url` is correct; verify network, firewall, and TLS certificate |
| `initialize: ...` | MCP handshake failed | Ensure server implements MCP protocol; check server logs |
| `list tools: ...` | Server connected but returned no tools | Server may have crashed during startup; check server logs |
| Server missing from dashboard | `enabled: false` in config | Set `enabled: true` or omit the field (default is true) |

### Reconnection

GoClaw health-checks every 30 seconds via ping. On failure it retries up to **10 times** with exponential backoff (2s initial, 60s max). After 10 failures the server is marked permanently disconnected.

```
WARN mcp.server.health_failed server=postgres error=...
INFO mcp.server.reconnecting  server=postgres attempt=3 backoff=8s
ERROR mcp.server.reconnect_exhausted server=postgres
```

If you see `reconnect_exhausted`, the server process has likely crashed. Restart the MCP server and then trigger a dashboard reconnect or restart GoClaw.

## Tool Registration

Tools are registered under the name `{prefix}__{tool_name}`. The prefix defaults to `mcp_{server_name}` (hyphens converted to underscores). You can override it with `tool_prefix` in the server config.

| Problem | Cause | Solution |
|---------|-------|----------|
| `mcp.tool.name_collision` in logs, tool skipped | Two servers expose a tool that resolves to the same registered name | Set a unique `tool_prefix` per server in config |
| Tools not visible to agent | Server connected but agent has no permission grant | Grant the server to the agent in the dashboard (Agents → MCP tab) |
| >40 tools → only `mcp_tool_search` visible | Search mode activated automatically above 40-tool threshold | Use `mcp_tool_search` to find and activate tools on demand; this is expected behavior |

## Transport Errors

### stdio

| Problem | Cause | Solution |
|---------|-------|----------|
| `exec: command not found` | Binary not in PATH or wrong `command` value | Use absolute path in `command`; verify the binary is installed |
| Process exits immediately | Server crashed on startup | Run the command manually in a terminal to see its error output |
| Env vars not passed | Missing entries in `env` map | Add required vars under `env` in the server config block |

### SSE / streamable-HTTP

| Problem | Cause | Solution |
|---------|-------|----------|
| `connection refused` | Server not running or wrong port | Start the server; verify `url` matches the listening address |
| `401 Unauthorized` | Missing or wrong auth header | Add the token under `headers` (e.g., `Authorization: Bearer <token>`) |
| TLS certificate error | Self-signed or expired cert | Use a valid cert, or run the MCP server behind a trusted reverse proxy |

## Tool Execution

| Problem | Cause | Solution |
|---------|-------|----------|
| `MCP server "X" is disconnected` | Server went offline after initial connect | Check server process; GoClaw retries reconnection automatically |
| `MCP tool "X" timeout after Ns` | Tool call exceeded `timeout_sec` (default 60s) | Increase `timeout_sec` in the server config; default is 60s |
| `MCP tool "X" error: ...` | Server returned an error during execution | Check MCP server logs for the root cause |
| Tool returns `[non-text content: ...]` | Server returned image/audio instead of text | Expected for non-text tools; content type is noted in the result |

## What's Next

- [Common Issues](/troubleshoot-common) — general startup and connectivity problems
- [Dashboard Tour](/dashboard-tour) — manage MCP servers and grants in the UI



---

# Database Issues

> Troubleshooting PostgreSQL migrations, pgvector, connection pool, and slow queries.

## Overview

GoClaw requires PostgreSQL 15+ with the `pgvector` and `pgcrypto` extensions. The database connection is configured exclusively via `GOCLAW_POSTGRES_DSN` (never stored in `config.json`). Migrations are managed with `golang-migrate` and run via `./goclaw migrate up`. Current schema version: **80**.

## Connection Failures

| Problem | Cause | Solution |
|---------|-------|----------|
| `GOCLAW_POSTGRES_DSN environment variable is not set` | DSN not exported | `export GOCLAW_POSTGRES_DSN=postgres://user:pass@host:5432/goclaw` |
| `open postgres: ...` | Invalid DSN format | Verify DSN; use `psql "$GOCLAW_POSTGRES_DSN"` to test manually |
| `ping postgres: dial error` | Postgres not running or wrong host/port | Start Postgres; check host, port, firewall |
| `ping postgres: password authentication failed` | Wrong credentials | Verify username and password in DSN |
| `ping postgres: database "goclaw" does not exist` | DB not created | `createdb goclaw` or `psql -c "CREATE DATABASE goclaw;"` |

GoClaw uses a fixed connection pool: **25 max open connections**, **10 max idle connections**. Adjust `max_connections` in `postgresql.conf` if you run multiple GoClaw instances.

**Connection pool exhaustion symptoms:** If all 25 connections are in use, new requests queue until a connection frees. Symptoms include sudden query latency spikes, timeout errors, and log lines like `pq: sorry, too many clients already`. To diagnose:

```sql
-- Check active connections to the goclaw database
SELECT count(*) FROM pg_stat_activity WHERE datname = 'goclaw';
```

If running multiple GoClaw instances, ensure `max_connections` in `postgresql.conf` is at least `25 × instances + 5`.

## Migration Failures

Run migrations manually:

```bash
./goclaw migrate up
```

| Problem | Cause | Solution |
|---------|-------|----------|
| `create migrator: ...` | Migrations directory not found | Run from the directory containing `migrations/`, or set `GOCLAW_MIGRATIONS_DIR` |
| `migrate up: ...` | SQL error in migration | Check Postgres logs; fix the underlying SQL issue |
| `dirty: true` in version output | Previous migration failed mid-way | Fix the failed migration manually, then run `./goclaw migrate force <version>` |
| `no change` | All migrations already applied | Normal — nothing to do |
| Data hooks failed (warning) | Post-migration data hook error | Non-fatal warning; check logs for details and re-run if needed |

**Recovering from a dirty state:**

```bash
# Check current version and dirty flag
./goclaw migrate version

# Force-set the version to the last known good migration (no SQL applied)
./goclaw migrate force <version_number>

# Then apply migrations again
./goclaw migrate up
```

## pgvector and pgcrypto Extensions

GoClaw requires **both** `pgvector` and `pgcrypto`. The first migration (`000001_init_schema.up.sql`) creates both extensions:

```sql
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
CREATE EXTENSION IF NOT EXISTS "vector";
```

`pgcrypto` is used for UUID generation (`gen_random_uuid()`). It is bundled with PostgreSQL's `postgresql-contrib` package on most platforms.

| Problem | Cause | Solution |
|---------|-------|----------|
| `extension "pgcrypto" does not exist` | `postgresql-contrib` not installed | `apt install postgresql-contrib` (Debian) or `brew install postgresql` already includes it |
| Migration fails at `CREATE EXTENSION IF NOT EXISTS "pgcrypto"` | Insufficient privileges | Connect as superuser or grant `CREATE EXTENSION` privilege |

## pgvector Extension

GoClaw uses `pgvector` for semantic memory search (1536-dimension HNSW indexes on `memory_chunks`, `skills`).

| Problem | Cause | Solution |
|---------|-------|----------|
| `extension "vector" does not exist` | pgvector not installed | Install pgvector: `apt install postgresql-15-pgvector` (Debian) or build from source |
| Migration fails at `CREATE EXTENSION IF NOT EXISTS "vector"` | Insufficient privileges | Connect as superuser or grant `CREATE EXTENSION` privilege |
| Vector search returns no results | Embeddings not generated | Check that an embedding-capable provider (Anthropic, OpenAI) is registered and the embedding backfill has run |
| HNSW index build is slow | Large `memory_chunks` table | Normal for first-time index creation; runs once during migration |

**Install pgvector on common platforms:**

```bash
# Debian/Ubuntu
apt install postgresql-15-pgvector

# macOS with Homebrew
brew install pgvector

# Docker (use the pgvector image)
docker pull pgvector/pgvector:pg15
```

## Slow Queries

Key indexes created by GoClaw's schema:

- Sessions: `idx_sessions_updated` (updated_at DESC), `idx_sessions_agent`, `idx_sessions_user`
- Memory: `idx_mem_vec` (HNSW vector cosine), `idx_mem_tsv` (GIN full-text), `idx_mem_agent_user`
- Traces: `idx_traces_agent_time`, `idx_traces_status` (errors only)
- Skills: `idx_skills_embedding` (HNSW), `idx_skills_visibility`

If queries are slow despite indexes:

```sql
-- Check for missing ANALYZE (stale statistics)
ANALYZE memory_chunks;
ANALYZE sessions;

-- Identify slow queries
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;
```

For vector search specifically, ensure `work_mem` is high enough for HNSW probes:

```sql
-- Session-level (or add to postgresql.conf)
SET work_mem = '256MB';
```

## Embedding Backfill

GoClaw automatically backfills embeddings at startup. When an embedding-capable provider (Anthropic or OpenAI) is configured, GoClaw launches background goroutines that call `BackfillEmbeddings` (memory chunks) and `BackfillSkillEmbeddings` (skills) for any rows with `embedding IS NULL`. This runs once per startup.

Watch for these startup log lines:

```
INFO memory embeddings enabled provider=anthropic model=text-embedding-3-small
INFO memory embeddings backfill complete chunks_updated=42
INFO skill embeddings backfill complete updated=5
```

If the log shows `memory embeddings disabled (no API key), chunks stored without vectors`, configure an embedding provider first.

If memory documents or skills were inserted before an embedding provider was configured, their `embedding` columns will be NULL and vector search will skip them.

To check for un-embedded rows:

```sql
SELECT COUNT(*) FROM memory_chunks WHERE embedding IS NULL;
SELECT COUNT(*) FROM skills WHERE embedding IS NULL AND status = 'active';
```

If backfill failed (check logs for `memory embeddings backfill failed`), restart GoClaw after fixing the provider — backfill will run again automatically.

## Backup and Restore

GoClaw uses standard PostgreSQL — any standard backup method works.

```bash
# Backup
pg_dump "$GOCLAW_POSTGRES_DSN" -Fc -f goclaw_backup.dump

# Restore
pg_restore -d "$GOCLAW_POSTGRES_DSN" --clean goclaw_backup.dump

# After restore, re-run migrations to ensure schema is current
./goclaw migrate up
```

After restoring, verify the pgvector extension is present:

```sql
SELECT * FROM pg_extension WHERE extname = 'vector';
```

## v3 Migration Failures (037–044)

> The schema now extends through **080**. The recovery steps below cover the v3 batch (037–044), which are the migrations most prone to failure on upgrades from older v3 installs; later migrations (045–080) are additive and rarely need manual intervention. See [Database Schema → Migration History](/database-schema) for the full list.

Migrations 037–044 are the v3 batch. If any fails:

| Migration | Common failure | Fix |
|-----------|---------------|-----|
| `000037` | `column already exists` on `agents` | Safe — the `ADD COLUMN IF NOT EXISTS` guards are idempotent; re-run `./goclaw migrate up` |
| `000038` | `relation "vault_documents" already exists` | Table exists from a partial run; restore from backup or manually drop and re-run |
| `000040` | `function immutable_array_to_string already exists` | Safe — `CREATE OR REPLACE FUNCTION` is idempotent |
| `000043` | `constraint "vault_documents_agent_id_scope_path_key" does not exist` | Constraint was already dropped; safe to continue; force version with `./goclaw migrate force 43` then `migrate up` |
| `000044` | Seed INSERT fails | Usually indicates a missing `agent_context_files` table; ensure migration 001 ran correctly |

**General recovery:**

```bash
# Check dirty state
./goclaw migrate version

# Force last good version then re-run
./goclaw migrate force <version_before_failed>
./goclaw migrate up
```

When in doubt, restore from backup before the v3 upgrade and retry.

## SQLite (Desktop) Caveats

The SQLite build does not support `pgvector` operations. The following limitations apply:

- `episodic_summaries`: vector (`embedding`) column exists but HNSW index is not created; vector search is disabled. Keyword FTS via `search_vector` works normally.
- `vault_documents`: auto-linking via vector similarity is disabled; LLM summarisation still runs.
- `kg_entities`: HNSW index not created; only keyword FTS available.

If you see warnings like `vault enrich: vector ops disabled (SQLite)` in logs, this is expected and not an error.

To check whether your build uses SQLite:

```bash
./goclaw version
# SQLite builds will show: storage=sqlite
```

## Migration #057 — Heartbeat FK Lock Note

Migration `000057_heartbeat_provider_fk_set_null` drops the existing `RESTRICT` foreign key on `agent_heartbeats.provider_id` and re-adds it with `ON DELETE SET NULL`. The `ALTER TABLE` takes a brief `ACCESS EXCLUSIVE` lock on `agent_heartbeats` during this change. On typical tables the lock is sub-second, but heartbeat workers may pause momentarily while it is held. If you have a very large `agent_heartbeats` table, plan the upgrade window accordingly and monitor for lock-wait timeouts.

## What's Next

- [Common Issues](/troubleshoot-common)
- [Provider issues](/troubleshoot-providers)
- [Channel issues](/troubleshoot-channels)



---

# Agent Team Issues

> Troubleshooting team creation, delegation, task routing, and inter-agent communication.

## Overview

Agent teams let a lead agent coordinate work across multiple member agents using a shared task board, messaging, and a shared workspace directory. Most issues fall into four categories: team setup, task lifecycle, dispatch failures, and messaging errors.

## Team Creation

| Problem | Cause | Solution |
|---------|-------|----------|
| Member agent not added to team | Agent key not found during team creation | Verify the agent key exists in the dashboard before creating the team |
| `failed to add member` (in logs) | DB error while adding a member during `teams.create` | Check PostgreSQL connectivity; retry team creation |
| Agent shows wrong role | Role assigned incorrectly at creation | Remove and re-add the member via the dashboard with the correct role |

## Delegation & Subagents

| Problem | Cause | Solution |
|---------|-------|----------|
| Task auto-fails with "auto-failed after N dispatch attempts" | Agent failed to complete the task 3 times in a row (circuit breaker hit) | Check the member agent's logs for repeated errors; fix the underlying issue then re-create the task |
| `team_tasks.dispatch: cannot resolve agent` (log) | Assigned agent ID not found in DB at dispatch time | Confirm the member agent was not deleted; re-assign the task to an active member |
| `team_tasks.dispatch: inbound buffer full` (log) | Message bus inbound queue is saturated | Transient — the dispatcher retries on the next ticker tick (up to 5 min); reduce concurrent team task volume if persistent |
| `spawn` used instead of delegation | Agent cloned itself instead of delegating to a team member | Instruct the lead agent: "Do NOT use `spawn` for team delegation — use `team_tasks` instead" |
| Subagent workspace not created | Workspace directory creation failed at run start | Check `data_dir` permissions; ensure the configured data directory is writable |

## Task Routing

| Problem | Cause | Solution |
|---------|-------|----------|
| Task stuck in `pending` | No owner assigned or blocker tasks not yet completed | Assign an owner via the dashboard, or wait for blocker tasks to finish — unblocked tasks auto-dispatch within 5 minutes |
| `only the team lead can perform this action` | A member agent tried a lead-only operation (create/delete tasks) | Only the lead agent's session can create or delete tasks; check which agent is calling `team_tasks` |
| `only the assigned task owner can update progress` | Lead tried to update progress on a member's task | Progress updates must come from the assigned member agent; the lead receives results automatically on completion |
| `blocked_by contains invalid task ID` | `blocked_by` list references a non-existent or wrong-team task UUID | Create dependency tasks first; use their returned UUIDs in `blocked_by` |
| `assignee not found` or `agent is not a member of this team` | Assignee key typo or agent removed from team | Verify the agent key with `team_tasks(action="list_members")`; re-add the agent if needed |
| `You must check existing tasks first` | Agent called `create` without first searching for duplicates | Call `team_tasks(action="search", query="<keywords>")` before creating a new task |
| Task deleted but still referenced | Task was deleted while in `in_progress` status | Only `completed`, `failed`, or `cancelled` tasks can be deleted; cancel the task first |

## Team Messaging

| Problem | Cause | Solution |
|---------|-------|----------|
| `agent "X" is not a member of your team` | Sending to an agent outside the team | Use `team_tasks(action="list_members")` to get valid agent keys |
| `to parameter is required for send action` | `team_message` called without a recipient | Provide the `to` field with the target agent key |
| `text parameter is required` | Message body missing in `send` or `broadcast` call | Include `text` in the tool arguments |
| `failed to send message` | DB error persisting the message | Check PostgreSQL logs; usually transient |
| `failed to broadcast message` | Bus or DB error during broadcast | Same as above — retry or check server logs |
| `failed to auto-create task` from broadcast (log) | Task auto-creation on broadcast receipt failed | Non-fatal — message is delivered but no task is created; create the task manually if needed |
| `failed to get unread messages` | DB read error for the mailbox | Check PostgreSQL connectivity |

## Subagent Orchestration (v3)

GoClaw v3 adds structured subagent management. These issues appear when using `spawn` with `action=wait` or the automatic retry/concurrency system.

| Problem | Cause | Solution |
|---------|-------|----------|
| `spawn` with `action=wait` never returns | All spawned children failed or timed out | Check subagent logs; the parent unblocks when all children complete or when `timeout` elapses |
| Subagent results lost after context compaction | In-flight tasks not in compaction prompt | Tasks are now persisted in `subagent_tasks` DB table (migration 000034) — results survive summarization |
| `max concurrent subagents reached` | Tenant hit `MaxSubagentConcurrent` edition limit | Reduce parallel spawns or upgrade edition; limit is scoped per tenant to prevent resource exhaustion |
| `max subagent depth reached` | Nested spawn exceeded `MaxSubagentDepth` | Flatten delegation chain; subagents cannot spawn deeper than the configured depth |
| Subagent auto-retried but produced wrong output | Default `MaxRetries=2` with linear backoff ran on LLM failure | Expected — retries improve reliability; if output is wrong, check agent instructions |
| `/subagents` Telegram command shows empty | `subagent_tasks` table not migrated | Run pending DB migrations; migration 000034 creates the table |
| `BatchQueue` results out of order | BatchQueue processes by tenant:agent batch, not insertion order | Expected — use task `blocked_by` dependencies if ordering is required |

**Checking subagent status:**
- Telegram: `/subagents` lists all active tasks; `/subagent <id>` shows detail from DB
- Dashboard: Teams → task board shows subagent task state in real time

## Diagnostics

Use the Dashboard **Teams** view to inspect task status, events, and member state. Server-side events stream in real time — filter by `team_id` to narrow down issues.

For low-level debugging, query the task event log:

```
team_tasks(action="events", task_id="<uuid>")
```

This returns the full state-change history for a task, including dispatch count stored in metadata.

## What's Next

- [Agent Teams guide](/teams-what-are-teams) — team setup, roles, and task board
- [Common Issues](/troubleshoot-common) — general gateway and agent troubleshooting