OpenClaw アプリ SDK

OpenClaw App SDKは、OpenClawプロセスの外部にあるアプリ向けの公開クライアントAPIです。スクリプト、ダッシュボード、CIジョブ、IDE拡張、その他の外部アプリがGatewayへ接続し、agent runを開始し、イベントをストリームし、結果を待機し、作業をキャンセルし、Gatewayリソースを検査したい場合は@openclaw/sdkを使用します。

現在提供されているもの

@openclaw/sdkには次が含まれています。

SDKは、これらのサーフェスで使用されるコア型もエクスポートします。 AgentRunParams、RunResult、RunStatus、OpenClawEvent、 OpenClawEventType、GatewayEvent、OpenClawTransport、 GatewayRequestOptions、SessionCreateParams、SessionSendParams、 ArtifactSummary、ArtifactQuery、ArtifactsListResult、 ArtifactsGetResult、ArtifactsDownloadResult、 TaskSummary、TaskStatus、TasksListParams、TasksListResult、 TasksGetResult、TasksCancelResult、RuntimeSelection、 EnvironmentSelection、WorkspaceSelection、ApprovalMode、および関連する 結果型です。

Gatewayへ接続する

明示的なGateway URLでクライアントを作成するか、テストや組み込みアプリランタイム向けにカスタムtransportを注入します。

 const oc = new OpenClaw({  url: "ws://127.0.0.1:18789",  token: process.env.OPENCLAW_GATEWAY_TOKEN,  requestTimeoutMs: 30_000,}); await oc.connect();

new OpenClaw({ gateway: "ws://..." })はurlと同等です。gateway: "auto"オプションはコンストラクターで受け付けられますが、自動Gateway discoveryはまだ独立したSDK機能ではありません。アプリがGatewayの検出方法をまだ知らない場合はurlを渡してください。

テストでは、OpenClawTransportを実装するオブジェクトを渡します。

const oc = new OpenClaw({  transport: {    async request(method, params) {      return { method, params };    },    async *events() {},  },});

agentを実行する

アプリがagentハンドルを必要とする場合はoc.agents.get(id)を使用し、その後agent.run()を呼び出します。

const agent = await oc.agents.get("main"); const run = await agent.run({  input: "Review this pull request and suggest the smallest safe fix.",  model: "openai/gpt-5.5",  sessionKey: "main",  timeoutMs: 30_000,}); for await (const event of run.events()) {  const data = event.data as { delta?: unknown };  if (event.type === "assistant.delta" && typeof data.delta === "string") {    process.stdout.write(data.delta);  }} const result = await run.wait({ timeoutMs: 120_000 });console.log(result.status);

openai/gpt-5.5のようなプロバイダー修飾付きmodel refは、Gatewayのproviderおよびmodelオーバーライドに分割されます。timeoutMsはSDK内ではミリ秒のままで、agent RPC向けにGateway timeout秒へ変換されます。

run.wait()はGatewayのagent.wait RPCを使用します。runがまだアクティブな間にwait期限が切れた場合、run自体がタイムアウトしたかのように見せかけるのではなく、status: "accepted"を返します。ランタイムタイムアウト、中止されたrun、キャンセルされたrunは、timed_outまたはcancelledに正規化されます。

sessionを作成して再利用する

アプリが永続的なtranscript状態を必要とする場合はsessionを使用します。

const session = await oc.sessions.create({  agentId: "main",  label: "release-review",}); const run = await session.send("Prepare release notes from the current diff.");await run.wait();

Session.send()はsessions.sendを呼び出し、Runを返します。sessionハンドルは次もサポートします。

await session.abort(run.id);await session.patch({ label: "renamed-session" });await session.compact({ maxLines: 200 });

イベントをストリームする

SDKは生のGatewayイベントを安定したOpenClawEventエンベロープに正規化します。

type OpenClawEvent = {  version: 1;  id: string;  ts: number;  type: OpenClawEventType;  runId?: string;  sessionId?: string;  sessionKey?: string;  taskId?: string;  agentId?: string;  data: unknown;  raw?: GatewayEvent;};

一般的なイベントタイプには次が含まれます。

Run.events()はイベントを1つのrun idに絞り込み、高速なrun向けにすでに見たイベントをリプレイします。つまり、ドキュメント化された次のフローは安全です。

const run = await agent.run("Summarize the latest session."); for await (const event of run.events()) {  if (event.type === "run.completed") {    break;  }}

アプリ全体のストリームにはoc.events()を使用します。生のGatewayフレームにはoc.rawEvents()を使用します。

モデル、ツール、artifact、approval

モデルヘルパーは現在のGatewayメソッドに対応します。

await oc.models.list();await oc.models.status({ probe: false }); // calls models.authStatus

ツールヘルパーは、Gatewayカタログ、有効なツールビュー、直接のGatewayツール呼び出しを公開します。oc.tools.invoke()は、ポリシーまたはapproval拒否でthrowするのではなく、型付きエンベロープを返します。

await oc.tools.list();await oc.tools.effective({ sessionKey: "main" });await oc.tools.invoke("tool-name", {  args: { input: "value" },  sessionKey: "main",  confirm: false,  idempotencyKey: "tool-call-1",});

artifactヘルパーは、session、run、またはtaskコンテキスト向けのGateway artifact projectionを公開します。各呼び出しには、明示的なsessionKey、runId、またはtaskIdスコープが1つ必要です。

const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });const first = artifacts[0]; if (first) {  const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });  const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });  console.log(download.encoding, download.url);}

approvalヘルパーはexec approval RPCを使用します。

const approvals = await oc.approvals.list();await oc.approvals.respond("approval-id", { decision: "approve" });

taskヘルパーは、openclaw tasksも支える永続的なtask台帳を使用します。

const tasks = await oc.tasks.list({ status: "running", sessionKey: "agent:main:main" });const task = await oc.tasks.get(tasks.tasks[0].id);await oc.tasks.cancel(task.task.id, { reason: "user stopped task" });

environmentヘルパーは、読み取り専用のGateway-localおよびnode discoveryを公開します。

const { environments } = await oc.environments.list();await oc.environments.status(environments[0].id);

現在明示的に未対応のもの

SDKには目指しているプロダクトモデル向けの名前が含まれていますが、Gateway RPCが存在するかのように暗黙的に振る舞うことはありません。これらの呼び出しは現在、明示的なunsupported errorをthrowします。

await oc.environments.create({});await oc.environments.delete("environment-id");

runごとのworkspace、runtime、environment、approvalsフィールドは将来の形状として型付けされていますが、現在のGatewayはagent RPC上でこれらのオーバーライドをサポートしていません。呼び出し元がそれらを渡した場合、SDKはrunを送信する前にthrowするため、デフォルトのworkspace、runtime、environment、approval動作で作業が誤って実行されることはありません。

App SDKとPlugin SDK

コードがOpenClawの外部にある場合はApp SDKを使用します。

• agent runを開始または監視するNodeスクリプト
• Gatewayを呼び出すCIジョブ
• ダッシュボードと管理パネル
• IDE拡張
• channel pluginになる必要がない外部ブリッジ
• 偽または実際のGateway transportを使うintegration test

コードがOpenClaw内部で実行される場合はPlugin SDKを使用します。

• provider plugin
• channel plugin
• ツールまたはライフサイクルフック
• agent harness plugin
• 信頼済みランタイムヘルパー

App SDKコードは@openclaw/sdkからimportする必要があります。Pluginコードは、ドキュメント化されたopenclaw/plugin-sdk/*サブパスからimportする必要があります。2つの契約を混在させないでください。

関連

• OpenClaw App SDK API 設計
• Gateway RPC リファレンス
• エージェントループ
• エージェントランタイム
• セッション
• バックグラウンドタスク
• ACP エージェント
• Plugin SDK 概要