メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw App SDKは、OpenClawプロセスの外部にあるアプリ向けの公開クライアントAPIです。スクリプト、ダッシュボード、CIジョブ、IDE拡張、その他の外部アプリがGatewayへ接続し、agent runを開始し、イベントをストリームし、結果を待機し、作業をキャンセルし、Gatewayリソースを検査したい場合は@openclaw/sdkを使用します。
App SDKはPlugin SDKとは異なります。 @openclaw/sdkはOpenClawの外部からGatewayと通信します。 openclaw/plugin-sdk/*は、OpenClaw内部で実行され、プロバイダー、チャンネル、ツール、フック、信頼済みランタイムを登録するPlugin専用です。

​
現在提供されているもの

@openclaw/sdkには次が含まれています。
サーフェス状態機能
OpenClaw準備完了メインのクライアントエントリポイント。transport、接続、リクエスト、イベントを所有します。
GatewayClientTransport準備完了Gatewayクライアントに支えられたWebSocket transport。
oc.agents準備完了agentハンドルを一覧表示、作成、更新、削除、取得します。
Agent.run()準備完了Gatewayのagent runを開始し、Runを返します。
oc.runs準備完了runを作成、取得、待機、キャンセル、ストリームします。
Run.events()準備完了高速なrun向けのリプレイ付きで、runごとの正規化済みイベントをストリームします。
Run.wait()準備完了agent.waitを呼び出し、安定したRunResultを返します。
Run.cancel()準備完了run idでsessions.abortを呼び出し、利用可能な場合はsession keyも使用します。
oc.sessions準備完了sessionハンドルを作成、解決、送信、パッチ、compact、取得します。
Session.send()準備完了sessions.sendを呼び出し、Runを返します。
oc.tasks準備完了Gateway task台帳のエントリを一覧表示、読み取り、キャンセルします。
oc.models準備完了models.listと現在のmodels.authStatusステータスRPCを呼び出します。
oc.tools準備完了ポリシーパイプラインを通じてGatewayツールを一覧表示、スコープ設定、呼び出します。
oc.artifacts準備完了Gateway transcript artifactを一覧表示、取得、ダウンロードします。
oc.approvals準備完了Gateway approval RPCを通じてexec approvalを一覧表示、解決します。
oc.environments一部対応Gateway-localおよびnode environment候補を一覧表示します。create/deleteは未接続です。
oc.rawEvents()準備完了高度なコンシューマー向けに生のGatewayイベントを公開します。
normalizeGatewayEvent()準備完了生のGatewayイベントを安定した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を注入します。 
import { OpenClaw } from "@openclaw/sdk";

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;
};
一般的なイベントタイプには次が含まれます。
イベントタイプ元のGatewayイベント
run.startedagentライフサイクル開始
run.completedagentライフサイクル終了
run.failedagentライフサイクルエラー
run.cancelled中止/キャンセルされたライフサイクル終了
run.timed_outタイムアウトによるライフサイクル終了
assistant.deltaAssistantストリーミング差分
assistant.messageAssistantメッセージ
thinking.delta思考またはplanストリーム
tool.call.startedツール/item/command開始
tool.call.deltaツール/item/command更新
tool.call.completedツール/item/command完了
tool.call.failedツール/item/command失敗またはブロック状態
approval.requestedExecまたはPlugin approval request
approval.resolvedExecまたはPlugin approval resolution
session.createdsessions.changed作成
session.updatedsessions.changed更新
session.compactedsessions.changed compaction
task.updatedTask更新イベント
artifact.updatedPatchストリームイベント
rawまだ安定したSDKマッピングがない任意のイベント
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つの契約を混在させないでください。

​
関連