Skip to content

Commit 4dac7bb

Browse files
gazeatcodegazeatcode
committed
docs(sdk): clarify app and plugin sdk boundary
1 parent c4f9cf1 commit 4dac7bb

4 files changed

Lines changed: 91 additions & 1 deletion

File tree

‎docs/.i18n/glossary.zh-CN.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -622,5 +622,45 @@
622622
{
623623
"source": "/cli/config",
624624
"target": "/cli/config"
625+
},
626+
{
627+
"source": "Media understanding pipeline",
628+
"target": "媒体理解管线"
629+
},
630+
{
631+
"source": "PDF tool",
632+
"target": "PDF 工具"
633+
},
634+
{
635+
"source": "Background tasks",
636+
"target": "后台任务"
637+
},
638+
{
639+
"source": "ACP agents",
640+
"target": "ACP agents"
641+
},
642+
{
643+
"source": "Command queue",
644+
"target": "命令队列"
645+
},
646+
{
647+
"source": "Messages",
648+
"target": "消息"
649+
},
650+
{
651+
"source": "Channel turn kernel",
652+
"target": "渠道回合内核"
653+
},
654+
{
655+
"source": "Building channel plugins",
656+
"target": "构建渠道插件"
657+
},
658+
{
659+
"source": "Plugin runtime helpers",
660+
"target": "插件运行时辅助工具"
661+
},
662+
{
663+
"source": "Plugin internals",
664+
"target": "插件内部机制"
625665
}
626666
]

‎docs/concepts/openclaw-sdk.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,27 @@ resources.
2121
register providers, channels, tools, hooks, or trusted runtimes.
2222
</Note>
2323

24+
## Boundary Checklist
25+
26+
Use `@openclaw/sdk` when the code is an external client of a running Gateway.
27+
That includes apps, scripts, dashboards, CI jobs, IDE extensions, and
28+
OpenMeow/OpenCoven-style dogfood clients.
29+
30+
External App SDK examples should:
31+
32+
- Import from `@openclaw/sdk`
33+
- Connect through Gateway URL, token, password, or a custom transport
34+
- Use Gateway-backed namespaces such as `oc.agents`, `oc.sessions`, `oc.runs`,
35+
`oc.models`, `oc.tools`, and `oc.approvals`
36+
- Treat raw Gateway events as an advanced escape hatch and prefer normalized
37+
SDK events for UI state
38+
- Avoid `openclaw/plugin-sdk/*`, `src/**`, plugin runtime APIs, and bundled
39+
plugin internals
40+
41+
Use the [Plugin SDK](/plugins/sdk-overview) only when the code is loaded by
42+
OpenClaw as trusted in-process plugin code that registers providers, channels,
43+
tools, hooks, services, or runtimes.
44+
2445
## What Ships Today
2546

2647
`@openclaw/sdk` ships with:
@@ -88,7 +109,9 @@ const oc = new OpenClaw({
88109
## Run An Agent
89110

90111
Use `oc.agents.get(id)` when the app wants an agent handle, then call
91-
`agent.run()`.
112+
`agent.run()`. This is the correct pattern for external clients such as
113+
OpenMeow, OpenCoven examples, local scripts, or CI jobs; those clients should
114+
not import Plugin SDK subpaths or OpenClaw core internals.
92115

93116
```typescript
94117
const agent = await oc.agents.get("main");

‎docs/plugins/sdk-overview.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,27 @@ reference for **what to import** and **what you can register**.
1919
instead.
2020
</Note>
2121

22+
## Where Plugin SDK Code Runs
23+
24+
Plugin SDK code runs inside OpenClaw's trusted plugin runtime. Use it when the
25+
code must extend OpenClaw by registering providers, channels, tools, hooks,
26+
services, Gateway plugin methods, or trusted runtime helpers.
27+
28+
Do not use the Plugin SDK for an external app that only needs to control or
29+
observe OpenClaw. OpenMeow/OpenCoven-style desktop apps, dashboards, IDE
30+
extensions, CI automation, and standalone scripts should import
31+
`@openclaw/sdk`, connect to the Gateway, and use the public App SDK contract
32+
documented in [OpenClaw App SDK](/concepts/openclaw-sdk).
33+
34+
Boundary summary:
35+
36+
| Code location | Correct SDK | Why |
37+
| ------------------------------------------ | ----------------------- | ---------------------------------------------------------- |
38+
| Outside OpenClaw: app, script, dashboard | `@openclaw/sdk` | Talks to Gateway RPCs and normalized events |
39+
| Inside OpenClaw: plugin runtime | `openclaw/plugin-sdk/*` | Registers trusted capabilities with the host |
40+
| Docs or examples for OpenMeow/OpenCoven UI | `@openclaw/sdk` | These are external app clients, not in-process plugins |
41+
| Provider, channel, tool, hook, or harness | `openclaw/plugin-sdk/*` | These extend OpenClaw from inside the trusted plugin layer |
42+
2243
<Tip>
2344
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.
2445
</Tip>

‎docs/reference/openclaw-sdk-api-design.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ The public app SDK should be built in two layers:
2424
2. A high-level ergonomic wrapper with `OpenClaw`, `Agent`, `Session`, `Run`,
2525
`Task`, `Artifact`, `Approval`, and `Environment` objects.
2626

27+
All App SDK examples should preserve the external-client boundary:
28+
`@openclaw/sdk` calls Gateway RPCs, and Gateway owns access to the OpenClaw
29+
runtime. OpenMeow/OpenCoven examples belong on this side of the boundary. They
30+
should not import `openclaw/plugin-sdk/*`, `src/**`, plugin runtime APIs, or
31+
other in-process implementation seams.
32+
2733
## Namespace design
2834

2935
The low-level namespaces should closely follow Gateway resources:

0 commit comments

Comments
 (0)