Skip to content

docs(sdk): clarify app and plugin sdk boundary#74825

Open
gazeatcode wants to merge 1 commit intoopenclaw:mainfrom
gazeatcode:docs/issue-74709-sdk-boundary
Open

docs(sdk): clarify app and plugin sdk boundary#74825
gazeatcode wants to merge 1 commit intoopenclaw:mainfrom
gazeatcode:docs/issue-74709-sdk-boundary

Conversation

@gazeatcode
Copy link
Copy Markdown

@gazeatcode gazeatcode commented Apr 30, 2026

Summary

  • Problem: the App SDK and Plugin SDK docs already mention the split, but the boundary is easy to miss when writing quickstarts or OpenMeow/OpenCoven-style examples.
  • Why it matters: external apps should talk to Gateway through @openclaw/sdk, while trusted in-process plugins should use openclaw/plugin-sdk/*; mixing these contracts leaks internals into public examples.
  • What changed: added an App SDK boundary checklist, a Plugin SDK runtime/boundary table, and API-design guidance that keeps OpenMeow/OpenCoven examples on the external client side.
  • What did NOT change (scope boundary): no SDK code, Gateway behavior, plugin contracts, or generated API surfaces changed.

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

Root Cause (if applicable)

N/A

  • Root cause: N/A
  • Missing detection / guardrail: N/A
  • Contributing context (if known): N/A

Regression Test Plan (if applicable)

N/A

  • Coverage level that should have caught this:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file: docs checks only.
  • Scenario the test should lock in: docs formatting, linting, MDX validity, i18n glossary coverage, and internal links remain valid.
  • Why this is the smallest reliable guardrail: the change is documentation-only.
  • Existing test that already covers this (if any): pnpm check:docs.
  • If no new test is added, why not: docs-only clarification.

User-visible / Behavior Changes

Docs now explicitly state that external apps, dashboards, scripts, IDE extensions, and OpenMeow/OpenCoven-style examples use @openclaw/sdk over Gateway, while provider/channel/tool/hook/runtime extensions use openclaw/plugin-sdk/* inside OpenClaw.

Diagram (if applicable)

External app/docs example -> @openclaw/sdk -> Gateway RPC/events -> OpenClaw runtime
Trusted plugin code       -> openclaw/plugin-sdk/* -> host registration APIs

Security Impact (required)

  • New permissions/capabilities? (Yes/No) No
  • 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) No
  • If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

  • OS: Linux
  • Runtime/container: Node 22 / pnpm repo scripts
  • Model/provider: N/A
  • Integration/channel (if any): docs
  • Relevant config (redacted): N/A

Steps

  1. Read docs/concepts/openclaw-sdk.md.
  2. Read docs/plugins/sdk-overview.md.
  3. Read docs/reference/openclaw-sdk-api-design.md.

Expected

  • App SDK docs clearly say @openclaw/sdk is for outside-process clients.
  • Plugin SDK docs clearly say openclaw/plugin-sdk/* is for trusted in-process plugin runtime code.
  • Cross-links and OpenMeow/OpenCoven guidance keep future examples on the correct side of the boundary.

Actual

  • Before this PR, the boundary existed but was less explicit in quickstart/example guidance.

Evidence

  • 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: pnpm check:docs; git diff --check upstream/main..HEAD.
  • Edge cases checked: docs formatter, markdown lint, MDX validation, zh-CN glossary entries required by the docs gate, and internal link audit.
  • What you did not verify: rendered Mintlify preview.

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

None.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS labels Apr 30, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented Apr 30, 2026 •
edited
Loading

Codex review: needs maintainer review before merge.

Summary
The PR adds App SDK/Plugin SDK boundary guidance to three docs pages and updates the zh-CN glossary without changing SDK or Gateway code.

Reproducibility: not applicable. as a bug reproduction. The high-confidence check is source and diff comparison: current main has baseline boundary wording but lacks the checklist, runtime table, and named example guidance that this PR adds.

Next step before merge
Maintainer review or merge is the remaining action; there is no discrete automation-repair defect in the docs-only diff.

Security
Cleared: Security review cleared: the PR changes Markdown docs and a glossary JSON file only, with no code execution, dependency, workflow, permissions, secrets, or package-resolution changes.

Review details

Best possible solution:

Review and land or lightly adjust this narrow docs PR so the public docs make the external App SDK versus in-process Plugin SDK boundary unmistakable.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction. The high-confidence check is source and diff comparison: current main has baseline boundary wording but lacks the checklist, runtime table, and named example guidance that this PR adds.

Is this the best way to solve the issue?

Yes. A docs-only update across the App SDK, Plugin SDK overview, and API-design pages is the narrow maintainable solution for the linked docs request; any disagreement should be handled as wording review on this PR.

Acceptance criteria:

  • pnpm check:docs
  • git diff --check upstream/main..HEAD

What I checked:

Likely related people:

  • vincentkoc: Local blame and current-main history attribute the current SDK docs snapshot and packages/sdk/src/client.ts surface to Vincent Koc in commit c7bbb3f, which is the docs/runtime area this PR extends. (role: recent maintainer; confidence: high; commits: c7bbb3f9af36, 9ef35ea5c71c; files: docs/concepts/openclaw-sdk.md, docs/plugins/sdk-overview.md, docs/reference/openclaw-sdk-api-design.md)
  • BunsDev: BunsDev opened linked maintainer-labeled issue Docs: clarify app SDK vs plugin SDK boundary #74709 with the acceptance criteria this PR is trying to satisfy, including the App SDK/Plugin SDK split and future OpenMeow/OpenCoven example guidance. (role: requesting maintainer; confidence: medium; files: docs/concepts/openclaw-sdk.md, docs/plugins/sdk-overview.md, docs/reference/openclaw-sdk-api-design.md)
  • steipete: The existing ClawSweeper review context for this PR identifies steipete as connected to earlier App SDK package/docs work and recent SDK page maintenance; this is relevant background for routing, though the local shallow history now blames the current snapshot to a later docs/runtime commit. (role: introduced behavior; confidence: medium; commits: c35ed548bf0c, 43f6c8b01aa7, cd0fb36c1cda; files: docs/concepts/openclaw-sdk.md, docs/reference/openclaw-sdk-api-design.md, packages/sdk/src/client.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9772ce6ce975.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation size: XS

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Docs: clarify app SDK vs plugin SDK boundary

1 participant

@gazeatcode