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

Documentation Index

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

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

このページは、公開 OpenClaw App SDK の詳細な API リファレンス設計です。意図的に Plugin SDK とは分離されています。
@openclaw/sdk は Gateway と通信するための外部アプリ/クライアントパッケージです。openclaw/plugin-sdk/* はインプロセスの Plugin オーサリング契約です。 エージェントを実行するだけでよいアプリから Plugin SDK のサブパスをインポートしないでください。
公開アプリ SDK は、次の 2 層で構築する必要があります。
  1. 低レベルの生成 Gateway クライアント。
  2. OpenClaw、Agent、Session、Run、 Task、Artifact、Approval、Environment オブジェクトを備えた、高レベルで使いやすいラッパー。

​
名前空間設計

低レベルの名前空間は Gateway リソースに密接に沿う必要があります。 
oc.agents.list();
oc.agents.get("main");
oc.agents.create(...);
oc.agents.update(...);

oc.sessions.list();
oc.sessions.create(...);
oc.sessions.resolve(...);
oc.sessions.send(...);
oc.sessions.messages(...);
oc.sessions.fork(...);
oc.sessions.compact(...);
oc.sessions.abort(...);

oc.runs.create(...);
oc.runs.get(runId);
oc.runs.events(runId, { after });
oc.runs.wait(runId);
oc.runs.cancel(runId);

oc.tasks.list(); // future API: current SDK throws unsupported
oc.tasks.get(taskId); // future API: current SDK throws unsupported
oc.tasks.cancel(taskId); // future API: current SDK throws unsupported
oc.tasks.events(taskId, { after }); // future API

oc.models.list();
oc.models.status(); // Gateway models.authStatus

oc.tools.list();
oc.tools.invoke(...); // future API: current SDK throws unsupported

oc.artifacts.list({ runId }); // future API: current SDK throws unsupported
oc.artifacts.get(artifactId); // future API: current SDK throws unsupported
oc.artifacts.download(artifactId); // future API: current SDK throws unsupported

oc.approvals.list();
oc.approvals.respond(approvalId, ...);

oc.environments.list(); // future API: current SDK throws unsupported
oc.environments.create(...); // future API: current SDK throws unsupported
oc.environments.status(environmentId); // future API: current SDK throws unsupported
oc.environments.delete(environmentId); // future API: current SDK throws unsupported
高レベルラッパーは、一般的なフローを快適にするオブジェクトを返す必要があります。 
const run = await agent.run(inputOrParams);
await run.cancel();
await run.wait();

for await (const event of run.events()) {
  // normalized event stream
}

const artifacts = await run.artifacts.list();
const session = await run.session();

​
イベント契約

公開 SDK は、バージョン付きで再生可能な正規化イベントを公開する必要があります。 
type OpenClawEvent = {
  version: 1;
  id: string;
  ts: number;
  type: OpenClawEventType;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  agentId?: string;
  data: unknown;
  raw?: unknown;
};
id は再生カーソルです。コンシューマーは events({ after: id }) で再接続し、保持期間が許す場合は取りこぼしたイベントを受信できる必要があります。 推奨される正規化イベントファミリー:
イベント意味
run.createdRun が受理された。
run.queuedRun がセッションレーン、ランタイム、または環境を待っている。
run.startedランタイムが実行を開始した。
run.completedRun が正常に終了した。
run.failedRun がエラーで終了した。
run.cancelledRun がキャンセルされた。
run.timed_outRun がタイムアウトを超過した。
assistant.deltaアシスタントのテキスト差分。
assistant.message完全なアシスタントメッセージまたは置換。
thinking.deltaポリシーで公開が許可されている場合の推論または計画の差分。
tool.call.startedツール呼び出しが開始された。
tool.call.deltaツール呼び出しが進行状況または部分出力をストリーミングした。
tool.call.completedツール呼び出しが正常に返った。
tool.call.failedツール呼び出しが失敗した。
approval.requestedRun またはツールが承認を必要としている。
approval.resolved承認が許可、拒否、期限切れ、またはキャンセルされた。
question.requestedランタイムがユーザーまたはホストアプリに入力を求めている。
question.answeredホストアプリが回答を提供した。
artifact.created新しいアーティファクトが利用可能になった。
artifact.updated既存のアーティファクトが変更された。
session.createdセッションが作成された。
session.updatedセッションのメタデータが変更された。
session.compactedセッション Compaction が発生した。
task.updatedバックグラウンドタスクの状態が変更された。
git.branchランタイムがブランチ状態を観測または変更した。
git.diffランタイムが diff を生成または変更した。
git.prランタイムがプルリクエストを開いた、更新した、またはリンクした。
ランタイムネイティブのペイロードは raw から利用できる必要がありますが、通常の UI でアプリが raw を解析する必要があってはいけません。

​
結果契約

Run.wait() は安定した結果エンベロープを返す必要があります。 
type RunResult = {
  runId: string;
  status: "accepted" | "completed" | "failed" | "cancelled" | "timed_out";
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  startedAt?: string | number;
  endedAt?: string | number;
  output?: {
    text?: string;
    messages?: SDKMessage[];
  };
  usage?: {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    costUsd?: number;
  };
  artifacts?: ArtifactSummary[];
  error?: SDKError;
};
結果は単純で安定している必要があります。タイムスタンプ値は Gateway の形状を保持するため、現在のライフサイクルに基づく Run は通常エポックミリ秒の数値を報告しますが、アダプターは引き続き ISO 文字列を表面化する場合があります。リッチな UI、ツールトレース、ランタイムネイティブの詳細はイベントとアーティファクトに属します。 accepted は非終端の wait 結果です。これは、Run がライフサイクルの終了/エラーを生成する前に Gateway の wait 期限が切れたことを意味します。timed_out として扱ってはいけません。timed_out は、Run が自身のランタイムタイムアウトを超過した場合のために予約されています。

​
承認と質問

コーディングエージェントは常に安全境界を越えるため、承認は第一級の存在でなければなりません。 
run.onApproval(async (request) => {
  if (request.kind === "tool" && request.toolName === "exec") {
    return request.approveOnce({ reason: "CI command allowed by policy" });
  }

  return request.askUser();
});
承認イベントには次を含める必要があります。
  • 承認 ID
  • Run ID とセッション ID
  • リクエスト種別
  • 要求されたアクションの要約
  • ツール名または環境アクション
  • リスクレベル
  • 利用可能な判断
  • 有効期限
  • 判断を再利用できるかどうか
質問は承認とは別です。質問はユーザーまたはホストアプリに情報を求めます。承認はアクションを実行する許可を求めます。

​
ToolSpace モデル

アプリは Plugin 内部をインポートせずにツールサーフェスを理解する必要があります。 
const tools = await run.toolSpace();

for (const tool of tools.list()) {
  console.log(tool.name, tool.source, tool.requiresApproval);
}
SDK は次を公開する必要があります。
  • 正規化されたツールメタデータ
  • ソース: OpenClaw、MCP、Plugin、チャネル、ランタイム、またはアプリ
  • スキーマ要約
  • 承認ポリシー
  • ランタイム互換性
  • ツールが hidden、readonly、write capable、host capable のいずれであるか
SDK を通じたツール呼び出しは、明示的でスコープ指定されている必要があります。ほとんどのアプリは、任意のツールを直接呼び出すのではなく、エージェントを実行するべきです。

​
アーティファクトモデル

アーティファクトはファイル以外も扱う必要があります。 
type ArtifactSummary = {
  id: string;
  runId?: string;
  sessionId?: string;
  type:
    | "file"
    | "patch"
    | "diff"
    | "log"
    | "media"
    | "screenshot"
    | "trajectory"
    | "pull_request"
    | "workspace";
  title?: string;
  mimeType?: string;
  sizeBytes?: number;
  createdAt: string;
  expiresAt?: string;
};
一般的な例:
  • ファイル編集と生成ファイル
  • パッチバンドル
  • VCS diff
  • スクリーンショットとメディア出力
  • ログとトレースバンドル
  • プルリクエストリンク
  • ランタイム軌跡
  • 管理環境ワークスペーススナップショット
アーティファクトアクセスは、すべてのアーティファクトが通常のローカルファイルであると仮定せず、リダクション、保持、ダウンロード URL をサポートする必要があります。

​
セキュリティモデル

アプリ SDK は権限について明示的でなければなりません。 推奨されるトークンスコープ:
スコープ許可内容
agent.readエージェントの一覧表示と検査。
agent.runRun の開始。
session.readセッションメタデータとメッセージの読み取り。
session.writeセッションの作成、送信、フォーク、Compaction、停止。
task.readバックグラウンドタスク状態の読み取り。
task.writeタスク通知ポリシーのキャンセルまたは変更。
approval.respondリクエストの承認または拒否。
tools.invoke公開されたツールの直接呼び出し。
artifacts.readアーティファクトの一覧表示とダウンロード。
environment.write管理環境の作成または破棄。
admin管理操作。
デフォルト:
  • デフォルトではシークレットを転送しない
  • 無制限の環境変数パススルーを行わない
  • シークレット値ではなくシークレット参照
  • 明示的なサンドボックスとネットワークポリシー
  • 明示的なリモート環境保持
  • ポリシーで別途証明されない限り、ホスト実行には承認を要求
  • 呼び出し元がより強い診断スコープを持たない限り、生のランタイムイベントは Gateway を出る前にリダクションされる

​
管理環境プロバイダー

管理エージェントは環境プロバイダーとして実装する必要があります。 
type EnvironmentProvider = {
  id: string;
  capabilities: {
    checkout?: boolean;
    sandbox?: boolean;
    networkPolicy?: boolean;
    secrets?: boolean;
    artifacts?: boolean;
    logs?: boolean;
    pullRequests?: boolean;
    longRunning?: boolean;
  };
};
最初の実装はホスト型 SaaS である必要はありません。既存の Node ホスト、一時ワークスペース、CI 風ランナー、または Testbox 風環境を対象にできます。重要な契約は次のとおりです。
  1. ワークスペースを準備する
  2. 安全な環境とシークレットをバインドする
  3. Run を開始する
  4. イベントをストリーミングする
  5. アーティファクトを収集する
  6. ポリシーに従ってクリーンアップまたは保持する
これが安定したら、ホスト型クラウドサービスは同じプロバイダー契約を実装できます。

​
パッケージ構造

推奨パッケージ:
パッケージ目的
@openclaw/sdk公開高レベル SDK と生成された低レベル Gateway クライアント。
@openclaw/sdk-reactダッシュボードとアプリビルダー向けの任意の React フック。
@openclaw/sdk-testingアプリ統合向けのテストヘルパーとフェイク Gateway サーバー。
このリポジトリには Plugin 用の openclaw/plugin-sdk/* がすでにあります。Plugin 作者とアプリ開発者を混同しないよう、その名前空間は分離したままにしてください。

​
生成クライアント戦略

低レベルクライアントは、バージョン管理された Gateway プロトコル スキーマから生成し、その後、手書きの使いやすいクラスでラップする必要があります。 レイヤー構成:
  1. Gateway スキーマを信頼できる唯一の情報源にする。
  2. 生成された低レベル TypeScript クライアント。
  3. 外部入力とイベントペイロード用のランタイムバリデーター。
  4. 高レベルの OpenClaw、Agent、Session、Run、Task、Artifact ラッパー。
  5. クックブック例と統合テスト。
利点:
  • プロトコルのドリフトが見える
  • テストで生成されたメソッドと Gateway エクスポートを比較できる
  • アプリ SDK が Plugin SDK 内部から独立したままになる
  • 低レベル利用者は引き続きプロトコル全体にアクセスできる
  • 高レベル利用者は小さな製品 API を利用できる

​
関連ドキュメント