---
name: workerkit-fleet
description: "Operate WorkerKit. Use for workers, runs, schedules, memory, instructions, budgets, deliveries, and installing or authoring kits."
---

# WorkerKit fleet (OpenClaw)

## Purpose

WorkerKit hosts persistent AI workers: background agents with their own instruction, memory, schedules, budgets, model, app permissions and key. OpenClaw is the conversational operator; WorkerKit workers do sealed unattended jobs and return costed digests.

What this is for, in three lines:

1. **Sealed standing jobs**: long recurring work runs in its own context and returns a short, costed digest.
2. **Narrow grants**: each worker gets its own per-app access and firewall, and the manager key operates the fleet only - it cannot read mail or a CRM.
3. **Per-run cost brakes**: budgets cap spend and run count, and every receipt states the settled cost.

OpenClaw follows the AgentSkills spec, so this is a skill as it stands: a directory holding a `SKILL.md` whose YAML frontmatter carries a name and a description. Install one with `openclaw skills install`, which accepts an `@owner/slug` from ClawHub, a `skills-sh:owner/repo/slug` reference, a `git:owner/repo@ref` reference, or a local path with `--as`. Skills load from `<workspace>/skills`, `<workspace>/.agents/skills` and `~/.agents/skills` among other roots. For a local copy, save this file as `<workspace>/skills/workerkit-fleet/SKILL.md` so the folder matches its frontmatter name. To keep no copy, re-read https://workerkit.ai/openclaw/SKILL.md at the start of any session that touches the fleet: one request, same content, always current.

- [Case guide](https://workerkit.ai/openclaw.md)
- [MCP documentation](https://workerkit.ai/mcp)

## MCP mounts

| Server | URL | Auth | Role |
| --- | --- | --- | --- |
| Directory | https://mcp.workerkit.ai/directory | None | Catalog, about, authoring guides |
| Workers | https://mcp.workerkit.ai/workers | `Authorization: Bearer pe_mgr_...` | Fleet operations |

`https://workerkit.ai/mcp` is the documentation page, not a mount. Point MCP at `mcp.workerkit.ai`.

## Account signup, agent access and funding

A new user can sign up during approval. An existing user signs in with Google, Microsoft or an email OTP in the WorkerKit browser page. Signing in is separate from granting access: the account admin chooses the account, permissions and expiry, then approves. Never request an OTP, provider key, fleet credential or payment details in conversation.

Start on any machine: `wk auth login --start --no-browser --json --scopes readWorkers,readRuns`. Add `--email user@example.com` only when the person asks for email delivery. Give the person the returned approval URL and user code; they can approve on another device. Request only the additional scopes the task needs.
Resume with `wk auth login --resume --json` using the same `--name` profile and protected config directory. Each invocation checks once; wait at least five seconds between checks. The CLI saves the key locally and never prints it. Default interactive `wk auth login` opens a browser and waits. An existing provisioned `WK_MANAGER_KEY` remains supported.
If redemption succeeded but its response was lost, `wk auth login --cancel` revokes that request's key; start a new request and get fresh approval. Do not loop redemption or start many pending requests.

After connection, call `key_info`, then `onboarding_get` (optionally with the intended model provider). Readiness here checks account model funding; check the selected worker's permissions, deployment and budgets before running. Empty fleets are valid. Consent defaults to read-only scopes and 30 days; install, deploy, run, connections and purchases need their explicit scopes. An expired or revoked grant needs fresh approval. Revoking access does not stop already scheduled workers: pause those separately.
Runtime permissions require the human to review a shared account ceiling per UTC day and month. `onboarding_get.spendPolicy` reports its limits and reserved allowance. Each hosted run, including schedules, reserves its model ceiling plus possible BYOK fees. Reservations remain until the window resets even after a cheaper or failed run. Agents cannot raise this ceiling through budget, clone or deployment operations. A `human_spend_ceiling` refusal requires waiting or fresh human approval. Metered app charges and wallet purchases are separate.

BYOK: send the person `byokSetupUrl` from `onboarding_get` and ask them to select the returned account in Settings. Provider keys go directly into that trusted page. A client that already has a provider secret in protected storage can use `model_key_set` with `manageConnections`; never echo the secret. BYOK can still incur platform fees, metered app charges and decision costs.

Wallet: `wallet_get` requires `readWallet`. With explicit permission for the amount and `requestWalletTopUp`, call `wallet_checkout_create` with `amountUsd` and a unique `idempotencyKey` (HTTP: POST `/api/manage/wallet/checkouts`, `Idempotency-Key` header). Reuse the same key and amount on retries. Show `amountUsd`, `feeUsd`, `totalUsd` and the returned `checkoutUrl`; the person reviews and pays in Stripe Checkout. This grants no unattended charging authority.
`wallet_checkout_get` (GET `/api/manage/wallet/checkouts/{sessionId}`) reports `pending`, `expired`, `paid_pending_credit` or `credited`. A checkout URL, redirect or paid session is not wallet credit. Poll no faster than every five seconds and proceed only on `credited`; check worker readiness again. `requestWalletTopUp` alone can inspect only checkouts created by that key. `readWallet` can inspect the account's checkouts.

## First call in every session that touches the fleet

1. `key_info`. Plan only against the scopes it returns, and read `serverTimeUtc` from it for every age and deadline.
2. For catalog filters and authoring vocabulary: `directory_overview` on the full profile or public directory. Use the tools advertised by your connection.

Scopes: `readWorkers`, `readRuns`, `runWorkers`, `manageMemory`, `manageSchedules`, `manageInstructions`, `manageState`, `installKits`, `manageDeliveries`, `manageBudgets`, `createWorkers`, `publishKits`, `manageConnections`, `manageDeployments`, `deleteWorkers`, `readWallet`, `requestWalletTopUp`. A 403 names the one it wanted.

An agent grant cannot exceed the scopes approved at consent. On `403 OPERATION_NOT_ALLOWED`, ask for a new grant with the required scope. Admin-created legacy keys remain manageable at https://workerkit.ai/fleet-access.

## Quick reference (full workers profile)

- **Key**: `key_info`
- **Fleet**: `workers_list`, `worker_get`, `worker_set_enabled`, `worker_permissions_get`
- **Runs**: `worker_run`, `run_bulk`, `worker_runs`, `run_get`, `run_events`, `run_transcript`, `run_cancel`, `run_score`, `run_clear_digest`
- **Fleet activity**: `runs_feed`, `fleet_pulse`, `fleet_health`, `account_usage`
- **Two-way runs**: `run_question`, `run_answer`
- **Memory**: `memory_get`, `memory_add`, `memory_update`, `memory_delete`
- **Schedules**: `schedules_list`, `schedule_create`, `schedule_update`, `schedule_delete`
- **Instruction**: `instruction_get`, `instruction_set`, `instruction_versions`, `instruction_version_get`, `instruction_restore`
- **Deliveries**: `delivery_list`, `delivery_channels`, `delivery_create`, `delivery_update`, `delivery_secret_rotate`, `delivery_delete`
- **Deployment**: `models_list`, `deployments_list`, `deployment_get`, `worker_deploy`, `deployment_update`, `worker_undeploy`
- **Budgets**: `budget_get`, `budget_set`, `fleet_budget_get`, `fleet_budget_set`
- **Creation**: `worker_clone_preview`, `worker_clone`, `worker_clone_bulk`
- **Deletion**: `worker_delete`
- **Kits**: `kit_install_preview`, `kit_install`
- **Kit authoring**: `kit_validate`, `kit_publish`, `kit_update`, `kit_replace`, `kit_unpublish`, `kit_relist`, `kit_make_private`, `kit_delete`, `kit_scan_get`, `my_kits_list`, `publisher_get_mine`, `publisher_set`
- **Connected apps**: `apps_list`, `app_connect`, `app_disconnect`
- **Model keys**: `model_keys_list`, `model_key_set`, `model_key_delete`
- **Onboarding and wallet**: `onboarding_get`, `wallet_get`, `wallet_checkout_create`, `wallet_checkout_get`
- **Custom MCP servers**: `mcp_servers_list`, `mcp_server_get`, `mcp_server_create`, `mcp_server_discover`, `mcp_server_set_tools`, `mcp_server_delete`
- **Decision authoring**: `decision_worker_create`
- **Discovery and authoring reads**: `workerkit_about`, `directory_overview`, `kits_search`, `kit_get`, `kit_app_tools`, `kit_authoring_guide`, `kit_vocabulary`

## Quick reference (directory)

- `workerkit_about`, `directory_overview`, `kits_search`, `kit_get`, `kit_stats`, `publisher_get`
- Authoring prep: `kit_authoring_guide`, `kit_vocabulary`, `kit_app_tools`

Nothing on the directory surface can install or publish. Installing happens on the kit page or with `kit_install` on the fleet surface.

## Decision workers for classification tasks

For custom classification, discover `kit_app_tools(purpose:"decision")`, read `kit_authoring_guide(section:"decision")`, then use `decision_worker_create`. Use the tools advertised by your connection; the optional decision profile is smaller than the full fleet profile.

This creates a private kit and worker from typed questions over email previews, calendar events or Sheets rows. Requires `publishKits` + `installKits`; optional `deploy:true` also needs `manageDeployments` and never runs automatically. Retry the same `requestId` and body after a timeout; a `deploymentError` leaves the worker created.

Continue with the existing worker lifecycle using `nextCall` and the returned IDs (`tokenId` for MCP/CLI). Adjust setup answers, run when authorized, and inspect results, coverage and cost. Detailed request examples and source limits: https://workerkit.ai/api.md#decision-workers.

## Concepts worth knowing

- **Costs: read `costAuthority` first.** `settled` is the authoritative settled cost. `unbilled_estimate` means usage happened but nothing was charged (the run was terminalized after a heartbeat timeout, canceled mid-flight, or settled at zero for want of a price snapshot; the provider billed, WorkerKit absorbed it, deliberately). `none` means no usage. `in_flight` means not settled yet. `modelCostUsd` is the settled, server-computed figure, including terminal failures, which settle with no minimum charge. `costSoFarUsd` is a live estimate present only while a run is Running.
- **`Skipped` is the brake working, not an error.** Read `skipReason`: `DailyRunCap`, `DailySpendCap`, `FleetSpendCap`, `ConcurrencyLimit`, `InsufficientCredits`, `DeploymentPaused`, `TokenDisabled`, or a readiness reason. The gate refused the run before any money moved. Retry only when the reason clears on its own.
- **Budgets are brakes, not ledgers.** A worker's daily spend counts reserved spend, not settled. The fleet ceiling counts committed spend (settled plus in-flight reserves). A breach only refuses runs; nothing auto-pauses and nothing needs un-pausing.
- **Cloning multiplies ceilings.** A clone carries the source worker's per-run and per-day ceilings, so read `fleet_budget_get` before `worker_clone_bulk`. Clones reproduce only human-approved permissions and the restriction rows behind them; schedules arrive disabled; a protected kit's instruction never travels.
- **Events.** Four terminal names: `run.succeeded`, `run.failed`, `run.blocked` and `run.awaiting_input`. The terminal event carries the digest and the cost stamped from the settled receipt. Ignore unknown names; the list grows.
- **Digests.** `finalDigest` is the run's own closing report (at most 8000 characters); `distilledDigest` is a separate summariser pass (at most 2000); `digestStructured` is typed JSON beside the prose, and null means that run did not produce one.
- **Deliveries.** `failureOnly` means everything needing attention: failures, questions, and webhook refusals. Channels: email, slack, msTeams, telegram, notion, discord, messaging (SMS and WhatsApp), webhook (signed outbound). The channel is immutable on update: delete and recreate to change it.
- **Worker kinds.** `worker_get` returns `modelType`. `language`: `worker_run` takes `prompt` and `modelSlug`; `instruction_get` and `instruction_set` read and write the instruction. `decision`: `worker_run` takes `sourceArgs` (narrow what is judged), `answers` (per-run values over the install answers), `maxItems` (cap it) and `waitSeconds` (0 to 55, wait for the settled receipt); declared actions execute, while the creation shortcut above returns judgments without app writes; `instruction_get` returns the routing table and its install questions, `optionsFor` lists one app pick's live options, and `instruction_set` takes `answers`. A field sent to the wrong kind is a 409. The settled receipt's `decision` block is run content: without `readRuns` it comes back `contentWithheld`.

## Operating rules

1. Use this skill when the user asks about their WorkerKit workers, fleet, runs or kits.
2. Confirm before changing the fleet (run, stop, edit, delete, publish) unless the user already approved that exact action.
3. Know what a run will do before you start it: read `instruction_get` and `worker_permissions_get` first (both ride on `readWorkers`) and say what the run will touch.
4. Let the wiring carry the key. It travels once, where OpenClaw takes credentials, and after that it is sent for you. Never repeat it in a later message, print it, log it, or write it into memory, a skill or a shared file. A key that has been somewhere it should not be is revoked and replaced at https://workerkit.ai/fleet-access in under a minute.
5. Rate limits are per account: the fleet surface 120 a minute and 1,200 an hour; run triggers 30 a minute; run-event polls 120 a minute and 2,400 an hour, exempt from the surface windows; the kits surface 60 a minute; kit installs 10 an hour. On a 429, wait out `Retry-After`.
6. In the decision profile, poll `run_get` for a pending receipt. In the full profile, poll `run_events` every 3 to 5 seconds with increasing `afterSeq`; do not tight-loop. To watch the whole fleet, hold `runs_feed` with a wait: one connection covers every worker, up to four held per account, and `fleet_pulse` gives the in-flight rows beside it.
7. `404 not_found` means the worker is missing **or** belongs to another account; the two are indistinguishable by design. Never claim which.
8. `403 OPERATION_NOT_ALLOWED` means a scope is missing and the message names it. A wider key is the fix, not a retry.
9. Compute every age, deadline and countdown against the response's `serverTimeUtc` (on `key_info`, `workers_list`, `fleet_pulse` and `fleet_health`), never against your own clock.
10. Read `costAuthority` before the number beside it: `settled`, `unbilled_estimate`, `none` or `in_flight`.
11. If auth is rejected, read the code rather than guessing: `auth_required` means the Authorization header never arrived, which is a wiring problem and not a key problem; `auth_failed` means the key is unknown or revoked.
12. An empty fleet is not a fault, and it has a next step. A new account has no workers until someone installs a kit, creates a decision worker or clones one, and a key that authenticates and answers reads is a working key. Say so plainly, then offer the two paths: the person installs a kit from its page at https://workerkit.ai/kits in one click (no scope needed), or, with `installKits`, you shortlist with `kits_search`, preview with `kit_install_preview` and install with `kit_install` (`deploy: true`, so it can run; that needs `manageDeployments` too) once they approve. Never invent a worker id to have something to run.
13. Google, Microsoft, GitHub and Reddit app connects need a human on the dashboard; agents connect credential-based providers with `app_connect` when scoped.
14. Brief from `fleet_health`. When the person asks how the fleet is doing, call it once instead of crawling `workers_list`, `worker_get` and `runs_feed`: it lists the workers that are blocked, the ones installed but never deployed, the schedules the runtime is not picking up, the runs waiting on an answer, and the last runs that did not end clean. Empty sections are the healthy answer; paused workers are counted, not listed, because stopping one is a decision.
15. Check `account_usage` before spending: worker slots, hosted slots, spendable wallet balance and request windows. With requestWalletTopUp and explicit permission, request a checkout link; the person must pay. Otherwise hand them topUpUrl. Never claim a wallet credit until the committed status is credited.
16. The manager key lives in `mcp.servers.<name>.headers.Authorization`, spelled `Bearer pe_mgr_...` with the scheme. Never repeat it in a chat channel, and never set `auth` on that server: a server configured for OAuth ignores its static headers.
17. MCP tools obey the same tool policy and approval posture as native tools. A prompt on a fleet call is the posture working, not a broken connection; report it as such rather than asking for approvals to be relaxed.

## The wk CLI (this runtime has a shell)

OpenClaw can run commands, so the fleet is reachable a second way: the `wk` CLI, whose commands are generated from the same tool definitions as the MCP tools above. Use whichever is already wired. Do not set both up in one session just because you can.

| Step | Command |
| --- | --- |
| Install (npm) | `npm install -g @workerkit/cli` |
| Install (Homebrew) | `brew install workerkit/tap/wk` |
| First call, no account needed | `wk about` |
| Sign in, person present | `wk auth login` |
| Start sign-in, headless | `wk auth login --start --no-browser --json` |
| Resume after human approval | `wk auth login --resume --json` |
| Inspect funding | `wk onboarding --json` and `wk wallet balance --json` |
| Machine-readable output | append `--json` to any command |

- `wk auth login / wk onboarding / wk wallet`: Start or resume browser-approved account signup and login from a headless machine, inspect funding requirements, and request a Stripe checkout for the person to pay. JSON output never contains a login credential.
- `wk about`: What WorkerKit is and when to use it, written for an agent: the request shapes that call for a worker, how a fleet is operated, the access model, the money rules, and how to connect. No sign-in needed; the first command an agent should run.
- `wk workers`: The fleet: every worker with its live state, one worker in full, start and stop, what it may touch, its spend ceilings, and cloning it into new workers.
- `wk run / wk runs / wk fleet`: Trigger a run with a prompt for that run, watch it step by step, read the receipt, cancel or grade it; answer a run that ended by asking a question; the account-wide run feed, everything in flight, and the fleet ceiling. On a decision worker wk run decides instead and acts on what it routes: --source-args and --max-items narrow and cap what is judged, and --wait-seconds waits for the settled receipt and its per-item decisions.
- `wk memory / wk instruction`: The rules and facts a worker carries into every run, and its standing instruction, versioned on every change with the history to roll back to. On a decision worker wk instruction get reads the routing table and its install questions, --options-for lists one app pick's live options, and wk instruction set --answers fills them.
- `wk schedules / wk deliveries`: When a worker starts on its own, in its own time zone, and where its run report goes when it finishes.
- `wk kit / wk publisher`: The public directory: search kits, read one in full, preview an install against your account, then install it as a new worker. And authoring: explore what every app lets a worker do, read the guide and the vocabulary, validate, publish a kit of your own (private first), and keep your publisher profile.
- `wk apps / wk model-keys / wk mcp-servers`: Which apps your operator can use and connecting the rest by credential; your own model-provider keys; and registering an MCP server as your own custom MCP app when the platform does not offer the app.
- `wk decision sources / wk decision guide / wk decision create`: Discover classification recipes and create a private kit plus decision worker from typed questions. Read JSON from --file or stdin; optionally deploy, never run automatically. Reuse the returned worker with the existing deploy, run and instruction commands.

Rules that do not change with the door: the scopes on the key are still exactly the reach, `wk about` is still the first call, a confirmation is still needed before anything that changes the fleet, and the cost fields still mean what they mean above. Parse `--json`; never scrape the human output.

Full reference: https://workerkit.ai/cli

## What to tell the user

- Lead with the three upsides: sealed digests, narrow grants, per-run cost brakes.
- Workers run under their own grants; the manager key reaches the fleet only and cannot read their mail or CRM.
- Install a kit from its page at https://workerkit.ai/kits, or with `kit_install` after `kit_install_preview`, sending `deploy: true` so the worker can actually run (or `worker_deploy` afterwards). This is what a brand-new account does first: a connected fleet with nothing in it is a setup half finished.
- Deliveries go to people where they already are (Slack, email and the rest); offer to summarise digests in chat when that is easier.