@openclaw/sdk availability: docs mention it, npm returns 404

[hushed plaza]

Hi OpenClaw team,

The docs mention using @openclaw/sdk for external apps:
https://docs.openclaw.ai/concepts/openclaw-sdk

But pnpm add @openclaw/sdk fails with a 404 from npm:

[ERR_PNPM_FETCH_404] GET https://registry.npmjs.org/@openclaw%2Fsdk: Not Found - 404

I also noticed that in the repo packages/sdk/package.json appears to be marked as private:

"name": "@openclaw/sdk"
"version": "0.0.0-private"
"private": true

Is this SDK currently available for external use, or is the documentation describing a future/planned API?

For now, what is the recommended way to trigger an OpenClaw agent from a Next.js backend/server action?

[somber beacon]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[zealous ginkgo]

I checked the current repo/docs: your npm 404 is expected right now. packages/sdk/package.json is still "version": "0.0.0-private" and "private": true, so @openclaw/sdk is not currently published for external pnpm add use. The App SDK docs appear to be ahead of the published package state.

For a Next.js backend/server action today, I’d use one of these trusted-backend paths:

1. HTTP, preferred for web apps: enable the Gateway OpenAI-compatible endpoint, then call /v1/responses or /v1/chat/completions from the server side only. It runs a normal OpenClaw agent turn under the hood.
   Docs: https://docs.openclaw.ai/gateway/openai-http-api and https://docs.openclaw.ai/gateway/openresponses-http-api

Minimal shape:

await fetch("http://127.0.0.1:18789/v1/responses", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.OPENCLAW_GATEWAY_TOKEN}`,
  },

[zealous ginkgo]

  body: JSON.stringify({
    model: "openclaw/default",
    input: "Do the thing from my app",
    user: conversationId, // stable session routing if desired
  }),
});

Enable it with:

{
  gateway: {
    http: {
      endpoints: {

[zealous ginkgo]

        responses: { enabled: true },
        // or: chatCompletions: { enabled: true }
      },
    },
  },
}

2. CLI, simplest if your Next.js app runs on the same host as OpenClaw:

openclaw agent --agent main --message "Do the thing" --json

Docs: https://docs.openclaw.ai/tools/agent-send and https://docs.openclaw.ai/cli/agent

[zealous ginkgo]

Important security note: Gateway HTTP auth is operator-level access, not a narrow user token. Keep it on loopback/tailnet/private ingress and keep the token only in the Next.js server environment, never in client code.

I would not use /tools/invoke for this specific case; that endpoint is for direct single-tool calls, and remote sessions_send is denied by default because it is a control-plane surface.