Pular para o conteúdo 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.

O SDK de Apps da OpenClaw é a API cliente pública para apps fora do processo da OpenClaw. Use @openclaw/sdk quando um script, painel, trabalho de CI, extensão de IDE ou outro app externo quiser se conectar ao Gateway, iniciar execuções de agente, transmitir eventos, aguardar resultados, cancelar trabalho ou inspecionar recursos do Gateway.
O SDK de Apps é diferente do Plugin SDK. @openclaw/sdk se comunica com o Gateway de fora da OpenClaw. openclaw/plugin-sdk/* é apenas para plugins que rodam dentro da OpenClaw e registram provedores, canais, ferramentas, hooks ou runtimes confiáveis.

​
O Que É Disponibilizado Hoje

@openclaw/sdk é disponibilizado com:
SuperfícieStatusO que faz
OpenClawProntoPonto de entrada principal do cliente. Gerencia transporte, conexão, solicitações e eventos.
GatewayClientTransportProntoTransporte WebSocket apoiado pelo cliente do Gateway.
oc.agentsProntoLista, cria, atualiza, exclui e obtém handles de agentes.
Agent.run()ProntoInicia uma execução agent do Gateway e retorna um Run.
oc.runsProntoCria, obtém, aguarda, cancela e transmite execuções.
Run.events()ProntoTransmite eventos normalizados por execução com replay para execuções rápidas.
Run.wait()ProntoChama agent.wait e retorna um RunResult estável.
Run.cancel()ProntoChama sessions.abort pelo id da execução, com chave de sessão quando disponível.
oc.sessionsProntoCria, resolve, envia para, aplica patches, compacta e obtém handles de sessão.
Session.send()ProntoChama sessions.send e retorna um Run.
oc.modelsProntoChama models.list e o RPC de status models.authStatus atual.
oc.toolsParcialLista o catálogo de ferramentas e ferramentas efetivas; a invocação direta de ferramentas não está conectada.
oc.approvalsProntoLista e resolve aprovações de execução por meio de RPCs de aprovação do Gateway.
oc.rawEvents()ProntoExpõe eventos brutos do Gateway para consumidores avançados.
normalizeGatewayEvent()ProntoConverte eventos brutos do Gateway para o formato de evento estável do SDK.
O SDK também exporta os tipos principais usados por essas superfícies: AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, 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 personalizado para testes e runtimes de apps embarcados. 
import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:14565",
  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 do Gateway ainda não é um recurso separado do 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 precisar de um handle de agente e, em seguida, 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 de provider e model do Gateway. timeoutMs permanece em milissegundos no 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 precisar de 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 aceitam: 
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

​
Transmitir Eventos

O 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 evento comuns incluem:
Tipo de eventoEvento de origem do Gateway
run.startedInício do ciclo de vida de agent
run.completedFim do ciclo de vida de agent
run.failedErro do ciclo de vida de agent
run.cancelledFim do ciclo de vida abortado/cancelado
run.timed_outFim do ciclo de vida por timeout
assistant.deltaDelta de streaming do assistente
assistant.messageMensagem do assistente
thinking.deltaFluxo de pensamento ou plano
tool.call.startedInício de ferramenta/item/comando
tool.call.deltaAtualização de ferramenta/item/comando
tool.call.completedConclusão de ferramenta/item/comando
tool.call.failedFalha ou status bloqueado de ferramenta/item/comando
approval.requestedSolicitação de aprovação de execução ou Plugin
approval.resolvedResolução de aprovação de execução ou Plugin
session.createdCriação de sessions.changed
session.updatedAtualização de sessions.changed
session.compactedCompaction de sessions.changed
task.updatedEventos de atualização de tarefa
artifact.updatedEventos de fluxo de patch
rawQualquer evento ainda sem um mapeamento estável do SDK
Run.events() filtra eventos para um único 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 E Aprovações

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 ferramenta expõem o catálogo do Gateway e a visualização de ferramentas efetivas: 
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
Helpers de aprovação usam os RPCs de aprovação de execução: 
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });

​
Explicitamente Sem Suporte Hoje

O 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 falta de suporte: 
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");

await oc.tools.invoke("tool-name", {});

await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");

await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");
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 chamadores os passarem, o SDK lança erro antes de enviar a execução para que o trabalho não seja executado acidentalmente com o comportamento padrão de workspace, runtime, ambiente ou aprovação.

​
SDK de Apps Versus Plugin SDK

Use o SDK de Apps quando o código estiver fora da OpenClaw:
  • scripts Node que iniciam ou observam execuções de agente
  • trabalhos de CI que chamam um Gateway
  • painéis 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 Gateway falsos ou reais
Use o Plugin SDK quando o código roda dentro da 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 do SDK de Apps deve importar de @openclaw/sdk. Código de Plugin deve importar dos subcaminhos documentados de openclaw/plugin-sdk/*. Não misture os dois contratos.

​
Documentação Relacionada