OpenClaw 面经

📖 "One Gateway per host; it is the only place that opens a WhatsApp session." — Gateway architecture

📖 "Exactly one Gateway controls a single Baileys session per host." — Gateway architecture

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

// src/gateway/server/http-listen.ts · L56-L67
      if (code === "EADDRINUSE" && attempt < maxRetries) {
        // Port may still be in TIME_WAIT after a recent process exit; retry.
        await closeServerQuietly(httpServer);
        await sleep(EADDRINUSE_RETRY_INTERVAL_MS);
        continue;
      }
      if (code === "EADDRINUSE") {
        throw new GatewayLockError(
          `another ${serviceName} instance is already listening on ${endpointScheme}://${bindHost}:${port}`,
          err,
        );
      }

// src/gateway/role-policy.ts · L11-L16
export function parseGatewayRole(roleRaw: unknown): GatewayRole | null {
  if (roleRaw === "operator" || roleRaw === "node") {
    return roleRaw;
  }
  return null;
}

📎 src/gateway/server.impl.ts · startGatewayServer — 源码

📎 src/gateway/server/http-listen.ts · GatewayLockError — 源码

📎 src/gateway/role-policy.ts · parseGatewayRole — 源码

📖 "First frame must be connect." — Gateway architecture

📖 "Handshake is mandatory; any non-JSON or non-connect first frame is a hard close." — Gateway architecture

📖 "Events are not replayed; clients must refresh on gaps." — Gateway architecture

sequenceDiagram
    participant Client
    participant Gateway
    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok) hello-ok
    Gateway-->>Client: event:presence / event:tick
    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent (streaming)
    Gateway-->>Client: res:agent final {runId, status, summary}

// src/gateway/server/ws-connection/message-handler.ts · L184-L324
  const handleMessage = async (data: RawData) => {
    if (isClosed()) {
      return;
    }
    // ...
        if (
          !isRequestFrame ||
          parsed.method !== "connect" ||
          !validateConnectParams(parsed.params)
        ) {
          const handshakeError = isRequestFrame
            ? parsed.method === "connect"
              ? `invalid connect params: ${formatValidationErrors(validateConnectParams.errors)}`
              : "invalid handshake: first request must be connect"
            : "invalid request frame";
    // ...
          return;
        }

// src/gateway/server-methods/agent-dedupe.ts · L5-L15
export function resolveAgentDedupeKeys(params: {
  idempotencyKey: string;
  execApprovalFollowupApprovalId?: string;
}): string[] {
  const keys = [`agent:${params.idempotencyKey}`];
  const approvalId = params.execApprovalFollowupApprovalId?.trim();
  if (approvalId) {
    keys.push(`agent:exec-approval-followup:${approvalId}`);
  }
  return uniqueStrings(keys);
}

📎 src/gateway/server/ws-connection/message-handler.ts · handleMessage — 源码

📎 src/gateway/server-methods/agent-dedupe.ts · resolveAgentDedupeKeys — 源码

📎 src/gateway/server-chat.ts · handleEvent — 源码

📖 "An agent runtime owns one prepared model loop: it receives the prompt," — Agent runtimes

📖 "A harness is the implementation that provides an agent runtime (code" — Agent runtimes

{
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
    },
  },
}

// src/agents/acp-runtime-overlay.ts · L10-L13
export type AgentRuntimeMetadata = {
  id: string;
  source: "implicit" | "model" | "provider" | "session" | "session-key";
};

// src/agents/model-runtime-policy.ts · L243-L300
export function resolveModelRuntimePolicy(params: {
  config?: OpenClawConfig;
  provider?: string;
  modelId?: string;
  agentId?: string;
  sessionKey?: string;
}): ResolvedModelRuntimePolicy {
  // ...
  if (hasRuntimePolicy(modelConfig?.agentRuntime)) {
    return {
      policy: modelConfig?.agentRuntime,
      source: "model",
      ...(inferredMatchedProvider ? { matchedProvider: inferredMatchedProvider } : {}),
    };
  }
  // ...
  if (hasRuntimePolicy(providerConfig?.agentRuntime)) {
    return {
      policy: providerConfig?.agentRuntime,
      source: "provider",
      ...(inferredMatchedProvider ? { matchedProvider: inferredMatchedProvider } : {}),
    };
  }
  return {};
}

📎 src/agents/acp-runtime-overlay.ts · AgentRuntimeMetadata — 源码

📎 src/agents/model-runtime-policy.ts · resolveModelRuntimePolicy — 源码

📖 "Model-scoped runtime policy wins." — Agent runtimes

📖 "Explicit provider/model plugin runtimes fail closed:" — Agent runtimes

📖 "claude-cli is not an embedded harness id and must not" — Agent runtimes

{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-8",
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

// src/agents/harness/selection.ts · L257-L360
function selectAgentHarnessDecision(
  params: AgentHarnessSelectionDecisionParams,
): AgentHarnessSelectionDecision {
  // ...
  // OpenClaw's built-in harness is intentionally not part of the plugin candidate list. Explicit plugin
  // runtimes fail closed; only `auto` may route an unmatched turn to OpenClaw.
  // ...
      throw new Error(
        `Requested agent harness "${runtime}" does not support ${formatProviderModel(params)}${
          support.reason ? ` (${support.reason})` : ""
        }.`,
      );
    }

// src/agents/model-runtime-aliases.ts · L39-L49
export function isCliRuntimeAliasForProvider(params: {
  runtime: string | undefined;
  provider: string | undefined;
  cfg?: OpenClawConfig;
}): boolean {
  return isCliRuntimeModelBackendForProvider({
    provider: params.provider,
    runtime: params.runtime,
    config: params.cfg,
  });
}

📎 src/agents/harness/selection.ts · selectAgentHarnessDecision — 源码

📎 src/agents/harness/policy.ts · resolveAgentHarnessPolicy — 源码

📎 src/agents/model-runtime-aliases.ts · isCliRuntimeAliasForProvider — 源码

📖 "New device IDs require pairing approval; the Gateway issues a device token" — Gateway architecture

📖 "Non-local connects still require explicit approval." — Gateway architecture

📖 "All connects must sign the connect.challenge nonce." — Gateway architecture

// src/gateway/server/ws-connection/handshake-auth-helpers.ts · L81-L119
export function shouldAllowSilentLocalPairing(params: {
  locality: PairingLocalityKind;
  hasBrowserOriginHeader: boolean;
  isControlUi: boolean;
  isWebchat: boolean;
  isNativeAppUi?: boolean;
  reason: "not-paired" | "role-upgrade" | "scope-upgrade" | "metadata-upgrade";
}): boolean {
  if (params.locality === "remote") {
    return false;
  }
  // ...
  return false;
}

// src/gateway/server/ws-connection/handshake-auth-helpers.ts · L330-L367
export function resolveDeviceSignaturePayloadVersion(params: {
  // ...
  const basePayload = {
    deviceId: params.device.id,
    clientId: params.connectParams.client.id,
    clientMode: params.connectParams.client.mode,
    role: params.role,
    scopes: params.scopes,
    signedAtMs: params.signedAtMs,
    token: signatureToken,
    nonce: params.nonce,
  };
  const payloadV3 = buildDeviceAuthPayloadV3({
    ...basePayload,
    platform: params.connectParams.client.platform,
    deviceFamily: params.connectParams.client.deviceFamily,
  });
  if (verifyDeviceSignature(params.device.publicKey, payloadV3, params.device.signature)) {
    return "v3";
  }
  // ...
  return null;
}

📎 src/gateway/server/ws-connection/connect-device-pairing.ts · authorizeGatewayConnectDevice — 源码

📎 src/gateway/server/ws-connection/handshake-auth-helpers.ts · shouldAllowSilentLocalPairing — 源码

📎 src/gateway/server/ws-connection/handshake-auth-helpers.ts · resolveDeviceSignaturePayloadVersion — 源码

📖 "On the first turn of a new session, OpenClaw injects the contents of these files into the system prompt's Project Context." — Agent runtime

📖 "Blank files are skipped." — Agent runtime

📖 "BOOTSTRAP.md is only created for a brand new workspace (no other bootstrap files present)." — Agent runtime

{ agents: { defaults: { skipBootstrap: true } } }

// src/agents/workspace.ts · L1078-L1143
export async function loadWorkspaceBootstrapFiles(dir: string): Promise<WorkspaceBootstrapFile[]> {
  // ...
  const result: WorkspaceBootstrapFile[] = [];
  for (const entry of entries) {
    if (
      entry.name === DEFAULT_MEMORY_FILENAME &&
      !(await exactWorkspaceEntryExists(resolvedDir, DEFAULT_MEMORY_FILENAME))
    ) {
      continue;
    }
    // ...
    } else {
      result.push({ name: entry.name, path: entry.filePath, missing: true });
    }
  }
  return result;
}

// src/agents/workspace.ts · L235-L249
export class WorkspaceVanishedError extends Error {
  readonly code = WORKSPACE_VANISHED_ERROR_CODE;
  readonly workspaceDir: string;
  readonly attestationPath: string;

  constructor(params: { workspaceDir: string; attestationPath: string }) {
    super(
      `OpenClaw workspace appears to have disappeared after a recent initialization: ${params.workspaceDir}. ` +
        `Refusing to reseed BOOTSTRAP.md over a recently attested workspace. ` +
        `Restore the workspace or remove ${params.attestationPath} if this reset was intentional.`,
    );
    this.name = "WorkspaceVanishedError";
    this.workspaceDir = params.workspaceDir;
    this.attestationPath = params.attestationPath;
  }

📎 src/agents/workspace.ts · loadWorkspaceBootstrapFiles — 源码

📎 src/agents/embedded-agent-helpers/bootstrap.ts · buildBootstrapContextFiles — 源码

📎 src/agents/workspace.ts · WorkspaceVanishedError — 源码

📖 "These surfaces are intentionally independent." — Agent runtimes

📖 "Design rule: if OpenClaw owns the surface, it can provide normal plugin hook" — Agent runtimes

// src/agents/openai-routing.ts · L37-L81
/** Resolves the provider-owned implicit runtime for one concrete OpenAI route. */
export function resolveOpenAIImplicitAgentRuntime(params: {
  // ...
}): "codex" | "openclaw" | null {
  if (!isOpenAIProvider(params.provider)) {
    return null;
  }
  // ...
  if (!resolution) {
    // Endpoint and adapter ownership stays in the provider artifact. Without
    // that policy, keep credentials and traffic on the core OpenClaw runtime.
    return "openclaw";
  }
  return resolution.kind !== "incompatible" && resolution.defaultRuntimeId === "codex"
    ? "codex"
    : "openclaw";
}

// src/context-engine/host-compat.ts · L35-L47
export const CODEX_APP_SERVER_CONTEXT_ENGINE_HOST = {
  id: "codex-app-server",
  label: "Codex app-server harness",
  capabilities: [
    "bootstrap",
    "assemble-before-prompt",
    "after-turn",
    "maintain",
    "compact",
    "runtime-llm-complete",
    "thread-bootstrap-projection",
  ],
} as const satisfies ContextEngineHostSupport;

📎 src/agents/openai-routing.ts · resolveOpenAIImplicitAgentRuntime — 源码

📎 src/context-engine/host-compat.ts · CODEX_APP_SERVER_CONTEXT_ENGINE_HOST — 源码

📎 src/agents/command/cli-compaction.ts · CODEX_APP_SERVER_OWNS_AUTO_COMPACTION_REASON — 源码

flowchart LR
  A[agent RPC 校验/解析 session] -->|立即返回 runId| B[agentCommand 解析 model/skills]
  B --> C[runEmbeddedAgent 串行队列+订阅事件]
  C --> D[stream: assistant/tool/lifecycle]
  D --> E[agent.wait 等待 end/error]

📖 "1. agent RPC validates params, resolves the session (sessionKey/sessionId), persists session metadata, and returns { runId, acceptedAt } immediately." — Agent loop

📖 "5. agent.wait (waitForAgentRun) waits for lifecycle end/error on a runId and returns { status: ok|error|timeout, startedAt, endedAt, error? }." — Agent loop

{ "status": "timeout", "startedAt": 1700000000000, "endedAt": null }

// src/agents/run-wait.ts · L362-L386
export async function waitForAgentRun(params: {
  runId: string;
  timeoutMs: number;
  callGateway?: GatewayCaller;
}): Promise<AgentWaitResult> {
  const timeoutMs = resolveRunWaitTimeoutMs(params.timeoutMs);
  try {
    const wait = await (params.callGateway ?? callGateway)({
      method: "agent.wait",
      params: {
        runId: params.runId,
        timeoutMs,
      },
      timeoutMs: addTimerTimeoutGraceMs(timeoutMs, 2_000),
    });
    if (wait?.status === "timeout") {
      return normalizeAgentWaitResult("timeout", wait);
    }
    if (wait?.status === "pending") {
      return normalizeAgentWaitResult("pending", wait);
    }
    if (wait?.status === "error") {
      return normalizeAgentWaitResult("error", wait);
    }
    return normalizeAgentWaitResult("ok", wait);

// src/agents/embedded-agent-runner/run-orchestrator.ts · L52-L73
export function runEmbeddedAgent(
  paramsInput: RunEmbeddedAgentParams,
): Promise<EmbeddedAgentRunResult> {
  const internalParamsInput = paramsInput as RunEmbeddedAgentInternalParams;
  const requestedProvider = normalizeOptionalString(internalParamsInput.provider);
  const requestedModel = normalizeOptionalString(internalParamsInput.model);
  const needsConfiguredDefault =
    !internalParamsInput.config && !requestedProvider && !requestedModel;
  const config =
    internalParamsInput.config ??
    (needsConfiguredDefault ? (getRuntimeConfigSnapshot() ?? undefined) : undefined);
  const lifecycleGeneration =
    internalParamsInput.lifecycleGeneration ??
    captureAgentRunLifecycleGeneration(internalParamsInput.runId);
  return withAgentRunLifecycleGeneration(lifecycleGeneration, () =>
    runEmbeddedAgentInternal({
      ...internalParamsInput,
      config,
      lifecycleGeneration,
    }),
  );
}

📎 src/agents/run-wait.ts · waitForAgentRun — 源码

📎 src/agents/embedded-agent-runner/run-orchestrator.ts · runEmbeddedAgent — 源码

📖 "When a run is already active, inbound messages steer into it by default. messages.queue controls the mode:" — Messages

📖 "Defaults: messages.queue.debounceMs is 500ms (applies to steer, followup, and collect batching alike), messages.queue.cap is 20 queued messages, and messages.queue.drop is summarize (old and new are also available). Configure per-channel overrides via messages.queue.byChannel and messages.queue.debounceMsByChannel." — Messages

{
  messages: {
    queue: { mode: "interrupt", cap: 20, drop: "summarize" },
  },
}

// src/gateway/server-methods/sessions-messaging.ts · L185-L205
  if (hasEmbeddedRun && params.sessionId) {
    abortEmbeddedAgentRun(params.sessionId);
  }

  // Clear queued follow-up work for both requested aliases and the canonical session id.
  clearSessionQueues([params.requestedKey, params.canonicalKey, params.sessionId]);

  if (hasEmbeddedRun && params.sessionId) {
    const ended = await waitForEmbeddedAgentRunEnd(params.sessionId, 15_000);
    if (!ended) {
      return {
        interrupted: true,
        error: errorShape(
          ErrorCodes.UNAVAILABLE,
          `Session ${params.requestedKey} is still active; try again in a moment.`,
        ),
      };
    }
  }

  return { interrupted: true };

// src/agents/lanes.ts · L26-L32
export function resolveNestedAgentLaneForSession(sessionKey: string | undefined): string {
  const trimmed = sessionKey?.trim();
  if (!trimmed) {
    return AGENT_LANE_NESTED;
  }
  return `${NESTED_LANE_PREFIX}${trimmed}`;
}

📎 src/gateway/server-methods/sessions-messaging.ts · interruptSessionRunIfActive — 源码

📎 src/agents/lanes.ts · resolveNestedAgentLaneForSession — 源码

📖 "Sessions are owned by the gateway, not by clients." — Messages

📖 dmScope: "per-channel-peer", // isolate by channel + sender — Session management

{
  session: {
    dmScope: "per-channel-peer", // isolate by channel + sender
  },
}

// src/routing/session-key.ts · L218-L233
    if (dmScope === "per-account-channel-peer" && peerId) {
      const channel = normalizeLowercaseStringOrEmpty(params.channel) || "unknown";
      const accountId = normalizeAccountId(params.accountId);
      return `agent:${normalizeAgentId(params.agentId)}:${channel}:${accountId}:direct:${peerId}`;
    }
    if (dmScope === "per-channel-peer" && peerId) {
      const channel = normalizeLowercaseStringOrEmpty(params.channel) || "unknown";
      return `agent:${normalizeAgentId(params.agentId)}:${channel}:direct:${peerId}`;
    }
    if (dmScope === "per-peer" && peerId) {
      return `agent:${normalizeAgentId(params.agentId)}:direct:${peerId}`;
    }
    return buildAgentMainSessionKey({
      agentId: params.agentId,
      mainKey: params.mainKey,
    });

// src/routing/session-key.ts · L273-L288
  for (const [canonical, ids] of Object.entries(identityLinks)) {
    const canonicalName = canonical.trim();
    if (!canonicalName) {
      continue;
    }
    if (!Array.isArray(ids)) {
      continue;
    }
    for (const id of ids) {
      const normalized = normalizeToken(id);
      if (normalized && candidates.has(normalized)) {
        return canonicalName;
      }
    }
  }
  return null;

📎 src/routing/session-key.ts · buildAgentPeerSessionKey — 源码

📎 src/routing/session-key.ts · resolveLinkedPeerId — 源码

📖 "Transcript writes are additionally protected by a session write lock on the session file. The lock is process-aware and file-based, so it catches writers that bypass the in-process queue or come from another process. Writers wait up to session.writeLock.acquireTimeoutMs (default 60000 ms; env override OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS) before reporting the session as busy." — Agent loop

📖 "Session write locks are non-reentrant by default. A helper that intentionally nests acquisition of the same lock while preserving one logical writer must opt in with allowReentrant: true." — Agent loop

export OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS=120000

// src/agents/session-write-lock.ts · L51-L56
const DEFAULT_SESSION_WRITE_LOCK_STALE_MS = 30 * 60 * 1000;
const DEFAULT_SESSION_WRITE_LOCK_MAX_HOLD_MS = 5 * 60 * 1000;
const DEFAULT_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS = 60_000;
const ABORTABLE_SESSION_WRITE_LOCK_POLL_MS = 100;
const DEFAULT_WATCHDOG_INTERVAL_MS = 60_000;
const DEFAULT_TIMEOUT_GRACE_MS = 2 * 60 * 1000;

// src/agents/session-write-lock.ts · L924-L936
  const allowReentrant = params.allowReentrant ?? false;
  const defaultOptions = resolveSessionWriteLockOptions();
  const timeoutMs = resolvePositiveMs(params.timeoutMs, defaultOptions.timeoutMs, {
    allowInfinity: true,
  });
  const staleMs = resolvePositiveMs(params.staleMs, defaultOptions.staleMs);
  const maxHoldMs = resolvePositiveMs(params.maxHoldMs, defaultOptions.maxHoldMs);
  const orphanPayloadGraceMs = resolveOrphanLockPayloadGraceMs(timeoutMs);
  const sessionFile = resolveSessionWriteLockTarget(params.sessionFile);
  const sessionDir = path.dirname(sessionFile);
  const normalizedSessionFile = await resolveNormalizedSessionFile(sessionFile);
  const lockPath = `${normalizedSessionFile}.lock`;
  await fs.mkdir(sessionDir, { recursive: true });

📎 src/agents/session-write-lock.ts · DEFAULT_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS — 源码

📎 src/agents/session-write-lock.ts · acquireSessionWriteLock — 源码

📖 "When both daily and idle resets are configured, whichever expires first wins." — Session management

📖 "- sessionStartedAt: when the current sessionId began; daily reset uses this." — Session management

📖 "- lastInteractionAt: last user/channel interaction that extends idle lifetime." — Session management

{
  session: {
    reset: { mode: "daily", atHour: 4 },
    resetByType: {
      group: { mode: "idle", idleMinutes: 120 },
      thread: { mode: "daily", atHour: 6 },
    },
  },
}

// src/agents/command/session.ts · L433-L450
  const fresh = sessionEntry
    ? lockedModelSelection ||
      (!terminalMainTranscriptNewerThanRegistry &&
        (skipImplicitExpiry ||
          evaluateSessionFreshness({
            updatedAt: sessionEntry.updatedAt,
            ...resolveSessionLifecycleTimestamps({
              entry: sessionEntry,
              agentId: sessionAgentId,
              storePath,
            }),
            now,
            policy: resetPolicy,
          }).fresh))
    : false;
  const sessionId =
    requestedSessionId || (fresh ? sessionEntry?.sessionId : undefined) || crypto.randomUUID();
  const isNewSession = !fresh && !requestedSessionId;

// src/agents/command/session.ts · L63-L92
export function clearRotatedSessionMetadata(entry: SessionEntry): SessionEntry {
  const next = {
    ...entry,
    sessionFile: undefined,
    // ...
    sessionStartedAt: undefined,
    lastInteractionAt: undefined,
  };

📎 src/agents/command/session.ts · resolveSession — 源码

📎 src/agents/command/session.ts · clearRotatedSessionMetadata — 源码

📖 "Channels can redeliver the same message after a reconnect. OpenClaw keeps an in-memory cache keyed by agent scope, channel route (channel + peer + account + thread), and message id, so a redelivered message does not trigger a second agent run. The cache entry expires after 20 minutes or once 5000 entries are tracked, whichever comes first." — Messages

📖 "- Control commands (stop/abort/status, etc.) bypass debouncing so they dispatch immediately." — Messages

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        discord: 1500,
        slack: 1500,
        whatsapp: 5000,
      },
    },
  },
}

// src/gateway/server-methods/agent-dedupe.ts · L5-L15
export function resolveAgentDedupeKeys(params: {
  idempotencyKey: string;
  execApprovalFollowupApprovalId?: string;
}): string[] {
  const keys = [`agent:${params.idempotencyKey}`];
  const approvalId = params.execApprovalFollowupApprovalId?.trim();
  if (approvalId) {
    keys.push(`agent:exec-approval-followup:${approvalId}`);
  }
  return uniqueStrings(keys);
}

// src/gateway/server-methods/agent-dedupe.ts · L17-L28
export function readGatewayDedupeEntry(params: {
  dedupe: GatewayRequestContext["dedupe"];
  keys: readonly string[];
}) {
  for (const key of params.keys) {
    const entry = params.dedupe.get(key);
    if (entry) {
      return entry;
    }
  }
  return undefined;
}

📎 src/gateway/server-methods/agent-dedupe.ts · resolveAgentDedupeKeys — 源码

📎 src/gateway/server-methods/agent-dedupe.ts · readGatewayDedupeEntry — 源码

📖 "The silent token NO_REPLY (case-insensitive, so no_reply also matches) means \"do not deliver a user-visible reply.\" When a turn also has pending tool media, such as generated TTS audio, OpenClaw strips the silent text but still delivers the media attachment." — Messages

📖 "- Direct conversations never receive NO_REPLY prompt guidance. If a direct run accidentally returns a bare silent token, OpenClaw suppresses it instead of rewriting or delivering it." — Messages

模型输出: NO_REPLY  (文本被剥离)
最终投递: 仅 TTS 音频附件

// src/agents/subagent-announce.ts · L147-L166
function stripAndClassifyReply(text: string): string | null {
  let result = text;
  let didStrip = false;
  const hasLeadingSilentToken = startsWithSilentToken(result, SILENT_REPLY_TOKEN);
  if (hasLeadingSilentToken) {
    result = stripLeadingSilentToken(result, SILENT_REPLY_TOKEN);
    didStrip = true;
  }
  if (hasLeadingSilentToken || result.toLowerCase().includes(SILENT_REPLY_TOKEN.toLowerCase())) {
    result = stripSilentToken(result, SILENT_REPLY_TOKEN);
    didStrip = true;
  }
  if (
    didStrip &&
    (!result.trim() || isSilentReplyText(result, SILENT_REPLY_TOKEN) || isAnnounceSkip(result))
  ) {
    return null;
  }
  return result;
}

📎 src/agents/subagent-announce.ts · stripAndClassifyReply — 源码

📖 "\"Context\" is everything OpenClaw sends to the model for a run. It is bounded by the model's context window (token limit)." — Context

📖 "Context is _not the same thing_ as \"memory\": memory can be stored on disk and reloaded later; context is what's inside the model's current window." — Context

📖 "Everything the model receives counts, including:" — Context

🧠 Context breakdown
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Session tokens (cached): 14,250 total / ctx=32,000

// src/agents/system-prompt-report.ts · L127-L128
  const toolsEntries = buildToolsEntries(params.tools);
  const toolsSchemaChars = toolsEntries.reduce((sum, t) => sum + (t.schemaChars ?? 0), 0);

// src/agents/system-prompt-report.ts · L159-L163
    tools: {
      listChars: 0,
      schemaChars: toolsSchemaChars,
      entries: toolsEntries,
    },

📎 src/agents/system-prompt-report.ts · buildSystemPromptReport — 源码

📖 "Every model has a context window: the maximum number of tokens it can process. When a conversation approaches that limit, OpenClaw compacts older messages into a summary so the chat can continue." — Compaction

📖 "The full conversation history stays on disk. Compaction only changes what the model sees on the next turn." — Compaction

📖 "Auto-compaction is on by default. It runs when the session nears the context limit, or when the model returns a context-overflow error (in which case OpenClaw compacts and retries)." — Compaction

📖 "Session pruning is a lighter-weight complement that trims tool output without summarizing." — Compaction

/compact Focus on the API design decisions

// src/agents/embedded-agent-helpers/provider-error-patterns.ts · L24-L47
const PROVIDER_CONTEXT_OVERFLOW_PATTERNS: readonly RegExp[] = [
  // AWS Bedrock validation / stream errors use provider-specific wording.
  /\binput token count exceeds the maximum number of input tokens\b/i,
  /\binput is too long for this model\b/i,

  // Google Vertex / Gemini REST surfaces this wording.
  /\binput exceeds the maximum number of tokens\b/i,

  // Ollama may append a provider prefix and extra token wording.
  /\bollama error:\s*context length exceeded(?:,\s*too many tokens)?\b/i,
// ...
];

📎 src/agents/embedded-agent-helpers/provider-error-patterns.ts · PROVIDER_CONTEXT_OVERFLOW_PATTERNS — 源码

📖 "A context engine controls how OpenClaw builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries." — Context engine

📖 "Every time OpenClaw runs a model prompt, the context engine participates at four lifecycle points:" — Context engine

📖 "OpenClaw ships with a built-in legacy engine and uses it by default." — Context engine

flowchart LR
  A[新消息到达] -->|Ingest| B[引擎存储/索引]
  B -->|Assemble| C[按 tokenBudget 返回有序消息 + systemPromptAddition]
  C --> D[模型运行]
  D -->|Compact 窗口满或 /compact| E[总结旧历史]
  D -->|After turn| F[持久化状态 / 后台压缩 / 更新索引]

// src/context-engine/types.ts · L64-L71
export type ContextEngineHostCapability =
  | "bootstrap"
  | "assemble-before-prompt"
  | "after-turn"
  | "maintain"
  | "compact"
  | "runtime-llm-complete"
  | "thread-bootstrap-projection";

// src/context-engine/types.ts · L7-L29
export type AssembleResult = {
  /** Ordered messages to use as model context */
  messages: AgentMessage[];
  /** Estimated total tokens in assembled context */
  estimatedTokens: number;
// ...
  /** Optional context-engine-provided instructions prepended to the runtime system prompt */
  systemPromptAddition?: string;

📎 src/context-engine/types.ts · ContextEngineHostCapability — 源码

📎 src/context-engine/types.ts · AssembleResult — 源码

📖 "ownsCompaction controls whether OpenClaw runtime's built-in in-attempt auto-compaction stays enabled for the run:" — Context engine

📖 "ownsCompaction: false does not mean OpenClaw automatically falls back to the legacy engine's compaction path." — Context engine

📖 "A no-op compact() is unsafe for an active non-owning engine because it disables the normal /compact and overflow-recovery compaction path for that engine slot." — Context engine

async compact({ sessionId, force }) {
  // Delegating mode: 复用 OpenClaw 内置压缩,而非自研算法
  return delegateCompactionToRuntime(/* ... */);
}

// src/context-engine/types.ts · L193-L198
export type ContextEngineInfo = {
  id: string;
  name: string;
  version?: string;
  /** True when the engine manages its own compaction lifecycle. */
  ownsCompaction?: boolean;

// src/context-engine/legacy.ts · L72-L85
  async compact(params: {
    sessionId: string;
    sessionKey: string;
    agentId?: string;
    sessionTarget?: ContextEngineSessionTarget;
    tokenBudget?: number;
    force?: boolean;
    currentTokenCount?: number;
    compactionTarget?: "budget" | "threshold";
    customInstructions?: string;
    runtimeContext?: ContextEngineRuntimeContext;
  }): Promise<CompactResult> {
    return await delegateCompactionToRuntime(params);
  }

📎 src/context-engine/types.ts · ownsCompaction — 源码

📎 src/context-engine/legacy.ts · delegateCompactionToRuntime — 源码

📖 "The system prompt is OpenClaw-owned and rebuilt each run." — Context

📖 "/context prefers the latest run-built system prompt report when available:" — Context

/status          # 窗口有多满 + 会话设置
/context list    # 注入了什么 + 粗略大小
/context detail  # 逐文件/逐 tool schema/逐 skill 的深度拆分
/context map     # treemap 图像

// src/agents/embedded-agent-helpers/bootstrap.ts · L91-L130
const DEFAULT_BOOTSTRAP_MAX_CHARS = 20_000;
const DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS = 60_000;
// ...
export function resolveBootstrapMaxChars(cfg?: OpenClawConfig, agentId?: string | null): number {
  const raw =
    cfg && agentId
      ? (resolveAgentConfig(cfg, agentId)?.bootstrapMaxChars ??
        cfg.agents?.defaults?.bootstrapMaxChars)
      : cfg?.agents?.defaults?.bootstrapMaxChars;
  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
    return Math.floor(raw);
  }
  return DEFAULT_BOOTSTRAP_MAX_CHARS;
}

📎 src/agents/embedded-agent-helpers/bootstrap.ts · resolveBootstrapMaxChars — 源码

📖 "By default, compaction uses the agent's primary model." — Compaction

📖 "When unset, compaction starts with the active session model." — Compaction

📖 "Before compaction, OpenClaw can run a silent memory flush turn to store durable notes to disk." — Compaction

{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

// src/agents/sessions/settings-manager.ts · L683-L693
  getCompactionKeepRecentTokens(): number {
    return this.settings.compaction?.keepRecentTokens ?? 20000;
  }

  getCompactionSettings(): { enabled: boolean; reserveTokens: number; keepRecentTokens: number } {
    return {
      enabled: this.getCompactionEnabled(),
      reserveTokens: this.getCompactionReserveTokens(),
      keepRecentTokens: this.getCompactionKeepRecentTokens(),
    };
  }

// src/agents/compaction.ts · L92-L104
function resolveIdentifierPreservationInstructions(
  instructions?: CompactionSummarizationInstructions,
): string | undefined {
  const policy = instructions?.identifierPolicy ?? "strict";
  if (policy === "off") {
    return undefined;
  }
  if (policy === "custom") {
    const custom = instructions?.identifierInstructions?.trim();
    return custom && custom.length > 0 ? custom : IDENTIFIER_PRESERVATION_INSTRUCTIONS;
  }
  return IDENTIFIER_PRESERVATION_INSTRUCTIONS;
}

📎 src/agents/sessions/settings-manager.ts · getCompactionKeepRecentTokens — 源码

📎 src/agents/compaction.ts · resolveIdentifierPreservationInstructions — 源码

📖 "OpenClaw remembers things by writing plain Markdown files in your agent's" — Memory overview

📖 "saved to disk; there is no hidden state." — Memory overview

Remember that I prefer TypeScript.

// src/memory/root-memory-files.ts · L5-L14
/** Canonical root memory file name used by current workspaces. */
export const CANONICAL_ROOT_MEMORY_FILENAME = "MEMORY.md";
/** Legacy root memory file name kept out of auxiliary scans. */
export const LEGACY_ROOT_MEMORY_FILENAME = "memory.md";
const ROOT_MEMORY_REPAIR_RELATIVE_DIR = ".openclaw-repair/root-memory";

/** Resolves the canonical root memory file path for a workspace. */
export function resolveCanonicalRootMemoryPath(workspaceDir: string): string {
  return path.join(workspaceDir, CANONICAL_ROOT_MEMORY_FILENAME);
}

📎 src/memory/root-memory-files.ts · CANONICAL_ROOT_MEMORY_FILENAME — 源码

📖 "When an embedding provider is configured, memory_search uses hybrid search:" — Memory overview

📖 "OpenClaw runs two retrieval paths in parallel and merges the results:" — Memory search

📖 "Explicit provider unavailable. If you name any other provider explicitly" — Memory search

flowchart LR
    Q["Query"] --> E["Embedding"]
    Q --> T["Tokenize"]
    E --> VS["Vector search"]
    T --> BM["BM25 search"]
    VS --> M["Weighted merge"]
    BM --> M
    M --> R["Top results"]

// src/agents/memory-search.ts · L123-L126
const DEFAULT_HYBRID_ENABLED = true;
const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;
const DEFAULT_HYBRID_CANDIDATE_MULTIPLIER = 4;

// src/agents/memory-search.ts · L188-L192
  // `none` is the built-in FTS-only sentinel, never a plugin capability.
  // Avoid cold plugin discovery when semantic memory is intentionally disabled.
  if (normalizeProviderId(providerId) === "none") {
    return undefined;
  }

📎 src/agents/memory-search.ts · DEFAULT_HYBRID_VECTOR_WEIGHT — 源码

📎 src/agents/memory-search.ts · getConfiguredMemoryEmbeddingProvider — 源码

📖 "MEMORY.md is the compact, curated layer: durable facts, preferences, standing" — Memory overview

📖 "If MEMORY.md grows past the bootstrap file budget, OpenClaw keeps the file on" — Memory overview

openclaw doctor

// src/agents/bootstrap-budget.ts · L155-L172
  return params.bootstrapFiles.map((file) => {
    const pathValue = normalizeOptionalString(file.path) ?? "";
    const rawChars = file.missing ? 0 : (file.content ?? "").trimEnd().length;
    const injected =
      (pathValue ? injectedByPath.get(pathValue) : undefined) ??
      injectedByPath.get(file.name) ??
      injectedByBaseName.get(file.name);
    const injectedChars = injected ? injected.length : 0;
    const truncated = !file.missing && injectedChars < rawChars;
    return {
      name: file.name,
      path: pathValue || file.name,
      missing: file.missing,
      rawChars,
      injectedChars,
      truncated,
    };
  });

📎 src/agents/bootstrap-budget.ts · buildBootstrapInjectionStats — 源码

📖 "Old notes gradually lose ranking weight so recent information surfaces first." — Memory search

📖 "evergreen and never decayed; only dated memory/YYYY-MM-DD.md files decay." — Memory search

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            mmr: { enabled: true },
            temporalDecay: { enabled: true },
          },
        },
      },
    },
  },
}

// src/agents/memory-search.ts · L127-L130
const DEFAULT_MMR_ENABLED = false;
const DEFAULT_MMR_LAMBDA = 0.7;
const DEFAULT_TEMPORAL_DECAY_ENABLED = false;
const DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS = 30;

📎 src/agents/memory-search.ts · DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS — 源码

📖 "OpenClaw runs a silent turn that reminds the agent to save important context" — Memory overview

📖 "Dreaming is an optional background consolidation pass for memory. It collects" — Memory overview

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

// src/memory-host-sdk/dreaming.ts · L38-L41
export const DEFAULT_MEMORY_DEEP_DREAMING_LIMIT = 10;
export const DEFAULT_MEMORY_DEEP_DREAMING_MIN_SCORE = 0.8;
export const DEFAULT_MEMORY_DEEP_DREAMING_MIN_RECALL_COUNT = 3;
export const DEFAULT_MEMORY_DEEP_DREAMING_MIN_UNIQUE_QUERIES = 3;

// src/agents/agent-tools.ts · L1009-L1013
  const toolsForMemoryFlush: AnyAgentTool[] = isMemoryFlushRun && memoryFlushWritePath ? [] : tools;
  if (isMemoryFlushRun && memoryFlushWritePath) {
    for (const tool of tools) {
      if (!MEMORY_FLUSH_ALLOWED_TOOL_NAMES.has(tool.name)) {
        continue;
      }

📎 src/memory-host-sdk/dreaming.ts · DEFAULT_MEMORY_DEEP_DREAMING_MIN_SCORE — 源码

📎 src/agents/agent-tools.ts · MEMORY_FLUSH_ALLOWED_TOOL_NAMES — 源码

📖 "Bindings are deterministic and most-specific wins." — Multi-agent routing

📖 "If multiple bindings match within the same tier, the first one in config order wins." — Multi-agent routing

📖 "A binding that omits accountId matches only the default account, not every account." — Multi-agent routing

{
  bindings: [
    {
      agentId: "opus",
      match: { channel: "whatsapp", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },
  ],
}

// src/routing/resolve-route.ts · L740-L818
    {
      matchedBy: "binding.peer",
      enabled: Boolean(peer),
      scopePeer: peer,
      candidates: collectPeerIndexedBindings(bindingsIndex, peer),
      predicate: (candidate) => candidate.match.peer.state === "valid",
    },
    // ...
    {
      matchedBy: "binding.channel",
      enabled: true,
      scopePeer: peer,
      candidates: bindingsIndex.byChannel,
      predicate: (candidate) => candidate.match.accountPattern === "*",
    },
  ];

  for (const tier of tiers) {
    if (!tier.enabled) {
      continue;
    }
    const matched = tier.candidates.find(
      (candidate) =>
        tier.predicate(candidate) &&
        matchesBindingScope(candidate.match, {
          ...baseScope,
          peer: tier.scopePeer,
        }),
    );
    if (matched) {
      if (shouldLogDebug) {
        logDebug(`[routing] match: matchedBy=${tier.matchedBy} agentId=${matched.binding.agentId}`);
      }
      return choose(matched.binding.agentId, tier.matchedBy, matched.binding.session);
    }
  }

📎 src/routing/resolve-route.ts · resolveAgentRoute — 源码

📖 "OpenClaw handles failures in two stages:" — Model failover

📖 "If all profiles for a provider fail, OpenClaw moves to the next model in agents.defaults.model.fallbacks." — Model failover

📖 "Overloaded and rate-limit errors are handled more aggressively than billing cooldowns: by default, OpenClaw allows one same-provider auth-profile retry, then switches to the next configured model fallback without waiting." — Model failover

flowchart TD
    A[解析 session model + auth-profile 偏好] --> B[构建候选链]
    B --> C[尝试当前 provider: auth-profile 轮换/冷却]
    C -->|失败且 failover-worthy| D[前进到下一个 model 候选]
    D --> E[重试前持久化 fallback override
modelOverrideSource: auto]
    E -->|候选失败| F[仅回滚匹配该候选的 override 字段]
    E -->|候选成功| G[发一次 fallback 状态通知]
    F -->|全部候选失败| H[抛出 FallbackSummaryError]

// src/agents/model-fallback.ts · L1085-L1111
  addExplicitCandidate(effectivePrimary);

  const modelFallbacks =
    params.fallbacksOverride !== undefined
      ? params.fallbacksOverride
      : resolveAgentModelFallbackValues(params.cfg?.agents?.defaults?.model);

  for (const raw of modelFallbacks) {
    const resolved = resolveModelRefFromString({
      cfg: params.cfg,
      raw,
      defaultProvider,
      aliasIndex,
      allowPluginNormalization: allowPluginModelAliases,
      manifestPlugins: params.manifestPlugins,
    });
    if (!resolved) {
      continue;
    }
    // Fallbacks are explicit user intent; do not silently filter them by the
    // model allowlist.
    addExplicitCandidate(normalizeCandidateRef(resolved.ref.provider, resolved.ref.model));
  }

  if (params.fallbacksOverride === undefined && primary?.provider && primary.model) {
    addExplicitCandidate(normalizeCandidateRef(primary.provider, primary.model));
  }

// src/agents/model-fallback.ts · L155-L175
class FallbackSummaryError extends Error {
  readonly attempts: FallbackAttempt[];
  readonly soonestCooldownExpiry: number | null;
  readonly sessionId?: string;
  readonly lane?: string;

  constructor(
    message: string,
    attempts: FallbackAttempt[],
    soonestCooldownExpiry: number | null,
    cause?: Error,
    attribution?: FailoverAttribution,
  ) {
    super(message, { cause });
    this.name = "FallbackSummaryError";
    this.attempts = attempts;
    this.soonestCooldownExpiry = soonestCooldownExpiry;
    this.sessionId = attribution?.sessionId;
    this.lane = attribution?.lane;
  }
}

📎 src/agents/model-fallback.ts · resolveFallbackCandidatesUncached — 源码

📎 src/agents/model-fallback.ts · FallbackSummaryError — 源码

📖 "If the selected provider/model fails before producing a reply, OpenClaw reports the failure instead of answering from an unrelated configured fallback." — Model failover

# /model ollama/qwen3.5:27b —— 显式用户选型，provider 不可达就直接失败
openclaw ... --model ollama/qwen3.5:27b

// src/agents/agent-scope.ts · L560-L577
  const agentFallbacksOverride = resolveAgentModelFallbacksOverride(params.cfg, params.agentId);
  if (!params.hasSessionModelOverride) {
    return agentFallbacksOverride;
  }
  const canUseConfiguredFallbacks =
    params.modelOverrideSource === "auto" ||
    (params.modelOverrideSource === undefined && params.hasAutoFallbackProvenance === true);
  if (!canUseConfiguredFallbacks) {
    return [];
  }
  const subagentFallbacksOverride = isSubagentSessionKey(params.sessionKey)
    ? resolveSubagentSpawnModelFallbacksOverride(params.cfg, params.agentId)
    : undefined;
  if (subagentFallbacksOverride !== undefined) {
    return subagentFallbacksOverride;
  }
  const defaultFallbacks = resolveAgentModelFallbackValues(params.cfg.agents?.defaults?.model);
  return agentFallbacksOverride ?? defaultFallbacks;

📎 src/agents/agent-scope.ts · resolveEffectiveModelFallbacks — 源码

📖 "Regular (non-billing, non-auth-permanent) cooldowns scale with the profile's recent error count:" — Model failover

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

// src/agents/auth-profiles/usage.ts · L667-L676
export function calculateAuthProfileCooldownMs(errorCount: number): number {
  const normalized = Math.max(1, errorCount);
  if (normalized <= 1) {
    return 30_000; // 30 seconds
  }
  if (normalized <= 2) {
    return 60_000; // 1 minute
  }
  return 5 * 60_000; // 5 minutes max
}

// src/agents/auth-profiles/usage.ts · L766-L777
function calculateDisabledLaneBackoffMs(params: {
  errorCount: number;
  baseMs: number;
  maxMs: number;
}): number {
  const normalized = Math.max(1, params.errorCount);
  const baseMs = Math.max(60_000, params.baseMs);
  const maxMs = Math.max(baseMs, params.maxMs);
  const exponent = Math.min(normalized - 1, 10);
  const raw = baseMs * 2 ** exponent;
  return Math.min(maxMs, raw);
}

📎 src/agents/auth-profiles/usage.ts · calculateAuthProfileCooldownMs — 源码

📎 src/agents/auth-profiles/usage.ts · calculateDisabledLaneBackoffMs — 源码

📖 "OAuth providers commonly mint a new refresh token on every login/refresh." — OAuth

📖 "To reduce that, OpenClaw treats the auth profile store as a token sink:" — OAuth

📖 "exchange the code at https://auth.openai.com/oauth/token" — OAuth

openclaw models auth login --provider openai
openclaw models auth login --provider openai --profile-id openai:work

// src/agents/auth-profiles/oauth-manager.ts · L257-L279
export function resolveEffectiveOAuthCredential(params: {
  store: AuthProfileStore;
  profileId: string;
  credential: OAuthCredential;
  readBootstrapCredential: OAuthManagerAdapter["readBootstrapCredential"];
}): OAuthCredential {
  const imported = params.readBootstrapCredential({
    store: params.store,
    profileId: params.profileId,
    credential: params.credential,
  });
  if (!imported) {
    return params.credential;
  }
  if (hasUsableOAuthCredential(params.credential)) {
    log.debug("resolved oauth credential from canonical local store", {
      profileId: params.profileId,
      provider: params.credential.provider,
      localExpires: params.credential.expires,
      externalExpires: imported.expires,
    });
    return params.credential;
  }

// src/agents/auth-profiles/oauth-manager.ts · L716-L735
    if (!params.forceRefresh && hasUsableOAuthCredential(effectiveCredential)) {
      return {
        apiKey: await adapter.buildApiKey(effectiveCredential.provider, effectiveCredential, {
          cfg: params.cfg,
          agentDir: params.agentDir,
        }),
        credential: effectiveCredential,
      };
    }

    try {
      const refreshed = await refreshOAuthTokenWithLock({
        profileId: params.profileId,
        provider: params.credential.provider,
        agentDir: params.agentDir,
        cfg: params.cfg,
        forceRefresh: params.forceRefresh,
        attemptedCredentials,
      });
      return refreshed;

📎 src/agents/auth-profiles/oauth-manager.ts · resolveEffectiveOAuthCredential — 源码

📎 src/agents/auth-profiles/oauth-manager.ts · resolveOAuthAccess — 源码

📖 "OpenClaw pins the chosen auth profile per session to keep provider caches warm. It does not rotate on every request." — Model failover

📖 "For OpenAI agent models, auth and runtime are separate." — Model failover

{
  auth: {
    order: {
      openai: ["openai:[email protected]", "openai:api-key-backup"],
    },
  },
}

// src/agents/auth-profiles/order.ts · L471-L502
  // Sort available profiles by type preference, then by lastUsed (oldest first = round-robin within type)
  const scored = available.map((profileId) => {
    const type = store.profiles[profileId]?.type;
    const typeScore = type === "oauth" ? 0 : type === "token" ? 1 : type === "api_key" ? 2 : 3;
    const lastUsed = store.usageStats?.[profileId]?.lastUsed ?? 0;
    return { profileId, typeScore, lastUsed };
  });

  // Primary sort: type preference (oauth > token > api_key).
  // Secondary sort: lastUsed (oldest first for round-robin within type).
  const sorted = scored
    .toSorted((a, b) => {
      // First by type (oauth > token > api_key)
      if (a.typeScore !== b.typeScore) {
        return a.typeScore - b.typeScore;
      }
      // Then by lastUsed (oldest first)
      return a.lastUsed - b.lastUsed;
    })
    .map((entry) => entry.profileId);

  // Append cooldown profiles at the end (sorted by cooldown expiry, soonest first)
  const cooldownSorted = inCooldown
    .map((profileId) => ({
      profileId,
      cooldownUntil:
        resolveProfileUnusableUntil(store.usageStats?.[profileId] ?? {}, forModel) ?? now,
    }))
    .toSorted((a, b) => a.cooldownUntil - b.cooldownUntil)
    .map((entry) => entry.profileId);

  return [...sorted, ...cooldownSorted];

📎 src/agents/auth-profiles/order.ts · orderProfilesByMode — 源码

📖 "Never reuse agentDir across agents — it causes auth/session state collisions." — Multi-agent routing

📖 "If you want a fully independent OAuth account, sign in from that agent." — Multi-agent routing

openclaw agents add work
openclaw agents add personal

// src/agents/auth-profiles/portability.ts · L38-L54
export function resolveAuthProfilePortability(
  credential: AuthProfileCredential,
): AuthProfilePortability {
  const override = hasAgentCopyOverride(credential);
  if (override === false) {
    return { portable: false, reason: "credential-opted-out" };
  }
  if (credential.type === "oauth") {
    if (!hasCopyableOAuthMaterial(credential)) {
      return { portable: false, reason: "non-portable-oauth-refresh-token" };
    }
    return override === true
      ? { portable: true, reason: "oauth-provider-opted-in" }
      : { portable: false, reason: "non-portable-oauth-refresh-token" };
  }
  return { portable: true, reason: "portable-static-credential" };
}

// src/agents/auth-profiles/store.ts · L208-L218
  // Local agent stores can inherit main OAuth credentials. Do not persist the
  // inherited copy unless the local store actually owns or improves it.
  const mainCredential = loadPersistedAuthProfileStore()?.profiles[params.profileId];
  return (
    mainCredential?.type === "oauth" &&
    (isDeepStrictEqual(mainCredential, params.credential) ||
      shouldUseMainOwnerForLocalOAuthCredential({
        local: params.credential,
        main: mainCredential,
      }))
  );

📎 src/agents/auth-profiles/portability.ts · resolveAuthProfilePortability — 源码

📎 src/agents/auth-profiles/store.ts · isInheritedMainOAuthCredential — 源码

📖 "OpenClaw uses it to define the Gateway WebSocket protocol (handshake, request/response, server events)." — TypeBox

📖 "One source of truth; everything else is generated." — TypeBox

📖 "The first frame must be a connect request." — TypeBox

📖 "Methods with side effects usually require an idempotencyKey in params" — TypeBox

{
  "type": "req",
  "id": "c1",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": { "id": "cli", "displayName": "example", "version": "dev", "platform": "node", "mode": "cli" }
  }
}

flowchart LR
  A[Client] -->|req:connect| B[Gateway]
  B -->|res:hello-ok| A
  B -->|event:tick| A
  A -->|req:health| B
  B -->|res:health| A

// src/gateway/server/ws-types.ts · L45-L53
export const WS_HANDSHAKE_PHASES = [
  "tcp_accepted",
  "ws_upgrade_started",
  "auth_credentials_received",
  "auth_validated",
  "session_attached",
  "hello_payload_prepared",
  "ready",
] as const;

// src/gateway/method-scopes.ts · L25-L33
/** Default scopes granted to CLI/operator clients when no narrower local policy is known. */
export const CLI_DEFAULT_OPERATOR_SCOPES: OperatorScope[] = [
  ADMIN_SCOPE,
  READ_SCOPE,
  WRITE_SCOPE,
  APPROVALS_SCOPE,
  PAIRING_SCOPE,
  TALK_SECRETS_SCOPE,
];

📎 src/gateway/server/ws-types.ts · WS_HANDSHAKE_PHASES — 源码

📎 src/gateway/method-scopes.ts · CLI_DEFAULT_OPERATOR_SCOPES — 源码

📖 "OpenClaw delivers all pending steering messages after the current assistant turn finishes executing its tool calls, before the next LLM call" — Command queue

📖 "interrupt: abort the active run for that session, then run the newest message." — Command queue

📖 "steer does not abort in-flight tools. Use /queue interrupt when the newest message should abort the current run." — Command queue

{
  messages: {
    queue: {
      mode: "steer",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

// src/agents/sessions/agent-session-prompting.ts · L419-L424
    } else if (this.isStreaming) {
      if (options?.deliverAs === "followUp") {
        this.agent.followUp(appMessage);
      } else {
        this.agent.steer(appMessage);
      }

📎 src/agents/sessions/agent-session-prompting.ts · sendCustomMessage — 源码

📖 "OpenClaw has two independent streaming layers, and there is" — Streaming and chunking

📖 "Block streaming sends assistant output in coarse chunks as it becomes available." — Streaming and chunking

📖 "No block streaming: blockStreamingDefault: \"off\" (only final reply)." — Streaming and chunking

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": { "toolProgress": true, "commandText": "status" }
      }
    }
  }
}

// src/agents/btw.ts · L1241-L1271
    if (event.type === "text_delta") {
      sawTextEvent = true;
      answerText += event.delta;
      chunker?.append(event.delta);
      if (chunker && params.resolvedBlockStreamingBreak === "text_end") {
        chunker.drain({ force: false, emit: (chunk) => void emitBlockChunk(chunk) });
      }
      continue;
    }

    if (event.type === "text_end" && chunker && params.resolvedBlockStreamingBreak === "text_end") {
      chunker.drain({ force: true, emit: (chunk) => void emitBlockChunk(chunk) });
      continue;
    }
// ...
  if (chunker && params.resolvedBlockStreamingBreak !== "text_end" && chunker.hasBuffered()) {
    chunker.drain({ force: true, emit: (chunk) => void emitBlockChunk(chunk) });
  }

📎 src/agents/btw.ts · runBtwSideQuestion — 源码

📖 "OpenClaw builds its own system prompt for every agent run; there is no runtime default prompt." — System prompt

📖 "buildAgentSystemPrompt renders the prompt from explicit inputs. It stays a pure renderer and does not read global config directly." — System prompt

📖 "Safety guardrails in the system prompt are advisory, not enforcement." — System prompt

Per-file max characters       agents.defaults.bootstrapMaxChars        默认 20000
Total across all files        agents.defaults.bootstrapTotalMaxChars   默认 60000
Truncation warning            agents.defaults.bootstrapPromptTruncationWarning  默认 always

// src/agents/system-prompt.ts · L1287-L1295
  // Channel/session-specific guidance lives below the cache boundary so large
  // stable workspace context can remain a byte-identical prefix across turns.
  lines.push(
    // Approval UI and owner identity vary by turn, so keep both below the stable prefix.
    // A tool_call_style override owns the complete section and suppresses default guidance.
    ...(providerSectionOverrides.tool_call_style
      ? []
      : [
          buildExecApprovalPromptGuidance({

📎 src/agents/system-prompt.ts · buildAgentSystemPrompt — 源码

📖 "Block chunking is implemented by EmbeddedBlockChunker:" — Streaming and chunking

📖 "Low bound: don't emit until buffer >= minChars (unless forced)." — Streaming and chunking

📖 "High bound: prefer splits before maxChars; if forced, split at maxChars." — Streaming and chunking

paragraph  -> "\n\n"
newline     -> "\n"
sentence    -> " "(空格)

// src/agents/embedded-agent-block-chunker.ts · L148-L165
  drain(params: { force: boolean; emit: (chunk: string) => void }) {
    // KNOWN: We cannot split inside fenced code blocks (Markdown breaks + UI glitches).
    // When forced (maxChars), we close + reopen the fence to keep Markdown valid.
    const { force, emit } = params;
    const minChars = Math.max(1, Math.floor(this.#chunking.minChars));
    const maxChars = Math.max(minChars, Math.floor(this.#chunking.maxChars));

    if (this.#buffer.length < minChars && !force) {
      return;
    }

    if (force && this.#buffer.length <= maxChars) {
      if (this.#buffer.trim().length > 0) {
        emit(this.#buffer);
      }
      this.#buffer = "";
      return;
    }

📎 src/agents/embedded-agent-block-chunker.ts · drain — 源码

📖 "OpenClaw serializes inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions." — Command queue

📖 "runEmbeddedAgent enqueues by session key (lane session:<key>) to guarantee only one active run per session." — Command queue

📖 "No external dependencies or background worker threads; pure TypeScript + promises." — Command queue

unconfigured lane  -> 1
main               -> 4   (可用 agents.defaults.maxConcurrent 调整)
subagent           -> 8

// src/agents/embedded-agent-runner/lanes.ts · L6-L19
export function resolveSessionLane(key: string) {
  const cleaned = key.trim() || CommandLane.Main;
  return cleaned.startsWith("session:") ? cleaned : `session:${cleaned}`;
}

export function resolveGlobalLane(lane?: string) {
  const cleaned = lane?.trim();
  // Cron jobs hold the cron lane slot; inner operations need a dedicated lane
  // to avoid deadlock without widening shared nested flows.
  if (cleaned === CommandLane.Cron) {
    return CommandLane.CronNested;
  }
  return cleaned ? cleaned : CommandLane.Main;
}

📎 src/agents/embedded-agent-runner/lanes.ts · resolveSessionLane — 源码

📖 "One always-on process for routing, control plane, and channel connections." — debug/trace mirrored to stdio

📖 "Default bind mode: loopback. Inside a detected container environment the effective default is auto (resolves to 0.0.0.0 for port-forwarding), unless Tailscale serve/funnel is active, which always forces loopback." — debug/trace mirrored to stdio

📖 "Auth is required by default." — debug/trace mirrored to stdio

📖 "refusing to bind gateway ... without auth" — debug/trace mirrored to stdio

openclaw gateway --port 18789
openclaw gateway status
openclaw channels status --probe

📖 "First frame must be a connect request." — Gateway protocol

📖 "Pre-connect frames are capped at 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES)." — Gateway protocol

📖 "Side-effecting methods require idempotency keys (see schema)." — Gateway protocol

📖 "Gateway returns a hello-ok frame with a snapshot (presence, health, stateVersion, uptimeMs) plus policy limits (maxPayload, maxBufferedBytes, tickIntervalMs)." — debug/trace mirrored to stdio

sequenceDiagram
    participant C as Client (operator/node)
    participant G as Gateway
    G-->>C: event connect.challenge {nonce, ts}
    C->>G: req connect {minProtocol:4, maxProtocol:4, role, scopes, auth}
    G-->>C: res hello-ok {server, features, snapshot, policy, auth}
    C->>G: req(method, params)
    G-->>C: res(ok/payload|error)

📖 "Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start." — Configuration

📖 "A rejected write is also saved as <path>.rejected.<timestamp> for inspection." — Configuration

📖 "Invalid configuration errors exit with code 78." — debug/trace mirrored to stdio

openclaw config validate
openclaw doctor
openclaw doctor --fix   # --repair 同义；--yes 跳过确认

📖 "The Gateway watches ~/.openclaw/openclaw.json and applies changes automatically - no manual restart needed for most settings." — Configuration

📖 "Hot-applies safe changes instantly. Automatically restarts for critical ones." — Configuration

📖 "gateway.* (port, bind, auth, tailscale, TLS, HTTP, push)" — Configuration

📖 "gateway.reload and gateway.remote are exceptions under gateway.* - changing them does not trigger a restart." — Configuration

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

📖 "operator: control-plane client (CLI/UI/automation)." — Gateway protocol

📖 "worker: cloud execution host on the dedicated, closed worker protocol." — Gateway protocol

📖 "The gateway treats these as claims and enforces server-side allowlists." — Gateway protocol

{
  "role": "node",
  "caps": ["camera", "canvas", "screen", "location", "voice"],
  "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
  "permissions": { "camera.capture": true, "screen.record": false }
}

📖 "If the file is missing, OpenClaw uses safe defaults." — Configuration

📖 "The active config path must be a regular file." — Configuration

📖 "Single file: replaces the containing object" — Configuration

📖 "Array of files: deep-merged in order (later wins), up to 10 nested levels deep" — Configuration

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

📖 "model: accepts either a string ("provider/model") or an object ({ primary, fallbacks })." — Configuration — agents

📖 "Object form sets primary plus ordered failover models." — Configuration — agents

📖 "Utility tasks make separate model calls and send task-specific content to the selected model provider." — Configuration — agents

📖 "maxConcurrent: max parallel agent runs across sessions (each session still serialized). Default: 4." — Configuration — agents

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

📖 "OpenClaw supports OAuth and API keys for model providers. For an always-on gateway host, an API key is the most predictable option; subscription/OAuth flows work too when they match your provider account model." — Run on the gateway host

📖 "For long-lived gateway hosts, an Anthropic API key is still the most predictable choice, with explicit server-side billing control." — Run on the gateway host

cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
EOF
openclaw models status
openclaw doctor

📖 "For model-provider credentials backed by SecretRefs, OpenClaw mints an opaque, process-local sentinel during model-auth resolution." — Secrets management

📖 "Unknown sentinel-shaped values fail closed before network activity. OpenClaw refuses to send the request rather than forwarding an unresolved sentinel to a provider." — Secrets management

📖 "Sentinels reduce plaintext exposure across the model-call chain, but they are not process isolation. The real value still exists in same-process memory and appears at the final adapter boundary." — Secrets management

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

📖 "OpenClaw rotates to the next key only when the error message matches: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted, or too many requests. Other errors are not retried with alternate keys. If all keys fail, the final error from the last attempt is returned." — Run on the gateway host

📖 "Removing saved auth does not revoke the key at the provider — rotate or revoke it in the provider dashboard when you need provider-side invalidation." — Run on the gateway host

export OPENROUTER_API_KEYS="key_a,key_b,key_c"
openclaw models status

📖 "Secrets resolve into an in-memory runtime snapshot, eagerly during activation, not lazily on request paths." — Secrets management

📖 "Reload is an atomic swap: full success, or keep the last-known-good snapshot." — Secrets management

📖 "Enabled surfaces: unresolved refs block startup/reload." — Secrets management

flowchart TD
  A[Startup preflight + final activation] --> C{Resolve active SecretRefs?}
  B[Config reload / secrets.reload] --> C
  C -- success --> D[Atomic swap new snapshot]
  C -- startup failure --> E[Abort gateway startup]
  C -- reload failure --> F[Keep last-known-good + DEGRADED]

📖 "OpenClaw reads auth profiles from each agent's openclaw-agent.sqlite. Endpoint details (baseUrl, api, model ids, headers, timeouts) belong under models.providers.<id> in openclaw.json or models.json, not in auth profiles." — Run on the gateway host

📖 "OAuth-mode profiles reject SecretRef credentials: if auth.profiles.<id>.mode is "oauth", a SecretRef-backed keyRef/tokenRef for that profile is rejected." — Run on the gateway host

openclaw models auth paste-token --provider openrouter
openclaw doctor --fix

📖 "When you remove provider auth through the gateway control plane, OpenClaw deletes the saved auth profiles for that provider and aborts active chat/agent runs whose selected model provider matches the removed one. Aborted runs emit the normal cancellation/lifecycle events with stopReason: "auth-revoked", so connected clients can show the run stopped because credentials were removed." — Run on the gateway host

openclaw models auth login --provider anthropic --force

📖 "OpenClaw can run tool execution inside a sandbox backend to reduce blast radius. Sandboxing is off by default and controlled by agents.defaults.sandbox (global) or agents.list[].sandbox (per-agent). The Gateway process always stays on the host; only tool execution moves into the sandbox when enabled." — Sandboxing

📖 "This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb." — Sandboxing

📖 "- non-main: sandbox every session except the agent's main session. The main session key is always agent:<agentId>:main (or global when session.scope is "global"); it is not configurable. Group/channel sessions use their own keys, so they always count as non-main and get sandboxed." — Sandboxing

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

📖 "1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) decides where tools run (sandbox backend vs host)." — Sandbox vs tool policy vs elevated

📖 "3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) is an exec-only escape hatch to run outside the sandbox when you are sandboxed (gateway by default, or node when the exec target is configured to node)." — Sandbox vs tool policy vs elevated

📖 "Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn't bring it back." — Sandboxing

flowchart TD
    A[工具调用] --> B{Tool policy: 被 deny?}
    B -->|是| X[拦截: deny always wins]
    B -->|否| C{Sandbox mode: 当前会话沙箱化?}
    C -->|否| H[在宿主机运行]
    C -->|是| D{Sandbox tool policy 允许?}
    D -->|否| X
    D -->|是| E{仅 exec: elevated on?}
    E -->|是| H
    E -->|否| S[在沙箱后端运行]

📖 "- deny always wins." — Sandbox vs tool policy vs elevated

📖 "- If allow is non-empty, everything else is treated as blocked." — Sandbox vs tool policy vs elevated

📖 "- Tool policy is the hard stop: /exec cannot override a denied exec tool." — Sandbox vs tool policy vs elevated

📖 "- Tool policy filters tool availability by name; it does not inspect side effects inside exec. If exec is allowed, denying write, edit, or apply_patch does not make shell commands read-only." — Sandbox vs tool policy vs elevated

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

📖 "agents.defaults.sandbox.workspaceAccess controls what the sandbox can see: "none", "ro", or "rw"." — Sandbox vs tool policy vs elevated

📖 "Inbound media is copied into the active sandbox workspace (media/inbound/*)." — Sandboxing

# workspaceAccess=none  → 隔离工作区,位于 ~/.openclaw/sandboxes,写工具作用于隔离副本
# workspaceAccess=ro    → agent 工作区只读挂到 /agent,write/edit/apply_patch 被禁用
# workspaceAccess=rw    → agent 工作区读写挂到 /workspace

📖 "Docker is the default backend once sandboxing is enabled. It runs tools and sandbox browsers locally through the Docker daemon socket (/var/run/docker.sock); isolation comes from Docker namespaces." — Sandboxing

📖 "Defaults: network: "none" (no egress), readOnlyRoot: true, capDrop: ["ALL"], image openclaw-sandbox:bookworm-slim." — Sandboxing

📖 "Use backend: "ssh" to sandbox exec, file tools, and media reads on an arbitrary SSH-accessible machine." — Sandboxing

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
        },
      },
    },
  },
}

📖 "Elevated does not grant extra tools; it only affects exec." — Sandbox vs tool policy vs elevated

📖 "- Elevated is not skill-scoped and does not override tool allow/deny." — Sandbox vs tool policy vs elevated

📖 "- Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (:ro or :rw)." — Sandboxing

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
  },
}

📖 "Operator scopes gate what a Gateway client can do after it authenticates." — Operator scopes

📖 "Operator RPC methods require the operator role; node-originated methods" — Operator scopes

flowchart TD
  C[WS client 连接] --> R{role?}
  R -->|operator| OP[operator 方法可达]
  R -->|node| ND[node.invoke 等 node 方法可达]
  OP --> S{scope 检查}
  S -->|通过| H[handler 执行]

📖 "Unknown future operator.* scopes require an exact match unless the caller" — Operator scopes

📖 "Each Gateway RPC has a least-privilege method scope that decides whether a" — Operator scopes

📖 "This lets lower-scope operators perform low-risk pairing actions without" — Operator scopes

# 需要 operator.write 即可
openclaw gateway call chat.send --text "hello"
# /config set / /config unset 额外要求 operator.admin

📖 "Breaking change: starting with 2026.3.31, node commands are disabled until node pairing is approved. Device pairing alone is no longer enough to expose declared node commands." — Node pairing

📖 "Commands queued before pairing approval are dropped, not deferred." — Node pairing

📖 "Node pairing approval records the trusted capability surface. It does not pin the live node command surface per node." — Node pairing

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes status

📖 "Device pairing records are the durable source of approved roles and scopes." — Operator scopes

📖 "device.pair.approve is reachable with operator.pairing, but approving an" — Operator scopes

📖 "First-time role: node device pairing from a private/CGNAT address is" — Node pairing

📖 "No blanket LAN or private-network auto-approve mode exists; SSH-verified" — Node pairing

{
  gateway: {
    nodes: {
      pairing: {
        // Disable entirely:
        sshVerify: false,
        // ...or scope/tune the probe:
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

📖 "The Gateway WebSocket binds to loopback by default, on port 18789 (gateway.port)." — Check if the tunnel is running

📖 "Keep the Gateway loopback-only unless you are sure you need a bind." — Check if the tunnel is running

📖 "--url never falls back to config or environment credentials." — Check if the tunnel is running

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

📖 "External uptime monitoring services should use the dedicated /health endpoint, not /v1/chat/completions." — Health checks

📖 "Monitoring services that ping every 15 minutes create ~96 sessions/day, each consuming 4-22KB. Over time this causes session store bloat and can lead to context window overflow." — Health checks

# BetterStack / UptimeRobot 都指向 /health,而不是推理入口
curl https://<your-gateway-host>:<port>/health
# 健康时返回 200 与 {"ok":true}

📖 "Restarting the gateway does not lose agent state." — Restart recovery

📖 "Runs interrupted more than 2 hours ago are finalized instead of resumed, so" — Restart recovery

flowchart TD
  A[请求式重启/升级] --> B[停止接新活]
  B --> C{drain 预算 5 分钟内完成?}
  C -->|是| D[无损重启, 什么都没打断]
  C -->|否/强制/崩溃| E[给 session 盖 recovery marker]
  E --> F[启动后几秒重新派发合成系统消息]
  F --> G{transcript 尾部安全?}
  G -->|是| H[从现有 transcript 续跑, 最多重试3次]
  G -->|否| I[发 resend 提示, 不盲目重跑]

📖 "Prompt injection is not solved by system prompt guardrails alone - those are soft guidance; hard enforcement comes from tool policy, exec approvals, sandboxing, and channel allowlists (which operators can still disable by design)." — /etc/ufw/after.rules (append as its own *filter section)

📖 "Prompt injection does not require public DMs: even if only you can message the bot, any untrusted content it reads (web search/fetch results, browser pages, emails, docs, attachments, pasted logs/code) can carry adversarial instructions." — /etc/ufw/after.rules (append as its own *filter section)

{
  tools: {
    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],
  },
}

📖 "Treat dmPolicy="open" and groupPolicy="open" as last-resort settings; prefer pairing + allowlists unless you fully trust every member of the room." — /etc/ufw/after.rules (append as its own *filter section)

📖 "Unknown senders get a pairing code; bot ignores them until approved. Codes expire after 1 hour" — /etc/ufw/after.rules (append as its own *filter section)

openclaw pairing list <channel>
openclaw pairing approve <channel> <code>

📖 "gateway.channelStaleEventThresholdMinutes: how long a connected channel can stay idle before the health monitor treats it as stale and restarts it. Default: 30. Keep this greater than or equal to gateway.channelHealthCheckMinutes." — Health checks

📖 "gateway.channelMaxRestartsPerHour: rolling one-hour cap for health-monitor restarts per channel/account. Default: 10." — Health checks

# session 行读的是存储的会话状态, 不代表 socket 还活着
openclaw sessions
# 实时连通性要用 channel status / health 命令
openclaw status --deep

📖 "openclaw gateway status shows Runtime: running, Connectivity probe: ok, and a Capability: ... line." — Troubleshooting

📖 "This is the deep runbook. Start at /help/troubleshooting for the fast triage flow first." — Troubleshooting

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

flowchart TD
    A{需要调度工作?} -->|是| B{精确时间还是灵活?}
    B -->|精确| C["Scheduled Tasks (Cron)"]
    B -->|灵活| D[Heartbeat]
    A -->|否, 响应生命周期事件| E[Hooks]

📖 "Use Scheduled Tasks (Cron) when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine." — Automation

📖 "Heartbeat turns do not create task records and do not extend daily/idle session reset freshness." — Automation

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

📖 "Cron runs inside the Gateway process, not inside the model. The Gateway must be running for schedules to fire." — Intended: "9 AM on the 15th, only if it's a Monday"

📖 "Job definitions, runtime state, and run history persist in OpenClaw's shared SQLite state database, so restarts do not lose schedules." — Intended: "9 AM on the 15th, only if it's a Monday"

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last

📖 "Every job carries exactly one payload kind, chosen by flag:" — Intended: "9 AM on the 15th, only if it's a Monday"

📖 "Timestamps without a timezone are treated as UTC." — Intended: "9 AM on the 15th, only if it's a Monday"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

📖 "When both the day-of-month and day-of-week fields are non-wildcard, croner matches when either field matches, not both. This is standard Vixie cron behavior." — Intended: "9 AM on the 15th, only if it's a Monday"

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

📖 "Hooks are small scripts that run inside the Gateway when agent events fire: commands like /new, /reset, /stop, session compaction, gateway lifecycle, and message flow." — List available hooks

📖 "Use internal hooks when you want automation that behaves like a small installed integration. Use typed plugin hooks when you need runtime lifecycle control." — List available hooks

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  // Your logic here

  // Optionally send a reply on replyable surfaces
  event.messages.push("Hook executed!");
};

export default handler;

📖 "Enabling cron.triggers.enabled lets agent-authored scripts run headlessly with the owning agent's full tool policy, including exec." — Intended: "9 AM on the 15th, only if it's a Monday"

📖 "The script must return { fire, message?, state? }." — Intended: "9 AM on the 15th, only if it's a Monday"

openclaw cron add \
  --name "PR CI watcher" \
  --every 30s \
  --trigger-script ./watch-pr-ci.js \
  --message "Respond to the CI status change" \
  --session isolated

📖 "Standing orders grant your agent permanent operating authority for defined programs." — Standing orders

📖 "Standing orders define what the agent is authorized to do. Cron jobs define when it happens." — Standing orders

openclaw cron add \
  --name daily-inbox-triage \
  --cron "0 8 * * 1-5" \
  --tz America/New_York \
  --timeout-seconds 300 \
  --announce \
  --channel imessage \
  --to "+1XXXXXXXXXX" \
  --message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns."

📖 "Tasks are records, not schedulers - cron and heartbeat decide _when_ work runs, tasks track _what happened_." — Background tasks

📖 "Each task moves through queued → running → terminal (succeeded, failed, timed_out, cancelled, or lost)." — Background tasks

stateDiagram-v2
    [*] --> queued
    queued --> running : agent starts
    running --> succeeded : completes ok
    running --> failed : error
    running --> timed_out : timeout exceeded
    queued --> cancelled : operator cancels
    running --> cancelled : operator cancels
    queued --> lost : backing state gone > 5 min
    running --> lost : backing state gone > 5 min

📖 "Task Flow is the orchestration layer above background tasks. A flow is a durable record of multi-step work with its own status, JSON state, revision counter, and linked task records." — List active and recent flows

📖 "Every mutation passes the flow's expected revision. A stale write is rejected as a revision conflict instead of clobbering newer state." — List active and recent flows

📖 "OpenClaw creates a mirrored one-task flow automatically when a detached ACP or subagent run starts (session-scoped tasks with deliverable completion)." — List active and recent flows

Flow: weekly-report
  Step 1: gather-data     → task created → succeeded
  Step 2: generate-report → task created → succeeded
  Step 3: deliver         → task created → running

📖 "Completion is push-driven: detached work can notify directly or wake the requester session/heartbeat when it finishes, so status polling loops are usually the wrong shape." — Background tasks

📖 "That means the usual workflow is push-based: start detached work once, then let the runtime wake or notify you on completion." — Background tasks

openclaw tasks notify <lookup> state_changes

📖 "Every task follows Execute-Verify-Report. No exceptions." — Standing orders

📖 "If execution fails: retry once with adjusted approach." — Standing orders

📖 "Never retry indefinitely - 3 attempts max, then escalate." — Standing orders

📖 "Session key = agent:channel:peer" — Threat model (MITRE ATLAS)

📖 "SSRF protection (DNS pinning + IP blocking)" — Threat model (MITRE ATLAS)

📖 "This threat model documents adversarial threats to the OpenClaw AI agent platform and ClawHub skill marketplace." — Threat model (MITRE ATLAS)

flowchart TD
    A[UNTRUSTED ZONE
WhatsApp/Telegram/Discord] --> B[TB1 Channel Access
Gateway: pairing/AllowFrom/auth]
    B --> C[TB2 Session Isolation
agent:channel:peer]
    C --> D[TB3 Tool Execution
Docker sandbox / SSRF 防护]
    D --> E[TB4 External Content
随机边界 XML 包裹]
    E --> F[TB5 Supply Chain
ClawHub skill 审核]

📖 "Pattern detection, external content wrapping; treated as out-of-scope for vulnerability reports absent a boundary bypass (see SECURITY.md)" — Threat model (MITRE ATLAS)

📖 "Critical - detection only, no blocking; sophisticated attacks bypass" — Threat model (MITRE ATLAS)

📖 "Content wrapping with random-boundary XML-style markers, homoglyph/special-token normalization, and a security notice" — Threat model (MITRE ATLAS)

T-EXEC-002 → T-EXFIL-001 → External exfiltration
(Poison URL content) → (Agent fetches & follows instructions) → (Data sent to attacker)

📖 "GitHub account age verification, static pattern/AST-adjacent scanning, LLM-based agentic risk review, VirusTotal scanning" — Threat model (MITRE ATLAS)

📖 "No runtime execution sandbox isolates a skill from the agent's own privileges once installed." — Threat model (MITRE ATLAS)

📖 "Critical - skills run with agent privileges" — Threat model (MITRE ATLAS)

T-PERSIST-001 → T-EVADE-001 → T-EXFIL-003
(Publish malicious skill) → (Evade moderation) → (Harvest credentials)

📖 "Allowlist + ask mode, plus command normalization (dispatch-wrapper unwrapping, inline-eval detection, shell-chain analysis)" — Threat model (MITRE ATLAS)

📖 "Critical - host execution possible when sandbox is disabled" — Threat model (MITRE ATLAS)

T-EXEC-001 → T-EXEC-004 → T-IMPACT-001
(Inject prompt) → (Bypass exec approval) → (Execute commands)

📖 "Critical | Package/release/repository compromise, active exploitation, or unauthenticated trust-boundary bypass with high-impact control or data exposure." — Incident response

📖 "Reproduce on supported releases and latest main, then implement and validate a patch with regression coverage." — Incident response

📖 "Run a short post-incident review: timeline, root cause, detection gap, prevention plan." — Incident response

GHSA 私密报告(已认证越权的高影响动作)
  → 分诊: 确认组件/版本/边界影响, 按 SECURITY.md 判定为安全问题
  → 定级: High
  → 响应: 私下 ack → 在 supported releases + main 复现 → 打补丁 + 回归覆盖 → 尽快出 patched release
  → 披露: GHSA + 协调披露, 适当时申请 CVE
  → 跟进: CI/release artifacts 验证 → 简短复盘 → 建加固/测试/文档任务并闭环

📖 "OpenClaw can route runtime HTTP and WebSocket traffic through an operator-managed forward proxy. This is optional defense in depth: central egress control, stronger SSRF protection, and destination auditability at the network boundary." — Network proxy

📖 "Because the proxy evaluates the destination at connect time, after DNS resolution and immediately before it opens the upstream connection, it also narrows the gap a DNS-rebinding attack relies on between an earlier application-level DNS check and the actual outbound connection." — Network proxy

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128

flowchart LR
  A[OpenClaw process] --> B[operator proxy]
  B -->|connect time: 解析并按 IP 拦截| C[destination]

📖 "it replaces caller-provided Node HTTP agents so explicit agents (including axios, got, node-fetch, and similar Node-agent-based clients) cannot silently bypass the proxy." — Network proxy

📖 "While the proxy is active, OpenClaw clears no_proxy/NO_PROXY. Those bypass lists are destination-based; leaving localhost or 127.0.0.1 there would let SSRF targets skip the proxy entirely." — Network proxy

OpenClaw process
  fetch, node:http, node:https, WebSocket clients  -> operator proxy -> destination

📖 "OpenClaw registers the active Gateway loopback authority as a direct-connect exception, so local Gateway WebSocket traffic connects without the proxy." — Network proxy

📖 "OpenClaw denies Gateway loopback control-plane connections and guarded Ollama loopback embedding connections before opening a socket." — Network proxy

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
  loopbackMode: gateway-only # gateway-only, proxy, or block

📖 "OpenClaw's formal security models (TLA+/TLC today) give a machine-checked argument that specific highest-risk paths — authorization, session isolation, tool gating, and misconfiguration safety — enforce their intended policy, under explicit stated assumptions." — Java 11+ required (TLC runs on the JVM).

📖 "This is not a proof that OpenClaw is secure in all respects, and it does not verify the full TypeScript implementation." — Java 11+ required (TLC runs on the JVM).

📖 "Results are bounded by the state space TLC explores. Green does not imply security beyond the modeled assumptions and bounds." — Java 11+ required (TLC runs on the JVM).

git clone https://github.com/vignesh07/openclaw-formal-models
cd openclaw-formal-models
make gateway-exposure-v2
make gateway-exposure-v2-protected
make gateway-exposure-v2-negative

📖 "A node is a companion device (macOS/iOS/watchOS/Android/headless) that connects to the Gateway with role: \"node\" and exposes a command surface (e.g. canvas.*, camera.*, device.*, notifications.*, system.*) via node.invoke." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

📖 "Nodes are peripherals, not gateways: they don't run the gateway service, and channel messages (Telegram, WhatsApp, etc.) land on the gateway, not on nodes." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

📖 "Nodes use device pairing. A node presents a signed device identity during connect; the Gateway creates a device pairing request for role: node." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

📖 "node.pair.* (CLI: openclaw nodes pending/approve/reject/remove/rename) is a separate, gateway-owned node pairing store that tracks the node's approved command/capability surface across reconnects. It does not gate transport authentication — device pairing does that." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

📖 "Node commands must pass two gates before they can be invoked:" — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

📖 "Dangerous or privacy-heavy commands still require explicit opt-in with gateway.nodes.allowCommands, even if a node declares them: camera.snap, camera.clip, screen.record, computer.act, contacts.add, calendar.add, reminders.add, health.summary, sms.send, sms.search. gateway.nodes.denyCommands always wins over defaults and extra allowlist entries." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

{
  gateway: {
    nodes: {
      allowCommands: ["camera.snap", "screen.record"],
      denyCommands: ["camera.clip"],
    },
  },
}

📖 "Computer use lets the gateway agent see and control a paired macOS desktop: it captures a screenshot with the existing screen.snapshot node command and drives the pointer and keyboard through a single dangerous node command, computer.act." — Computer use

📖 "Authorization is deliberately split between enabling and use." — Computer use

📖 "Before authorization, every layer (tool policy, gateway command policy, macOS setting, Accessibility, and Screen Recording) must agree." — Computer use

/phone arm computer 30m
/phone status
/phone disarm

flowchart LR
  A[vision model] --> B[computer tool]
  B --> C[node.invoke computer.act]
  C --> D[macOS node]
  D --> E[Peekaboo + CoreGraphics]
  D --> F[screen.snapshot 截屏 model-only]

📖 "Use a node host when your Gateway runs on one machine and you want commands to execute on another. The model still talks to the gateway; the gateway forwards exec calls to the node host when host=node is selected." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

📖 "The exec path prepares a canonical systemRunPlan before approval; once granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields, and re-validates the working directory before running." — Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

📖 "OpenClaw can summarize inbound media (image/audio/video) before the reply pipeline runs, so command parsing and routing work off short text instead of raw bytes." — Media understanding

📖 "Original media is always delivered to the model as usual; when understanding fails or is disabled, the reply flow continues unchanged." — Media understanding

{
  tools: {
    media: {
      concurrency: 2,
      models: [
        { provider: "openai", model: "gpt-5.6-sol", capabilities: ["image"] },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
    },
  },
}

📖 "Native Talk is a continuous loop: listen for speech, send the transcript to the model through the active session, wait for the response, then speak it via the configured Talk provider (talk.speak)." — Talk mode

📖 "Client-owned realtime Talk forwards provider tool calls through talk.client.toolCall instead of calling chat.send directly." — Talk mode

flowchart TD
  A[realtime 配置] --> B{provider 是 OpenAI 且
transport=webrtc 或省略?}
  B -->|是| C[client-owned WebRTC]
  B -->|否| D[Gateway-owned relay]
  A2[非 realtime 配置] --> E[native speech loop]

📖 "Audio files under 1024 bytes are treated as empty/corrupt and skipped before transcription; the agent gets a deterministic placeholder transcript instead." — Media understanding

📖 "Configured models.providers.* entries that support audio are tried before local CLIs." — Media understanding

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
          },
        ],
      },
    },
  },
}

📖 "First non-empty line only; the JSON line is stripped before TTS playback." — Talk mode

📖 "Interrupt on speech (default on): if the user talks while the assistant is speaking, playback stops and the interruption timestamp is noted for the next prompt." — Talk mode

{ "voice": "<voice-id>", "once": true }

📖 "OpenClaw capabilities across channels, routing, media, and UX." — Features

📖 "Embedded agent runtime with tool streaming" — Features

📖 "Discord, iMessage, Signal, Slack, Telegram, WhatsApp, WebChat, and more with a single Gateway." — Features

flowchart LR
  A[聊天渠道
Telegram/Slack/iMessage] --> B[Gateway 网关]
  B --> C[多智能体路由
隔离会话]
  C --> D[内嵌 Agent 运行时
tool streaming]
  D --> E[流式回复 + chunking]
  E --> A

📖 "Get OpenClaw installed and run your first chat in minutes." — Copy your built static files into that directory.

📖 "You should see the Gateway listening on port 18789." — Copy your built static files into that directory.

📖 "This opens the Control UI in your browser. If it loads, everything is working." — Copy your built static files into that directory.

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

📖 "Node.js 22.22.3+, 24.15+, or 25.9+" — Copy your built static files into that directory.

📖 "An API key** from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you" — Copy your built static files into that directory.

📖 "Check your Node version with node --version." — Copy your built static files into that directory.

node --version   # 需 >= 22.22.3 / 24.15 / 25.9,推荐 24.x

📖 "iMessage, Telegram, and WebChat ship with the core install; every other channel is an" — Features

📖 "Group chat support with mention-based activation" — Features

📖 "DM safety with allowlists and pairing" — Features

openclaw plugins install @openclaw/<id>
# 或在 onboarding / channels 流程中按需添加:
openclaw channels add

📖 "Multi-agent routing with isolated sessions per workspace or sender" — Features

📖 "Sessions: direct chats collapse into shared main; groups are isolated" — Features

📖 "Streaming and chunking for long responses" — Features

flowchart TD
  DM1[私聊 A] --> M[shared main]
  DM2[私聊 B] --> M
  G1[群聊 X] --> S1[隔离会话 X]
  G2[群聊 Y] --> S2[隔离会话 Y]

📖 "35+ model providers (Anthropic, OpenAI, Google, and more)" — Features

📖 "Subscription auth via OAuth (e.g. OpenAI Codex)" — Features

📖 "Browser automation, exec, sandboxing" — Features

📖 "Cron jobs and heartbeat scheduling" — Features

{
  "provider": "openai-compatible",
  "note": "可指向 vLLM / SGLang / Ollama / llama.cpp / LM Studio 等任意 OpenAI 兼容或 Anthropic 兼容端点"
}

📖 "A tool is a typed function the agent can call, such as exec, browser," — Overview

📖 "A skill is a SKILL.md instruction pack loaded into the agent prompt. Use" — Overview

📖 "A plugin can add tools, skills, channels, model providers, speech," — Overview

flowchart TD
    A[要扩展 agent 能力?] --> B{需要它去执行动作?}
    B -->|是, 已有能力| C[用 Tool: exec/browser/message]
    B -->|需要教它一套工作流| D[用 Skill: SKILL.md 指令包]
    B -->|需要新集成/凭据/运行时| E[用 Plugin: 注册 tools/channels/providers]

📖 "OpenClaw can talk to you on any chat app you already use. Each channel connects via the Gateway." — Chat channels

📖 "iMessage, Telegram, and the WebChat UI ship with the core install." — Chat channels

📖 "Fastest setup is usually Telegram (simple bot token, no plugin install)." — Chat channels

openclaw plugins install @openclaw/discord
openclaw gateway status   # 重启后确认 Gateway 已加载新渠道

📖 "OpenClaw can use many LLM providers. Pick a provider, authenticate, then set the" — Provider directory

📖 "Authenticate with the provider (usually via openclaw onboard)." — Provider directory

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}