Set up WorkerKit in OpenClaw.

Before you start

What you need.

A running OpenClaw Gateway on a machine you control, on Node 24.16 or later or Node 26.1 or later. Node 22, 23 and 25 are unsupported, and a Gateway that will not start after an upgrade is usually this rather than the config.

An OpenClaw build of 2026.5.12 or later, where the custom-header redirect advisory was fixed. Step 1 is the upgrade, and running it is quicker than establishing which build you are on.

A WorkerKit account, and admin access on it: creating a manager key is an admin-only action at AI access. The Free plan is enough, and no card is needed.

About a minute of the human's time. OpenClaw does everything except creating the key.

OpenClaw connects directly to the hosted WorkerKit MCP endpoint over streamable HTTP. Add the URL and Authorization header using OpenClaw's transport reference at docs.openclaw.ai/cli/mcp/transports.

This guide uses a bearer header; the OAuth alternative is described below. Use the WorkerKit MCP address above. workerkit.ai/mcp is the documentation page.

The case for connecting at all is on the OpenClaw page.

Step 0. Human, about a minute

Upgrade the Gateway before you hand it a key.

A bearer header on a remote MCP server is exactly the shape one OpenClaw advisory covered, so bring the Gateway up to date before the key exists.

Advisory GHSA-rjxq-qqhf-8hwh (CVE-2026-53840), rated CVSS 7.1, described operator-configured custom MCP headers being forwarded on a cross-origin redirect from the MCP endpoint. OSV records it fixed in 2026.5.12, so that is the floor for this setup: a credential is what was at stake, not a feature. Run the upgrade for whichever way OpenClaw was installed rather than working out which build is on the machine, since the vendor documents the install and upgrade commands and no version check. And if a bearer key was already configured on an older build, rotate it after upgrading rather than reusing it, which is one action at AI access and drops the new key into the same config entry.

• Upgrade: macOS, Linux or WSL2, then Windows PowerShell, then npm on any of them curl -fsSL https://openclaw.ai/install.sh | bash iwr -useb https://openclaw.ai/install.ps1 | iex npm install -g openclaw@latest --allow-scripts=openclaw

Step 1. Human, about 60 seconds

Create the manager key.

The key is the whole of the authentication on this door, so it comes first. Its scopes are exactly what OpenClaw will be able to do.

1. 01

   Sign in as the account that owns the fleet

   At workerkit.ai. Someone who belongs to several accounts confirms the active one first: a key created in the wrong account shows up later as an empty fleet, and checking now saves that round trip.

2. 02

   Open AI access

   workerkit.ai/fleet-access is an admin-only page. A member sees a notice saying so rather than a broken page.

3. 03

   Create a manager key named for its purpose

   Name it for the assistant that will hold it. A purpose-specific name makes the key easy to audit, and easy to revoke later without touching anything else.

4. 04

   Pick its scopes

   The tables below say what each one grants. Start with the reads and add only the scopes needed for the approved task. Choose an expiry and request fresh approval when more access is needed.

5. 05

   Copy the key once

   It is shown at creation and never again, so keep it to hand for the wiring step. No scope gives it app credentials, but invokeActions returns an Action worker's tool results, so grant it only where an agent should call those tools.

A client that cannot run an OAuth flow takes the same fleet on one header instead. An account admin creates a key at https://workerkit.ai/fleet-access, copies it once, and it becomes the value of an Authorization header on the fleet mount. That header is the whole of the authentication: there is nothing to register and nothing to pre-approve.

A key carries the scopes it was granted when it was created. Granting a scope later never reaches an existing key: if a call answers 403 OPERATION_NOT_ALLOWED, an admin re-scopes the key at AI access or creates a new one, and the new key drops into the same place. Read key_info rather than assuming.

Step 2. Agent

Add the fleet mount with one header.

The same entry plus one pair in the optional headers map. That header is the whole of the authentication: there is nothing to register and nothing to pre-approve.

• Config file: the documented form, alongside the first server "workerkit": { "url": "https://mcp.workerkit.ai/workers", "transport": "streamable-http", "headers": { "Authorization": "Bearer pe_mgr_..." } }
• CLI: the --header flag is documented and repeatable, but the vendor documents no value syntax for it. Read the command's own help before using it, or write the config form above, which is the shape the docs do spell out openclaw mcp add --help openclaw mcp add workerkit --url https://mcp.workerkit.ai/workers --transport streamable-http --header <the form the help above gives>
• Control UI: Settings, then MCP /settings/mcp > Configured servers > Add server Name: workerkit Transport: Streamable HTTP URL: https://mcp.workerkit.ai/workers Header: the scoped config editor further down the same page Then: Save & Publish

The header value is spelled Authorization: Bearer pe_mgr_..., with the word Bearer and the space; a bare key arrives with no scheme and is refused. Do not set auth on this server: a server configured for OAuth ignores static Authorization headers, so the two are mutually exclusive per server rather than stackable, and setting both leaves a header that is silently doing nothing.

In the Control UI, use the scoped config editor for headers and advanced settings. Choose Save & Publish to start the connection, then run the connection checks below. From chat, use the plus button > Connectors > Add MCP server and choose This session or Everywhere.

OpenClaw recommends an environment reference for the bearer key. Follow its published syntax and test it: the interpolation contract is not documented. If you use a literal key, keep the config private and rotate the key at AI access when needed.

Step 3. Human, optional

Or connect without holding a key.

OpenClaw documents an OAuth mode for remote servers, and the fleet mount is an OAuth 2.1 authorization server. Take this path only if you would rather no key sat in your config.

What is documented on both sides: OpenClaw accepts auth set to oauth on a remote server, with openclaw mcp login <name> as the step that completes it, and the WorkerKit fleet mount publishes OAuth discovery, accepts dynamic client registration and runs authorization-code with PKCE. What is not documented is whether OpenClaw registers itself with a server it has not seen before, so this path is offered rather than walked. If it connects, the person experience is the one below.

1. 01

   Give the client the URL and nothing else

   The fleet mount publishes OAuth discovery, so a client that supports it finds the authorization server on its own and registers itself. There is no client ID to create, no secret to store and no redirect address to register in advance.

2. 02

   Approve on the WorkerKit consent page

   The client sends the person to https://workerkit.ai/mcpauth. Signing in there is what proves who is connecting; nothing is typed into the assistant.

3. 03

   An account admin picks the key the client will hold

   The consent page lists the account's manager keys and can create one on the spot, so a first connect needs no visit to AI access beforehand. It is admin-only on the server, not just in the page: a member sees an honest notice rather than a broken screen.

4. 04

   Scopes are chosen with the key, and are the whole of the reach

   Whatever that key carries is exactly what the assistant can do, and nothing on it reaches a connected app. Narrow it now or widen it later; a new key drops into the same connection.

Nothing is pasted into the chat on this path, which is its real advantage: the credential never passes through a message, a log or a screenshot, and revoking it later is one action in the dashboard rather than an edit inside the assistant. OAuth ignores static Authorization headers. If OAuth fails, remove auth and use the bearer-header setup above.

Step 4. Agent

Prove it starts, then read the key.

Saving a server is not the same as running one. Probe the transport first, then ask the key what it is allowed to do.

• 1. Live proof the server starts and lists tools, then what OpenClaw actually saved openclaw mcp doctor workerkit --probe openclaw mcp show workerkit --json openclaw mcp status --verbose
• 2. Ask the key what it can do (no arguments) key_info

openclaw mcp doctor --probe is the verification the vendor names, because a saved server is only a config entry until a transport starts. openclaw mcp reload refreshes the runtime if an edit has not been picked up, and mcp show --json settles any argument about whether a header was written where you think it was. Then key_info returns the account title, the key name, the scopes and expiry, and serverTimeUtc; any valid key may ask. Confirm the scope list matches what was granted, and plan against what it returns rather than what was intended. If something is missing, an admin re-scopes at AI access or creates a new key, and the new key drops into the same config entry.

Step 5. Agent

Install the WorkerKit skill.

OpenClaw follows the AgentSkills spec, so the skill file is installable as it stands rather than pasted into instructions.

• Put the file in a directory of its own, then install that directory mkdir -p workerkit-fleet curl -fsSL https://workerkit.ai/openclaw/SKILL.md -o workerkit-fleet/SKILL.md openclaw skills install ./workerkit-fleet --as workerkit-fleet

A skill is a directory containing a SKILL.md whose YAML frontmatter carries at minimum a name and a description, and the description is what decides whether the skill is loaded at all. The file above is already that, so the directory is the only thing to make. openclaw skills install also accepts an @owner/slug from ClawHub, a skills-sh:owner/repo/slug reference and a git:owner/repo@ref reference, which are the forms to use if you mirror this file into a repository of your own. Skills load from <workspace>/skills, <workspace>/.agents/skills and ~/.agents/skills among other roots, in that order of precedence.

If you would rather keep no copy, fetch https://workerkit.ai/openclaw/SKILL.md at the start of any session that touches the fleet and read it before the first call: one request, same content, always the current version.

Step 6. Agent

Run the smoke test.

List the fleet and read recent runs, which alone prove the setup. If the account has workers, read one before running it, run it with approval, and report the receipt.

If the fleet is empty after workers_list and runs_feed, the connection is working. New accounts have no workers yet. Skip the run commands and continue to the first-worker step.

If the fleet has workers, pick one whose effects are reads. Judge it from the instruction and the permissions, never from the name: a worker whose apps are all read-level and whose instruction only gathers, summarises or reports is safe to run; one that sends, posts, writes, orders or pays is not, whatever it is called. If none is clearly read-only, run one with an explicit prompt for that run bounding it to a read.

• 1. The directory is alive: confirm a kit count comes back directory_overview
• 2. The fleet list: report how many workers the assistant can see workers_list
• 3. Recent runs across the fleet: confirms readRuns runs_feed { "limit": 5 }
• 4. Before running anything, read what that worker does and what it may touch. Both ride on readWorkers, and this is the step that decides whether the run is safe instruction_get worker_permissions_get
• 5. Run it with the person's approval, then poll every 3 to 5 seconds until a terminal event arrives: run.succeeded, run.failed, run.blocked or run.awaiting_input worker_run run_events { "afterSeq": <lastSeq> }
• 6. Read the receipt: costAuthority first, then modelCostUsd run_get

Read costAuthority first, then modelCostUsd beside it, and report both. A null finalDigest is not a failure: a run produces one only when its harness wrote a report. A costAuthority of unbilled_estimate, none or in_flight is not a failure either; it says how far to trust the number, and the operating rules below say what each value means. A Skipped run is also a pass, and it is the cost brake working: the gate refused the run before any money moved. Report the skipReason rather than retrying. Then report the fleet size, the active scopes, and what the test cost, and the fleet is live. If every call stops for an approval prompt, that is the session permission posture rather than a connection fault: the guarded and read-only postures can prompt the operator for unannotated tools.

Step 7. Human and agent

Give the fleet its first worker.

A new account starts empty. Install a kit from its page in one click, or preview and install one with kit_install_preview and kit_install once the person approves.

A new WorkerKit account starts with no workers, so the last step of setup is getting one. A kit is a ready-made worker: its instruction, its exact app permissions and its schedule, written and reviewed in advance, so installing one is how a fleet usually starts rather than a shortcut. There are two paths, and either ends with something to operate. OpenClaw can search kits through WorkerKit and explain their requirements before installation.

1. 01

   The one-click path: install a kit from its page

   Browse the catalog at workerkit.ai/kits, open a kit whose job you recognise, and install it. It arrives pre-instructed, pre-permissioned and pre-scheduled, and asks for whatever it needs to connect. This path needs no scope on the manager key at all, so it works on the first session whatever the key can do.

2. 02

   The agent path: shortlist, preview, approve, install

   With installKits on the key, the assistant can do the whole thing in chat: shortlist with kits_search, read the candidate with kit_get, then call kit_install_preview to surface its setup questions and exactly what the new worker would be allowed to touch. Put that in front of the person in plain words, and call kit_install once they approve, with deploy set to true so the new worker is actually able to run (that half needs manageDeployments on the key; without it the worker is installed but inert until worker_deploy). The new worker's key is shown once in the response.

3. 03

   Then run it once and read the receipt

   A worker earns its place on the first run. Trigger it with worker_run, follow run_events until a terminal event arrives, and report the digest and the settled cost from run_get. Set a schedule with schedule_create when the person is happy with what it did, and the fleet is not just connected, it is working.

Step 8. Agent, optional

The second door: the wk CLI.

OpenClaw runs on your own hardware and carries terminal tools, so the same fleet is reachable by running commands as well as by speaking MCP. Either door is complete; wire the one this runtime is already holding.

The commands are generated from the same tool definitions the MCP server serves to agents, so the CLI is not a cut-down view of the fleet: what an agent can do over MCP, a shell can do. Which one a runtime reaches for is a question of what it is already holding, not of what it can reach.

1. 01

   The catalog needs no account at all

   wk about, wk kit search and the rest of the directory side read the public catalog exactly as a visitor does. Run wk about first in any session: it is what WorkerKit is and when to use it, written for an agent, and it needs no key.

2. 02

   Headless: put a manager key in the environment

   An account admin creates a key at https://workerkit.ai/fleet-access and it travels as the WK_MANAGER_KEY environment variable, which is the path written for scripts and agents. It touches no profile and no keychain, so a container or a restarted process picks it up from its own environment rather than from state on a disk.

3. 03

   Start headless, approve on any device

   wk auth login --start --no-browser --json returns an approval URL and code. Add --email when the person requests email delivery. They sign in with an existing account or an invitation, choose their account, scopes and expiry, and approve. New users without an invitation join the waitlist at workerkit.ai/waitlist. Run wk auth login --resume --json after at least five seconds to collect the approved key into local credential storage. No raw key appears in output. Interactive wk auth login opens a browser and waits.

4. 04

   Read the output as data

   --json is a stable machine contract rather than a pretty-printer, --plain strips the chrome for a narrow terminal, and exit codes are documented. Parse --json; never scrape the human output, which is free to change.

• npm npm install -g @workerkit/cli
• Homebrew brew install workerkit/tap/wk

Nothing above changes on this path. The scopes on the key are still exactly the reach, an approval is still needed before anything that alters the fleet, and the cost fields still mean what they mean. What changes is only where the call is made from.

The full command reference is the wk CLI page.

Classification on demand

Create a decision worker from your questions.

Categorize, score or triage connected data, then reuse and adjust the worker.

Reuse an existing worker or decision kit when its questions fit. For a custom classification task, creation compiles a supported source recipe and typed questions into a private kit and an installed decision worker. Optional deploy:true adds deployment; creation never starts a run or adds a schedule. The kit can be edited and published later through the normal kit lifecycle.

On the workers connection, call kit_app_tools(purpose:"decision") for recipes, argument schemas, permissions and examples, then kit_authoring_guide(section:"decision"). Check account connections with apps_list; public discovery does not check them. Send the request to decision_worker_create, follow nextCall, then use worker_run and run_get. Running needs runWorkers; results need readRuns. Use instruction_get / instruction_set for saved category or level answers, or answers on one run. Structural question/source changes need a revised kit and a replacement install. Check receipt status, coverage, omissions, warnings and cost before claiming completion.

Start with email-previews, calendar-events or sheets-rows. These recipes return judgments without app writes. Email previews do not include full threads; calendar events are invitation data, not transcripts; Sheets needs a Google file ID, a finite tab-qualified range and a columns map. A connected app alone does not make every tool a supported source. Source filters select evidence, not permissions: the Sheets recipe grants spreadsheet reads across the linked Drive account.

Supply 1–8 questions: choice with named options, score with ordered levels, or noul for the probability of a statement. Choice adds unclear automatically. Set an explicit confidenceFloor between 0 and 1; it routes uncertainty and does not promise accuracy. maxItems is 1–50, default 20. Creation requires createWorkers; optional deployment also needs manageDeployments.

Use a fresh requestId for each new worker. Retry with the same ID and identical body to recover the original receipt; a changed body returns 409. The response includes tokenId for MCP/CLI worker commands, stable workerId, kitSlug, readiness and nextCall. A deploymentError means the worker already exists: fix deployment on that worker. The receipt is a snapshot; check current worker readiness before running. No worker API secret is returned.

The workers connection includes discovery and authoring, so classification needs one MCP connection. Its full profile includes fleet management, app resource discovery, kit authoring and public directory reads. For a smaller list, a client that supports custom headers can send X-WorkerKit-Profile: decision on every request, including initialization, listing and calls, to select the smaller workflow tool set. A server operator can instead set MCP_WORKERS_PROFILE=decision. The endpoint and existing sign-in stay the same; a profile grants no additional permissions. Reconnect and relist after changing profiles. Use the advertised tool list: fleet administration, publishing, Action worker and event-stream tools require the full profile. Successful responses include structured content and a text fallback; creation declares an output schema.

Read the request example and full contract.

App tools, no model

Call app tools through an Action worker.

One exact app operation per call, with the inputs you supply.

An Action worker (modelType: "none") exposes 1 to 64 selected app tools and has no model, instruction, schedule or deployment. Each call invokes one tool with the arguments the caller sends, under the worker's own app access, and readiness.canInvoke on worker_get says whether its tools can be called now. Run and deploy requests answer 400 action_worker_requires_invoke.

On the workers connection's full profile: action_worker_options lists apps with no tools selected; pass an explicit app for schemas and defaults (readWorkers). action_worker_create requires an explicit app or actionSpec and copies the selected app's default tools, or takes an actionSpec of 1 to 64, plus a slackConnectionId for Slack tools when the account has more than one Slack bot (createWorkers); worker_tools lists the saved tools (readWorkers); worker_tool_call calls one with arguments, plus an idempotencyKey on a write (invokeActions); worker_tool_invocation reads a write's receipt (invokeActions). Pass the returned tokenId. kits_search(modelType:"none") finds Action kits; install one with kit_install and no deploy.

An explicit actionSpec needs no app and can span native or reviewed MCP apps. Private API tools require a dashboard binding to a published version; they are not actionSpec refs.

A write tool (readOnly: false) needs an idempotency key. Repeating the key with the same arguments returns the stored receipt (a confirmation, not the app's response) without calling the app again; with other arguments it is a 409. A call answers with status succeeded, denied, failed, in_progress or outcome_unknown; branch on it, not on the HTTP code. On outcome_unknown the write may have happened: never resend it automatically, under any key; read the receipt and check the app. Each call counts toward the worker's daily request limit; a refusal marked retryable, such as usage_limit, is retried later under a new key. Only the owner changes the selected tools, in the dashboard.

Read the call examples.

Least privilege

What each scope grants.

The key's scopes are exactly its reach, and a refusal names the scope it wanted. Start with the reads and add scopes as the work asks for them.

Operating rules

What the agent follows on every call.

The same rules the skill file carries, so a session that read neither still has them. Every row is a fact of the platform, not advice.

Quick answers

Symptoms, causes, fixes.

Each WorkerKit failure names itself in the response, so an agent never has to guess which one it met: read the code, apply the row, and carry on.