Autonomous Agents¶

Management API는 프로바이더 탐색, 게이트웨이 수명주기, 채널, 스킬, 모델 동기화, 메시징, Hermes 관리를 위해 /autonomous 아래에 34개 작업을 제공합니다. 기본 base URL은 http://127.0.0.1:8001/api/v1입니다. 이 페이지의 모든 작업은 /api/docs의 Swagger UI에서 Autonomous Agents 태그 아래에 표시됩니다.

새 연동에는 hermes를 사용하세요. claw는 데스크톱 런타임에서 유효한 프로바이더 종류이지만, 기존 /claw/* 라우트는 두 번째 autonomous-agent API가 아니라 호환성 표면입니다. 레거시 /claw 라우트를 참고하세요.

프로바이더 모델과 런타임 가용성¶

GET /autonomous/providers는 실행 중인 프로세스에 등록된 프로바이더를 반환합니다. 각 ProviderDescriptor에는 다음 필드가 있습니다.

• kind: claw 또는 hermes입니다.
• displayName: 사용자에게 표시하는 프로바이더 이름입니다.
• capabilities: 기능 flag, 지원 메시징 플랫폼, 실행 모드입니다.
• installed: 환경 탐지가 미해결 issue를 보고하지 않을 때만 true입니다.
• gateway: 가장 최근 GatewayInfo이며, 게이트웨이를 실행한 적이 없으면 null입니다.

Capability flag는 supportsMessagingChannels, supportsSkills, supportsProfiles, supportsMcp, supportsModelBridge, supportsGatewayLogs, supportsChannelHistory, supportsSkillToggle입니다.

GET /autonomous/availability는 등록되지 않은 프로바이더를 포함해 이 빌드가 아는 모든 프로바이더 종류를 보고합니다. 각 행에는 kind, displayName, runtimeRequirement, available, 선택적인 unavailableReason이 있습니다. runtimeRequirement는 Hermes에서 universal, Claw에서 desktop_only입니다. 최상위 anyAvailable과 선택적인 unavailableReason은 전체 기능 상태를 설명합니다.

Hermes는 데스크톱 앱과 aigo-server 모두에서 등록됩니다. 게이트웨이를 실행하려면 접근 가능한 Docker 또는 Apple Container 런타임과 사용할 수 있는 이미지가 필요합니다. Claw는 데스크톱 앱에서만 등록됩니다. 따라서 headless 서버는 Hermes를 사용 가능, Claw를 사용 불가로 보고하고 /autonomous/providers에는 Hermes만 포함합니다.

설치 또는 시작 전에 /autonomous/providers/{kind}/environment를 확인하세요. EnvironmentReport에는 containerRuntime, image, gatewayRunning, issues, 프로바이더별 extra 데이터가 있습니다. Issue tag는 container_runtime_not_found, container_runtime_unsupported, image_missing, image_outdated, gateway_not_running, port_in_use, persistent_volume_unavailable, custom입니다.

인증과 scope¶

X-API-Key, Authorization: Bearer token 또는 login endpoint가 반환한 aigo_session cookie로 인증합니다.

Route manifest는 세 가지 scope를 적용합니다.

Admin key는 이 검사를 만족합니다. Admin이 아닌 key에는 아래 표에 적힌 정확한 scope가 필요합니다.

프로바이더 endpoint¶

아래 path에는 /api/v1 prefix를 생략했습니다.

URL이 {kind}의 source of truth입니다. Gateway와 message handler는 body의 provider가 URL과 다르면 URL의 프로바이더로 정규화합니다. Gateway 시작 body는 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에는 modelId, displayName, contextWindow가 있습니다. SendMessageRequest에는 provider, channelId, content, 선택적인 idempotencyKey가 있습니다. Message content는 64 KiB, idempotency key는 256 byte로 제한됩니다.

프로바이더 이벤트 스트림¶

GET /autonomous/events는 인증이 필요한 Server-Sent Events stream입니다. SSE event field는 ProviderEvent.type 값이고 data field는 전체 JSON event입니다. 현재 variant는 다음과 같습니다.

서버는 15초마다 ping keepalive를 보냅니다. Process-wide subscriber cap이 event broadcaster를 보호하며, cap을 넘는 연결은 429를 받습니다.

같은 provider event는 application event bus에도 전달됩니다. 호환 envelope은 autonomous:provider_event입니다. Typed bus 이름은 autonomous:gateway-status-changed, autonomous:channel-updated, autonomous:message-received, autonomous:skill-updated, autonomous:model-sync-changed, autonomous:install-progress, autonomous:governance-event입니다. Consumer는 gap을 허용하고 lagged 뒤에 상태를 다시 조회해야 합니다.

Hermes 프로필과 migration¶

Profile 이름은 소문자, 숫자, underscore, hyphen을 사용하고 문자 또는 숫자로 시작하며 최대 64자입니다. Profile response에는 name, path, isDefault, createdAt, 선택적인 lastActiveAt, 선택적인 description이 있습니다.

Migration은 dryRun, preset (user_data 또는 full), targetProfile을 받습니다. Report에는 dryRun, items, warnings, 선택적인 error가 있습니다. 먼저 dry run을 실행하세요. Migration은 OpenClaw source directory를 삭제하지 않으며 그 안의 raw secret 값을 읽지 않습니다.

Hermes MCP 서버¶

HermesMcpServer에는 id, name, command, args, env, scope, enabled가 있습니다. Scope는 profile, user, system입니다. 등록과 삭제는 먼저 영속화한 뒤, 게이트웨이가 지원하면 daemon reload를 요청합니다. ReloadResult.status는 reloaded, gateway_not_running, unsupported, error입니다.

MCP env map의 값은 client boundary에서 secret으로 취급하세요. Log나 command history에 출력하지 마세요.

Hermes 설정과 승인¶

Folder permission에는 path, level, recursive, 선택적인 description이 있습니다. Profile 하나에 최대 64개 entry를 둘 수 있습니다. Container limit는 선택적인 cpuShares, memoryMib, pidsLimit 값입니다.

Approval decision은 { "decision": "approve" } 또는 { "decision": "deny", "reason": "..." }입니다. Pending row에는 request id, profile, operation과 target id, description, actor label, 생성 시각, redacted payloadSummary가 있습니다. 적용된 결정은 history로 이동합니다.

Hermes 플랫폼 credential¶

지원하는 platform identifier는 whatsapp, telegram, slack, discord, imessage, signal, teams, matrix, mattermost, email, sms, dingtalk, feishu, wecom, bluebubbles, home_assistant, google_chat입니다.

Desktop caller는 secret 값을 미리 저장하고 field 이름에서 secure-storage handle로 매핑하는 fieldNames map을 보냅니다. 인증된 headless caller는 secrets map을 보낼 수 있습니다. Service는 이 값을 server-side secure storage의 server-derived key에 즉시 저장합니다. Raw 값은 반환, log, Hermes binding 영속화, event emit 대상이 아닙니다. Response에는 credentialsRef, credentialsSet 같은 binding metadata만 있습니다.

JSON body의 platform은 URL의 {platform}과 일치해야 합니다. 다르면 400으로 거부합니다.

실행 예제¶

예제를 실행하기 전에 base URL과 access key를 설정합니다.

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

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"

설치가 완료되면 202를 반환합니다. install_progress가 필요하면 POST 전에 /autonomous/events를 구독하세요.

게이트웨이 시작과 상태 확인¶

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"

예제 이미지를 Hermes 설치에 설정한 이미지로 바꾸세요.

Telegram credential 설정과 테스트¶

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"

이 예제는 jq가 필요하며 token을 process argument가 아니라 standard input으로 보냅니다. Loopback이 아닌 network에서 inline secret을 보낼 때는 HTTPS Management API endpoint를 사용하세요.

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"

레거시 /claw 라우트¶

서버는 이전 desktop client를 위해 /claw 아래의 36개 라우트를 계속 받습니다. 이 라우트는 canonical provider-neutral API를 중복하고 desktop-specific shape를 유지하며 headless 서버에서 동작할 수 없으므로 Swagger와 새 CLI coverage에서 의도적으로 제외합니다. 새 연동은 /autonomous/providers/claw/*와 /autonomous/hermes/migrate-claw를 사용해야 합니다.

명시적인 /claw OpenAPI exemption은 문서화되지 않은 현재 API가 아니라 호환성 결정입니다. 이 라우트를 제거하려면 별도의 호환성 및 release 결정이 필요합니다.

CLI¶

aigo autonomous command group은 모든 /autonomous route를 다룹니다. Provider command, Hermes subcommand, input file form, event following은 CLI 레퍼런스를 참고하세요.