Appearance
Connections and directories
Some services run many agents: a gateway on this Mac, a platform you reach over the network. Instead of asking people to set up each agent by hand, a plugin declares a connection, set up once in Settings, and gives its agent a directory: the live list of agents on that service. The app syncs the list into the Agent library, offers New, Edit and Delete when the plugin handles them, draws a tab in the inspector from data the plugin returns, and starts each new agent's DM with an introduction. This page explains what the person sees and what your plugin does about it.
Preview
The TypeScript SDK is being designed in the open. APIs on this page may change before the first release.
What the person sees
Settings. A plugin with a connection gets its own pane in Settings, titled after the plugin. When the connection declares where the service runs on this Mac, the pane says "OpenClaw is running on this Mac." with Connect, and the Agent library shows the same card. Connecting ticks through three rows: found the service, paired this Mac, loaded your agents. If the service wants the person to approve the new device, the pane says "Approve this Mac on the gateway." with the command to run, and keeps trying. Once connected, the pane shows where the service is, its version, what the app may do there ("Admin: the app can make, edit and delete agents." or "Read only.", with Request admin access) and the agents it found. Connect another gateway… asks for an address and a token for a service on another machine. Disconnect keeps the gateway listed; its agents stay in the library but say "Not connected" until the person connects again.
The Agent library. The service's agents appear in a section of their own, each with its pal, name, "What it's for" line and a caption saying where it runs. The list stays in sync: an agent made on the service appears, a renamed one is renamed, a deleted one is marked missing but its rooms keep their history. Every agent gets a DM.
New, Edit and Delete. With a directory that handles create, New offers "OpenClaw agent…": a sheet with the name, the pal, an emoji, "What it's for", the model (from your plugin's list), "How it should work" and, under Advanced, the workspace. While your plugin works, the footer shows each step you report: "Making its workspace…", "Writing its soul…". Edit sends only what changed, and if the agent's instructions changed on the service meanwhile, the person chooses Keep Mine or Take Theirs. Delete asks "Delete “Care” from OpenClaw?" with a switch to move its files to the Trash.
The inspector. A tab you declare shows what your plugin returns for the agent in that room: sections of rows with a title, a detail, a state dot and a note. It's read-only, with Reload, and when the service is offline it shows the last copy and says so.
The introduction. A new agent's DM opens with a line saying where it was made, then the agent gets a turn with no message, so it can say hello and ask what it's for. See The introduction.
The person never copies a token on their own Mac: the app reads the service's one-time secret once, hands it to your plugin for that one call, and keeps only what your plugin stores for itself.
Declare them
A connection is a named entry in connections, with code at src/connections/<name>.ts. A directory is a field on an agent, with code at src/directories/<agent>.ts. An inspector tab names a tab the app draws from inspect.
json
"connections": [
{
"name": "gateway",
"title": "OpenClaw",
"description": "The OpenClaw gateway on this Mac, or one you can reach.",
"preferences": [
{ "name": "gatewayUrl", "type": "url", "title": "Gateway address",
"default": "ws://127.0.0.1:18789", "required": true }
],
"local": {
"probeUrl": "http://127.0.0.1:18789/healthz",
"bootstrap": { "file": "~/.openclaw/openclaw.json", "tokenPath": "gateway.auth.token" }
}
}
],
"agents": [
{
"name": "openclaw",
"title": "OpenClaw",
"description": "An agent running on your OpenClaw gateway, with its tools, approvals and questions.",
"directory": { "connection": "gateway", "create": true, "update": true, "delete": true }
}
],
"inspectorTabs": [{ "name": "skills", "title": "Skills, tools and memory" }],
"permissions": { "network": [{ "preference": "gatewayUrl" }] }The connection's preferences are asked for in the Settings pane, not per agent. An agent with a directory needs no address or token preferences of its own: the connection holds them. See Manifest for every field.
local says how the app may find the service on this Mac. It sends a GET to probeUrl (with the port the bootstrap file names, when it differs: gateway.port beside gateway.auth.token); a 200 with ok: true in the body means the service is running, and the pane says so. On Connect, the app reads the one-time secret at bootstrap.tokenPath in bootstrap.file, only from a JSON file in a dot folder under the home folder (never under ~/.ssh, ~/.aws and the like), hands it to your connect as bootstrapToken, and never keeps it.
The connection
src/connections/<name>.ts default-exports defineConnection(handlers). The app calls connect when the person presses Connect, and again at launch for every connection it has saved and not disconnected, with no bootstrapToken: your plugin then connects with what it kept in secrets.
ts
import { CallError, defineConnection } from '@agentplaygrounds/sdk'
type Preferences = { gatewayUrl: string }
export default defineConnection<Preferences>({
async connect(context) {
context.notify({ state: 'connecting', detail: context.preferences.gatewayUrl })
const stored = await context.secrets.get('deviceToken')
if (!context.bootstrapToken && !stored) {
throw new CallError('needs-token', 'Nothing to connect with. Press Connect to pair again.')
}
// A bootstrap token pairs anew; otherwise the device token from last time still stands.
const device = context.bootstrapToken ? await pair(context.bootstrapToken) : await resume(stored!)
await context.secrets.set('deviceToken', device.token)
context.notify({ state: 'connected', detail: 'This Mac', version: device.version, access: device.access })
return { title: 'OpenClaw', detail: 'This Mac', version: device.version, access: device.access, deviceId: device.id }
},
async disconnect(context) {
await context.secrets.remove('deviceToken')
context.notify({ state: 'offline', detail: 'Disconnected' })
},
async status(context) {
const token = await context.secrets.get('deviceToken')
return token ? { state: 'connected', detail: 'This Mac', access: 'admin' } : { state: 'offline', detail: 'Not connected' }
},
async requestAccess(context, { level }) {
const request = await askForScopes(level)
return { status: 'pending', requestId: request.id, command: `openclaw devices approve ${request.id}` }
},
})The pattern to copy: the bootstrap token is the service's shared secret, handed over once to pair. Pairing yields a token for this device, and that is the only secret you store. The shared token is used and forgotten.
ConnectionContext
| Property | Description |
|---|---|
id | The record id: one connection as set up in Settings. The one found on this Mac and each remote gateway have their own. |
preferences | The connection's preferences from your manifest, as the person filled them in. |
bootstrapToken | The service's one-time secret, when the app read it for this call. Use it, don't keep it. |
hints | What the app knows about the service on this machine: stateDir, the folder the bootstrap file lives in, when it's local. |
signal | Aborted when the app cancels the call. |
ask | Prompts, bound to this call: a pairing code, a token the person pastes. |
storage, secrets | The plugin's storage and secrets under connection.<id>., so each connection keeps its own device identity and token. |
notify(status) | Reports the connection's state as it changes. The pane follows it. |
notify takes { state, detail?, requestId?, command?, version?, access? }. The states are connecting, pairing, connected, offline and failed. detail is one line for the pane: the host name, or what went wrong. For pairing, send the requestId and the command the person runs on the service to approve the device; the pane shows the command with Copy and says the app keeps trying.
The handlers
| Handler | Returns | Notes |
|---|---|---|
connect(context) | { title, detail, version?, access, deviceId? } | Connects, pairing if needed. access is "admin" or "read-only": with read-only, the app disables New, Edit and Delete and offers Request admin access. Throw needs-token when there is nothing to connect with. |
disconnect(context) | nothing | Forgets the token and closes the socket. The app keeps the record. |
status(context) | { state, detail?, … } | The current state, for when the app asks instead of listening. |
requestAccess(context, { level: 'admin' }) | { status: 'approved' | 'pending', requestId?, command? } | Asks the service for more access. pending comes with what the person has to run or approve. |
Only connect is required.
The directory
src/directories/<agent>.ts default-exports defineDirectory(handlers). The app calls list after connect and whenever you tell it the list changed, and the others when the person uses New, Edit, Delete or opens the inspector.
ts
import { CallError, defineDirectory, notify } from '@agentplaygrounds/sdk'
export default defineDirectory({
async list(context) {
const { agents, defaultId } = await gateway(context).agents()
return { agents: agents.map(toDirectoryAgent), defaultId, access: 'admin' }
},
async create(context, { draft }) {
context.progress('workspace', 'Making its workspace…')
const made = await gateway(context).create(draft)
context.progress('soul', 'Writing its soul…')
await writeInstructions(context, made.id, draft.instructions)
notify('directory.changed', { connection: context.connection })
return made
},
})DirectoryContext
| Property | Description |
|---|---|
connection | The record id the app is asking over: the same id the connection's connect was given. |
signal | Aborted when the app cancels the call. |
ask | Prompts, bound to this call. |
storage, secrets | The connection's scoped storage and secrets, the same the connection's handlers see, so the directory can reach the service with what connect kept. |
progress(step, title) | A step of a long call. The New sheet shows title in its footer while it waits: progress('soul', 'Writing its soul…'). |
The calls
| Handler | Returns | What the app does with it |
|---|---|---|
list(context) | { agents: DirectoryAgent[], defaultId?, access } | Syncs the agents into the library. Rows with kind: 'system' are the service's own and never shown. |
get(context, { id }) | DirectoryDetail | Opens Edit with the agent's instructions and their instructionsHash. |
options(context, { field: 'model' }) | { options: ModelOption[], default? } | Fills the Model menu in New and Edit. model is the only field so far. |
create(context, { draft }) | DirectoryAgent | Makes the agent, then syncs. The sheet keeps the pal the person chose even if your row says otherwise. |
update(context, { id, patch }) | DirectoryAgent | Saves Edit. The patch holds only the fields that changed. |
delete(context, { id, deleteFiles }) | { removed: string[], failed: { path, reason }[] } | Removes the agent, and its files when deleteFiles is true. Paths in failed are shown to the person. |
inspect(context, { id, roomId? }) | { sections: InspectorSection[] } | Draws the inspector tab for that agent, in that room. |
Only list is required. The manifest's create, update and delete say which of New, Edit and Delete the app offers; declare only what you implement.
When the list changes on the service, say so and the app lists again:
ts
notify('directory.changed', { connection: context.connection })Send it after your own writes too, once at the end. notify is dropped in a host that doesn't make calls, so it's safe anywhere.
The shapes
An agent, as the service lists it:
ts
type DirectoryAgent = {
id: string // its id on the service
name: string
description?: string // one line: what it's for
emoji?: string
pal?: { shape: string; color: BrandColor } // a shape from the app's catalog in a brand color
model?: { value: string; title: string }
kind?: 'agent' | 'system'
attention?: string // one line when the service says it needs attention there
workspace?: string
}pal.shape is a shape id from the app's pal catalog, like watering-can; a shape the app doesn't know is ignored. attention shows as help on the agent's row: "Needs attention on the gateway".
What New sends, and what Edit sends:
ts
type DirectoryDraft = {
name: string
description?: string
emoji?: string
model?: string // a ModelOption's value
pal?: { shape: string; color: BrandColor; svg?: string }
instructions?: string
workspace?: string
}
type DirectoryPatch = Partial<DirectoryDraft> & { instructionsBaseHash?: string }pal.svg is the pal drawn, for a service that keeps an avatar image. With instructionsBaseHash, the write of instructions is conditional on that hash: throw conflict when it's stale, and the person chooses Keep Mine or Take Theirs. Without it, the write overwrites.
What get returns, and a model for the menu:
ts
type DirectoryDetail = DirectoryAgent & { instructions?: string; instructionsHash?: string }
type ModelOption = {
value: string
title: string // "Claude Haiku 4.5"
group?: string // "Claude"; the menu groups when there's more than one
available: boolean // unavailable options are shown disabled
note?: string // why it isn't available, or what it needs
}What inspect returns:
ts
type InspectorSection = {
id: string
title: string
rows: { title: string; detail?: string; state?: 'on' | 'off' | 'needs' | 'ok' | 'warn'; note?: string }[]
}on and ok draw a success dot, needs and warn a warning dot, off a quiet one; the colors follow the theme. note is a caption under the row.
Errors
Throw a CallError with a code, and the app turns it into the right sentence and the right button. Any thrown error with a code works; CallError is the typed way, and details carries what the app needs for some codes.
ts
throw new CallError('name-taken', `An agent named ${draft.name} already exists.`, { name: draft.name })| Code | Throw it when | What the app shows, for a plugin titled OpenClaw |
|---|---|---|
name-taken | An agent with that name exists. details: { name? } | "An agent called “Care” is already on this gateway.", with the Name field focused |
needs-admin | The connection has read-only access | "You need admin access on this gateway to make agents." with Request admin access |
needs-token | connect has nothing to connect with: no bootstrap token and nothing stored | Your message, under the gateway row in Settings, with Try Again |
conflict | The instructions changed since instructionsBaseHash. details: { currentHash } | "Care changed its files while you were editing." with Keep Mine and Take Theirs |
only-agent | The service keeps one agent and this is it | "Care is the only agent on this gateway. OpenClaw keeps one." |
offline | The service isn't answering | "OpenClaw isn't answering. Is the gateway running?"; on Delete: "OpenClaw isn't answering. Try again when it's back." |
gateway | The service refused; your message says why | "OpenClaw couldn't make the agent: " and your message |
files-failed | The agent was made but its files weren't finished. details: { id } | "Care was made, but its soul couldn't be written." with Try Again, which calls update with the whole draft |
The person reads your message for needs-token and gateway, so write a sentence, without codes or addresses: "The token was refused. Check gateway.auth.token on the gateway's machine."
The introduction
When the person creates an agent with Start a DM with it on, the app opens the DM, adds a line saying where the agent was made, and starts a turn with turn.reason === 'introduce': no message, from is the person, canPass is false. It happens once, in that DM. Your agent says hello and asks what it should know.
ts
import { note, text, type AgentContext } from '@agentplaygrounds/sdk'
export default async function* care({ agent, turn, connection }: AgentContext) {
if (turn.reason === 'introduce') {
yield text(`Hi, I'm ${agent.name}. What matters most in this job?`)
return
}
// …
}On an agent from a directory, agent.remoteId is its id on the service, agent.emoji its emoji there, and connection.id is the record id the connection's connect was given, so the agent can reach the service with the same scoped secrets.
The note event. When your plugin does something on the agent's behalf that the person should see, say it as a note: a line in the room from the plugin, never as the agent's words.
ts
yield note(`Saved to ${agent.name}'s soul and notes.`)The app shows it as a quiet line after the reply. A host that hasn't said it shows notes drops it, so nothing is shown instead; check hostCapabilities().notes when you'd rather say it in text.
How the OpenClaw plugin answers. OpenClaw agents can't be relied on to write their own files: their file tools wait on approvals and failed every way it was tried, so the plugin, not the agent, writes them. On the introduce turn it sends the agent the message "[Agent Playgrounds] Introduce yourself." with a system prompt for this conversation only: your name is Care, the person said you're for "Keeps my 23 house plants alive", say hello in a sentence or two, then ask at most three short questions, one message at a time, only about what you don't know yet, and when you have your answers end your reply with a block the person never sees. The plugin holds back anything that looks like the start of that block as the reply streams, so the person never sees a half-written one. When the block arrives, the plugin writes it into the agent's SOUL.md, AGENTS.md and USER.md on the gateway, with hash checks, yields the note "Saved to Care's soul and notes.", tells the app the directory changed, and closes the introduction. If the person starts giving the agent work instead of answering, the agent does the work and closes the introduction in the same reply; after six turns it closes on its own.
The OpenClaw plugin, in short
The connection pairs with the gateway as a device of its own. With a bootstrap token it asks for admin, so the app can make, edit and delete agents; without one it connects with the device token it kept, and the scopes that token was issued with.
ts
// src/connections/gateway.ts
export default defineConnection<{ gatewayUrl: string }>({
async connect(context) {
const url = context.preferences.gatewayUrl
context.notify({ state: 'connecting', detail: `Found OpenClaw · ${url}` })
const gateway = gatewayFor(context.id, { url, secrets: context.secrets, bootstrapToken: context.bootstrapToken })
gateway.onPairingRequired(({ requestId }) =>
context.notify({ state: 'pairing', requestId, command: `openclaw devices approve ${requestId}` }))
const hello = await gateway.start() // throws CallError('needs-token') with nothing to connect with
if (context.hints?.stateDir) await context.storage.set('stateDir', context.hints.stateDir)
const detail = isLoopback(url) ? 'This Mac' : new URL(url).hostname
context.notify({ state: 'connected', detail, version: hello.version, access: hello.access })
return { title: 'OpenClaw', detail, version: hello.version, access: hello.access, deviceId: hello.deviceId }
},
})The directory maps the gateway's list to rows. "What it's for" is the agent's identity theme on the gateway; the pal is kept as a marker in the agent's avatar, so OpenClaw's own apps show it too.
ts
// src/directories/openclaw.ts
async list(context) {
const { agents, defaultId } = await gatewayFor(context.connection).agents()
return {
agents: agents.map((a) => ({
id: a.id,
name: a.identity?.name ?? a.name ?? a.id,
description: a.identity?.theme,
emoji: a.identity?.emoji,
pal: palMarker(a.identity?.avatar),
model: a.model?.primary ? { value: a.model.primary, title: modelTitle(a.model.primary) } : undefined,
kind: a.kind ?? 'agent',
attention: a.status === 'degraded' ? 'Needs attention on the gateway' : undefined,
workspace: a.workspace,
})),
defaultId,
access: gatewayFor(context.connection).access,
}
}Creating an agent is several steps on the gateway, and the sheet shows each one. The agent's instructions live in a managed section of its AGENTS.md, so get returns that section and its file hash, and update writes it back only if the hash still matches. Always pass a workspace: OpenClaw keeps an agent's folder on delete when it was made inside the shared one, so the plugin uses the stateDir the connection stored.
ts
async create(context, { draft }) {
const gateway = gatewayFor(context.connection)
const id = slug(draft.name)
if (await gateway.has(id)) throw new CallError('name-taken', `An agent called ${draft.name} is already on this gateway.`, { name: draft.name })
context.progress('workspace', 'Making its workspace…')
const workspace = draft.workspace ?? `${await context.storage.get('stateDir')}/workspace-${id}`
await gateway.create({ name: draft.name, model: draft.model, workspace })
context.progress('look', 'Setting its look…')
await gateway.update(id, { emoji: draft.emoji, avatar: avatarWith(draft.pal) })
context.progress('soul', 'Writing its soul…')
try {
await writeManagedSections(gateway, id, draft) // SOUL.md, AGENTS.md; blanks the first-run ritual
} catch (error) {
throw new CallError('files-failed', `${draft.name} was made, but its files couldn't be written.`, { id })
}
notify('directory.changed', { connection: context.connection })
return (await gateway.agent(id))!
}The agent itself reads the record from context.connection and its id from agent.remoteId, so a hand-added agent from before the plugin had a connection still works from its own saved preferences:
ts
// src/agents/openclaw.ts
export default async function* openclaw({ agent, connection, preferences, turn }: AgentContext<Preferences>) {
const gateway = connection ? gatewayFor(connection.id) : legacyGateway(preferences)
const agentId = agent.remoteId ?? preferences.agentId ?? (await gateway.agents()).defaultId
if (turn.reason === 'introduce') { yield* introduce(gateway, agentId, agent); return }
// …
}Test it
PluginHost from @agentplaygrounds/test-host makes the same calls the app does. call returns the handler's result or rejects with the CallError your plugin threw, and notifications collects what your plugin sent on its own.
ts
import { PluginHost } from '@agentplaygrounds/test-host'
const host = await PluginHost.load({ bundle, manifest, secrets: new Map() })
const connected = await host.call('connection.connect', {
connection: 'gateway', id: 'local', preferences: { gatewayUrl: 'ws://127.0.0.1:18789' }, bootstrapToken: token,
})
const { agents } = await host.call('directory.list', { connection: 'local' })
const care = await host.call('directory.create', { connection: 'local', draft: { name: 'Care', model: 'claude/haiku' } })
host.notifications.filter((n) => n.name === 'directory.progress')Load the host with capabilities: {} to see how your plugin behaves in a host that makes no calls: it still loads, its agents still answer, and notify and note are dropped. packages/test-host/test/fixtures/directory in the SDK is a complete worked example: a connection that pairs with a one-time token and keeps only the device token, a directory with every call and every error, and an agent that answers the introduce turn with a note.
Next steps
- Manifest: every field of
connections,directory,inspectorTabsand hidden preferences. - Agents and events:
Turnwithintroduce,AgentContext.connectionand thenoteevent. - Connect your first agent: if you haven't written an agent yet.