SDK de Aplicativo do OpenClaw

A OpenClaw App SDK é a API pública de cliente para apps fora do processo do OpenClaw. Use @openclaw/sdk quando um script, dashboard, tarefa de CI, extensão de IDE ou outro app externo quiser se conectar ao Gateway, iniciar execuções de agentes, transmitir eventos, aguardar resultados, cancelar trabalho ou inspecionar recursos do Gateway.

O que está disponível hoje

@openclaw/sdk inclui:

A SDK também exporta os tipos principais usados por essas superfícies: 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 e tipos de resultado relacionados.

Conectar a um Gateway

Crie um cliente com uma URL explícita do Gateway, ou injete um transporte customizado para testes e runtimes de apps incorporados.

 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://..." }) é equivalente a url. A opção gateway: "auto" é aceita pelo construtor, mas a descoberta automática de Gateway ainda não é um recurso separado da SDK; passe url quando o app ainda não souber como descobrir o Gateway.

Para testes, passe um objeto que implemente OpenClawTransport:

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

Executar um agente

Use oc.agents.get(id) quando o app quiser um handle de agente e então chame 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);

Referências de modelo qualificadas por provedor, como openai/gpt-5.5, são divididas em substituições provider e model do Gateway. timeoutMs permanece em milissegundos na SDK e é convertido para segundos de timeout do Gateway para o RPC agent.

run.wait() usa o RPC agent.wait do Gateway. Um prazo de espera que expira enquanto a execução ainda está ativa retorna status: "accepted" em vez de fingir que a própria execução atingiu timeout. Timeouts de runtime, execuções abortadas e execuções canceladas são normalizados para timed_out ou cancelled.

Criar e reutilizar sessões

Use sessões quando o app quiser estado durável de transcrição.

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() chama sessions.send e retorna um Run. Handles de sessão também oferecem suporte a:

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

Transmitir eventos

A SDK normaliza eventos brutos do Gateway em um envelope OpenClawEvent estável:

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

Tipos de eventos comuns incluem:

Run.events() filtra eventos para um id de execução e reproduz eventos já vistos para execuções rápidas. Isso significa que o fluxo documentado é seguro:

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

Para fluxos de todo o app, use oc.events(). Para frames brutos do Gateway, use oc.rawEvents().

Modelos, ferramentas, artefatos e aprovações

Os helpers de modelo mapeiam para métodos atuais do Gateway:

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

Helpers de ferramentas expõem o catálogo do Gateway, a visualização efetiva de ferramentas e a invocação direta de ferramentas do Gateway. oc.tools.invoke() retorna um envelope tipado em vez de lançar exceção para recusas por política ou aprovação.

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

Helpers de artefatos expõem a projeção de artefatos do Gateway para contexto de sessão, execução ou tarefa. Cada chamada exige um escopo explícito sessionKey, runId ou 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);}

Helpers de aprovação usam os RPCs de aprovação de exec:

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

Helpers de tarefas usam o ledger durável de tarefas que também sustenta 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" });

Helpers de ambiente expõem descoberta somente leitura local ao Gateway e de nó:

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

Explicitamente sem suporte hoje

A SDK inclui nomes para o modelo de produto que queremos, mas não finge silenciosamente que RPCs do Gateway existem. Atualmente, estas chamadas lançam erros explícitos de não suporte:

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

Os campos por execução workspace, runtime, environment e approvals são tipados como formato futuro, mas o Gateway atual não oferece suporte a essas substituições no RPC agent. Se os chamadores os passarem, a SDK lança erro antes de enviar a execução para que o trabalho não seja executado acidentalmente com comportamento padrão de workspace, runtime, ambiente ou aprovação.

App SDK vs Plugin SDK

Use a App SDK quando o código estiver fora do OpenClaw:

• scripts Node que iniciam ou observam execuções de agentes
• tarefas de CI que chamam um Gateway
• dashboards e painéis administrativos
• extensões de IDE
• pontes externas que não precisam se tornar plugins de canal
• testes de integração com transportes de Gateway falsos ou reais

Use a Plugin SDK quando o código roda dentro do OpenClaw:

• plugins de provedor
• plugins de canal
• hooks de ferramenta ou ciclo de vida
• plugins de harness de agente
• helpers de runtime confiável

Código da App SDK deve importar de @openclaw/sdk. Código de Plugin deve importar de subcaminhos documentados de openclaw/plugin-sdk/*. Não misture os dois contratos.

Relacionado

• Design da API do SDK de aplicativos OpenClaw
• Referência de RPC do Gateway
• Loop de agentes
• Runtimes de agentes
• Sessões
• Tarefas em segundo plano
• Agentes ACP
• Visão geral do SDK de Plugin