API Reference

This page documents the runtime-facing @clawjs/claw surface you use in application code. The exhaustive export inventory for @clawjs/claw and @clawjs/core lives in Public Surface.

Factories

import { Claw, createClaw } from "@clawjs/claw";

const claw = await Claw({
  runtime: {
    adapter: "openclaw",
  },
  workspace: {
    appId: "demo",
    workspaceId: "demo-main",
    agentId: "demo-main",
    rootDir: "./workspace",
  },
});

const same = await createClaw({
  runtime: { adapter: "openclaw" },
  workspace: {
    appId: "demo",
    workspaceId: "demo-main",
    agentId: "demo-main",
    rootDir: "./workspace",
  },
});

CreateClawOptions

Path	Description
runtime.adapter	Required runtime adapter id such as openclaw, demo, hermes, or ironclaw.
runtime.agentDir	Optional runtime agent directory override.
runtime.homeDir, configPath, workspacePath, authStorePath	Optional adapter-specific path overrides.
runtime.gateway	Optional gateway url, token, port, and configPath overrides.
runtime.env	Optional environment override passed to adapter commands.
workspace.appId	Stable application id persisted in the manifest.
workspace.workspaceId	Stable workspace id.
workspace.agentId	Stable agent id for runtime-specific state.
workspace.rootDir	Workspace root on disk.
templates.pack	Optional template-pack path applied during workspace initialization.

Instance Namespaces

Namespace	Methods
claw.runtime	context, status, gateway.*, install/uninstall/repair/setup methods, command builders, plan builders, OpenClaw context helpers
claw.workspace	init, attach, validate, repair, previewReset, reset, listManagedFiles, canonicalPaths, inspect
claw.files	template packs, binding sync, settings schema/value storage, workspace file read/write/preview/inspect, managed block helpers
claw.compat	refresh, read
claw.doctor	run
claw.models	list, catalog, getDefault, setDefault
claw.providers	list, catalog, authState
claw.auth	status, diagnostics, login, setApiKey, saveApiKey, removeProvider
claw.scheduler	list, run, enable, disable
claw.memory	list, search
claw.skills	list, sync
claw.channels	list
claw.telegram	secret provisioning, bot connection, webhook and polling control, commands, chat inspection, moderation, invite links, update sync
claw.inference	generateText
claw.secrets	list, describe, doctorKeychain, ensureHttpReference, ensureTelegramBotReference
claw.conversations	session CRUD, title generation, structured reply streaming, chunk streaming
claw.data	document, collection, asset, rootDir
claw.orchestration	snapshot
claw.watch	file, transcript, runtimeStatus, providerStatus, events, eventsIterator

Runtime

const status = await claw.runtime.status();
const context = claw.runtime.context();

await claw.runtime.install("npm");
await claw.runtime.setupWorkspace();

const gateway = await claw.runtime.gateway.status();
await claw.runtime.gateway.start();
await claw.runtime.gateway.waitUntilReady({ timeoutMs: 15_000 });

claw.runtime also exposes command builders and plan builders for install, uninstall, repair, and workspace setup:

claw.runtime.installCommand();
claw.runtime.uninstallCommand();
claw.runtime.repairCommand();
claw.runtime.setupWorkspaceCommand();

claw.runtime.installPlan();
claw.runtime.uninstallPlan();
claw.runtime.repairPlan();
claw.runtime.setupWorkspacePlan();

For OpenClaw-specific app-state management, the same namespace exposes discoverContext, migrateLegacyState, and detachWorkspace.

Workspace

await claw.workspace.init();
const manifest = await claw.workspace.attach();
const validation = await claw.workspace.validate();
const repaired = await claw.workspace.repair();
const resetPlan = await claw.workspace.previewReset({ removeConversations: true });
const resetResult = await claw.workspace.reset({ removeConversations: true });
const inspection = await claw.workspace.inspect();

inspect() returns both resolved workspace file paths and the parsed manifest, compat snapshot, observed snapshots, and the current intent/observed stores currently persisted in the workspace.

Intent, Observed, and Features

const allIntents = claw.intent.get();
const modelsIntent = claw.intent.get("models");
await claw.intent.patch("models", { defaultModel: "openai/gpt-5.4" });
await claw.intent.plan({ domains: ["models", "providers"] });
await claw.intent.apply({ domains: ["models", "providers"] });
const drift = await claw.intent.diff({ domains: ["models", "providers"] });

const observed = claw.observed.read();
await claw.observed.refresh({ domains: ["models", "providers", "channels"] });

const features = claw.features.describe();

Files

The file surface is documented in depth in Files & Templates. The runtime-facing methods are:

await claw.files.applyTemplatePack("/path/to/pack.json");

claw.files.diffBinding(binding, settings, render);
claw.files.syncBinding(binding, settings, render);

claw.files.readBindingStore();
claw.files.writeBindingStore(bindings);
claw.files.readSettingsSchema();
claw.files.writeSettingsSchema(schema);
claw.files.readSettingsValues();
claw.files.writeSettingsValues(values);
claw.files.validateSettings(values);
claw.files.renderTemplate(template, values);
claw.files.updateSettings(values, { autoSync: true, renderers });

claw.files.readWorkspaceFile("SOUL.md");
claw.files.writeWorkspaceFile("SOUL.md", nextContent);
claw.files.writeWorkspaceFilePreservingManagedBlocks("SOUL.md", nextContent);
claw.files.previewWorkspaceFile("SOUL.md", nextContent);
claw.files.inspectWorkspaceFile("SOUL.md");
claw.files.inspectManagedBlock("SOUL.md", "tone");
claw.files.mergeManagedBlocks(original, edited);

Models, Providers, and Auth

const providers = await claw.providers.list();
const providerCatalog = await claw.providers.catalog();
const authState = await claw.providers.authState();

const models = await claw.models.list();
const modelCatalog = await claw.models.catalog();
const defaultModel = await claw.models.getDefault();
await claw.models.setDefault("openai/gpt-4.1");

const summaries = await claw.auth.status();
const authDiagnostics = claw.auth.diagnostics("openai");
await claw.auth.login("openai", { setDefault: true });
claw.auth.setApiKey("openai", "sk-...", "default");
await claw.auth.saveApiKey("openai", "sk-...");
claw.auth.removeProvider("openai");

These auth operations also update the canonical provider intent under .clawjs/intents/providers.json, while observed auth summaries stay rebuildable under .clawjs/observed/providers.json.

Speech / TTS

const ttsConfig = claw.tts.config();

claw.tts.setConfig({
  provider: "openai",
  enabled: true,
  autoRead: true,
  voice: "nova",
  model: "tts-1",
});

await claw.intent.apply({ domains: ["speech"] });

Optional Runtime Subsystems

await claw.scheduler.list();
await claw.scheduler.run("daily-summary");
await claw.scheduler.enable("daily-summary");
await claw.scheduler.disable("daily-summary");

await claw.memory.list();
await claw.memory.search("incident");

await claw.skills.list();
await claw.skills.sync();

await claw.channels.list();

Always check status.capabilityMap before assuming these subsystems are supported by the current adapter.

Telegram and Secrets

await claw.telegram.provisionSecretReference({
  secretName: "my_bot_token",
  apiBaseUrl: "https://api.telegram.org",
});

await claw.telegram.connectBot({ secretName: "my_bot_token" });
await claw.telegram.status();
await claw.telegram.configureWebhook({ url: "https://example.com/telegram" });
await claw.telegram.disableWebhook();
await claw.telegram.startPolling({ timeoutSeconds: 30 });
await claw.telegram.stopPolling();
await claw.telegram.setCommands([{ command: "help", description: "Show help" }]);
await claw.telegram.getCommands();
await claw.telegram.listChats();
await claw.telegram.getChat(123);
await claw.telegram.getChatAdministrators(123);
await claw.telegram.getChatMember(123, 456);
await claw.telegram.setChatPermissions(123, { can_send_messages: false });
await claw.telegram.banOrRestrictMember({ action: "ban", chatId: 123, userId: 456 });
await claw.telegram.createInviteLink(123, { name: "Support" });
await claw.telegram.revokeInviteLink(123, "https://t.me/+...");
await claw.telegram.sendMessage({ chatId: 123, text: "hello" });
await claw.telegram.sendMedia({ type: "photo", chatId: 123, media: "https://..." });
await claw.telegram.syncUpdates();
await claw.telegram.ingestUpdate(updatePayload);

await claw.secrets.list("telegram");
await claw.secrets.describe("my_bot_token");
await claw.secrets.doctorKeychain();
await claw.secrets.ensureHttpReference({
  name: "service_token",
  allowedHosts: ["api.example.com"],
  allowedHeaderNames: ["Authorization"],
});
await claw.secrets.ensureTelegramBotReference({
  name: "my_bot_token",
  apiBaseUrl: "https://api.telegram.org",
});

Inference and Conversations

const result = await claw.inference.generateText({
  messages: [{ role: "user", content: "Summarize the repo." }],
  transport: "auto",
});

const session = claw.conversations.createSession("Repo tour");
claw.conversations.appendMessage(session.sessionId, {
  role: "user",
  content: "Explain the runtime layout.",
});

const loaded = claw.conversations.getSession(session.sessionId);
const sessions = claw.conversations.listSessions();
claw.conversations.updateSessionTitle(session.sessionId, "Runtime layout");
await claw.conversations.generateTitle({ sessionId: session.sessionId });

for await (const event of claw.conversations.streamAssistantReplyEvents({
  sessionId: session.sessionId,
  transport: "auto",
})) {
  if (event.type === "chunk") process.stdout.write(event.chunk.delta);
}

for await (const chunk of claw.conversations.streamAssistantReply({
  sessionId: session.sessionId,
})) {
  if (!chunk.done) process.stdout.write(chunk.delta);
}

Data Store and Orchestration

const preferences = claw.data.document("preferences");
preferences.write({ locale: "en" });
const saved = preferences.read();

const tasks = claw.data.collection("tasks");
tasks.put("build", { state: "queued" });
const allTasks = tasks.entries();

const asset = claw.data.asset("artifacts/report.txt");
asset.writeText("ready");

const orchestration = await claw.orchestration.snapshot();

The workspace data store is a simple file-backed storage layer for JSON documents, keyed collections, and raw assets rooted under the current workspace.

Watchers

The watcher surface is documented in depth in Watchers & Events. The instance-level methods are:

const stopFile = claw.watch.file("SOUL.md", (event) => {});
const stopTranscript = claw.watch.transcript("session-id", (event) => {});
const stopRuntime = claw.watch.runtimeStatus((status) => {});
const stopProviders = claw.watch.providerStatus((providers) => {});
const stopEvents = claw.watch.events("workspace.initialized", (event) => {});

for await (const event of claw.watch.eventsIterator("*")) {
  console.log(event.type, event.payload);
  break;
}

Contracts

The main runtime contracts come from @clawjs/core. The most important ones are RuntimeInfo, RuntimeCapabilityMap, ProviderDescriptor, ModelDescriptor, AuthState, SchedulerDescriptor, MemoryDescriptor, SkillDescriptor, ChannelDescriptor, Message, SessionRecord, TemplatePack, and BindingDefinition.