Managing Agents

What Is an Agent in Relay?

An agent in Relay is an AI assistant (or any autonomous service) that receives events from apps and sends back responses. Think of agents as team members that apps can invoke.

Examples:

Athena — general-purpose personal assistant
Klyve — technical specialist for code review and workflows
Custom agents — any service running the OpenClaw Relay plugin (or compatible)

Agents operate within your organization and can only receive events from allowlisted apps.

Registering a New Agent

To register an agent:

Go to the Agents page in the dashboard sidebar
Click Register New Agent
Fill in the agent details:
- Agent Name — display name (e.g., "Athena", "Klyve", "ResearchBot")
- Agent ID — URL-safe slug (e.g., "athena", "klyve", "research-bot")
  - Must be unique within your organization
  - Lowercase letters, numbers, hyphens only
  - Cannot be changed after creation
- Description — what this agent does (e.g., "Personal assistant for general tasks")
  - Optional but recommended
  - Visible to apps when they discover agents
Click Register

Relay creates the agent and generates an agent token.

Agent Tokens

When you register an agent, Relay generates a unique token that looks like:

rla_athena_k9x2p2d7q4v1r9z5k3j8h2...

Token Security

This token is shown exactly once. After you leave the page, you cannot retrieve it again. You must store it immediately and securely.

Where to store your agent token:

Plugin config: In your openclaw-relay-plugin configuration file
Environment variables: RELAY_AGENT_TOKEN_ATHENA=rla_athena_...
Secrets manager: AWS Secrets Manager, HashiCorp Vault, etc.
Never in version control — always in .env.local or .gitignore

Token Format

rla_{agent_id}_{random_string}

rla_ — prefix identifying this as an agent token
{agent_id} — your agent's ID (e.g., "athena")
{random_string} — cryptographically random suffix

Relay stores only a bcrypt hash of the full token in the database. The plaintext is never logged or recoverable.

Agent Detail Page

Click an agent name to view its detail page:

Connection Status

Live indicator showing whether the agent is currently connected to Relay:

Connected — agent's WebSocket is open and authenticated
Disconnected — agent is not connected (may be offline, crashed, or not yet deployed)
Last Connected — timestamp of the most recent connection
Session TTL — how long agent sessions persist (e.g., "14 days")

This helps you monitor agent availability. If a critical agent is offline, you'll see it immediately.

Configuration

Field	Value	Notes
Agent ID	`athena`	URL-safe identifier
Name	`Athena`	Display name
Description	`Personal EA for general tasks`	What the agent does
Organization	`Acme Corp`	The organization that owns this agent
Created	`2026-04-03 09:22 UTC`	Registration date
Status	Active / Inactive	Whether the agent can receive events

Event History

A table showing recent events sent to this agent:

Event ID	App	Thread	Status	Latency	Timestamp
evt_k9p2	portal	task-123	delivered	2300ms	2026-04-07 10:15
evt_k8m1	portal	task-456	failed	—	2026-04-07 10:12
evt_k7l5	flow	job-789	delivered	1800ms	2026-04-07 10:05

Click an event to see full details (payload, reply, timeline).

Allowlist

Shows which apps can send events to this agent:

If empty: Agent is open to all apps in the organization
If populated: Only listed apps can reach this agent

Click Configure Allowlist to add or remove apps. See Managing Allowlists for details.

Deactivating an Agent

If an agent is no longer active:

Open the agent's detail page
Click Deactivate Agent
Confirm the action

A deactivated agent cannot authenticate to Relay's WebSocket. If someone tries to connect with its token, the connection will be rejected.

Apps sending events to a deactivated agent will receive an error.

Use Cases for Deactivation

Maintenance: Temporarily shut down an agent for updates
Deprecation: Phase out an old agent in favor of a new one
Cleanup: Remove experimental agents from production

Token Rotation

If you suspect an agent token has been compromised, or if you rotate tokens periodically:

Open the agent's detail page
Click Rotate Token
Relay issues a new token (shown immediately — copy it!)
The old token has a 1-hour grace period

The Grace Period

After you rotate an agent's token:

✅ New token works immediately
✅ Old token still works for 1 hour (allows for graceful reconnection)
❌ After 1 hour, old token is completely invalid

This gives you time to update the plugin's or service's configuration without dropping active sessions.

How to Rotate in Practice

In Relay dashboard: Click "Rotate Token" for the agent
Copy the new token
Update your OpenClaw plugin config or agent service: Replace the old token with the new one
Restart the service (or restart the plugin)
Verify connection: Check the connection status on the agent detail page

Within the 1-hour grace period:

The service will attempt to reconnect with the new token
Existing sessions may briefly pause but will resume
After 1 hour, only the new token is valid

Monitoring

Agent Availability

The connection status shows whether your agent is online. If an agent goes offline:

Check the agent service logs
Verify the token is correct (compare with Relay dashboard)
Verify the service has outbound WSS access to api.relay.ckgworks.com
Check if the token has been rotated (and if the service is using the new one)
Ensure session storage (for OpenClaw) is healthy

Event Success Rate

Monitor the event history for patterns:

Status "delivered": Agent processed the event and sent a reply
Status "failed": Agent errored out or timed out
Status "pending": Agent is processing (or was processing when event was logged)
Status "rejected": App is not allowlisted (shouldn't reach this agent)

If you see many failures, investigate:

Is the agent service healthy?
Are there rate limits being hit?
Are sessions timing out prematurely?

Session Management

Each agent has a session TTL (time-to-live) — the maximum duration a conversation can persist. Examples:

Athena: 14 days — conversations stay fresh longer
Klyve: 30 days — technical workflows benefit from longer context

Sessions are stored in the OpenClaw plugin's backend. When the TTL expires, the session is discarded.

How Sessions Work

App sends: { agent_id: "athena", thread_id: "task-123", payload: {...} }
                    ↓
Relay forwards with session_key: "relay:portal:task-123"
                    ↓
OpenClaw plugin resumes or creates session "relay:portal:task-123"
                    ↓
Agent responds using full conversation history (within TTL window)

If the same thread_id is used again within the TTL, the agent resumes the conversation.

Best Practices

1. Use Clear Agent IDs

When registering an agent, choose a memorable ID:

✅ "athena" — clear and memorable
✅ "klyve" — distinctive
❌ "agent1" — ambiguous
❌ "test" — will be confusing later

2. Write Descriptive Names and Descriptions

The description appears in agent discovery results. Make it useful:

Name: Athena
Description: Personal assistant for general tasks, summaries, and analysis

Name: Klyve
Description: Technical specialist for code review, debugging, and workflow automation

3. Secure Your Agent Token

Store in configuration files that are .gitignore'd
Use environment variables or a secrets manager
Never share via email or chat
Rotate periodically

4. Monitor Connection Status

Check the dashboard regularly — is your agent online?
Set up alerts if an agent goes offline unexpectedly
If you deploy a new version, verify it reconnects to Relay

5. Configure Allowlists Intentionally

Decide whether your agent should be open to all apps or restricted:

Open: Default for general-purpose agents (Athena)
Restricted: For specialized agents (Klyve for Portal + Flow only)

See Managing Allowlists for details.

6. Rotate Tokens Periodically

Even if your agent token hasn't been compromised, rotate it every few months as a security best practice.

7. Monitor Event Success

Regularly check the event history for failures or anomalies:

High failure rate → investigate agent health
Repeated rejections → check allowlist configuration
Slow latencies → may indicate agent is overwhelmed or network is slow

Summary

Register agents in the dashboard
Store tokens immediately — they're shown only once
Monitor connection status — ensure your agent stays online
Configure allowlists to control which apps can reach it
Rotate tokens periodically or if compromised
Deactivate agents when they're no longer active
Check event history to monitor integration health

Next steps:

Configure allowlists to control agent access
Set up the OpenClaw Relay plugin for your agent
Monitor event logs to see real-time traffic

What Is an Agent in Relay?​

Registering a New Agent​

Agent Tokens​

Token Security​

Token Format​

Agent Detail Page​

Connection Status​

Configuration​

Event History​

Allowlist​

Deactivating an Agent​

Use Cases for Deactivation​

Token Rotation​

The Grace Period​

How to Rotate in Practice​

Monitoring​

Agent Availability​

Event Success Rate​

Session Management​

How Sessions Work​

Best Practices​

1. Use Clear Agent IDs​

2. Write Descriptive Names and Descriptions​

3. Secure Your Agent Token​

4. Monitor Connection Status​

5. Configure Allowlists Intentionally​

6. Rotate Tokens Periodically​

7. Monitor Event Success​

Summary​