mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 05:30:42 +00:00
docs: clarify app sdk documentation
This commit is contained in:
Peter Steinberger
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
@@ -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"
|
||||
]
|
||||
|
||||
@@ -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**.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
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.
|
||||
</Tip>
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
<Note>
|
||||
`@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.
|
||||
</Note>
|
||||
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user