Orca API
The Orca plugin (extensions/orca) exposes a versioned client API over the gateway WebSocket,
registered via api.registerGatewayMethod. Setup, pairing, and grants are covered in
Orca.
- Params are strict objects: unknown keys fail with
orca-invalid-params. targetIdnames a configured CLI target or a paired host (p-prefix); max 64 characters.terminalhandles match^term_[A-Za-z0-9-]{1,80}$.- Write methods return
{ ok: true }(launch adds fields) and invalidate the target’s snapshot cache. - Write methods log an audit line with the caller, target, and ids; never the typed text.
Scopes and grants
- Read methods (
orca.v1.access,snapshot,screen,repos,requests) and write methods (orca.v1.send,launch,respond,message) admit narrow user-client sessions as well as operators.orca.v1.admin.*is unclassified and fails closed tooperator.admin. - Operators see every target in
controlmode. - A narrow caller (
openclaw-user-client) resolves to a person throughsession.identityLinks, then toplugins.entries.orca.config.access.users[<person>]. No grant means no targets. A target outside the grant fails withorca-access-denied; a write on areadgrant fails withorca-read-only. Enforcement sits in the method handler. - Chat methods (
requests,respond,message) need a paired target; CLI targets fail withorca-not-structured.
Methods
orca.v1.access
Params: none.
Result: { enabled, mode?, targets, launchAgents }. A narrow caller with no grant gets
{ enabled: false, targets: [], launchAgents: [] }, not an error. Otherwise mode is read or
control, and each target is { id, label, transport: "paired" | "cli", structured }.
structured is true for paired targets. Clients hide the Orca entry when enabled is false.
orca.v1.snapshot
Params: targetId.
Result: { targetId, fetchedAt, truncated, worktrees, agents }, capped at snapshotLimit
agents (truncated set when cut).
worktrees[]:{ id, name, repo, branch, status, parentWorktreeId, lastActivityAt }.agents[]:{ key, kind: "terminal" | "chat", worktreeId, agentType, state, needsAttention, attention: { kind, message } | null, plan, title, prompt, lastMessage, updatedAt, terminal, sessionId }. Terminal agents carryterminal; chat agents carrysessionId.
orca.v1.screen
Params: targetId, terminal.
Result: { status, lines, truncated }, the last 200 lines of the terminal.
orca.v1.repos
Params: targetId.
Result: { repos: [{ id, name }] }, for picking a repo when launching into a new worktree.
orca.v1.requests
Params: targetId, sessionId.
Result: { items }, the session’s pending prompts. Each item is { itemId, revision, kind: "approval" | "question", title, detail, planText, options, questions }; options[] is { id, label, intent: "grant" | "refuse" | null }.
orca.v1.send
Types into a terminal. Requires control.
Exactly one of
text or key is required.
orca.v1.launch
Starts an agent session. Requires control.
Exactly one of
worktreeId or newWorktree is required. Result:
{ ok: true, kind?, detail?, promptDelivery? }, where kind is structured (a chat) or
terminal, and detail is a human-readable note. promptDelivery is set only when the session
started but the prompt may not have reached the agent: not-delivered (Orca did not send it) or
unconfirmed (Orca could not confirm it arrived). Clients should show the prompt back to the user
rather than launch again. The CLI transport never sets it.
Mobile-scoped pairings can launch into existing worktrees. A new worktree needs worktree.create in
Orca’s mobile method set; see pairing scope. A host that cannot launch
agents or serve chats fails with orca-method-unavailable and the message “This Orca host cannot
launch agents for WednesdayAI; update Orca on that host.” or “This Orca host cannot serve chat
sessions to WednesdayAI; update Orca or turn chats on.”
orca.v1.respond
Answers a pending request. Requires control and a paired target.
Params: targetId, sessionId, itemId, revision (integer from orca.v1.requests), and
exactly one of optionId (approval) or answers (question: 1 to 10 of { questionId, optionIds (max 20), other? }). A request that moved on fails with orca-request-stale;
refetch and retry.
orca.v1.message
Sends a chat message. Requires control and a paired target.
Params: targetId, sessionId, text (1 to 8000 characters). Result: { ok: true }.
Admin methods
Operator-only (operator.admin); narrow callers get orca-access-denied.
orca.v1.admin.targets(no params):{ targets: [{ id, label, transport, state, endpoint?, scope?, lastError?, runtimeVersion? }] }. CLI targets reportstate: "unprobed".orca.v1.admin.pair(code, up to 131072 characters;label, up to 48): pairs a host and returns{ targetId }.orca.v1.admin.unpair(targetIdof a paired host): returns{ ok: true }.
Errors
Errors use gateway codesINVALID_REQUEST or UNAVAILABLE, with details.reason:
Versioning
Method names are versioned. A breaking change ships a neworca.v2.* family side-by-side with
orca.v1.*. Clients discover served methods via the hello-ok features.methods advertisement
and should feature-detect; the web client shows Orca only when the gateway serves the orca.v1
family and the caller holds a grant.