@botcord/daemon 0.2.4 → 0.2.6

package/src/agent-workspace.ts

@@ -7,8 +7,14 @@
  *   codex-home/  — per-agent CODEX_HOME used by the codex adapter so codex
  *                  reads a daemon-written AGENTS.md (systemContext carrier)
  *                  and stores its sessions/ without touching ~/.codex.
- *
- * See docs/daemon-agent-workspace-plan.md §4 for the full layout rationale.
+ *   hermes-home/      — per-agent HERMES_HOME used by the hermes-acp
+ *                       adapter (carries .env, state.db, skills/) so
+ *                       hermes-acp's per-user state stays isolated.
+ *   hermes-workspace/ — per-agent runtime cwd for hermes-acp; the adapter
+ *                       writes systemContext into AGENTS.md here every turn.
+ *                       Kept separate from `workspace/` so daemon-written
+ *                       systemContext does not clobber the user/agent-
+ *                       editable workspace AGENTS.md.
  */
 import {
   chmodSync,
@@ -16,6 +22,7 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readFileSync,
   readlinkSync,
   symlinkSync,
   unlinkSync,
@@ -60,6 +67,26 @@ export function agentCodexHomeDir(agentId: string): string {
   return path.join(agentHomeDir(agentId), "codex-home");
 }
 
+/**
+ * Per-agent HERMES_HOME. Carries the hermes-acp `.env`, `state.db`, and
+ * `skills/` so each daemon-managed agent has an isolated hermes config
+ * tree and never reads/writes the user's `~/.hermes`.
+ */
+export function agentHermesHomeDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "hermes-home");
+}
+
+/**
+ * Per-agent runtime cwd for hermes-acp. Distinct from `workspace/` so the
+ * adapter can rewrite `AGENTS.md` here every turn (carrying the dynamic
+ * systemContext) without clobbering the user/agent-editable workspace
+ * `AGENTS.md`. hermes discovers `AGENTS.md` from cwd upward, so the file
+ * must live alongside the spawn cwd.
+ */
+export function agentHermesWorkspaceDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "hermes-workspace");
+}
+
 export interface WorkspaceSeed {
   displayName?: string;
   bio?: string;
@@ -89,10 +116,14 @@ This directory is your persistent workspace. You run with \`cwd\` set here.
 
 ## How to use this
 
-You are **instructed** to skim \`identity.md\`, \`memory.md\`, \`task.md\` before each
-response and to write back what changed after meaningful turns. Nothing in the
-runtime enforces this — the daemon does not auto-load these files into your
-context. Treat AGENTS.md as a convention, not a mechanism.
+- \`identity.md\` is **auto-loaded** by the daemon and injected into every turn's
+  system context as the \`[BotCord Identity]\` block. Edits to this file (yours,
+  the dashboard's via \`applyAgentIdentity\`, or a hello-snapshot reapply) take
+  effect on the next turn — no restart needed.
+- \`memory.md\` and \`task.md\` are **convention, not mechanism**. The daemon does
+  not auto-load them; you are instructed to skim them before responding and to
+  write back what changed after meaningful turns. Keep them tight enough to be
+  worth re-reading.
 `;
 
 const MEMORY_MD = `# Memory
@@ -100,9 +131,9 @@ const MEMORY_MD = `# Memory
 <!--
 Long-lived facts about the user, past decisions, and preferences that should
 survive across conversations. Organize by topic. Keep entries short. Prune
-regularly — AGENTS.md instructs the runtime to consult this file before each
-response, but nothing loads it automatically; keep it short enough to be
-worth re-reading.
+regularly — AGENTS.md instructs you to consult this file before each
+response, but nothing loads it automatically (unlike identity.md); keep it
+short enough to be worth re-reading.
 -->
 `;
 
@@ -217,6 +248,28 @@ export function ensureAgentCodexHome(agentId: string): string {
   return dir;
 }
 
+/**
+ * Idempotently create the per-agent HERMES_HOME and HERMES workspace
+ * directories. Writes a stub `.env` inside HERMES_HOME so hermes-acp's
+ * `_load_env` does not log "No .env found" on every spawn; users can edit
+ * this file to add API keys / model overrides.
+ */
+export function ensureAgentHermesWorkspace(agentId: string): {
+  hermesHome: string;
+  hermesWorkspace: string;
+} {
+  const hermesHome = agentHermesHomeDir(agentId);
+  const hermesWorkspace = agentHermesWorkspaceDir(agentId);
+  mkdirTolerant(hermesHome);
+  mkdirTolerant(hermesWorkspace);
+  writeIfMissing(
+    path.join(hermesHome, ".env"),
+    "# hermes-agent environment overrides for this BotCord agent.\n" +
+      "# Add e.g. HERMES_INFERENCE_PROVIDER=openrouter, OPENROUTER_API_KEY=...\n",
+  );
+  return { hermesHome, hermesWorkspace };
+}
+
 /**
  * Idempotently create the agent's home / workspace / state directories and
  * seed the workspace Markdown files. Existing files are never overwritten —
@@ -235,6 +288,7 @@ export function ensureAgentWorkspace(agentId: string, seed: WorkspaceSeed): void
   mkdirTolerant(notes);
   mkdirTolerant(state);
   ensureAgentCodexHome(agentId);
+  ensureAgentHermesWorkspace(agentId);
 
   const agentsMdPath = path.join(workspace, "AGENTS.md");
   const claudeMdPath = path.join(workspace, "CLAUDE.md");
@@ -245,3 +299,113 @@ export function ensureAgentWorkspace(agentId: string, seed: WorkspaceSeed): void
   writeIfMissing(path.join(workspace, "task.md"), TASK_MD);
   writeIfMissing(path.join(notes, ".gitkeep"), "");
 }
+
+/** Patch fields accepted by {@link applyAgentIdentity}. `bio = null` clears it. */
+export interface AgentIdentityPatch {
+  displayName?: string;
+  bio?: string | null;
+}
+
+/**
+ * Result of applying an identity patch. `changed` is true only when the
+ * file was rewritten on disk; `skipped` reports why (no-op vs. unable).
+ */
+export interface AgentIdentityApplyResult {
+  changed: boolean;
+  skipped?: "missing-file" | "no-change" | "unparseable";
+}
+
+const DISPLAY_NAME_LINE = /^- \*\*Display name\*\*: .*$/m;
+// Match the Bio section's body. Anchor on the next `##` heading when one
+// exists, otherwise consume to end-of-file — keeps the rewrite working when
+// the user has stripped Role/Boundaries sections.
+const BIO_SECTION = /(## Bio\n\n)([\s\S]*?)(\n+##\s|$)/;
+
+/**
+ * Surgically rewrite the `Display name` and `Bio` fields inside an existing
+ * `identity.md`, preserving anything the user has authored elsewhere
+ * (Role / Boundaries / arbitrary new sections). No-op when the file is
+ * missing — provisioning will create it with the correct values, and
+ * subsequent hello snapshots simply reapply the dashboard truth.
+ *
+ * The identity.md template carries `Role` / `Boundaries` headings after
+ * `## Bio`; we anchor the Bio rewrite on "next `##`" so user-added
+ * paragraphs inside Bio are replaced wholesale (the dashboard is the
+ * source of truth) without disturbing siblings.
+ */
+export function applyAgentIdentity(
+  agentId: string,
+  patch: AgentIdentityPatch,
+): AgentIdentityApplyResult {
+  assertSafeAgentId(agentId);
+  const file = path.join(agentWorkspaceDir(agentId), "identity.md");
+  if (!existsSync(file)) {
+    return { changed: false, skipped: "missing-file" };
+  }
+
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return { changed: false, skipped: "missing-file" };
+  }
+
+  const original = text;
+  let touched = false;
+
+  if (typeof patch.displayName === "string") {
+    const value = patch.displayName.length > 0 ? patch.displayName : FIELD_PLACEHOLDER;
+    if (DISPLAY_NAME_LINE.test(text)) {
+      // Use a function replacer so `$1`, `$&` etc. inside the value are
+      // treated literally rather than as backreferences.
+      text = text.replace(DISPLAY_NAME_LINE, () => `- **Display name**: ${value}`);
+      touched = true;
+    } else {
+      // Heavily-edited file without the canonical metadata block — bail
+      // out rather than guess where to splice.
+      return { changed: false, skipped: "unparseable" };
+    }
+  }
+
+  if (patch.bio !== undefined) {
+    const bioText =
+      patch.bio !== null && patch.bio.trim().length > 0
+        ? patch.bio.trim()
+        : BIO_PLACEHOLDER;
+    if (BIO_SECTION.test(text)) {
+      text = text.replace(BIO_SECTION, (_match, head, _body, tail) => `${head}${bioText}${tail}`);
+      touched = true;
+    } else {
+      return { changed: false, skipped: "unparseable" };
+    }
+  }
+
+  if (!touched || text === original) {
+    return { changed: false, skipped: "no-change" };
+  }
+
+  writeFileSync(file, text, { mode: 0o600 });
+  return { changed: true };
+}
+
+/**
+ * Read the agent's `identity.md` verbatim, if it exists. Returns the raw
+ * contents (including the leading `# Identity` heading) so callers can
+ * splice it into the system context. Returns `null` when the workspace
+ * has not been provisioned yet, the file is empty, or the read fails.
+ *
+ * Each call hits disk — same contract as `readWorkingMemory`, so a
+ * dashboard-driven edit (`applyAgentIdentity` from a control frame, or
+ * a hello-snapshot reapply, or the agent's own self-edit) is visible
+ * on the very next turn without restarting the gateway.
+ */
+export function readIdentity(agentId: string): string | null {
+  assertSafeAgentId(agentId);
+  const file = path.join(agentWorkspaceDir(agentId), "identity.md");
+  try {
+    const raw = readFileSync(file, "utf8");
+    return raw.trim().length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}

package/src/config.ts

@@ -13,7 +13,24 @@ export const SNAPSHOT_PATH = path.join(DAEMON_DIR, "snapshot.json");
  * Adapter ids. Built-in adapters are enumerated for editor hints; any string
  * accepted by the registry is valid at runtime.
  */
-export type AdapterName = "claude-code" | "codex" | "gemini" | (string & {});
+export type AdapterName = "claude-code" | "codex" | "gemini" | "openclaw-acp" | (string & {});
+
+/**
+ * One OpenClaw gateway profile. Referenced by `RouteRule.gateway` and
+ * `DaemonRouteDefault.gateway` (and `StoredBotCordCredentials.openclawGateway`)
+ * via `name`. `tokenFile` is `~`-expanded and read at `toGatewayConfig` time;
+ * read failures do not block boot — the gateway becomes unusable but other
+ * gateways still work.
+ */
+export interface OpenclawGatewayProfile {
+  name: string;
+  url: string;
+  /** Bearer token; mutually-exclusive priority is `token > tokenFile`. */
+  token?: string;
+  tokenFile?: string;
+  /** Default OpenClaw agent profile name when a route does not pin one. */
+  defaultAgent?: string;
+}
 
 /**
  * Predicates selecting messages for a route. `roomId` / `roomPrefix` are
@@ -41,12 +58,23 @@ export interface RouteRule {
   cwd: string;
   /** Extra CLI flags appended to the adapter invocation. */
   extraArgs?: string[];
+  /**
+   * Required when `adapter === "openclaw-acp"`: name of an entry in
+   * `DaemonConfig.openclawGateways[]`.
+   */
+  gateway?: string;
+  /** Overrides `OpenclawGatewayProfile.defaultAgent` when set. */
+  openclawAgent?: string;
 }
 
 export interface DaemonRouteDefault {
   adapter: AdapterName;
   cwd: string;
   extraArgs?: string[];
+  /** Same semantics as `RouteRule.gateway`. */
+  gateway?: string;
+  /** Same semantics as `RouteRule.openclawAgent`. */
+  openclawAgent?: string;
 }
 
 /**
@@ -90,6 +118,28 @@ export interface DaemonConfig {
   routes: RouteRule[];
   /** If true, stream blocks (only meaningful for rm_oc_* rooms). */
   streamBlocks: boolean;
+  /**
+   * Persistent transcript-logging settings (design §3 / §6). Defaults to
+   * disabled — see `BOTCORD_TRANSCRIPT` for env-driven temporary overrides.
+   */
+  transcript?: TranscriptConfig;
+
+  /**
+   * Optional registry of OpenClaw gateway endpoints. Routes / managed routes
+   * with `adapter === "openclaw-acp"` reference these by `name`. Resolution
+   * to {@link ResolvedOpenclawGateway} happens eagerly in `toGatewayConfig`
+   * so the dispatcher never re-queries this list.
+   */
+  openclawGateways?: OpenclawGatewayProfile[];
+}
+
+/**
+ * Persistent transcript settings (design §6). Default-off — `botcord-daemon
+ * transcript enable` flips `enabled` and `transcript disable` flips it back.
+ * The env var `BOTCORD_TRANSCRIPT` can override at boot.
+ */
+export interface TranscriptConfig {
+  enabled?: boolean;
 }
 
 /**
@@ -160,11 +210,15 @@ function ensureDir(): void {
   }
 }
 
+export const CONFIG_MISSING = "CONFIG_MISSING";
+
 export function loadConfig(): DaemonConfig {
   if (!existsSync(CONFIG_PATH)) {
-    throw new Error(
-      `daemon config not found at ${CONFIG_PATH}. Run \`botcord-daemon init\` first.`,
-    );
+    const err = new Error(`daemon config not found at ${CONFIG_PATH}`) as Error & {
+      code?: string;
+    };
+    err.code = CONFIG_MISSING;
+    throw err;
   }
   const raw = readFileSync(CONFIG_PATH, "utf8");
   const parsed = JSON.parse(raw) as Partial<DaemonConfig>;
@@ -196,6 +250,65 @@ export function loadConfig(): DaemonConfig {
   }
   validateAdapter(parsed.defaultRoute.adapter, "defaultRoute.adapter");
 
+  const gatewaysRaw = (parsed as Partial<DaemonConfig>).openclawGateways;
+  const gatewayNames = new Set<string>();
+  if (gatewaysRaw !== undefined) {
+    if (!Array.isArray(gatewaysRaw)) {
+      throw new Error(
+        `daemon config "openclawGateways" must be an array (${CONFIG_PATH})`,
+      );
+    }
+    for (const [i, g] of gatewaysRaw.entries()) {
+      if (!g || typeof g !== "object") {
+        throw new Error(
+          `daemon config openclawGateways[${i}] is not an object (${CONFIG_PATH})`,
+        );
+      }
+      const gg = g as Partial<OpenclawGatewayProfile>;
+      if (typeof gg.name !== "string" || gg.name.length === 0) {
+        throw new Error(
+          `daemon config openclawGateways[${i}].name must be a non-empty string (${CONFIG_PATH})`,
+        );
+      }
+      if (typeof gg.url !== "string" || gg.url.length === 0) {
+        throw new Error(
+          `daemon config openclawGateways[${i}].url must be a non-empty string (${CONFIG_PATH})`,
+        );
+      }
+      if (gatewayNames.has(gg.name)) {
+        throw new Error(
+          `daemon config openclawGateways[${i}].name "${gg.name}" duplicated (${CONFIG_PATH})`,
+        );
+      }
+      gatewayNames.add(gg.name);
+    }
+  }
+
+  const validateGatewayRef = (
+    adapter: string,
+    gateway: unknown,
+    where: string,
+  ): void => {
+    if (adapter === "openclaw-acp") {
+      if (typeof gateway !== "string" || gateway.length === 0) {
+        throw new Error(
+          `daemon config ${where} adapter "openclaw-acp" requires a "gateway" name (${CONFIG_PATH})`,
+        );
+      }
+      if (!gatewayNames.has(gateway)) {
+        throw new Error(
+          `daemon config ${where}.gateway "${gateway}" not in openclawGateways (${CONFIG_PATH})`,
+        );
+      }
+    }
+  };
+
+  validateGatewayRef(
+    parsed.defaultRoute.adapter,
+    (parsed.defaultRoute as DaemonRouteDefault).gateway,
+    "defaultRoute",
+  );
+
   const routesRaw = parsed.routes ?? [];
   if (!Array.isArray(routesRaw)) {
     throw new Error(`daemon config "routes" must be an array (${CONFIG_PATH})`);
@@ -210,6 +323,7 @@ export function loadConfig(): DaemonConfig {
       );
     }
     validateAdapter(r.adapter, `routes[${i}].adapter`);
+    validateGatewayRef(r.adapter, (r as RouteRule).gateway, `routes[${i}]`);
   }
   // Preserve the on-disk shape as-is so `config` prints what the user wrote.
   // Resolution of agents vs agentId happens at the consumption boundary
@@ -219,6 +333,20 @@ export function loadConfig(): DaemonConfig {
     routes: routesRaw,
     streamBlocks: parsed.streamBlocks ?? true,
   };
+  if (parsed.transcript && typeof parsed.transcript === "object") {
+    const t: TranscriptConfig = {};
+    if (typeof parsed.transcript.enabled === "boolean") t.enabled = parsed.transcript.enabled;
+    out.transcript = t;
+  }
+  if (gatewaysRaw && Array.isArray(gatewaysRaw)) {
+    out.openclawGateways = (gatewaysRaw as OpenclawGatewayProfile[]).map((g) => {
+      const copy: OpenclawGatewayProfile = { name: g.name, url: g.url };
+      if (typeof g.token === "string") copy.token = g.token;
+      if (typeof g.tokenFile === "string") copy.tokenFile = g.tokenFile;
+      if (typeof g.defaultAgent === "string") copy.defaultAgent = g.defaultAgent;
+      return copy;
+    });
+  }
   if (hasAgents) out.agents = (parsed.agents as string[]).slice();
   if (hasLegacy) out.agentId = parsed.agentId;
   if (discovery && typeof discovery === "object") {

package/src/control-channel.ts

@@ -5,8 +5,6 @@
  * Independent from the agent data-plane WS: different auth (user access
  * token vs agent JWT), different endpoint (`/daemon/ws`), different
  * lifecycle (alive even when zero agents are bound).
- *
- * See `docs/daemon-control-plane-plan.md` §4.1, §4.3, §8.
  */
 import WebSocket from "ws";
 import {
@@ -31,8 +29,7 @@ const REPLAY_DEDUPE_CAP = 256;
 
 /**
  * Build the canonical signing input for a control frame: RFC 8785 (JCS)
- * canonicalization of `{id, type, params, ts}`. Per
- * `docs/daemon-control-plane-api-contract.md` §3.3 — the Hub uses Python
+ * canonicalization of `{id, type, params, ts}`. The Hub uses Python
  * `jcs.canonicalize` over the same object before signing.
  *
  * Excludes `sig` by definition. `params` defaults to `{}` (empty object)

package/src/daemon-config-map.ts

@@ -1,15 +1,109 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 import type {
   GatewayChannelConfig,
   GatewayConfig,
   GatewayRoute,
+  ResolvedOpenclawGateway,
   RouteMatch,
   TrustLevel as GatewayTrustLevel,
 } from "./gateway/index.js";
-import type { DaemonConfig, RouteRule } from "./config.js";
+import type {
+  DaemonConfig,
+  DaemonRouteDefault,
+  OpenclawGatewayProfile,
+  RouteRule,
+} from "./config.js";
 import { resolveAgentIds } from "./config.js";
 import { agentWorkspaceDir } from "./agent-workspace.js";
 import { log as daemonLog } from "./log.js";
 
+/** Per-agent metadata cached from credentials, used by `buildManagedRoutes`. */
+export interface AgentRuntimeMeta {
+  runtime?: string;
+  cwd?: string;
+  /** OpenClaw gateway profile name to lookup in the registry. */
+  openclawGateway?: string;
+  /** Optional override of the OpenClaw agent profile within the gateway. */
+  openclawAgent?: string;
+}
+
+/** Profile + tokenFile-resolved bearer token. Exported so other module-boundary
+ *  paths (runtime probing, post-provision hot-add) reuse the same resolver
+ *  instead of duplicating tokenFile semantics. */
+export interface PreparedGatewayProfile extends OpenclawGatewayProfile {
+  /** Token actually usable at dispatch time; empty when load failed. */
+  resolvedToken?: string;
+  /** Reason `resolvedToken` is empty, for logs. */
+  tokenError?: string;
+}
+
+function expandHome(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return path.join(homedir(), p.slice(2));
+  return p;
+}
+
+/** Resolve one profile's token (inline > tokenFile). Failures are swallowed
+ *  into `tokenError`; `resolvedToken` is left undefined. Logs at warn for ops
+ *  visibility. */
+export function prepareGatewayProfile(
+  p: OpenclawGatewayProfile,
+): PreparedGatewayProfile {
+  const prepared: PreparedGatewayProfile = { ...p };
+  if (p.token && p.token.length > 0) {
+    prepared.resolvedToken = p.token;
+  } else if (p.tokenFile && p.tokenFile.length > 0) {
+    try {
+      prepared.resolvedToken = readFileSync(expandHome(p.tokenFile), "utf8").trim();
+    } catch (err: any) {
+      prepared.tokenError = err?.message ?? String(err);
+      daemonLog.warn("daemon.config.openclaw.tokenfile_failed", {
+        gateway: p.name,
+        tokenFile: p.tokenFile,
+        error: prepared.tokenError,
+      });
+    }
+  }
+  return prepared;
+}
+
+/** Build a name → prepared-profile map for a config's gateway registry. */
+export function prepareGatewayProfiles(
+  profiles: OpenclawGatewayProfile[] | undefined,
+): Map<string, PreparedGatewayProfile> {
+  const out = new Map<string, PreparedGatewayProfile>();
+  if (!profiles) return out;
+  for (const p of profiles) out.set(p.name, prepareGatewayProfile(p));
+  return out;
+}
+
+function resolveGateway(
+  profiles: Map<string, PreparedGatewayProfile>,
+  gatewayName: string | undefined,
+  agentOverride: string | undefined,
+  where: string,
+): ResolvedOpenclawGateway | undefined {
+  if (!gatewayName) {
+    daemonLog.warn("daemon.config.openclaw.missing_gateway", { where });
+    return undefined;
+  }
+  const profile = profiles.get(gatewayName);
+  if (!profile) {
+    daemonLog.warn("daemon.config.openclaw.unknown_gateway", { where, gateway: gatewayName });
+    return undefined;
+  }
+  const resolved: ResolvedOpenclawGateway = {
+    name: profile.name,
+    url: profile.url,
+  };
+  if (profile.resolvedToken) resolved.token = profile.resolvedToken;
+  const agent = agentOverride ?? profile.defaultAgent;
+  if (agent) resolved.openclawAgent = agent;
+  return resolved;
+}
+
 /** Options accepted by {@link toGatewayConfig}. */
 export interface ToGatewayConfigOptions {
   /**
@@ -19,13 +113,12 @@ export interface ToGatewayConfigOptions {
    */
   agentIds?: string[];
   /**
-   * Per-agent runtime/cwd cached from credentials (see
-   * `docs/agent-runtime-property-plan.md`). When present for an agent id,
-   * `toGatewayConfig` synthesizes a terminal route pinning that agent's
+   * Per-agent runtime/cwd cached from credentials. When present for an agent
+   * id, `toGatewayConfig` synthesizes a terminal route pinning that agent's
    * turns to its runtime. Explicit `cfg.routes` entries still win because
    * synthesized routes are appended after them.
    */
-  agentRuntimes?: Record<string, { runtime?: string; cwd?: string }>;
+  agentRuntimes?: Record<string, AgentRuntimeMeta>;
 }
 
 /**
@@ -60,7 +153,11 @@ function mapTrustLevel(
  * legacy alias and its canonical field are present, the canonical field
  * wins and a warning is logged.
  */
-function mapRoute(r: RouteRule): GatewayRoute {
+function mapRoute(
+  r: RouteRule,
+  profiles: Map<string, PreparedGatewayProfile>,
+  index: number,
+): GatewayRoute {
   const match: RouteMatch = {};
   if (r.match.channel) match.channel = r.match.channel;
   if (r.match.accountId) match.accountId = r.match.accountId;
@@ -96,13 +193,22 @@ function mapRoute(r: RouteRule): GatewayRoute {
   if (typeof r.match.mentioned === "boolean") match.mentioned = r.match.mentioned;
 
   const rawTrust = (r as { trustLevel?: "owner" | "untrusted" }).trustLevel;
-  return {
+  const out: GatewayRoute = {
     match,
     runtime: r.adapter,
     cwd: r.cwd,
     extraArgs: r.extraArgs,
     trustLevel: mapTrustLevel(rawTrust),
   };
+  if (r.adapter === "openclaw-acp") {
+    out.gateway = resolveGateway(
+      profiles,
+      r.gateway,
+      r.openclawAgent,
+      `routes[${index}]`,
+    );
+  }
+  return out;
 }
 
 /**
@@ -135,6 +241,8 @@ export function toGatewayConfig(
 
   // DaemonConfig's typed surface doesn't carry `trustLevel`, but we read it
   // defensively so future config extensions can propagate without a shape bump.
+  const profiles = prepareGatewayProfiles(cfg.openclawGateways);
+
   const rawDefaultTrust = (cfg.defaultRoute as { trustLevel?: "owner" | "untrusted" })
     .trustLevel;
   const defaultRoute: GatewayRoute = {
@@ -145,8 +253,17 @@ export function toGatewayConfig(
     // (direct → cancel-previous, group → serial).
     trustLevel: mapTrustLevel(rawDefaultTrust),
   };
+  if (cfg.defaultRoute.adapter === "openclaw-acp") {
+    const dr = cfg.defaultRoute as DaemonRouteDefault;
+    defaultRoute.gateway = resolveGateway(
+      profiles,
+      dr.gateway,
+      dr.openclawAgent,
+      "defaultRoute",
+    );
+  }
 
-  const routes: GatewayRoute[] = (cfg.routes ?? []).map(mapRoute);
+  const routes: GatewayRoute[] = (cfg.routes ?? []).map((r, i) => mapRoute(r, profiles, i));
 
   // Synthesize a per-agent route for every bound agent and hand it to the
   // gateway via the managed-routes bucket (plan §10.1). User-authored
@@ -158,6 +275,7 @@ export function toGatewayConfig(
     agentIds,
     opts.agentRuntimes ?? {},
     defaultRoute,
+    profiles,
   );
 
   return {
@@ -185,17 +303,43 @@ export function toGatewayConfig(
  */
 export function buildManagedRoutes(
   agentIds: string[],
-  agentRuntimes: Record<string, { runtime?: string; cwd?: string }>,
+  agentRuntimes: Record<string, AgentRuntimeMeta>,
   defaultRoute: GatewayRoute,
+  openclawProfiles?: Map<string, PreparedGatewayProfile>,
 ): Map<string, GatewayRoute> {
   const out = new Map<string, GatewayRoute>();
+  // Lazy-build profile map when caller didn't pass one (legacy callers).
+  const profiles = openclawProfiles ?? new Map<string, PreparedGatewayProfile>();
   for (const agentId of agentIds) {
     const meta = agentRuntimes[agentId] ?? {};
-    out.set(agentId, {
+    const runtime = meta.runtime ?? defaultRoute.runtime;
+    const route: GatewayRoute = {
       match: { accountId: agentId },
-      runtime: meta.runtime ?? defaultRoute.runtime,
+      runtime,
       cwd: meta.cwd || agentWorkspaceDir(agentId),
-    });
+      // Inherit defaultRoute's extraArgs so synthesized per-agent routes
+      // pick up operator-wide flags (e.g. `--permission-mode bypassPermissions`)
+      // that would otherwise apply only to agents listed in `cfg.routes[]`.
+      ...(defaultRoute.extraArgs ? { extraArgs: defaultRoute.extraArgs.slice() } : {}),
+    };
+    if (runtime === "openclaw-acp") {
+      // Per RFC §3.4: prefer credentials, fall back to defaultRoute.gateway.
+      const gatewayName = meta.openclawGateway ?? defaultRoute.gateway?.name;
+      const agentOverride = meta.openclawAgent;
+      const resolved = gatewayName
+        ? resolveGateway(profiles, gatewayName, agentOverride, `managedRoute[${agentId}]`)
+        : defaultRoute.gateway;
+      if (!resolved) {
+        // No usable gateway — skip the managed route so defaultRoute can take over.
+        daemonLog.warn("daemon.config.openclaw.managed_route_skipped", {
+          agentId,
+          gatewayName,
+        });
+        continue;
+      }
+      route.gateway = resolved;
+    }
+    out.set(agentId, route);
   }
   return out;
 }