openclaw - ✅(Solved) Fix Gateway RPC: add SDK-facing tools.invoke [3 pull requests, 2 comments, 3 participants]

BunsDev · 2026-04-30T00:59:30Z

[openclaw] PR 74786: feat gateway : add SDK tools.invoke RPC - Repository: openclaw/openclaw - Author: gazeatcode - State: open | merged: False - Link: https:/… # PR #74786: feat(gateway): add SDK tools.invoke RPC - Repository: openclaw/openclaw - Author: gazeatcode - State: open | merged: False - Link: https://github.com/openclaw/openclaw/pull/74786 ## Description (problem / solution / changelog) ## Summary - Problem: `@openclaw/sdk` exposes `oc.tools.invoke()` as an unsupported scaffold while the Gateway only supports direct tool invocation through HTTP `/tools/invoke`. - Why it matters: SDK clients need a protocol-defined tool invocation path that preserves Gateway policy, owner-only filtering, and plugin approval semantics. - What changed: added `tools.invoke` protocol schemas, method registration/scope, a Gateway handler, shared direct-tool invocation core reused by HTTP, SDK typing/client support, docs, changelog, and targeted tests. - What did NOT change (scope boundary): did not broaden HTTP auth behavior, did not bypass existing tool policies, and did not allow high-risk direct tools unless the existing `gateway.tools.allow` path permits them. ## Change Type (select all) - [ ] Bug fix - [x] Feature - [x] Refactor required for the fix - [x] Docs - [x] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [x] Gateway / orchestration - [x] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [x] API / contracts - [x] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes #74705 - Related # - [ ] This PR fixes a bug or regression ## Root Cause (if applicable) - Root cause: N/A - Missing detection / guardrail: N/A - Contributing context (if known): the SDK had an unsupported `oc.tools.invoke()` placeholder and the existing direct invocation implementation lived only in the HTTP route. ## Regression Test Plan (if applicable) - Coverage level that should have caught this: - [x] Unit test - [x] Seam / integration test - [x] End-to-end test - [ ] Existing coverage already sufficient - Target test or file: `packages/sdk/src/index.test.ts`, `src/gateway/server-methods/tools-invoke.test.ts`, `src/gateway/protocol/index.test.ts`, `src/gateway/method-scopes.test.ts`, `src/gateway/tools-invoke-http.test.ts`, `src/agents/pi-tools.before-tool-call.e2e.test.ts` - Scenario the test should lock in: SDK calls `tools.invoke`, Gateway validates the params/result contract, method scopes require operator write, direct invoke still uses Gateway allow/deny filtering, and plugin approvals can return typed approval-required state without waiting when `confirm: true` is omitted. - Why this is the smallest reliable guardrail: these tests cover the SDK client seam, protocol validation, handler mapping, shared HTTP behavior, and plugin approval mode without broad end-to-end tool execution setup. - Existing test that already covers this (if any): existing HTTP direct invocation tests covered `/tools/invoke`; this PR extends that path through the shared core. - If no new test is added, why not: N/A ## User-visible / Behavior Changes SDK clients can call `oc.tools.invoke("tool-name", { args, sessionKey, agentId, confirm, idempotencyKey })`. Without `confirm: true`, plugin approval requests return a typed `{ ok: false, requiresApproval: true, approvalId, error }` result instead of waiting for approval and executing. ## Diagram (if applicable) ```text Before: SDK -> oc.tools.invoke() -> unsupported error HTTP -> /tools/invoke -> direct tool invoke path After: SDK -> tools.invoke RPC -> shared direct tool invoke core -> policy/hooks/approval/tool HTTP -> /tools/invoke -> shared direct tool invoke core -> policy/hooks/approval/tool ``` ## Security Impact (required) - New permissions/capabilities? (`Yes/No`) Yes - Secrets/tokens handling changed? (`Yes/No`) No - New/changed network calls? (`Yes/No`) No - Command/tool execution surface changed? (`Yes/No`) Yes - Data access scope changed? (`Yes/No`) Yes - If any `Yes`, explain risk + mitigation: this adds a direct tool invocation RPC, so the handler requires `operator.write`, treats only `operator.admin` callers as owner for owner-only tools, reuses the same direct-invocation Gateway tool allow/deny filtering as HTTP `/tools/invoke`, runs the existing before-tool-call/plugin approval pipeline, and returns typed approval-required results when callers omit `confirm: true`. ## Repro + Verification ### Environment - OS: Linux - Runtime/container: Node 22 + pnpm - Model/provider: N/A - Integration/channel (if any): Gateway RPC / SDK - Relevant config (redacted): default test config ### Steps 1. Call `oc.tools.invoke("demo", { args: { input: "hello" } })` from the SDK. 2. Call Gateway `tools.invoke` with `{ name, args, sessionKey, agentId, confirm }`. 3. Exercise a plugin approval request without `confirm: true`. ### Expected - SDK sends `tools.invoke` RPC params. - Gateway validates params, resolves the scoped tool through normal policy, a

openclaw2026-04-30 00:59:30

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#74705•Fetched 2026-04-30 06:20:59

View on GitHub

Comments

Participants

Timeline

Reactions

Author

Participants

Timeline (top)

cross-referenced ×4commented ×2mentioned ×1subscribed ×1

PR fix notes

PR #74786: feat(gateway): add SDK tools.invoke RPC

Repository: openclaw/openclaw
Author: gazeatcode
State: open | merged: False
Link: https://github.com/openclaw/openclaw/pull/74786

Description (problem / solution / changelog)

Summary

Problem: @openclaw/sdk exposes oc.tools.invoke() as an unsupported scaffold while the Gateway only supports direct tool invocation through HTTP /tools/invoke.
Why it matters: SDK clients need a protocol-defined tool invocation path that preserves Gateway policy, owner-only filtering, and plugin approval semantics.
What changed: added tools.invoke protocol schemas, method registration/scope, a Gateway handler, shared direct-tool invocation core reused by HTTP, SDK typing/client support, docs, changelog, and targeted tests.
What did NOT change (scope boundary): did not broaden HTTP auth behavior, did not bypass existing tool policies, and did not allow high-risk direct tools unless the existing gateway.tools.allow path permits them.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #74705
Related #
This PR fixes a bug or regression

Root Cause (if applicable)

Root cause: N/A
Missing detection / guardrail: N/A
Contributing context (if known): the SDK had an unsupported oc.tools.invoke() placeholder and the existing direct invocation implementation lived only in the HTTP route.

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: packages/sdk/src/index.test.ts, src/gateway/server-methods/tools-invoke.test.ts, src/gateway/protocol/index.test.ts, src/gateway/method-scopes.test.ts, src/gateway/tools-invoke-http.test.ts, src/agents/pi-tools.before-tool-call.e2e.test.ts
Scenario the test should lock in: SDK calls tools.invoke, Gateway validates the params/result contract, method scopes require operator write, direct invoke still uses Gateway allow/deny filtering, and plugin approvals can return typed approval-required state without waiting when confirm: true is omitted.
Why this is the smallest reliable guardrail: these tests cover the SDK client seam, protocol validation, handler mapping, shared HTTP behavior, and plugin approval mode without broad end-to-end tool execution setup.
Existing test that already covers this (if any): existing HTTP direct invocation tests covered /tools/invoke; this PR extends that path through the shared core.
If no new test is added, why not: N/A

User-visible / Behavior Changes

SDK clients can call oc.tools.invoke("tool-name", { args, sessionKey, agentId, confirm, idempotencyKey }). Without confirm: true, plugin approval requests return a typed { ok: false, requiresApproval: true, approvalId, error } result instead of waiting for approval and executing.

Diagram (if applicable)

Before:
SDK -> oc.tools.invoke() -> unsupported error
HTTP -> /tools/invoke -> direct tool invoke path

After:
SDK -> tools.invoke RPC -> shared direct tool invoke core -> policy/hooks/approval/tool
HTTP -> /tools/invoke -> shared direct tool invoke core -> policy/hooks/approval/tool

Security Impact (required)

New permissions/capabilities? (Yes/No) Yes
Secrets/tokens handling changed? (Yes/No) No
New/changed network calls? (Yes/No) No
Command/tool execution surface changed? (Yes/No) Yes
Data access scope changed? (Yes/No) Yes
If any Yes, explain risk + mitigation: this adds a direct tool invocation RPC, so the handler requires operator.write, treats only operator.admin callers as owner for owner-only tools, reuses the same direct-invocation Gateway tool allow/deny filtering as HTTP /tools/invoke, runs the existing before-tool-call/plugin approval pipeline, and returns typed approval-required results when callers omit confirm: true.

Repro + Verification

Environment

OS: Linux
Runtime/container: Node 22 + pnpm
Model/provider: N/A
Integration/channel (if any): Gateway RPC / SDK
Relevant config (redacted): default test config

Steps

Call oc.tools.invoke("demo", { args: { input: "hello" } }) from the SDK.
Call Gateway tools.invoke with { name, args, sessionKey, agentId, confirm }.
Exercise a plugin approval request without confirm: true.

Expected

SDK sends tools.invoke RPC params.
Gateway validates params, resolves the scoped tool through normal policy, and returns success or typed refusal.
Plugin approval returns requiresApproval: true without executing when confirm: true is omitted.

Actual

Matches expected in targeted tests.

Evidence

Attach at least one:

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

Human Verification (required)

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

Verified scenarios: SDK tools.invoke request construction, protocol validation, method scope registration, Gateway handler mapping, shared HTTP direct invoke behavior, plugin approval request-only behavior, formatting, whitespace, and TypeScript checks.
Edge cases checked: invalid params, admin owner context, typed approval-required result, HTTP high-risk tool deny filtering, plugin/core tool fallback, hook-blocked calls, tool input/auth errors, and agent/session mismatch handling in the core path.
What you did not verify: live Gateway invocation against a real external plugin approval UI.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

Backward compatible? (Yes/No) Yes
Config/env changes? (Yes/No) No
Migration needed? (Yes/No) No
If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: direct tool invocation is a sensitive Gateway surface.
- Mitigation: require operator scope, preserve owner-only filtering, reuse Gateway direct-tool allow/deny filtering, and keep plugin approval gates in the execution path.

Changed files

CHANGELOG.md (modified, +1/-0)
apps/macos/Sources/OpenClawProtocol/GatewayModels.swift (modified, +34/-0)
apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift (modified, +34/-0)
docs/concepts/openclaw-sdk.md (modified, +11/-2)
docs/gateway/protocol.md (modified, +13/-1)
docs/reference/openclaw-sdk-api-design.md (modified, +1/-1)
packages/sdk/src/client.ts (modified, +33/-4)
packages/sdk/src/index.e2e.test.ts (modified, +2/-0)
packages/sdk/src/index.test.ts (modified, +60/-3)
packages/sdk/src/types.ts (modified, +32/-0)
src/agents/pi-tools.before-tool-call.e2e.test.ts (modified, +29/-0)
src/agents/pi-tools.before-tool-call.ts (modified, +16/-0)
src/gateway/method-scopes.test.ts (modified, +1/-0)
src/gateway/method-scopes.ts (modified, +1/-0)
src/gateway/protocol/index.test.ts (modified, +38/-0)
src/gateway/protocol/index.ts (modified, +10/-0)
src/gateway/protocol/schema/agents-models-skills.ts (modified, +47/-0)
src/gateway/protocol/schema/protocol-schemas.ts (modified, +4/-0)
src/gateway/protocol/schema/types.ts (modified, +2/-0)
src/gateway/server-methods-list.ts (modified, +1/-0)
src/gateway/server-methods.ts (modified, +2/-0)
src/gateway/server-methods/tools-invoke.test.ts (added, +128/-0)
src/gateway/server-methods/tools-invoke.ts (added, +45/-0)
src/gateway/tools-invoke-core.ts (added, +325/-0)
src/gateway/tools-invoke-http.test.ts (modified, +13/-0)
src/gateway/tools-invoke-http.ts (modified, +21/-193)

PR #74804: feat(gateway): add SDK-facing tools.invoke RPC

Repository: openclaw/openclaw
Author: ai-hpc
State: open | merged: False
Link: https://github.com/openclaw/openclaw/pull/74804

Description (problem / solution / changelog)

Summary

Problem: @openclaw/sdk exposes a tools namespace, but oc.tools.invoke() had no Gateway RPC method to call and remained unsupported.
Why it matters: SDK clients need a typed WebSocket path for generic tool invocation that follows the same Gateway auth, tool policy, deny-list, and plugin approval semantics as the existing HTTP /tools/invoke route.
What changed: adds tools.invoke to the Gateway RPC surface, protocol schemas, method discovery, scope gating, SDK client/types, and docs; shared Gateway tool-invoke logic now backs both HTTP and RPC paths.
What did NOT change (scope boundary): no new tool policy bypass, no new default tool allow-list expansion, no config migration, and no replay cache beyond using idempotencyKey as the stable tool-call id when supplied.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #74705
Related #74704
This PR fixes a bug or regression

Root Cause (if applicable)

N/A

Regression Test Plan (if applicable)

N/A

User-visible / Behavior Changes

SDK clients can now call oc.tools.invoke(name, params) through the Gateway. The RPC method accepts SDK-style name and HTTP-compatible tool aliases, optional action, args, sessionKey, agentId, confirm, reserved dryRun, and idempotencyKey fields.

Diagram (if applicable)

Before:
SDK oc.tools.invoke() -> unsupported error
HTTP POST /tools/invoke -> existing Gateway tool path

After:
SDK oc.tools.invoke() -> WS tools.invoke -> shared Gateway tool path -> policy/deny-list/approval/tool result
HTTP POST /tools/invoke -> shared Gateway tool path -> existing HTTP envelope

Security Impact (required)

New permissions/capabilities? (Yes/No) Yes
Secrets/tokens handling changed? (Yes/No) No
New/changed network calls? (Yes/No) No
Command/tool execution surface changed? (Yes/No) Yes
Data access scope changed? (Yes/No) Yes
If any Yes, explain risk + mitigation: This exposes an existing direct tool-invoke capability over Gateway WS for SDK clients. It is gated by operator.write, reuses the existing Gateway tool policy chain and HTTP deny-list semantics, preserves owner-only filtering, and reports plugin approval-needed refusals unless the caller explicitly opts into confirm: true.

Repro + Verification

Environment

OS: Ubuntu 24.04
Runtime/container: Node 22 / pnpm dev checkout
Model/provider: N/A
Integration/channel (if any): Gateway RPC + SDK
Relevant config (redacted): default local test config

Steps

Call SDK oc.tools.invoke() before this change.
Observe it throws the existing unsupported namespace error because no Gateway tools.invoke method exists.
Apply this PR and call oc.tools.invoke("sessions_list", { args: {}, sessionKey: "main" }).
Verify the SDK sends tools.invoke, the Gateway enforces operator.write, and the response uses a typed tool result/refusal envelope.

Expected

SDK clients can invoke allowed tools through Gateway RPC.
Disallowed or approval-required tools do not bypass policy and return typed refusal state.
HTTP /tools/invoke behavior remains compatible.

Actual

Implemented as expected in targeted unit, gateway, agent, SDK, and SDK e2e coverage.

Evidence

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

Human Verification (required)

Verified scenarios: SDK tools.invoke dispatch, Gateway tools.invoke handler success envelope, malformed RPC params rejection, operator.write method scope, HTTP /tools/invoke compatibility, and plugin approval-needed typed refusal without opening an approval request by default.
Edge cases checked: HTTP tool alias compatibility, SDK name field, high-risk deny-list preservation, owner-only filtering path, configured session fallback, gateway.tools.allow/deny precedence, and confirm: false approval reporting behavior.
What you did not verify: live third-party SDK consumer behavior outside the repo tests.

Commands run:

git diff --check refs/remotes/openclaw/main...HEAD
pnpm test src/gateway/tools-invoke-http.test.ts src/gateway/method-scopes.test.ts src/agents/pi-tools.before-tool-call.embedded-mode.test.ts packages/sdk/src/index.test.ts packages/sdk/src/index.e2e.test.ts src/gateway/protocol/index.test.ts -- --reporter=verbose
pnpm check:changed --base refs/remotes/openclaw/main

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) No
Migration needed? (Yes/No) No
If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: The new RPC surface could drift from the HTTP tool-invoke behavior over time.
- Mitigation: HTTP and RPC now share the same Gateway tool-invoke helper, and tests cover both surfaces.
Risk: Approval behavior could unexpectedly open approval prompts for SDK callers.
- Mitigation: the default RPC path reports typed approval-needed refusal; callers must pass confirm: true to request approval explicitly.

Changed files

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift (modified, +106/-0)
apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift (modified, +106/-0)
docs/concepts/openclaw-sdk.md (modified, +26/-20)
docs/gateway/protocol.md (modified, +9/-1)
packages/sdk/src/client.ts (modified, +13/-4)
packages/sdk/src/index.e2e.test.ts (modified, +10/-0)
packages/sdk/src/index.test.ts (modified, +33/-3)
packages/sdk/src/index.ts (modified, +2/-0)
packages/sdk/src/types.ts (modified, +20/-0)
src/agents/pi-tools.before-tool-call.embedded-mode.test.ts (modified, +28/-0)
src/agents/pi-tools.before-tool-call.ts (modified, +25/-0)
src/gateway/method-scopes.test.ts (modified, +1/-0)
src/gateway/method-scopes.ts (modified, +1/-0)
src/gateway/protocol/index.ts (modified, +7/-0)
src/gateway/protocol/schema/agents-models-skills.ts (modified, +45/-0)
src/gateway/protocol/schema/protocol-schemas.ts (modified, +6/-0)
src/gateway/protocol/schema/types.ts (modified, +2/-0)
src/gateway/server-methods-list.ts (modified, +1/-0)
src/gateway/server-methods.ts (modified, +2/-0)
src/gateway/server-methods/tools-invoke.ts (added, +89/-0)
src/gateway/tools-invoke-http.test.ts (modified, +88/-0)
src/gateway/tools-invoke-http.ts (modified, +18/-222)
src/gateway/tools-invoke-shared.ts (added, +291/-0)

PR #74847: feat(gateway): add SDK task ledger RPCs

Repository: openclaw/openclaw
Author: tmimmanuel
State: open | merged: False
Link: https://github.com/openclaw/openclaw/pull/74847

Description (problem / solution / changelog)

Summary

Problem: @openclaw/sdk exposed oc.tasks.*, but list, get, and cancel still threw unsupported errors because Gateway had no SDK-facing task ledger RPCs.
Why it matters: OpenMeow and other app clients need stable task visibility for detached/background work without reading internal logs or CLI-only surfaces.
What changed: Added tasks.list, tasks.get, and tasks.cancel Gateway RPCs, SDK methods/types, protocol schemas, scopes, docs, and regression coverage.
What did NOT change (scope boundary): This does not add tool invocation, artifact APIs, environment provisioning, or new task runtime semantics.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #74707
Related #74704
Related #74705
Related #74706
Related #74708
Related #74709
Related https://github.com/OpenCoven/open-meow-sdk
This PR fixes a bug or regression

Root Cause (if applicable)

Root cause: Gateway already had a durable task registry, but no public RPC contract or SDK bridge exposed it to external app clients.
Missing detection / guardrail: SDK coverage only locked in unsupported task errors instead of the app-client task ledger contract.
Contributing context (if known): The OpenMeow gap map calls out tasks.list, tasks.get, and tasks.cancel as missing basics.

Regression Test Plan (if applicable)

Coverage level that should have caught this: Unit test and seam / integration test.
Target test or file: src/gateway/server-methods/tasks.test.ts, src/gateway/protocol/index.test.ts, packages/sdk/src/index.test.ts, packages/sdk/src/index.e2e.test.ts.
Scenario the test should lock in: SDK task methods route to Gateway RPCs, task statuses are app-facing and stable, filters work, scopes are classified, and cancel returns a clear result contract.
Why this is the smallest reliable guardrail: It exercises the protocol and SDK seams without requiring a live detached task runtime.
Existing test that already covers this (if any): Existing task registry tests cover the underlying task lifecycle.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

oc.tasks.list(), oc.tasks.get(taskId), and oc.tasks.cancel(taskId) now call Gateway task ledger RPCs instead of throwing unsupported errors.

Diagram (if applicable)

Before:
[external app] -> [@openclaw/sdk oc.tasks.*] -> [unsupported error]

After:
[external app] -> [@openclaw/sdk oc.tasks.*] -> [Gateway tasks.* RPC] -> [durable task registry]

Security Impact (required)

New permissions/capabilities? (Yes/No) Yes
Secrets/tokens handling changed? (Yes/No) No
New/changed network calls? (Yes/No) No
Command/tool execution surface changed? (Yes/No) No
Data access scope changed? (Yes/No) Yes
If any Yes, explain risk + mitigation: tasks.list and tasks.get require operator.read; tasks.cancel requires operator.write. The RPCs expose task metadata from the existing durable task registry and do not expose secrets.

Repro + Verification

Environment

OS: Ubuntu/Linux local workspace
Runtime/container: Node 22.22.0 via nvm, pnpm 10.33.2
Model/provider: N/A
Integration/channel (if any): Gateway WebSocket RPC / @openclaw/sdk
Relevant config (redacted): N/A

Steps

On current main, call oc.tasks.list(), oc.tasks.get("task-id"), or oc.tasks.cancel("task-id").
Observe the SDK unsupported error.
Apply this PR.
Call the same SDK methods against a Gateway with task records.

Expected

SDK task methods route to Gateway task ledger RPCs and return stable task summaries or cancel results.

Actual

Before this PR, SDK task methods throw unsupported errors.

Evidence

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

Lint evidence:

git diff --check HEAD~1 HEAD
targeted oxlint on changed TS files
markdownlint-cli2 docs/concepts/openclaw-sdk.md

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) No
Migration needed? (Yes/No) No
If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: SDK-facing task statuses intentionally differ from internal registry statuses.
Mitigation: Tests lock in the public mapping, including succeeded to completed and lost to failed.

Changed files

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift (modified, +214/-0)
apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift (modified, +214/-0)
docs/concepts/openclaw-sdk.md (modified, +12/-5)
packages/sdk/src/client.ts (modified, +13/-9)
packages/sdk/src/index.e2e.test.ts (modified, +54/-0)
packages/sdk/src/index.test.ts (modified, +64/-9)
packages/sdk/src/index.ts (modified, +6/-0)
packages/sdk/src/types.ts (modified, +50/-0)
src/gateway/method-scopes.test.ts (modified, +3/-0)
src/gateway/method-scopes.ts (modified, +3/-0)
src/gateway/protocol/index.test.ts (modified, +21/-0)
src/gateway/protocol/index.ts (modified, +31/-0)
src/gateway/protocol/schema.ts (modified, +1/-0)
src/gateway/protocol/schema/protocol-schemas.ts (modified, +16/-0)
src/gateway/protocol/schema/tasks.ts (added, +91/-0)
src/gateway/protocol/schema/types.ts (modified, +7/-0)
src/gateway/server-methods-list.ts (modified, +3/-0)
src/gateway/server-methods.ts (modified, +2/-0)
src/gateway/server-methods/tasks.test.ts (added, +167/-0)
src/gateway/server-methods/tasks.ts (added, +205/-0)
src/tasks/detached-task-runtime-contract.ts (modified, +1/-0)
src/tasks/task-registry.ts (modified, +5/-2)

Code Example

type ToolsInvokeParams = {
  name: string;
  args?: Record<string, unknown>;
  sessionKey?: string;
  agentId?: string;
  confirm?: boolean;
  idempotencyKey?: string;
};

RAW_BUFFERClick to expand / collapse

Goal

Add a Gateway RPC method for SDK-facing generic tool invocation.

There is an HTTP /tools/invoke route, but @openclaw/sdk currently has oc.tools.invoke() scaffolded as unsupported. The SDK should have a clean Gateway RPC method with the same policy/approval semantics as other tool invocation paths.

Proposed method

tools.invoke

type ToolsInvokeParams = {
  name: string;
  args?: Record<string, unknown>;
  sessionKey?: string;
  agentId?: string;
  confirm?: boolean;
  idempotencyKey?: string;
};

Acceptance criteria

Runs through the normal Gateway tool policy pipeline.
Preserves plugin confirmation and approval semantics.
Supports session/agent scoping.
Returns typed refusal/approval-needed state.
Includes tests for interactive refusal without confirmation.
@openclaw/sdk can implement oc.tools.invoke() against it.

References

extent analysis

TL;DR

Implement a Gateway RPC method tools.invoke with the proposed ToolsInvokeParams type to support generic tool invocation in the SDK.

Guidance

Review the proposed ToolsInvokeParams type to ensure it aligns with the required policy and approval semantics.
Implement the tools.invoke Gateway RPC method, integrating it with the normal Gateway tool policy pipeline.
Develop tests to verify the method's behavior, including interactive refusal without confirmation and session/agent scoping.
Update the @openclaw/sdk to implement oc.tools.invoke() against the new RPC method.

Example

// Example implementation of the tools.invoke RPC method
async function toolsInvoke(params: ToolsInvokeParams) {
  // Run through the normal Gateway tool policy pipeline
  const policyResult = await runPolicyPipeline(params);
  // Preserve plugin confirmation and approval semantics
  if (policyResult.requiresApproval) {
    // Return typed refusal/approval-needed state
    return { approvalNeeded: true };
  }
  // Invoke the tool with the provided args and session/agent scoping
  const result = await invokeTool(params.name, params.args, params.sessionKey, params.agentId);
  return result;
}

Notes

The implementation details may vary depending on the specific requirements and existing infrastructure of the Gateway and SDK.

Recommendation

Apply workaround: Implement the proposed tools.invoke RPC method to support generic tool invocation in the SDK, as it aligns with the acceptance criteria and proposed method.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#docker error #permission error #memory optimization #batch processing #GPU compatibility

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.