From cd0fb36c1cda8b4cd5893cf5024ad7b43535e472 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 30 Apr 2026 01:38:48 +0100 Subject: [PATCH] docs: clarify app sdk documentation --- AGENTS.md | 1 + docs/.i18n/glossary.zh-CN.json | 8 +++++++ docs/concepts/openclaw-sdk.md | 27 ++++++++++++++--------- docs/docs.json | 4 ++-- docs/plugins/sdk-overview.md | 12 ++++++++-- docs/reference/openclaw-sdk-api-design.md | 23 ++++++++++++------- 6 files changed, 53 insertions(+), 22 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 74178f687d7..96459cd7d87 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -142,6 +142,7 @@ Telegraph style. Root rules only. Read scoped `AGENTS.md` before subtree work. ## Docs / Changelog - Docs change with behavior/API. Use docs list/read_when hints; docs links per `docs/AGENTS.md`. +- Docs final answers: when doc files changed, end with the relevant full `https://docs.openclaw.ai/...` URL(s). - Changelog user-facing only; pure test/internal usually no entry. - Changelog placement: active version `### Changes`/`### Fixes`; every added entry must include at least one `Thanks @author` attribution, using credited GitHub username(s). Never add `Thanks @codex`, `Thanks @openclaw`, or `Thanks @steipete`. - Changelog bullets are always single-line. No wrapping/continuation across multiple lines. Long entries stay on one long line so dedupe, PR-ref, and credit-audit tooling work and so the visual style stays uniform. diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index ff1616612c9..820bb01a785 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -11,6 +11,14 @@ "source": "OpenAI provider", "target": "OpenAI provider" }, + { + "source": "OpenClaw App SDK", + "target": "OpenClaw 应用 SDK" + }, + { + "source": "OpenClaw App SDK API design", + "target": "OpenClaw 应用 SDK API 设计" + }, { "source": "Azure Speech", "target": "Azure Speech" diff --git a/docs/concepts/openclaw-sdk.md b/docs/concepts/openclaw-sdk.md index 16599878051..5bca17b1b9e 100644 --- a/docs/concepts/openclaw-sdk.md +++ b/docs/concepts/openclaw-sdk.md @@ -1,17 +1,24 @@ --- -summary: "Design proposal for a public OpenClaw app SDK for agent runs, sessions, tasks, artifacts, and managed environments" -title: "OpenClaw SDK design" +summary: "Public OpenClaw App SDK design for external apps, scripts, dashboards, CI jobs, and IDE extensions" +title: "OpenClaw App SDK" +sidebarTitle: "App SDK" read_when: - You are designing or implementing a public OpenClaw app SDK - You are comparing OpenClaw agent APIs with Cursor, Claude Agent SDK, OpenAI Agents, Google ADK, OpenCode, Codex, or ACP - - You need to decide whether a feature belongs in the public app SDK, plugin SDK, Gateway protocol, ACP backend, or managed environment layer + - You need to decide whether a feature belongs in the public App SDK, Plugin SDK, Gateway protocol, ACP backend, or managed environment layer --- -This page is a design proposal for a future public **OpenClaw app SDK**. It is -separate from the existing [plugin SDK](/plugins/sdk-overview). +This page is a design proposal for the public **OpenClaw App SDK**. It is +separate from the existing [Plugin SDK](/plugins/sdk-overview). -The plugin SDK is for code that runs inside OpenClaw and extends providers, -channels, tools, hooks, and trusted runtimes. The app SDK should be for + + Use `@openclaw/sdk` when an external app, script, dashboard, CI job, or IDE + extension wants to run and observe OpenClaw agents through the Gateway. Use + `openclaw/plugin-sdk/*` only when writing a plugin that runs inside OpenClaw. + + +The Plugin SDK is for code that runs inside OpenClaw and extends providers, +channels, tools, hooks, and trusted runtimes. The App SDK should be for external applications, scripts, dashboards, CI jobs, IDE extensions, and automation systems that want to run and observe OpenClaw agents through a stable public API. @@ -231,7 +238,7 @@ agent is a normal run in a managed environment, not a special product fork. The detailed namespace, event, result, approval, artifact, security, package, and environment provider contracts live in -[OpenClaw SDK API design](/reference/openclaw-sdk-api-design). +[OpenClaw App SDK API design](/reference/openclaw-sdk-api-design). ## Cookbook plan @@ -262,7 +269,7 @@ client examples belong in an advanced section. - Agree on public nouns and names. - Decide package names. - Define the first event taxonomy. -- Mark the current plugin SDK as intentionally separate in docs. +- Mark the current Plugin SDK as intentionally separate in docs. ### Phase 1: Low-level generated client @@ -330,7 +337,7 @@ Copy these ideas: Avoid these traps: - A public SDK that is just a thin dump of Gateway internals. -- A public SDK that imports plugin SDK subpaths. +- A public SDK that imports Plugin SDK subpaths. - A public SDK where events are only `stream` plus `data`. - A cloud-first API that makes local OpenClaw feel like a legacy mode. - Runtime selection hidden in model id prefixes. diff --git a/docs/docs.json b/docs/docs.json index bc2a3ba2896..13c6c1995dc 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1114,7 +1114,6 @@ "concepts/agent", "concepts/agent-loop", "concepts/agent-runtimes", - "concepts/openclaw-sdk", "concepts/system-prompt", "concepts/context", "concepts/context-engine", @@ -1205,7 +1204,7 @@ ] }, { - "group": "SDK reference", + "group": "Plugin SDK reference", "pages": [ "plugins/sdk-overview", "plugins/sdk-subpaths", @@ -1656,6 +1655,7 @@ "group": "RPC and API", "pages": [ "reference/rpc", + "concepts/openclaw-sdk", "reference/openclaw-sdk-api-design", "reference/device-models" ] diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index b6f2774d310..36c78bad9af 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -1,7 +1,7 @@ --- summary: "Import map, registration API reference, and SDK architecture" title: "Plugin SDK overview" -sidebarTitle: "SDK overview" +sidebarTitle: "Plugin SDK overview" read_when: - You need to know which SDK subpath to import from - You want a reference for all registration methods on OpenClawPluginApi @@ -11,6 +11,14 @@ read_when: The plugin SDK is the typed contract between plugins and core. This page is the reference for **what to import** and **what you can register**. + + This page is for plugin authors using `openclaw/plugin-sdk/*` inside + OpenClaw. For external apps, scripts, dashboards, CI jobs, and IDE extensions + that want to run agents through the Gateway, use the + [OpenClaw App SDK](/concepts/openclaw-sdk) and the `@openclaw/sdk` package + instead. + + Looking for a how-to guide instead? Start with [Building plugins](/plugins/building-plugins), use [Channel plugins](/plugins/sdk-channel-plugins) for channel plugins, [Provider plugins](/plugins/sdk-provider-plugins) for provider plugins, and [Plugin hooks](/plugins/hooks) for tool or lifecycle hook plugins. @@ -346,7 +354,7 @@ Facade-loaded bundled plugin public surfaces (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts`, and similar public entry files) prefer the active runtime config snapshot when OpenClaw is already running. If no runtime snapshot exists yet, they fall back to the resolved config file on disk. -Packaged bundled plugin facades should be loaded through the OpenClaw SDK +Packaged bundled plugin facades should be loaded through OpenClaw's plugin facade loaders; direct imports from `dist/extensions/...` bypass staged runtime dependency mirrors that packaged installs use for plugin-owned dependencies. diff --git a/docs/reference/openclaw-sdk-api-design.md b/docs/reference/openclaw-sdk-api-design.md index da94270de55..412495af023 100644 --- a/docs/reference/openclaw-sdk-api-design.md +++ b/docs/reference/openclaw-sdk-api-design.md @@ -1,15 +1,22 @@ --- -summary: "Reference design for the proposed public OpenClaw app SDK API, event taxonomy, artifacts, approvals, and package structure" -title: "OpenClaw SDK API design" +summary: "Reference design for the public OpenClaw App SDK API, event taxonomy, artifacts, approvals, and package structure" +title: "OpenClaw App SDK API design" +sidebarTitle: "App SDK API design" read_when: - You are implementing the proposed public OpenClaw app SDK - You need the draft namespace, event, result, artifact, approval, or security contract for the app SDK - - You are comparing Gateway protocol resources with the high-level OpenClaw SDK wrapper + - You are comparing Gateway protocol resources with the high-level OpenClaw App SDK wrapper --- -This page is the detailed API reference design for the proposed public -[OpenClaw SDK](/concepts/openclaw-sdk). It is intentionally separate from the -[plugin SDK](/plugins/sdk-overview). +This page is the detailed API reference design for the public +[OpenClaw App SDK](/concepts/openclaw-sdk). It is intentionally separate from +the [Plugin SDK](/plugins/sdk-overview). + + + `@openclaw/sdk` is the external app/client package for talking to the + Gateway. `openclaw/plugin-sdk/*` is the in-process plugin authoring contract. + Do not import Plugin SDK subpaths from apps that only need to run agents. + The public app SDK should be built in two layers: @@ -368,13 +375,13 @@ Benefits: - protocol drift is visible - tests can compare generated methods with Gateway exports -- app SDK stays independent from plugin SDK internals +- App SDK stays independent from Plugin SDK internals - low-level consumers still have full protocol access - high-level consumers get the small product API ## Related docs -- [OpenClaw SDK design](/concepts/openclaw-sdk) +- [OpenClaw App SDK](/concepts/openclaw-sdk) - [Gateway RPC reference](/reference/rpc) - [Agent loop](/concepts/agent-loop) - [Agent runtimes](/concepts/agent-runtimes)