SDK de la aplicación OpenClaw

El OpenClaw App SDK es la API pública de cliente para apps fuera del proceso de OpenClaw. Usa @openclaw/sdk cuando un script, panel, tarea de CI, extensión de IDE u otra app externa quiera conectarse al Gateway, iniciar ejecuciones de agente, transmitir eventos, esperar resultados, cancelar trabajo o inspeccionar recursos del Gateway.

Lo que se entrega hoy

@openclaw/sdk se entrega con:

El SDK también exporta los tipos principales usados por esas superficies: 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 y tipos de resultado relacionados.

Conectarse a un Gateway

Crea un cliente con una URL explícita del Gateway, o inyecta un transporte personalizado para pruebas y runtimes de apps embebidas.

 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://..." }) es equivalente a url. La opción gateway: "auto" es aceptada por el constructor, pero el descubrimiento automático del Gateway aún no es una función separada del SDK; pasa url cuando la app aún no sepa cómo descubrir el Gateway.

Para pruebas, pasa un objeto que implemente OpenClawTransport:

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

Ejecutar un agente

Usa oc.agents.get(id) cuando la app quiera un handle de agente y luego llama a 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);

Las referencias de modelo calificadas por proveedor, como openai/gpt-5.5, se dividen en sobreescrituras provider y model del Gateway. timeoutMs permanece en milisegundos en el SDK y se convierte a segundos de timeout del Gateway para el RPC agent.

run.wait() usa el RPC agent.wait del Gateway. Un plazo de espera que vence mientras la ejecución sigue activa devuelve status: "accepted" en lugar de simular que la propia ejecución agotó el tiempo. Los timeouts de runtime, las ejecuciones abortadas y las ejecuciones canceladas se normalizan a timed_out o cancelled.

Crear y reutilizar sesiones

Usa sesiones cuando la app quiera estado duradero de transcripción.

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() llama a sessions.send y devuelve un Run. Los handles de sesión también admiten:

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

Transmitir eventos

El SDK normaliza eventos sin procesar del Gateway en un sobre estable 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;};

Los tipos de evento comunes incluyen:

Run.events() filtra eventos a un id de ejecución y reproduce eventos ya vistos para ejecuciones rápidas. Eso significa que el flujo documentado es seguro:

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

Para flujos de toda la app, usa oc.events(). Para frames sin procesar del Gateway, usa oc.rawEvents().

Modelos, herramientas, artefactos y aprobaciones

Los helpers de modelo se asignan a métodos actuales del Gateway:

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

Los helpers de herramienta exponen el catálogo del Gateway, la vista efectiva de herramientas y la invocación directa de herramientas del Gateway. oc.tools.invoke() devuelve un sobre tipado en lugar de lanzar errores por rechazos de política o aprobación.

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",});

Los helpers de artefacto exponen la proyección de artefactos del Gateway para contexto de sesión, ejecución o tarea. Cada llamada requiere un ámbito explícito sessionKey, runId o taskId:

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);}

Los helpers de aprobación usan los RPCs de aprobación de exec:

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

Los helpers de tarea usan el registro duradero de tareas que también respalda openclaw tasks:

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" });

Los helpers de entorno exponen descubrimiento de solo lectura local del Gateway y del nodo:

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

Explícitamente no admitido hoy

El SDK incluye nombres para el modelo de producto que queremos, pero no simula silenciosamente que existan RPCs del Gateway. Estas llamadas actualmente lanzan errores explícitos de no compatibilidad:

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

Los campos por ejecución workspace, runtime, environment y approvals están tipados como forma futura, pero el Gateway actual no admite esas sobreescrituras en el RPC agent. Si los llamadores los pasan, el SDK lanza un error antes de enviar la ejecución para que el trabajo no se ejecute accidentalmente con el comportamiento predeterminado de workspace, runtime, entorno o aprobación.

App SDK frente a Plugin SDK

Usa el App SDK cuando el código vive fuera de OpenClaw:

• scripts de Node que inician u observan ejecuciones de agente
• tareas de CI que llaman a un Gateway
• paneles y paneles de administración
• extensiones de IDE
• puentes externos que no necesitan convertirse en plugins de canal
• pruebas de integración con transportes de Gateway falsos o reales

Usa el Plugin SDK cuando el código se ejecuta dentro de OpenClaw:

• plugins de proveedor
• plugins de canal
• hooks de herramienta o ciclo de vida
• plugins de harness de agente
• helpers de runtime de confianza

El código de App SDK debe importar desde @openclaw/sdk. El código de Plugin debe importar desde subrutas documentadas de openclaw/plugin-sdk/*. No mezcles los dos contratos.

Relacionado

• Diseño de la API del SDK de apps de OpenClaw
• Referencia de RPC de Gateway
• Bucle del agente
• Entornos de ejecución de agentes
• Sesiones
• Tareas en segundo plano
• Agentes ACP
• Descripción general del SDK de Plugin