OpenClaw 架构拆解：Gateway、推理循环、工具系统与 SubAgent

// 请求
{
  type: "req",
  id: "request-id",
  method: "sessions.list",
  params: {}
}

// 响应
{
  type: "res",
  id: "request-id",
  ok: true,
  payload: {}
}

// 事件
{
  type: "event",
  event: "presence.updated",
  payload: {},
  seq: 100,
  stateVersion: 20
}

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

openclaw gateway install
systemctl --user enable --now openclaw-gateway.service

# 启动网关
openclaw gateway --port 18789

# 查看状态
openclaw gateway status
openclaw gateway status --deep

# 健康检查
openclaw gateway health
openclaw channels status --probe

# 发现局域网网关
openclaw gateway discover

# 实时日志
openclaw logs --follow

{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "your-token"
    },
    "tls": {
      "enabled": true,
      "certPath": "/path/to/cert.pem",
      "keyPath": "/path/to/key.pem"
    },
    "reload": {
      "mode": "hybrid",
      "debounceMs": 300
    }
  }
}

async function runEmbeddedPiAgent() {
  while (true) {
    if (exceedMaxLoopIterations()) {
      throw new Error("too many run loop iterations");
    }

    try {
      const result = await runEmbeddedAttempt();
      return result.payloads;
    } catch (err) {
      if (isContextOverflow(err)) {
        await compactSessionHistory();
        continue;
      }

      if (isAuthFailure(err)) {
        await rotateProfile();
        continue;
      }

      if (isTimeout(err) && canRetry()) {
        continue;
      }

      throw err;
    }
  }
}

用户消息
  ↓
runAgentTurnWithFallback()
  ↓
runEmbeddedPiAgent()
  ↓
runEmbeddedAttempt()
  ↓
createAgentSession() + activeSession.prompt()
  ↓
LLM 调用 + 工具循环
  ↓
subscribeEmbeddedPiSession()
  ↓
onPartialReply / onBlockReply / onToolResult
  ↓
回复投递

type CronSchedule =
  | { kind: "at"; at: string }
  | { kind: "every"; everyMs: number; anchorMs?: number }
  | { kind: "cron"; expr: string; tz?: string; staggerMs?: number };

const MAX_TIMER_DELAY_MS = 60_000;
const MIN_REFIRE_GAP_MS = 2_000;

export function armTimer(state: CronServiceState) {
  const nextAt = nextWakeAtMs(state);
  const delay = Math.max(nextAt - Date.now(), 0);
  const clampedDelay = Math.min(delay, MAX_TIMER_DELAY_MS);

  state.timer = setTimeout(() => {
    void onTimer(state).catch((err) => {
      state.logger.error(err);
    });
  }, clampedDelay);
}

~/.openclaw/cron/jobs.json

~/.openclaw/cron/runs/<jobId>.jsonl

type CronStoreFile = {
  version: 1;
  jobs: CronJob[];
};

type CronJob = {
  id: string;
  name: string;
  enabled: boolean;
  schedule: CronSchedule;
  sessionTarget: "main" | "isolated";
  payload: CronPayload;
  state: CronJobState;
};

export async function start(state: CronServiceState) {
  await ensureLoaded(state, { skipRecompute: true });

  for (const job of state.jobs) {
    if (job.state.runningAtMs) {
      job.state.runningAtMs = undefined;
    }
  }

  await runMissedJobs(state);
  recomputeNextRuns(state);
  armTimer(state);
}

{
  "kind": "systemEvent",
  "text": "现在生成今天的日程摘要"
}

{
  "kind": "agentTurn",
  "message": "检查仓库中最近的错误日志，并生成摘要",
  "model": "claude-sonnet-4",
  "timeoutMs": 600000
}

export async function executeJobCoreWithTimeout(state, job) {
  const abortController = new AbortController();
  const jobTimeoutMs = resolveCronJobTimeoutMs(job);

  return await Promise.race([
    executeJobCore(state, job, abortController.signal),
    new Promise((_, reject) => {
      setTimeout(() => {
        abortController.abort();
        reject(new Error("cron: job execution timed out"));
      }, jobTimeoutMs);
    })
  ]);
}

30s → 1min → 5min → 15min → 60min

const cron = new CronService({
  enqueueSystemEvent: (text, opts) => {
    enqueueSystemEvent(text, {
      sessionKey: opts.sessionKey,
      contextKey: opts.contextKey
    });
  },

  requestHeartbeatNow: (opts) => {
    requestHeartbeatNow({
      reason: opts.reason,
      agentId: opts.agentId,
      sessionKey: opts.sessionKey
    });
  },

  runHeartbeatOnce: async (opts) => {
    return await runHeartbeatOnce({
      cfg,
      reason: opts.reason,
      agentId: opts.agentId,
      sessionKey: opts.sessionKey
    });
  }
});

if (webhookTarget && evt.summary) {
  await fetch(webhookTarget.url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${webhookToken}`
    },
    body: JSON.stringify(evt)
  });
}

openclaw cron status
openclaw cron list
openclaw cron add
openclaw cron edit
openclaw cron remove <id>
openclaw cron run <id>

function createOpenClawCodingTools() {
  const policy = resolveEffectiveToolPolicy();

  const coding = createBaseCodingTools();
  const exec = createExecTool();
  const openclaw = createOpenClawTools();
  const plugins = resolvePluginTools();

  const merged = [
    ...coding,
    exec,
    ...openclaw,
    ...plugins
  ];

  const filtered = applyToolPolicyPipeline(merged, policy);
  const normalized = normalizeToolParameters(filtered);

  return normalized.map(wrapToolWithBeforeToolCallHook);
}

type AnyAgentTool = {
  name: string;
  label?: string;
  description: string;
  parameters?: unknown;
  execute?: (
    id: string,
    args: unknown,
    signal: AbortSignal
  ) => Promise<unknown>;
  ownerOnly?: boolean;
};

Profile Policy
  → Provider Profile Policy
  → Global Policy
  → Agent Policy
  → Group Policy
  → Sandbox Policy
  → Subagent Policy

type ToolPolicyConfig = {
  allow?: string[];
  alsoAllow?: string[];
  deny?: string[];
  profile?: "minimal" | "coding" | "messaging" | "full";
};

type PluginToolRegistration = {
  pluginId: string;
  factory: OpenClawPluginToolFactory;
  names: string[];
  optional: boolean;
  source: string;
};

POST /tools/invoke
Content-Type: application/json
Authorization: Bearer your-token

{
  "tool": "browser",
  "action": "screenshot",
  "args": {
    "url": "https://example.com"
  },
  "sessionKey": "agent:main"
}

{agentId}:{mainKey}:{channel}:{accountId}:{peerKind}:{peerId}

src/
├── channels/
│   ├── plugins/
│   │   ├── types.plugin.ts
│   │   ├── types.adapters.ts
│   │   ├── types.core.ts
│   │   └── registry-loader.ts
│   ├── dock.ts
│   ├── registry.ts
│   ├── allow-from.ts
│   ├── channel-config.ts
│   └── session.ts
├── routing/
│   ├── resolve-route.ts
│   ├── bindings.ts
│   └── session-key.ts
├── telegram/
├── discord/
├── slack/
├── signal/
├── imessage/
├── web/
├── infra/outbound/
└── plugins/

extensions/
├── msteams/
├── matrix/
├── zalo/
└── voice-call/

const CONTEXT_WINDOW_HARD_MIN_TOKENS = 16_000;
const CONTEXT_WINDOW_WARN_BELOW_TOKENS = 32_000;

const BASE_CHUNK_RATIO = 0.4;
const MIN_CHUNK_RATIO = 0.15;
const SAFETY_MARGIN = 1.2;

isOversizedForSummary(message, contextWindow);

const DEFAULT_CONTEXT_PRUNING_SETTINGS = {
  mode: "cache-ttl",
  ttlMs: 5 * 60 * 1000,
  keepLastAssistants: 3,

  softTrimRatio: 0.3,
  hardClearRatio: 0.5,
  minPrunableToolChars: 50_000,

  softTrim: {
    maxChars: 4_000,
    headChars: 1_500,
    tailChars: 1_500
  },

  hardClear: {
    enabled: true,
    placeholder: "[Old tool result content cleared]"
  }
};

const SINGLE_TOOL_RESULT_CONTEXT_SHARE = 0.5;
const TOOL_RESULT_CHARS_PER_TOKEN_ESTIMATE = 2;

const maxSingleToolResultChars =
  contextWindowTokens * 2 * 0.5;

const contextBudgetChars =
  contextWindowTokens * 4 * 0.75;

// 超预算时压缩最旧工具结果

[compacted: tool output removed to free context]

{
  "agents": {
    "defaults": {
      "bootstrapMaxChars": 20000,
      "bootstrapTotalMaxChars": 150000
    }
  }
}

{
  "agents": {
    "defaults": {
      "contextTokens": 200000,
      "bootstrapMaxChars": 20000,
      "bootstrapTotalMaxChars": 150000,
      "compaction": {
        "mode": "auto",
        "targetTokens": 0.7
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m",
        "keepLastAssistants": 3,
        "softTrimRatio": 0.3,
        "hardClearRatio": 0.5
      }
    }
  },
  "models": {
    "providers": {
      "anthropic": {
        "models": [
          {
            "id": "claude-sonnet-4",
            "contextWindow": 200000
          }
        ]
      }
    }
  }
}

export function getSubagentDepthFromSessionStore(
  sessionKey: string | undefined | null,
  opts?: {
    cfg?: OpenClawConfig;
    store?: Record<string, SessionDepthEntry>;
  }
): number {
  const fallbackDepth = getSubagentDepth(sessionKey);

  const entry = loadSessionEntry(sessionKey);
  const storedDepth = normalizeSpawnDepth(entry?.spawnDepth);

  if (storedDepth !== undefined) {
    return storedDepth;
  }

  const parentDepth = depthFromStore(entry?.spawnedBy);
  return parentDepth + 1 || fallbackDepth;
}

type SubagentRunRecord = {
  runId: string;
  childSessionKey: string;
  requesterSessionKey: string;
  requesterOrigin?: DeliveryContext;

  task: string;
  cleanup: "delete" | "keep";
  label?: string;
  model?: string;
  runTimeoutSeconds?: number;
  spawnMode?: SpawnSubagentMode;

  createdAt: number;
  startedAt?: number;
  endedAt?: number;

  outcome?: SubagentRunOutcome;
  suppressAnnounceReason?: "steer-restart" | "killed";
  endedReason?: SubagentLifecycleEndedReason;
};

function buildSubagentSystemPrompt(params: {
  requesterSessionKey?: string;
  childSessionKey: string;
  label?: string;
  task?: string;
  childDepth?: number;
  maxSpawnDepth?: number;
}) {
  const canSpawn = params.childDepth < params.maxSpawnDepth;

  const lines = [
    "# Subagent Context",
    "You are a subagent spawned for a specific task.",
    "",
    "## Your Role",
    `- You were created to handle: ${params.task}`,
    "- Complete this task. That's your entire purpose.",
    "",
    "## Rules",
    "1. Stay focused.",
    "2. Complete the task.",
    "3. Don't initiate unrelated actions.",
    "4. Be ephemeral.",
    "5. Trust push-based completion.",
    "6. Re-read with smaller chunks if tool output was compacted."
  ];

  if (canSpawn) {
    lines.push(
      "## Sub-Agent Spawning",
      "You CAN spawn your own sub-agents using sessions_spawn.",
      "Use the subagents tool to steer, kill, or check status."
    );
  } else {
    lines.push(
      "## Sub-Agent Spawning",
      "You are a leaf worker and CANNOT spawn further sub-agents."
    );
  }

  return lines.join("\n");
}

function resolveRequesterKey(params: {
  cfg: OpenClawConfig;
  agentSessionKey?: string;
}) {
  const callerSessionKey = resolveInternalSessionKey(params.agentSessionKey);

  if (!isSubagentSessionKey(callerSessionKey)) {
    return {
      requesterSessionKey: callerSessionKey,
      callerIsSubagent: false
    };
  }

  const callerDepth = getSubagentDepthFromSessionStore(callerSessionKey);
  const maxSpawnDepth =
    params.cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? 1;

  if (callerDepth < maxSpawnDepth) {
    return {
      requesterSessionKey: callerSessionKey,
      callerIsSubagent: true
    };
  }

  const spawnedBy = loadSessionEntry(callerSessionKey)?.spawnedBy;
  return {
    requesterSessionKey: spawnedBy || callerSessionKey,
    callerIsSubagent: true
  };
}

async function cascadeKillChildren(params: {
  parentChildSessionKey: string;
}) {
  const childRuns = listSubagentRunsForRequester(
    params.parentChildSessionKey
  );

  let killed = 0;

  for (const run of childRuns) {
    if (!run.endedAt) {
      const result = await killSubagentRun(run);
      if (result.killed) {
        killed += 1;
      }
    }

    const cascade = await cascadeKillChildren({
      parentChildSessionKey: run.childSessionKey
    });

    killed += cascade.killed;
  }

  return { killed };
}

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2,
        maxChildrenPerAgent: 5,
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
        model: "claude-3-haiku",
        thinking: "medium"
      }
    },
    list: [
      {
        agentId: "orchestrator",
        subagents: {
          allowAgents: ["*"]
        }
      }
    ]
  },
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
        allow: ["read", "exec"]
      }
    }
  }
}

export function registerDiscordSubagentHooks() {
  const hookRunner = getGlobalHookRunner();

  hookRunner.register("subagent_spawning", async (event) => {
    const thread = await createDiscordThread({
      channelId: event.requester.to,
      name: `Subagent: ${event.label || event.agentId}`
    });

    return {
      status: "ok",
      threadBindingReady: true,
      threadId: thread.id
    };
  });

  hookRunner.register("subagent_delivery_target", async (event) => {
    const binding = getThreadBinding(event.childSessionKey);

    if (binding) {
      return {
        origin: {
          channel: "discord",
          to: binding.channelId,
          threadId: binding.threadId
        }
      };
    }

    return {
      origin: event.requesterOrigin
    };
  });
}

export const enum CommandLane {
  Main = "main",
  Cron = "cron",
  Subagent = "subagent",
  Nested = "nested"
}

async function maybeQueueSubagentAnnounce(params) {
  const queueSettings = resolveQueueSettings(params);
  const isActive = isEmbeddedPiRunActive(params.sessionId);

  if (queueSettings.mode === "steer") {
    const steered = queueEmbeddedPiMessage(
      params.sessionId,
      params.triggerMessage
    );

    if (steered) {
      return "steered";
    }
  }

  if (isActive && queueSettings.mode === "followup") {
    enqueueAnnounce({
      key: buildAnnounceQueueKey(params.sessionKey, params.origin),
      item: params.announce,
      settings: queueSettings,
      send: sendAnnounce
    });

    return "queued";
  }

  return "none";
}

用户：研究 A、B、C 三个主题并生成报告

主智能体：
  - sessions_spawn(task: "研究主题 A", label: "research-a")
  - sessions_spawn(task: "研究主题 B", label: "research-b")
  - sessions_spawn(task: "研究主题 C", label: "research-c")

research-a 完成后通告结果
research-b 完成后通告结果
research-c 完成后通告结果

主智能体汇总三个结果，生成最终报告

用户：重构这个大型项目

主智能体：
  - sessions_spawn(
      task: "协调重构工作",
      agentId: "orchestrator",
      label: "refactor-coordinator"
    )

refactor-coordinator：
  - sessions_spawn(task: "重构模块 A", label: "worker-a")
  - sessions_spawn(task: "重构模块 B", label: "worker-b")
  - sessions_spawn(task: "重构模块 C", label: "worker-c")

worker-a / worker-b / worker-c 完成后通告给 refactor-coordinator
refactor-coordinator 汇总后通告主智能体
主智能体向用户报告完成情况

用户在 Discord 线程中：监控这个服务的性能

主智能体：
  - sessions_spawn(
      task: "启动性能监控",
      thread: true,
      mode: "session"
    )

Discord 扩展创建专用线程
子智能体在该线程中持续运行

用户：当前状态如何？
消息路由到绑定的子智能体会话

用户：/unfocus
解除线程绑定，后续消息回到主智能体