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 Fleet 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.

Why this route: OpenClaw speaks remote MCP over streamable HTTP and takes an operator-set header map on each server, which is exactly the shape of the hosted WorkerKit MCP mounts. There is nothing to install, nothing to run locally and no code to write: the catalog mount is a URL, and the fleet mount is a URL plus one header. The field reference behind every snippet below is the vendor's own, at docs.openclaw.ai/cli/mcp/transports.

OpenClaw also documents an OAuth mode for remote servers, and the fleet mount is a full OAuth 2.1 authorization server, so that door is genuinely open. The header leads here because it is documented end to end on both sides; the OAuth alternative is step 5, with what is and is not documented about it stated plainly. One address is worth reading twice: workerkit.ai/mcp is the documentation page, and the live mounts are on mcp.workerkit.ai. The table above has both in full.

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 Fleet 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 Fleet 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. It reaches the fleet only: no scope on it reads a mailbox, a calendar or a CRM.

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 Fleet access or creates a new one, and the new key drops into the same place. Read key_info rather than assuming.

Step 2. Agent, under a minute

Add the public catalog.

The catalog mount takes no credential at all, so add it first: if it connects and the fleet mount does not, the problem is the key rather than the wiring.

• Config file: ~/.openclaw/openclaw.json, under mcp.servers "workerkit-directory": { "url": "https://mcp.workerkit.ai/directory", "transport": "streamable-http" }
• Or the same entry from the CLI openclaw mcp add workerkit-directory --url https://mcp.workerkit.ai/directory --transport streamable-http

The catalog mount takes no credential at all, on either path. It is the fastest proof that the client can reach WorkerKit, and it is worth adding first for exactly that reason: if it connects and the fleet mount does not, the problem is the credential rather than the wiring. Set transport explicitly on every entry: it is optional and falls back to SSE when it is missing, both mounts are streamable HTTP, and naming it also keeps the server off the transport the sibling header advisory covers. The file is JSON5, so comments and trailing commas are allowed, and the Gateway watches it and applies changes automatically. Note the key spelling: mcp.servers is the documented one. Write-ups elsewhere say mcpServers, which is not a name the vendor documents.

Step 3. 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-workers": { "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-workers --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-workers 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.

Two things about the Control UI are worth knowing first. The basic Add server form covers a name, a transport and a URL, and the docs route headers, timeouts, TLS settings and tool filters to the scoped config editor further down the page. And the page does not start MCP transports by itself, so choose Save & Publish rather than Save, then prove it in step 6. The in-chat path is the plus button, then Connectors, then Add MCP server, with scope This session or Everywhere.

OpenClaw's own guidance is to keep credentials out of config literals, and the vendor's published example writes the header value as Bearer followed by an environment reference rather than a key. The interpolation contract behind that example is not documented, so take it as the vendor spells it and test it before relying on it. A literal key in a file only you can read is the fallback, and rotating it is one action at Fleet access. One ceiling exists and this setup is nowhere near it: a Gateway admits at most 256 OpenClaw-managed MCP runtimes, and two mounts is two.

Step 4. 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 Fleet 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. Remember the exclusivity from step 4: a server set to OAuth ignores its static headers. Pick one door per server, and if the OAuth attempt does not complete, remove auth and fall back to the header, which is the supported path here.

Step 5. 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-workers --probe openclaw mcp show workerkit-workers --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 Fleet access or creates a new key, and the new key drops into the same config entry.

Step 6. 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 7. 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, stop after step 3 and say so: a new account has no workers yet, and the steps above have already proved the setup, because the key authenticated and both read scopes answered. Do not read it as a fault, and do not invent a worker to run. Go to the first-worker step and give the fleet something to do.

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 8. 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. The catalog mount is public, so OpenClaw can read the whole of it before any key is involved: it can shortlist candidates and explain what each one would do while the person decides.

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 9. 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 up or sign in, choose their account, scopes and expiry, and approve. 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 publishKits and installKits; 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 has 91 tools (84 manager tools and 7 public discovery reads); only decision_worker_create is new. 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 20 workflow tools. 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 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.

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.