# CLAWD agent workspace

Open `https://clawdmail.app/agents` and sign in with an approved CLAWD Mail account. Select a role, provide a task and role-specific details, and run CLAWD. The twelve presets adapt the supplied local AgentMail examples; the OpenAI terminal example becomes a CLAWD terminal assistant powered by xAI.

| Example | Interactive workflow | External execution requirements |
| --- | --- | --- |
| inbox-zero | Classify, prioritize, summarize, and propose replies to selected mail | Applying labels or autonomous cleanup is separate |
| invoice-processor | Extract invoice fields, match supplied purchase orders, and flag exceptions | Accounting and payment integrations |
| openai-terminal | Ask CLAWD for commands, explanations, and mail research | Commands are returned for review; no server shell execution |
| podcast-booking-agent | Qualify a guest and prepare booking outreach | Calendar availability and actual booking integration |
| receipt-parser-agent | Extract receipt records and summarize expenses by currency | Expense-system submission and currency conversion data |
| sales-signal-router | Classify buying signals and draft routing recommendations | CRM, team assignment, and notification integrations |
| sales-agent | Qualify leads and draft outreach and follow-ups | CRM and scheduled follow-up execution |
| scheduling-agent | Propose times and prepare calendar-invite content | Calendar access and confirmed event creation |
| support-agent | Triage support requests and draft grounded answers | Live knowledge base and ticket-system updates |
| voice-to-email | Browser dictation or pasted transcript to a reviewed email | Dictation availability depends on the browser speech service |
| x402-payment-agent | Validate invoice/payment details and produce an approval plan | Connected wallet and a real payment adapter; no funds move here |
| note-taker | Turn notes or transcripts into minutes, actions, and digests | Scheduled delivery requires a scheduler |

## Private context and output

Tasks can run without an inbox. Selecting an inbox or conversation authorizes bounded read access only to that account’s owned mailbox. Runs are saved in private R2 under the creator’s namespace. Recent history can be reopened, copied, downloaded as text, and used for follow-up tasks. When a result contains a supported fenced artifact, separate buttons download validated JSON, CSV, Markdown, or an importable calendar `.ics` file.

The separate Save draft action requires an owned inbox and reviewed recipient, subject, and body. It stores an unsent draft that appears in the mailbox’s Drafts folder. Sending remains an explicit mailbox action. Agent runs do not execute commands, archive mail, write CRM records, book calendars, or pay invoices.

## xAI and inputs

Configure `XAI_API_KEY` on the backend for the primary xAI Responses API and `grok-4.7`. Configure `OPENROUTER_API_KEY` for the fallback provider. The workspace uses OpenRouter when xAI is unavailable; completed results identify the model that actually answered. Provider keys are never returned to browsers. Missing configuration, unavailable credits, rejected credentials, and provider failures are displayed without fabricated results.

Task text, supplied role details, selected inbox context, bounded conversation history, and uploaded images are sent to xAI, or through OpenRouter to the configured fallback model if xAI is unavailable. This workspace’s tools only read the selected owned inbox; web search and fetching supplied document URLs are disabled. xAI Responses requests use `store: false`. OpenRouter Chat Completions requests instead use `provider.data_collection: 'deny'` to exclude providers that collect user data, as described in [OpenRouter’s provider routing documentation](https://openrouter.ai/docs/guides/routing/provider-selection); this is a routing preference, not a zero-retention guarantee. Private run results persist in the application’s R2 storage.

Up to four PNG, JPEG, or WebP images are accepted with a combined decoded size limit of 600 KiB. The browser downsizes and compresses larger receipt/invoice images before submitting them. PDF documents and arbitrary URLs are not fetched by this route; paste extracted document text or upload a supported image. Browser speech recognition may use the browser vendor’s speech service; users can always paste a transcript.

## API

All routes require an approved individual account session and use same-origin credentials:

- `GET /api/agents`: role catalog and model configuration.
- `GET /api/agents/runs`: recent caller-owned runs.
- `POST /api/agents/runs`: run `{agentId,prompt,inputs,inboxId?,threadId?,history?,images?}`.
- `GET /api/agents/runs/:id`: read caller-owned run.
- `GET /api/agents/runs/:id/download`: download completed output.
- `POST /api/agents/runs/:id/draft`: explicitly save reviewed `{inboxId,to,subject,text}` as an unsent draft.

The workspace operates directly in the web service and does not require the automatic responder’s separate worker. Existing automatic replies retain their own configuration and lifecycle.

## Live voice and vision

Each role also offers a private CLAWD session powered by the supplied Vision-Agents framework, with xAI primary and configured OpenRouter alternatives. Choose voice only, voice with your camera, or voice with a screen you select, then explicitly start the session. Your selected role, task details, owned inbox context, and optional public Solana identifiers are fixed when it starts. Stop before starting with new context.

The custom CLAWD panel provides microphone and speaker controls, a chosen-view preview, typed questions, explicit view analysis, a transcript, and read-only research receipts. xAI `grok-voice-think-fast-2.0` handles speech and conversation. If native xAI speech is unavailable, OpenRouter `openai/gpt-audio-mini` processes bounded microphone turns and returns real synthesized audio in the same session. This alternative works one speech turn at a time. A safe mid-session switch clears queued audio, displays the actual provider/model, and asks for a fresh turn; partial speech or uncertain tool effects stop rather than replaying the question. `grok-4.7` analyzes sampled camera or screen frames when requested, with the configured OpenRouter vision model as a fallback. Showing a preview or connecting a socket alone does not establish an AI observation.

Sessions last up to ten minutes and stop after sixty seconds without input. One session can run per account. Concurrent capacity is returned by the server and shared across private agents and broadcast companions; production currently admits ten provider sessions, with fifty local slots available after verified provider capacity. The browser ends its capture tracks when you stop, change roles, leave the page, or lose account access. An uncertain server shutdown remains visible and offers Retry Stop. Each account receives one successful AI session per UTC day across both surfaces. Stop or disconnect after connection consumes that allowance; the next reset time is shown in the controls. See [Capacity and operations](CAPACITY.md).

Optional Solana tools read verified mainnet network state, public wallet holdings and recent signatures, transaction details, mint data, and configured market data. They cannot sign, submit, trade, launch, or pay. Receipts identify successful reads and unavailable providers separately. Selected-inbox tools remain limited to that account’s owned inbox.

Raw live media is not added to saved task history. The page holds its transcript until you leave or change roles; the server temporarily keeps up to forty transcript/observation entries and a stopped-session export for up to five minutes. Export the transcript or explicitly use it in a normal saved task when you want reusable output. Providers apply their own data policies. See [Vision-Agents operation](VISION-AGENTS.md) and [Privacy](PRIVACY.md).

The private endpoints require the same approved individual account session and current account terms:

- `GET /api/agents/realtime/config`: safe provider and framework readiness.
- `GET /api/agents/realtime/session`: the caller’s current session.
- `POST /api/agents/realtime/sessions`: start `{agentId,visionSource,prompt?,inputs?,inboxId?,threadId?,solanaContext?}`.
- `POST /api/agents/realtime/sessions/:id/stop`: stop with an empty `{}` body.
- `GET /api/agents/realtime/sessions/:id/transcript/download`: caller-owned temporary transcript export.
- `/api/agents/realtime/:id/bridge`: same-origin, account-bound WebSocket for the created session.