Summary

• Problem: OpenClaw did not have a maintained World AgentKit path for protecting selected agent tool calls with World-backed human-in-the-loop approval.
• Why it matters: AgentKit users need a proof-of-human gate that works from the normal OpenClaw TUI/chat approval flow. Hosted demos can avoid local World signing keys when an operator explicitly configures a trusted broker.
• What changed: added the opt-in bundled agentkit plugin, World ID human approval mode, hosted/custom World approval configuration, AgentKit CLI/status/request helpers, proof-backed plugin approval resolution, TUI/chat/channel approval actions, docs, changelog, and focused tests.
• What did NOT change (scope boundary): AgentKit remains disabled by default, protected tools are explicitly configured, hosted broker URLs are explicit with no default OpenClaw remote endpoint, browser/web_fetch behavior is not capped by core logic, and generic plugin approvals cannot allow AgentKit World HITL requests unless AgentKit resolves them through the verified proof-backed path.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes N/A
• Related N/A
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: World AgentKit HITL blocks configured protected tools, renders a TUI/chat approval card with World QR/link actions, and only releases the pending tool call after World verification or denial.
• Real environment tested: macOS local checkout, isolated OpenClaw home/state, local hosted broker/signing setup kept outside the repo in a private folder, OpenAI model auth copied into the isolated test home.
• Exact steps or command run after this patch: ran the isolated hosted AgentKit HITL harness, started the gateway and TUI separately, asked the agent to access worldcoin/wld-android, approved the resulting exec request with World App, then repeated multiple pending exec requests to exercise allow-once, remaining-pending reminders, and allow-always session trust.
• Evidence after fix: copied live output below, redacted for approval IDs, World request IDs, QR/link contents, app/RP IDs, local token values, and signing-key paths.

Copied live TUI output (redacted):

openclaw tui - ws://127.0.0.1:19061 - agent agentkit-hosted-e2e (AgentKit hosted E2E)
session agent:agentkit-hosted-e2e:tui-<redacted>

can you please access worldcoin/wld-android repo and list the 2 top PRs?

🛡️ Plugin approval required
Title: World proof required for exec
Description: Verify with World before `exec` runs in this session. Use the approval actions below, or list pending requests with `/agentkit approvals`.
Tool: exec
Plugin: agentkit
Agent: agentkit-hosted-e2e
ID: plugin:<redacted>
Expires in: 600s
Reply with:
- /agentkit approve plugin:<redacted> allow-once
- /agentkit approve plugin:<redacted> allow-always
- /approve plugin:<redacted> deny

Verify with World
Approval: plugin:<redacted>
World request: <redacted>
Scope: this blocked action only.

Scan with World App:
<QR code rendered in the TUI>

Link:
https://world.org/verify?<redacted>

✅ Plugin approval allowed once. ID: plugin:<redacted>

World verification approved one `exec` request, but 1 more AgentKit approval is still pending for this session.
The agent turn will not finish until every blocked tool call is resolved.

Pending AgentKit approvals:
- plugin:<redacted>
  tool: exec
  title: World proof required for exec
  agent: agentkit-hosted-e2e
  session: agent:agentkit-hosted-e2e:tui-<redacted>
  expires in: 538s

Approve the remaining request, deny it, or use `Verify and trust for session` on a pending request to cover this tool for the session.

Copied live gateway output (redacted):

[gateway] http server listening (9 plugins: acpx, agentkit, bonjour, browser, device-pair, file-transfer, memory-core, phone-control, talk-voice; 2.0s)
[gateway] ready
[ws] ⇄ res ✓ agents.list 145ms conn=<redacted> id=<redacted>
[ws] ⇄ res ✓ plugin.approval.waitDecision 21233ms conn=<redacted> id=<redacted>
[ws] ⇄ res ✓ plugin.approval.waitDecision 18957ms conn=<redacted> id=<redacted>

• Observed result after fix: the protected tool stayed blocked until approval, denial did not require proof, allow-once did not persist a reusable grant, allow-always persisted the configured grant and resolved matching pending approvals, and retry prompts stayed actionable after failed/reused World sessions.
• What was not tested: a production-hosted shared OpenClaw World app operated by OpenClaw maintainers; the local hosted broker path was used as the current demo/test bridge.
• Before evidence (optional but encouraged): earlier local runs showed missing/invalid isolated auth, browser/keychain noise when browser/web_fetch was enabled in the test agent, stale pending approvals after multiple tool calls, and second matching approvals not being reprompted/resolved reliably.

Root Cause (if applicable)

• Root cause: OpenClaw had generic plugin approval plumbing, but no proof-owned approval resolution path for a plugin that must verify an external World proof before allowing a tool call. The first AgentKit pass also allowed some generic approval paths and multi-request flows to behave like ordinary approvals instead of proof-backed HITL.
• Missing detection / guardrail: there were no contract tests for plugin approval allowedDecisions, command-only approval actions, proof-backed plugin resolution, retryable chat/TUI approval payloads, matching pending approval cleanup after persistent trust, or hosted human-approval readiness without an explicit broker.
• Contributing context (if known): World ID's Node flow needs an IDKit WASM fetch compatibility shim, and bundled plugin runtime packaging needs root-owned runtime deps for internalized bundled plugins.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/agentkit/src/*.{test.ts}, src/gateway/server-methods/plugin-approval.test.ts, src/gateway/method-scopes.test.ts, src/plugin-sdk/approval-renderers.test.ts, channel approval renderer tests, and the isolated hosted human HITL harness.
• Scenario the test should lock in: AgentKit World HITL exposes only deny to generic approval surfaces, requires proof-backed plugin.approval.resolveVerified for allow decisions, renders command actions across TUI/chat/channel surfaces, keeps failed approvals retryable, requires explicit hosted broker configuration, and handles multiple pending matching tool calls reliably.
• Why this is the smallest reliable guardrail: the tests sit at the plugin, gateway approval, SDK renderer, and channel rendering seams that would regress independently.
• Existing test that already covers this (if any): none before this integration.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• New opt-in bundled agentkit plugin with World AgentKit registration/status/request/verifier CLI helpers.
• New configurable HITL mode can block configured protected tools until World-backed human approval succeeds.
• TUI/chat/channel approval cards can show plugin command actions such as Verify with World plus decision actions such as Deny.
• Hosted World approval broker mode requires an explicit hitl.humanApproval.brokerUrl; OpenClaw does not ship a default remote broker URL.
• Custom World app/RP/signing key remains configurable for self-hosted and enterprise approval paths.

Diagram (if applicable)

Before:
[protected tool call] -> [generic plugin approval] -> [ordinary allow/deny]

After:
[protected AgentKit tool call] -> [AgentKit approval card] -> [World QR/link] -> [proof-backed AgentKit resolveVerified] -> [tool runs]

Security Impact (required)

• New permissions/capabilities? (Yes/No) Yes.
• Secrets/tokens handling changed? (Yes/No) Yes.
• New/changed network calls? (Yes/No) Yes.
• Command/tool execution surface changed? (Yes/No) Yes.
• Data access scope changed? (Yes/No) No.
• If any Yes, explain risk + mitigation: AgentKit HITL is opt-in and only blocks explicitly configured protected tools. Generic approval clients can deny AgentKit requests but cannot allow proof-required requests unless the AgentKit plugin verifies World proof and calls the admin-scoped plugin.approval.resolveVerified method for its own plugin id. Hosted broker URLs are explicitly configured; OpenClaw no longer defaults to an OpenClaw-operated remote broker. Hosted mode sends only the derived World action, operator-facing description, TTL, and environment to the configured broker. Custom signing keys are config/env driven; no signing key or app secret is committed. IDKit file-fetch compatibility is scoped to IDKit's own WASM file and restores global fetch after use.

Repro + Verification

Environment

• OS: macOS local development machine.
• Runtime/container: Node 22, pnpm workspace, local OpenClaw checkout.
• Model/provider: OpenAI GPT-5.4 for the isolated TUI E2E exercise.
• Integration/channel (if any): OpenClaw TUI plus bundled AgentKit plugin.
• Relevant config (redacted): AgentKit hitl.mode: "human-approval", protected tool exec, explicit hosted broker URL, World app/RP ids, signing key file outside the repo, isolated OpenClaw home/state.

Steps

1. Enable bundled agentkit in an isolated OpenClaw config with hitl.enabled: true, hitl.mode: "human-approval", a protected tool such as exec, and an explicit hitl.humanApproval.brokerUrl.
2. Start the isolated gateway and TUI.
3. Ask the agent for a task that requires the protected tool.
4. Use the rendered AgentKit approval card QR/link to verify with World App.
5. Repeat with multiple pending protected tool calls and test allow-once, allow-always, and deny paths.

Expected

• Protected tool calls remain pending until World verification or denial.
• Generic approval allow is rejected for proof-required AgentKit approvals.
• Hosted mode is not ready until hitl.humanApproval.brokerUrl is configured.
• allow-once resolves only the current request and does not create a future grant.
• allow-always stores a scoped grant and resolves matching pending approvals.
• Failed World sessions leave an actionable retry prompt.

Actual

• Matches expected in the local isolated hosted HITL run.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Copied live output
• Screenshot/recording
• Perf numbers (if relevant)

Validation run on the rebased branch:

• pnpm docs:list passed.
• pnpm install completed after dependency updates.
• pnpm exec oxfmt --check --threads=1 $(git diff --name-only origin/main...HEAD | awk '{print $1}') passed on 108 files before the follow-up; after the follow-up, pnpm exec oxfmt --check --threads=1 extensions/agentkit/src/config.ts extensions/agentkit/src/status.test.ts extensions/agentkit/openclaw.plugin.json && git diff --check passed.
• pnpm config:docs:check passed after regenerating docs/.generated/config-baseline.sha256.
• pnpm deps:root-ownership:check passed.
• pnpm test extensions/agentkit/src/cli.test.ts extensions/agentkit/src/command.test.ts extensions/agentkit/src/hitl.test.ts extensions/agentkit/src/hitl-approvals.test.ts extensions/agentkit/src/human-approval.test.ts extensions/agentkit/src/human-approval-background.test.ts extensions/agentkit/src/protected-request.test.ts extensions/agentkit/src/status.test.ts extensions/agentkit/src/world-id.runtime.test.ts extensions/telegram/src/approval-handler.runtime.test.ts extensions/qqbot/src/bridge/approval/handler-runtime.test.ts extensions/matrix/src/approval-handler.runtime.test.ts src/gateway/server-methods/plugin-approval.test.ts src/gateway/method-scopes.test.ts src/gateway/server-methods/chat.directive-tags.test.ts src/plugin-sdk/approval-renderers.test.ts src/media/qr-terminal.test.ts -- --reporter=verbose passed 7 Vitest shards / 219 tests.
• pnpm build passed.
• Dist smoke passed before the follow-up: built dist/extensions/agentkit/index.js imports, shared SDK QR renderer works, @worldcoin/idkit-core resolves, IDKit WASM exists, and request-signing exports are present.
• OPENCLAW_LOCAL_CHECK=1 OPENCLAW_LOCAL_CHECK_MODE=throttled pnpm check:changed currently fails on an upstream-main Google Chat type error: extensions/googlechat/src/channel.ts(39,8): error TS2724: "./channel.deps.runtime.js" has no exported member named 'ChannelMessageActionName'. Proof this PR does not touch the failing files: git diff --exit-code origin/main -- extensions/googlechat/src/channel.ts extensions/googlechat/src/channel.deps.runtime.ts exits cleanly.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: isolated gateway/TUI AgentKit HITL prompt, World QR/link rendering, World App approval, proof-backed allow, deny without proof, failed/retry prompt behavior, multiple pending approvals, allow-once no persistent grant, allow-always scoped grant and sibling pending approval resolution.
• Edge cases checked: missing/invalid isolated model auth, hosted broker signature flow, explicit hosted broker readiness, custom signing key config errors, IDKit WASM fetch restoration, x402 challenge envelope support, Matrix/Telegram/QQ plugin command action rendering, and generic approval decision restrictions.
• What you did not verify: maintainer-operated production OpenClaw-hosted World app/broker, because this PR only includes the configurable client-side integration and local/private hosted test setup.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes.
• Config/env changes? (Yes/No) Yes, new optional plugins.entries.agentkit.config fields.
• Migration needed? (Yes/No) No.
• If yes, exact upgrade steps: N/A. AgentKit is disabled by default; users opt in by enabling the plugin, configuring protected tools, and choosing either explicit hosted broker URL or custom World credentials for human approval mode.

Risks and Mitigations

• Risk: A generic approval client could accidentally allow a proof-required AgentKit request.
  • Mitigation: AgentKit requests expose only deny to generic decisions; allow decisions require AgentKit-owned resolveVerified after World proof.
• Risk: Hosted World approval introduces operator trust and availability considerations.
  • Mitigation: hosted mode is explicit/configurable, custom app/RP/signing key remains supported, no default remote broker URL is shipped, and no secrets are committed.
• Risk: Plugin approval action payloads may render differently across channels.
  • Mitigation: SDK renderer plus Matrix, Telegram, QQ, TUI/chat tests cover command actions and allowed decisions.