Autonomous Agents¶

The Management API exposes 34 operations under /autonomous for provider discovery, gateway lifecycle, channels, skills, model synchronization, messaging, and Hermes administration. The default base URL is http://127.0.0.1:8001/api/v1. Every operation on this page appears in Swagger UI at /api/docs under the Autonomous Agents tag.

Use hermes for new integrations. claw remains a valid provider kind on a desktop runtime, but the old /claw/* routes are a compatibility surface rather than a second autonomous-agent API. See Legacy /claw routes.

Provider model and runtime availability¶

GET /autonomous/providers returns the providers registered in the running process. Each ProviderDescriptor contains:

• kind: claw or hermes.
• displayName: the user-facing provider name.
• capabilities: feature flags and the supported messaging platforms and execution modes.
• installed: true only when environment detection reports no outstanding issue.
• gateway: the latest GatewayInfo, or null before a gateway has run.

Capability flags are supportsMessagingChannels, supportsSkills, supportsProfiles, supportsMcp, supportsModelBridge, supportsGatewayLogs, supportsChannelHistory, and supportsSkillToggle.

GET /autonomous/availability reports every provider kind known to the build, including providers that are not registered. Each row contains kind, displayName, runtimeRequirement, available, and an optional unavailableReason. runtimeRequirement is universal for Hermes and desktop_only for Claw. The top-level anyAvailable and optional unavailableReason describe the domain as a whole.

Hermes is registered by both the desktop app and aigo-server. Its gateway still needs an accessible Docker or Apple Container runtime and a usable image. Claw is registered only by the desktop app. A headless server therefore reports Hermes as available and Claw as unavailable, while /autonomous/providers contains only Hermes.

Check /autonomous/providers/{kind}/environment before install or start. Its EnvironmentReport contains containerRuntime, image, gatewayRunning, issues, and provider-specific extra data. Issue tags include container_runtime_not_found, container_runtime_unsupported, image_missing, image_outdated, gateway_not_running, port_in_use, persistent_volume_unavailable, and custom.

Authentication and scopes¶

Authenticate with X-API-Key, an Authorization: Bearer token, or the aigo_session cookie returned by the login endpoint.

The route manifest applies three scopes:

An Admin key satisfies these checks. A non-admin key needs the exact scope listed in the tables below.

Provider endpoints¶

Paths omit the /api/v1 prefix.

The URL is the source of truth for {kind}. The gateway and message handlers normalize a mismatched provider field to the URL provider. A gateway start body uses the flattened GatewayStartOptions shape:

{
  "provider": "hermes",
  "containerConfig": {
    "image": "ghcr.io/example/hermes:latest",
    "additionalMounts": [],
    "timeout": 1800000,
    "idleTimeout": null
  },
  "host": "127.0.0.1",
  "port": 39050
}

ModelSummary has modelId, displayName, and contextWindow. SendMessageRequest has provider, channelId, content, and optional idempotencyKey. Message content is limited to 64 KiB and the idempotency key to 256 bytes.

Provider event stream¶

GET /autonomous/events is an authenticated Server-Sent Events stream. The SSE event field is the ProviderEvent.type value and the data field is the complete JSON event. Current variants are:

The server sends a ping keepalive every 15 seconds. A process-wide subscriber cap protects the event broadcaster; a connection beyond the cap receives 429.

The same provider events are mirrored onto the application event bus. The compatibility envelope is autonomous:provider_event. Typed bus names are autonomous:gateway-status-changed, autonomous:channel-updated, autonomous:message-received, autonomous:skill-updated, autonomous:model-sync-changed, autonomous:install-progress, and autonomous:governance-event. Consumers must tolerate gaps and refetch state after lagged.

Hermes profiles and migration¶

Profile names use lowercase letters, digits, underscores, and hyphens, start with a letter or digit, and are at most 64 characters. A profile response contains name, path, isDefault, createdAt, optional lastActiveAt, and optional description.

Migration accepts dryRun, preset (user_data or full), and targetProfile. The report contains dryRun, items, warnings, and optional error. Run a dry run first. Migration never deletes the OpenClaw source directory and never reads raw secret values from it.

Hermes MCP servers¶

HermesMcpServer contains id, name, command, args, env, scope, and enabled. Scope is profile, user, or system. Registration and removal persist first, then request a daemon reload when the gateway supports it. ReloadResult.status is reloaded, gateway_not_running, unsupported, or error.

Treat values in the MCP env map as secrets at the client boundary. Do not print them in logs or command history.

Hermes settings and approvals¶

A folder permission contains path, level, recursive, and optional description. A profile accepts at most 64 entries. Container limits are optional cpuShares, memoryMib, and pidsLimit values.

An approval decision is either { "decision": "approve" } or { "decision": "deny", "reason": "..." }. Pending rows include the request id, profile, operation and target ids, description, actor label, creation time, and a redacted payloadSummary. Applied decisions move to history.

Hermes platform credentials¶

Supported platform identifiers are whatsapp, telegram, slack, discord, imessage, signal, teams, matrix, mattermost, email, sms, dingtalk, feishu, wecom, bluebubbles, home_assistant, and google_chat.

Desktop callers pre-store secret values and send a fieldNames map from field names to secure-storage handles. Authenticated headless callers may send a secrets map. The service writes those values immediately to server-side secure storage under server-derived keys. Raw values are never returned, logged, persisted in the Hermes binding, or emitted as an event. Responses contain only binding metadata such as credentialsRef and credentialsSet.

The platform in the JSON body must match {platform} in the URL. A mismatch is rejected with 400.

Walkthroughs¶

Set the base URL and an access key before running the examples:

export AIGO_URL=http://127.0.0.1:8001/api/v1
export AIGO_API_KEY=replace-me

Detect and install Hermes¶

curl -sS -H "X-API-Key: $AIGO_API_KEY" \
  "$AIGO_URL/autonomous/providers/hermes/environment"

curl -sS -X POST -H "X-API-Key: $AIGO_API_KEY" \
  "$AIGO_URL/autonomous/providers/hermes/install"

Installation returns 202 after the operation completes. Subscribe to /autonomous/events before the POST when you need install_progress updates.

Start and inspect the gateway¶

curl -sS -X POST \
  -H "X-API-Key: $AIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"hermes","containerConfig":{"image":"ghcr.io/example/hermes:latest","additionalMounts":[],"timeout":1800000,"idleTimeout":null},"host":"127.0.0.1","port":39050}' \
  "$AIGO_URL/autonomous/providers/hermes/gateway/start"

curl -sS -H "X-API-Key: $AIGO_API_KEY" \
  "$AIGO_URL/autonomous/providers/hermes/gateway"

Replace the example image with the image configured for your Hermes installation.

Set and test Telegram credentials¶

read -rsp "Telegram bot token: " TELEGRAM_BOT_TOKEN
jq -n --arg token "$TELEGRAM_BOT_TOKEN" \
  '{platform:"telegram",fieldNames:{},secrets:{botToken:$token}}' | \
curl -sS -X POST \
  -H "X-API-Key: $AIGO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  "$AIGO_URL/autonomous/hermes/platforms/telegram/credentials"
unset TELEGRAM_BOT_TOKEN

curl -sS -X POST -H "X-API-Key: $AIGO_API_KEY" \
  "$AIGO_URL/autonomous/hermes/platforms/telegram/test"

This example requires jq and sends the token through standard input instead of a process argument. Use an HTTPS Management API endpoint when sending inline secrets over a non-loopback network.

Decide a pending approval¶

curl -sS -H "X-API-Key: $AIGO_API_KEY" \
  "$AIGO_URL/autonomous/hermes/settings/pending-approvals"

curl -sS -X POST \
  -H "X-API-Key: $AIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"replace-with-pending-id","decision":{"decision":"approve"}}' \
  "$AIGO_URL/autonomous/hermes/settings/approve"

Legacy /claw routes¶

The server still accepts 36 routes under /claw for older desktop clients. They are deliberately excluded from Swagger and new CLI coverage because they duplicate the canonical provider-neutral API, retain desktop-specific shapes, and cannot work on a headless server. New integrations must use /autonomous/providers/claw/* and /autonomous/hermes/migrate-claw.

The explicit /claw OpenAPI exemption is a compatibility decision, not an undocumented current API. Removing those routes requires a separate compatibility and release decision.

CLI¶

The aigo autonomous command group covers every /autonomous route. See the CLI reference for provider commands, Hermes subcommands, input-file forms, and event following.