Sync Gateway Templates

Synchronizes agent templates (TOOLS.md, IDENTITY.md, SOUL.md) from Mission Control to agent workspaces on the gateway. This operation writes or updates configuration files for board agents and optionally the gateway main agent.

Authentication

Requires organization admin authentication via Authorization: Bearer <token> header.

Path Parameters

gateway_id

UUID

required

Gateway UUID to synchronize

Query Parameters

include_main

boolean

default:"true"

Include the gateway main agent in the sync operation

lead_only

boolean

default:"false"

Sync only board lead agents (skip worker agents)

reset_sessions

boolean

default:"false"

Force reset of agent sessions during sync

rotate_tokens

boolean

default:"false"

Generate new authentication tokens for all agentsCritical: Required when:

First-time gateway setup
Agents are missing from openclaw.json
Agent tokens were compromised

force_bootstrap

boolean

default:"false"

Force re-bootstrap of agent provisioning

overwrite

boolean

default:"false"

Overwrite existing template files even if unchanged

board_id

UUID

Limit sync to agents on a specific board

Response

gateway_id

UUID

Gateway UUID that was synchronized

include_main

boolean

Whether main agent was included in sync

reset_sessions

boolean

Whether sessions were reset

agents_updated

integer

Number of agents successfully updated

agents_skipped

integer

Number of agents skipped (no changes or errors)

main_updated

boolean

Whether the main agent was updated

errors

GatewayTemplatesSyncError[]

Array of per-agent errors encountered during sync

agent_id

UUID

Agent UUID that failed

agent_name

string

Agent display name

board_id

UUID

Board UUID if agent is board-scoped

message

string

Error description

Template Sync Workflow

For each agent selected for sync:

Read existing token from TOOLS.md (if rotate_tokens=false)
Generate new token (if rotate_tokens=true or token not found)
Render templates from Jinja2 sources:
- BOARD_TOOLS.md.j2 → TOOLS.md
- BOARD_IDENTITY.md.j2 → IDENTITY.md (if identity_template exists)
- BOARD_SOUL.md.j2 → SOUL.md (if soul_template exists)
Write files to agent workspace via gateway RPC: agents.files.set()
Update database with new token hash (if rotated)

Template Variables

Templates are rendered with these variables:

base_url - Mission Control API URL (from BASE_URL env var)
auth_token - Agent authentication token
agent_name - Agent display name
agent_id - Agent UUID
board_id - Board UUID (for board agents)
workspace_root - Gateway workspace root path
workspace_path - Agent’s specific workspace path

When to Use `rotate_tokens=true`

Required in these scenarios:

First-time setup: Initial gateway configuration
Missing openclaw.json entries: Agents mc-* were removed from gateway config
Token compromise: Security incident requiring token rotation
Cannot read TOOLS.md: Gateway returns “file not found” errors

Symptoms requiring token rotation:

{
  "errors": [
    {
      "agent_name": "Financial Ops Lead",
      "message": "unable to read AUTH_TOKEN from TOOLS.md (run with rotate_tokens=true)"
    }
  ]
}

Example Request (Normal Sync)

curl -X POST "https://api.example.com/api/v1/gateways/55cc268a-4b45-400f-accf-201e025232ac/templates/sync" \
  -H "Authorization: Bearer your-token-here"

Example Request (Full Reset)

curl -X POST "https://api.example.com/api/v1/gateways/55cc268a-4b45-400f-accf-201e025232ac/templates/sync?rotate_tokens=true&overwrite=true&reset_sessions=true" \
  -H "Authorization: Bearer your-token-here"

Example Request (Board-Specific Sync)

curl -X POST "https://api.example.com/api/v1/gateways/55cc268a-4b45-400f-accf-201e025232ac/templates/sync?board_id=550e8400-e29b-41d4-a716-446655440000&overwrite=true" \
  -H "Authorization: Bearer your-token-here"

Example Response (Success)

{
  "gateway_id": "55cc268a-4b45-400f-accf-201e025232ac",
  "include_main": true,
  "reset_sessions": false,
  "agents_updated": 5,
  "agents_skipped": 0,
  "main_updated": true,
  "errors": []
}

Example Response (With Errors)

{
  "gateway_id": "55cc268a-4b45-400f-accf-201e025232ac",
  "include_main": true,
  "reset_sessions": false,
  "agents_updated": 3,
  "agents_skipped": 2,
  "main_updated": true,
  "errors": [
    {
      "agent_id": "c91361ef-6d85-439c-82e1-8f388a302e6a",
      "agent_name": "Financial Ops Lead",
      "board_id": "550e8400-e29b-41d4-a716-446655440000",
      "message": "unable to read AUTH_TOKEN from TOOLS.md (run with rotate_tokens=true)"
    }
  ]
}

Common Sync Scenarios

Scenario 1: Regular Template Update

After updating agent templates or configuration:

curl -X POST "$BASE_URL/api/v1/gateways/$GATEWAY_ID/templates/sync?overwrite=true" \
  -H "Authorization: Bearer $TOKEN"

Scenario 2: Initial Gateway Setup

First time configuring a gateway:

curl -X POST "$BASE_URL/api/v1/gateways/$GATEWAY_ID/templates/sync?rotate_tokens=true&overwrite=true&force_bootstrap=true" \
  -H "Authorization: Bearer $TOKEN"

Scenario 3: Emergency Token Rotation

After security incident:

curl -X POST "$BASE_URL/api/v1/gateways/$GATEWAY_ID/templates/sync?rotate_tokens=true&reset_sessions=true&overwrite=true" \
  -H "Authorization: Bearer $TOKEN"

Scenario 4: Sync Single Board

Update only agents on a specific board:

curl -X POST "$BASE_URL/api/v1/gateways/$GATEWAY_ID/templates/sync?board_id=$BOARD_ID&overwrite=true" \
  -H "Authorization: Bearer $TOKEN"

Scenario 5: Update Only Lead Agents

Sync configuration for board leads only:

curl -X POST "$BASE_URL/api/v1/gateways/$GATEWAY_ID/templates/sync?lead_only=true&overwrite=true" \
  -H "Authorization: Bearer $TOKEN"

Error Recovery

”unable to read AUTH_TOKEN from TOOLS.md”

Cause: Agent entry missing from openclaw.json on the gateway. Solution:

curl -X POST "$BASE_URL/api/v1/gateways/$GATEWAY_ID/templates/sync?rotate_tokens=true&overwrite=true" \
  -H "Authorization: Bearer $TOKEN"

“Gateway RPC call failed”

Causes:

Gateway is offline or unreachable
Network connectivity issues
Gateway authentication failed

Solution:

Check gateway status: systemctl status openclaw-gateway
Verify network: nc -zv gateway-host 18789
Test gateway auth: Review gateway logs

”Missing scope: operator.read”

Cause: Gateway missing dangerouslyDisableDeviceAuth setting. Solution: Update ~/.openclaw/openclaw.json:

{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true,
      "dangerouslyDisableDeviceAuth": true
    }
  }
}

Then restart gateway and retry sync.

Best Practices

Regular Syncs: Run template sync after updating agent configurations
Token Rotation: Use rotate_tokens=true only when necessary (expensive operation)
Dry Runs: Test sync on a single board first before syncing all boards
Error Monitoring: Check errors array in response and fix before retrying
Incremental Updates: Use board_id parameter to limit scope when possible
Overwrite Control: Use overwrite=false (default) to avoid unnecessary writes

Template Files Generated

TOOLS.md

Contains API credentials and endpoints:

# API Configuration

- BASE_URL=https://api.example.com
- AUTH_TOKEN=agent-secret-token
- AGENT_ID=c91361ef-6d85-439c-82e1-8f388a302e6a
- BOARD_ID=550e8400-e29b-41d4-a716-446655440000
- WORKSPACE_ROOT=/home/ubuntu/.openclaw
- WORKSPACE_PATH=/home/ubuntu/.openclaw/workspace-mc-c91361ef

## Making API Calls

curl -H "X-Agent-Token: $AUTH_TOKEN" \
  "$BASE_URL/api/v1/agent/healthz"

IDENTITY.md

Agent role and behavior (if identity_template is set):

# Agent Identity

You are a CFO agent responsible for financial planning and analysis.

## Responsibilities
- Review budget proposals
- Analyze financial metrics
- Report to board on financial health

SOUL.md

Deeper agent instructions (if soul_template is set):

# Agent Soul

When critical blockers appear, escalate in plain language.

Always verify budget numbers before approving.

Authentication

Organizations

Boards

Tasks

Agents

Gateways

Approvals

Skills & Tags

Activity & Metrics

Authentication

Path Parameters

Query Parameters

Response

Template Sync Workflow

Template Variables

When to Use `rotate_tokens=true`

Example Request (Normal Sync)

Example Request (Full Reset)

Example Request (Board-Specific Sync)

Example Response (Success)

Example Response (With Errors)

Common Sync Scenarios

Scenario 1: Regular Template Update

Scenario 2: Initial Gateway Setup

Scenario 3: Emergency Token Rotation

Scenario 4: Sync Single Board

Scenario 5: Update Only Lead Agents

Error Recovery

”unable to read AUTH_TOKEN from TOOLS.md”

“Gateway RPC call failed”

”Missing scope: operator.read”

Best Practices

Template Files Generated

TOOLS.md

IDENTITY.md

SOUL.md

Build docs developers (and LLMs) love

Authentication

Organizations

Boards

Tasks

Agents

Gateways

Approvals

Skills & Tags

Activity & Metrics

Documentation Index

​Authentication

​Path Parameters

​Query Parameters

​Response

​Template Sync Workflow

​Template Variables

​When to Use rotate_tokens=true

​Example Request (Normal Sync)

​Example Request (Full Reset)

​Example Request (Board-Specific Sync)

​Example Response (Success)

​Example Response (With Errors)

​Common Sync Scenarios

​Scenario 1: Regular Template Update

​Scenario 2: Initial Gateway Setup

​Scenario 3: Emergency Token Rotation

​Scenario 4: Sync Single Board

​Scenario 5: Update Only Lead Agents

​Error Recovery

​”unable to read AUTH_TOKEN from TOOLS.md”

​“Gateway RPC call failed”

​”Missing scope: operator.read”

​Best Practices

​Template Files Generated

​TOOLS.md

​IDENTITY.md

​SOUL.md

Build docs developers (and LLMs) love

Authentication

Path Parameters

Query Parameters

Response

Template Sync Workflow

Template Variables

When to Use `rotate_tokens=true`

Example Request (Normal Sync)

Example Request (Full Reset)

Example Request (Board-Specific Sync)

Example Response (Success)

Example Response (With Errors)

Common Sync Scenarios

Scenario 1: Regular Template Update

Scenario 2: Initial Gateway Setup

Scenario 3: Emergency Token Rotation

Scenario 4: Sync Single Board

Scenario 5: Update Only Lead Agents

Error Recovery

”unable to read AUTH_TOKEN from TOOLS.md”

“Gateway RPC call failed”

”Missing scope: operator.read”

Best Practices

Template Files Generated

TOOLS.md

IDENTITY.md

SOUL.md