Saltar al contenido principal

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.

Esta página es el diseño detallado de referencia de API para el SDK de aplicaciones de OpenClaw público. Está separada intencionalmente del SDK de Plugin.
@openclaw/sdk es el paquete externo de aplicación/cliente para comunicarse con el Gateway. openclaw/plugin-sdk/* es el contrato de autoría de plugins en proceso. No importes subrutas del SDK de Plugin desde aplicaciones que solo necesitan ejecutar agentes.
El SDK público de aplicaciones debe construirse en dos capas:
  1. Un cliente Gateway generado de bajo nivel.
  2. Un contenedor ergonómico de alto nivel con objetos OpenClaw, Agent, Session, Run, Task, Artifact, Approval y Environment.

​
Diseño de espacios de nombres

Los espacios de nombres de bajo nivel deben seguir de cerca los recursos del 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
Los contenedores de alto nivel deben devolver objetos que hagan cómodos los flujos comunes: 
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();

​
Contrato de eventos

El SDK público debe exponer eventos versionados, reproducibles y normalizados. 
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 es un cursor de reproducción. Los consumidores deben poder reconectarse con events({ after: id }) y recibir los eventos perdidos cuando la retención lo permita. Familias de eventos normalizados recomendadas:
EventoSignificado
run.createdEjecución aceptada.
run.queuedLa ejecución espera un carril de sesión, runtime o entorno.
run.startedEl runtime inició la ejecución.
run.completedLa ejecución finalizó correctamente.
run.failedLa ejecución terminó con un error.
run.cancelledLa ejecución fue cancelada.
run.timed_outLa ejecución superó su tiempo de espera.
assistant.deltaDelta de texto del asistente.
assistant.messageMensaje completo del asistente o reemplazo.
thinking.deltaDelta de razonamiento o plan, cuando la política permite exponerlo.
tool.call.startedComenzó la llamada a la herramienta.
tool.call.deltaLa llamada a la herramienta transmitió progreso o salida parcial.
tool.call.completedLa llamada a la herramienta se completó correctamente.
tool.call.failedLa llamada a la herramienta falló.
approval.requestedUna ejecución o herramienta necesita aprobación.
approval.resolvedLa aprobación fue concedida, denegada, expiró o fue cancelada.
question.requestedEl runtime solicita entrada del usuario o de la app anfitriona.
question.answeredLa app anfitriona proporcionó una respuesta.
artifact.createdNuevo artefacto disponible.
artifact.updatedUn artefacto existente cambió.
session.createdSesión creada.
session.updatedLos metadatos de la sesión cambiaron.
session.compactedSe produjo la Compaction de la sesión.
task.updatedEl estado de la tarea en segundo plano cambió.
git.branchEl runtime observó o cambió el estado de la rama.
git.diffEl runtime produjo o cambió un diff.
git.prEl runtime abrió, actualizó o vinculó una pull request.
Las cargas nativas del runtime deben estar disponibles mediante raw, pero las apps no deben tener que analizar raw para la UI normal.

​
Contrato de resultados

Run.wait() debe devolver un envoltorio de resultado estable: 
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;
};
El resultado debe ser simple y estable. Los valores de marca temporal conservan la forma del Gateway, por lo que las ejecuciones actuales respaldadas por ciclo de vida suelen informar números de milisegundos desde epoch, mientras que los adaptadores aún pueden exponer cadenas ISO. La UI enriquecida, las trazas de herramientas y los detalles nativos del runtime pertenecen a los eventos y artefactos. accepted es un resultado de espera no terminal: significa que el plazo de espera del Gateway expiró antes de que la ejecución produjera un fin/error de ciclo de vida. No debe tratarse como timed_out; timed_out se reserva para una ejecución que superó su propio tiempo de espera de runtime.

​
Aprobaciones y preguntas

Las aprobaciones deben ser entidades de primera clase porque los agentes de programación cruzan constantemente límites de seguridad. 
run.onApproval(async (request) => {
  if (request.kind === "tool" && request.toolName === "exec") {
    return request.approveOnce({ reason: "CI command allowed by policy" });
  }

  return request.askUser();
});
Los eventos de aprobación deben llevar:
  • id de aprobación
  • id de ejecución e id de sesión
  • tipo de solicitud
  • resumen de la acción solicitada
  • nombre de la herramienta o acción de entorno
  • nivel de riesgo
  • decisiones disponibles
  • expiración
  • si la decisión puede reutilizarse
Las preguntas están separadas de las aprobaciones. Una pregunta solicita información al usuario o a la app anfitriona. Una aprobación solicita permiso para realizar una acción.

​
Modelo ToolSpace

Las apps necesitan entender la superficie de herramientas sin importar componentes internos de plugins. 
const tools = await run.toolSpace();

for (const tool of tools.list()) {
  console.log(tool.name, tool.source, tool.requiresApproval);
}
El SDK debe exponer:
  • metadatos de herramienta normalizados
  • origen: OpenClaw, MCP, plugin, canal, runtime o app
  • resumen de esquema
  • política de aprobación
  • compatibilidad de runtime
  • si una herramienta está oculta, es de solo lectura, puede escribir o puede actuar como anfitriona
La invocación de herramientas a través del SDK debe ser explícita y acotada. La mayoría de las apps deben ejecutar agentes, no llamar directamente a herramientas arbitrarias.

​
Modelo de artefactos

Los artefactos deben cubrir más que archivos. 
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;
};
Ejemplos comunes:
  • ediciones de archivos y archivos generados
  • paquetes de parches
  • diffs de VCS
  • capturas de pantalla y salidas multimedia
  • registros y paquetes de trazas
  • enlaces de pull request
  • trayectorias de runtime
  • snapshots de workspace de entornos administrados
El acceso a artefactos debe admitir redacción, retención y URLs de descarga sin asumir que cada artefacto es un archivo local normal.

​
Modelo de seguridad

El SDK de aplicaciones debe ser explícito sobre la autoridad. Alcances de token recomendados:
AlcancePermite
agent.readListar e inspeccionar agentes.
agent.runIniciar ejecuciones.
session.readLeer metadatos y mensajes de sesiones.
session.writeCrear sesiones, enviarles contenido, bifurcarlas, compactarlas y abortarlas.
task.readLeer el estado de tareas en segundo plano.
task.writeCancelar o modificar la política de notificación de tareas.
approval.respondAprobar o denegar solicitudes.
tools.invokeInvocar directamente herramientas expuestas.
artifacts.readListar y descargar artefactos.
environment.writeCrear o destruir entornos administrados.
adminOperaciones administrativas.
Valores predeterminados:
  • sin reenvío de secretos de forma predeterminada
  • sin paso irrestricto de variables de entorno
  • referencias a secretos en lugar de valores de secretos
  • política explícita de sandbox y red
  • retención explícita de entorno remoto
  • aprobaciones para ejecución en el anfitrión salvo que la política demuestre lo contrario
  • eventos raw de runtime redactados antes de salir del Gateway salvo que el llamador tenga un alcance de diagnóstico más fuerte

​
Proveedor de entorno administrado

Los agentes administrados deben implementarse como proveedores de entorno. 
type EnvironmentProvider = {
  id: string;
  capabilities: {
    checkout?: boolean;
    sandbox?: boolean;
    networkPolicy?: boolean;
    secrets?: boolean;
    artifacts?: boolean;
    logs?: boolean;
    pullRequests?: boolean;
    longRunning?: boolean;
  };
};
La primera implementación no necesita ser un SaaS alojado. Puede apuntar a hosts node existentes, workspaces efímeros, runners de estilo CI o entornos de estilo Testbox. El contrato importante es:
  1. preparar workspace
  2. enlazar entorno y secretos seguros
  3. iniciar ejecución
  4. transmitir eventos
  5. recopilar artefactos
  6. limpiar o retener según la política
Una vez que esto sea estable, un servicio en la nube alojado puede implementar el mismo contrato de proveedor.

​
Estructura de paquetes

Paquetes recomendados:
PaquetePropósito
@openclaw/sdkSDK público de alto nivel y cliente Gateway generado de bajo nivel.
@openclaw/sdk-reactHooks React opcionales para dashboards y creadores de apps.
@openclaw/sdk-testingHelpers de prueba y servidor Gateway falso para integraciones de apps.
El repo ya tiene openclaw/plugin-sdk/* para plugins. Mantén ese espacio de nombres separado para evitar confundir a autores de plugins con desarrolladores de apps.

​
Estrategia de cliente generado

El cliente de bajo nivel debería generarse a partir de esquemas versionados del protocolo de Gateway y luego envolverse con clases ergonómicas escritas manualmente. Capas:
  1. Esquema de Gateway como fuente de verdad.
  2. Cliente TypeScript de bajo nivel generado.
  3. Validadores en tiempo de ejecución para entradas externas y cargas útiles de eventos.
  4. Envoltorios de alto nivel OpenClaw, Agent, Session, Run, Task y Artifact.
  5. Ejemplos de recetario y pruebas de integración.
Beneficios:
  • la divergencia del protocolo es visible
  • las pruebas pueden comparar los métodos generados con las exportaciones de Gateway
  • el SDK de aplicaciones permanece independiente de los elementos internos del Plugin SDK
  • los consumidores de bajo nivel siguen teniendo acceso completo al protocolo
  • los consumidores de alto nivel obtienen la pequeña API del producto

​
Documentación relacionada