@shadowob/cloud 1.1.6-dev.311

package/images/hermes-runner/entrypoint.mjs

@@ -0,0 +1,283 @@
+/**
+ * Hermes runner entrypoint.
+ *
+ * Materializes generated Hermes files and starts `hermes gateway` with the
+ * ShadowOB platform plugin enabled.
+ */
+
+import { spawn, spawnSync } from 'node:child_process'
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { createServer } from 'node:http'
+import { dirname, join, resolve } from 'node:path'
+
+const RUNTIME_NAME = 'hermes-runner'
+const CONFIG_MOUNT = process.env.SHADOW_RUNNER_CONFIG_MOUNT ?? '/etc/openclaw'
+const RUNTIME_FILES_PATH = join(CONFIG_MOUNT, 'runtime-files.json')
+const RUNTIME_EXTENSIONS_PATH = join(CONFIG_MOUNT, 'runtime-extensions.json')
+const RUNNER_HOME = process.env.HOME ?? '/home/shadow'
+const HEALTH_PORT = Number.parseInt(
+  process.env.SHADOW_RUNNER_HEALTH_PORT ?? process.env.OPENCLAW_GATEWAY_PORT ?? '3100',
+  10,
+)
+const LOG_DIR = process.env.SHADOW_RUNNER_LOG_DIR ?? '/var/log/shadowob'
+const ALLOWED_FILE_ROOTS = [RUNNER_HOME, '/home/openclaw', '/workspace', '/etc/shadowob']
+
+let ready = false
+let child = null
+
+const KEY_PATTERNS = [
+  /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+  /\bsk-proj-[A-Za-z0-9_-]{20,}\b/g,
+  /\bsk-[A-Za-z0-9]{20,}\b/g,
+  /\bgsk_[A-Za-z0-9]{20,}\b/g,
+  /\bBearer\s+[A-Za-z0-9._-]{20,}/g,
+  /\bshadow-[A-Za-z0-9._-]{20,}/g,
+]
+
+function redact(line) {
+  let result = line
+  for (const pattern of KEY_PATTERNS) {
+    pattern.lastIndex = 0
+    result = result.replace(pattern, '[REDACTED]')
+  }
+  return result
+}
+
+function loadJson(path, fallback) {
+  if (!existsSync(path)) return fallback
+  const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return fallback
+  return parsed
+}
+
+function resolveEnvPlaceholders(value) {
+  return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => process.env[key] ?? '')
+}
+
+function assertAllowedPath(path) {
+  const absolute = resolve(path)
+  if (!ALLOWED_FILE_ROOTS.some((root) => absolute === root || absolute.startsWith(`${root}/`))) {
+    throw new Error(`Refusing to materialize runtime file outside allowed roots: ${path}`)
+  }
+  return absolute
+}
+
+function modeForPath(path) {
+  if (path.endsWith('/.env') || path.endsWith('.yaml') || path.endsWith('.json')) return 0o600
+  return 0o644
+}
+
+function materializeRuntimeFiles() {
+  const files = loadJson(RUNTIME_FILES_PATH, {})
+  for (const [path, content] of Object.entries(files)) {
+    if (typeof content !== 'string') continue
+    const absolute = assertAllowedPath(path)
+    const mode = modeForPath(absolute)
+    mkdirSync(dirname(absolute), { recursive: true })
+    writeFileSync(absolute, resolveEnvPlaceholders(content), { encoding: 'utf-8', mode })
+    chmodSync(absolute, mode)
+    console.log(`[entrypoint] wrote ${absolute}`)
+  }
+}
+
+function materializeCredentialFiles() {
+  const runtimeExtensions = loadJson(RUNTIME_EXTENSIONS_PATH, {})
+  const files = Array.isArray(runtimeExtensions.credentialFiles)
+    ? runtimeExtensions.credentialFiles
+    : []
+  for (const file of files) {
+    if (!file || typeof file.envKey !== 'string' || typeof file.path !== 'string') continue
+    const value = process.env[file.envKey]
+    if (!value) continue
+    const absolute = assertAllowedPath(file.path)
+    const mode =
+      typeof file.mode === 'string' && /^[0-7]{3,4}$/.test(file.mode)
+        ? Number.parseInt(file.mode, 8)
+        : 0o600
+    mkdirSync(dirname(absolute), { recursive: true })
+    writeFileSync(absolute, value, { encoding: 'utf-8', mode })
+    chmodSync(absolute, mode)
+    console.log(`[entrypoint] materialized credential file ${absolute}`)
+  }
+}
+
+function entriesWithMarker(root, marker) {
+  if (!existsSync(root)) return []
+  if (existsSync(join(root, marker))) return [{ source: root, name: root.split('/').pop() }]
+  return readdirSync(root)
+    .map((name) => ({ source: join(root, name), name }))
+    .filter((entry) => {
+      try {
+        return statSync(entry.source).isDirectory() && existsSync(join(entry.source, marker))
+      } catch {
+        return false
+      }
+    })
+}
+
+function subagentEntries(root) {
+  if (!existsSync(root)) return []
+  return readdirSync(root)
+    .map((name) => ({ source: join(root, name), name }))
+    .filter((entry) => {
+      try {
+        const stat = statSync(entry.source)
+        if (stat.isFile()) return entry.name.endsWith('.md')
+        return stat.isDirectory()
+      } catch {
+        return false
+      }
+    })
+}
+
+function copyIfMissing(source, destination) {
+  if (existsSync(destination)) return false
+  mkdirSync(dirname(destination), { recursive: true })
+  cpSync(source, destination, { recursive: true })
+  return true
+}
+
+function isAllowedPluginAssetRoot(path) {
+  const absolute = resolve(path)
+  return [RUNNER_HOME, '/home/openclaw', '/workspace'].some(
+    (root) => absolute === root || absolute.startsWith(`${root}/`),
+  )
+}
+
+function materializePluginRuntimeAssets() {
+  const runtimeExtensions = loadJson(RUNTIME_EXTENSIONS_PATH, {})
+  const skillRoots = Array.isArray(runtimeExtensions.skillSources)
+    ? runtimeExtensions.skillSources
+        .map((source) => (typeof source?.targetPath === 'string' ? source.targetPath : undefined))
+        .filter((path) => path && isAllowedPluginAssetRoot(path))
+        .filter(Boolean)
+    : []
+  const subagentRoots = Array.isArray(runtimeExtensions.subagentSources)
+    ? runtimeExtensions.subagentSources
+        .map((source) => (typeof source?.targetPath === 'string' ? source.targetPath : undefined))
+        .filter((path) => path && isAllowedPluginAssetRoot(path))
+        .filter(Boolean)
+    : []
+  const skillDestinations = ['/workspace/.agents/skills', join(RUNNER_HOME, '.hermes/skills')]
+  const subagentDestinations = ['/workspace/.agents/agents', join(RUNNER_HOME, '.hermes/agents')]
+
+  for (const root of skillRoots) {
+    for (const entry of entriesWithMarker(root, 'SKILL.md')) {
+      for (const destinationRoot of skillDestinations) {
+        if (copyIfMissing(entry.source, join(destinationRoot, entry.name))) {
+          console.log(`[entrypoint] mirrored plugin skill ${entry.name} to ${destinationRoot}`)
+        }
+      }
+    }
+  }
+  for (const root of subagentRoots) {
+    for (const entry of subagentEntries(root)) {
+      for (const destinationRoot of subagentDestinations) {
+        if (copyIfMissing(entry.source, join(destinationRoot, entry.name))) {
+          console.log(`[entrypoint] mirrored plugin subagent ${entry.name} to ${destinationRoot}`)
+        }
+      }
+    }
+  }
+}
+
+function startHealthServer() {
+  const server = createServer((req, res) => {
+    if (req.url === '/health' || req.url === '/ready') {
+      res.writeHead(ready ? 200 : 503, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ status: ready ? 'ready' : 'starting', runtime: RUNTIME_NAME }))
+      return
+    }
+    if (req.url === '/live') {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ status: 'live', runtime: RUNTIME_NAME }))
+      return
+    }
+    res.writeHead(404)
+    res.end()
+  })
+  server.listen(HEALTH_PORT, '0.0.0.0', () => {
+    console.log(`[entrypoint] health server listening on :${HEALTH_PORT}`)
+  })
+  return server
+}
+
+function verifyBinary(command, args) {
+  const result = spawnSync(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10_000,
+  })
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed: ${result.stderr?.toString() ?? ''}`)
+  }
+}
+
+function startHermes() {
+  mkdirSync(LOG_DIR, { recursive: true })
+  const proc = spawn('hermes', ['gateway'], {
+    env: {
+      ...process.env,
+      HERMES_HOME: process.env.HERMES_HOME ?? join(RUNNER_HOME, '.hermes'),
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    cwd: '/workspace',
+  })
+  child = proc
+  proc.stdout.on('data', (chunk) => process.stdout.write(redact(chunk.toString())))
+  proc.stderr.on('data', (chunk) => process.stderr.write(redact(chunk.toString())))
+  proc.on('exit', (code, signal) => {
+    ready = false
+    console.error(`[entrypoint] hermes exited code=${code ?? 'null'} signal=${signal ?? 'null'}`)
+    process.exit(code ?? 1)
+  })
+  setTimeout(() => {
+    if (!proc.killed) ready = true
+  }, 3000)
+}
+
+function setupSignals(server) {
+  const shutdown = (signal) => {
+    ready = false
+    server.close()
+    if (child && !child.killed) child.kill(signal)
+    setTimeout(() => process.exit(0), 5000).unref()
+  }
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+  process.on('SIGINT', () => shutdown('SIGINT'))
+}
+
+async function main() {
+  console.log(`[entrypoint] ${RUNTIME_NAME} starting`)
+  mkdirSync('/workspace', { recursive: true })
+  mkdirSync('/etc/shadowob', { recursive: true })
+  materializeRuntimeFiles()
+  materializeCredentialFiles()
+  materializePluginRuntimeAssets()
+
+  if (process.env.SHADOW_RUNNER_VALIDATE_ONLY === '1') {
+    verifyBinary('hermes', ['--version'])
+    verifyBinary('shadowob', ['--help'])
+    verifyBinary('shadowob-connector', ['--help'])
+    ready = true
+    console.log('[entrypoint] validation completed')
+    return
+  }
+
+  const server = startHealthServer()
+  setupSignals(server)
+  startHermes()
+}
+
+main().catch((err) => {
+  console.error('[entrypoint] Fatal:', err)
+  process.exit(1)
+})

package/images/openclaw-runner/Dockerfile

@@ -0,0 +1,212 @@
+# syntax=docker/dockerfile:1.7
+
+# ─── OpenClaw Runner ──────────────────────────────────────────────────────
+# Container image for OpenClaw gateway runtime.
+#
+# User:   shadow:1000
+# Home:   /home/shadow
+# State:  /home/shadow/.openclaw   (emptyDir mount)
+# Config: /etc/openclaw              (ConfigMap mount, read-only)
+# Logs:   /var/log/openclaw          (emptyDir mount)
+#
+# Build from the repository root so the image can include the local
+# packages/openclaw-shadowob build:
+#   docker build -t ghcr.io/buggyblues/openclaw-runner:latest \
+#     -f apps/cloud/images/openclaw-runner/Dockerfile .
+# ──────────────────────────────────────────────────────────────────────────
+
+# ── Stage 1: Builder ─────────────────────────────────────────────────────
+FROM node:22-bookworm-slim AS builder
+
+WORKDIR /build
+
+ARG OPENCLAW_VERSION=2026.5.7
+ARG SHADOWOB_OPENCLAW_PLUGIN_VERSION=latest
+ARG PLAYWRIGHT_VERSION=1.59.1
+
+# git is required by some npm packages during install. Enable pnpm here so the
+# local Shadow workspace packages are built inside the image, not copied as
+# host-generated dist artifacts.
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates git && \
+    rm -rf /var/lib/apt/lists/* && \
+    corepack enable && \
+    corepack prepare pnpm@10.19.0 --activate
+
+# Install OpenClaw and the published shadowob plugin first. This provides a
+# stable runtime dependency layer; local package source changes below only
+# invalidate the small workspace build and overlay layers.
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+    npm init -y && \
+    npm install --prefer-offline --no-audit --fund=false \
+      "openclaw@${OPENCLAW_VERSION}" \
+      "@shadowob/openclaw-shadowob@${SHADOWOB_OPENCLAW_PLUGIN_VERSION}" \
+      "@shadowob/cli@latest" \
+      "@shadowob/connector@latest" \
+      "playwright-core@${PLAYWRIGHT_VERSION}"
+
+# Cleanup dev artifacts to reduce image size. This depends only on npm deps,
+# so local plugin edits do not force the dependency install/cleanup layers.
+RUN find node_modules -type d \( -name ".github" -o -name "test" -o -name "tests" \
+      -o -name "__tests__" -o -name "examples" \) \
+      -exec rm -rf {} + 2>/dev/null || true && \
+    find node_modules -type d -name "docs" ! -path "*/openclaw/docs*" \
+      -exec rm -rf {} + 2>/dev/null || true && \
+    find node_modules \( -name "*.d.ts" -o -name "*.d.ts.map" -o -name "*.js.map" \
+      -o -name "CHANGELOG.md" -o -name "README.md" \) \
+      -delete 2>/dev/null || true
+
+# Install the minimal workspace needed to build the local Shadow plugin. Copy
+# only lockfiles and manifests first so dependency resolution stays cached while
+# TypeScript source changes.
+WORKDIR /workspace
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.json .npmrc ./
+COPY packages/shared/package.json packages/shared/package.json
+COPY packages/sdk/package.json packages/sdk/package.json
+COPY packages/cli/package.json packages/cli/package.json
+COPY packages/openclaw-shadowob/package.json packages/openclaw-shadowob/package.json
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm config set store-dir /pnpm/store && \
+    pnpm install --frozen-lockfile --ignore-scripts \
+      --filter @shadowob/openclaw-shadowob... \
+      --filter @shadowob/cli...
+
+# Build local packages in-container. This makes the image reproducible in CI and
+# keeps it independent from whatever dist/ happens to exist on the host.
+COPY packages/shared packages/shared
+COPY packages/sdk packages/sdk
+COPY packages/cli packages/cli
+COPY packages/openclaw-shadowob packages/openclaw-shadowob
+RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store,sharing=locked \
+    pnpm --filter @shadowob/shared build && \
+    pnpm --filter @shadowob/sdk build && \
+    pnpm --filter @shadowob/cli build && \
+    pnpm --filter @shadowob/openclaw-shadowob build
+
+# Overlay the freshly built local Shadow packages into the runtime dependency
+# tree, preventing the bundled extension from resolving older published code.
+WORKDIR /build
+RUN for pkg in shared sdk cli; do \
+      rm -rf "node_modules/@shadowob/${pkg}" && \
+      mkdir -p "node_modules/@shadowob/${pkg}" && \
+      cp -r "/workspace/packages/${pkg}/package.json" "/workspace/packages/${pkg}/dist" "node_modules/@shadowob/${pkg}/"; \
+    done
+RUN mkdir -p extensions/shadowob && \
+    cp -r /workspace/packages/openclaw-shadowob/package.json \
+      /workspace/packages/openclaw-shadowob/openclaw.plugin.json \
+      /workspace/packages/openclaw-shadowob/dist \
+      /workspace/packages/openclaw-shadowob/skills \
+      extensions/shadowob/
+
+# ── Stage 2: Runner ─────────────────────────────────────────────────────
+FROM node:22-bookworm-slim AS runner
+
+LABEL org.opencontainers.image.source="https://github.com/nicepkg/shadow"
+LABEL org.opencontainers.image.description="Shadow Cloud OpenClaw Runner"
+
+ARG PLAYWRIGHT_VERSION=1.59.1
+
+# Install runtime dependencies (rarely changes → good cache layer). Chromium
+# and Playwright browsers are intentionally baked into the image so OpenClaw
+# browser/canvas tools do not try to bootstrap them after the gateway is live.
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ca-certificates \
+      chromium \
+      chromium-driver \
+      curl \
+      fonts-liberation \
+      fonts-noto-cjk \
+      fonts-noto-color-emoji \
+      git \
+      libasound2 \
+      libatk-bridge2.0-0 \
+      libatk1.0-0 \
+      libcups2 \
+      libdrm2 \
+      libgbm1 \
+      libgtk-3-0 \
+      libnss3 \
+      libx11-xcb1 \
+      libxcomposite1 \
+      libxdamage1 \
+      libxrandr2 \
+      python-is-python3 \
+      python3 \
+      python3-pip \
+      python3-venv \
+      tini \
+      xdg-utils && \
+    rm -rf /var/lib/apt/lists/* && \
+    mkdir -p /ms-playwright && \
+    npx -y "playwright@${PLAYWRIGHT_VERSION}" install --with-deps chromium && \
+    chmod -R 755 /ms-playwright
+
+# Create non-root user shadow:1000
+# node images ship with node:node at UID/GID 1000 — remove it first
+RUN userdel -r node 2>/dev/null || true; \
+    groupdel node 2>/dev/null || true; \
+    groupadd -g 1000 shadow; \
+    useradd -u 1000 -g shadow -m -d /home/shadow -s /usr/sbin/nologin shadow
+
+# Setup directories
+WORKDIR /app
+RUN mkdir -p /home/shadow/.openclaw /etc/openclaw /etc/shadowob /var/log/openclaw \
+      /workspace /tmp/openclaw /tmp/npm-cache && \
+    ln -s /home/shadow /home/openclaw && \
+    chown -R shadow:shadow /home/shadow /etc/shadowob /var/log/openclaw \
+      /workspace /tmp/openclaw /tmp/npm-cache /app
+
+# Copy stable OpenClaw runtime deps first.
+COPY --from=builder --chown=shadow:shadow /build/node_modules ./node_modules
+COPY --from=builder --chown=shadow:shadow /build/package.json ./package.json
+
+# Symlink openclaw to PATH (local install only, no global npm install)
+RUN ln -s /app/node_modules/.bin/openclaw /usr/local/bin/openclaw && \
+    ln -s /app/node_modules/.bin/shadowob /usr/local/bin/shadowob && \
+    ln -s /app/node_modules/.bin/shadowob-connector /usr/local/bin/shadowob-connector
+
+# Copy local extensions before dependency warmup so the image carries the exact
+# plugin runtime dependency set used at startup. The extension layer is still
+# after node_modules, so ordinary plugin edits do not invalidate the large
+# pnpm install/build layers.
+COPY --from=builder --chown=shadow:shadow /build/extensions ./extensions
+
+# Stage bundled plugin runtime deps in the image so the first real Buddy reply
+# does not spend minutes installing optional tool/provider packages.
+COPY --chown=shadow:shadow apps/cloud/images/openclaw-runner/warm-runtime-deps.mjs ./warm-runtime-deps.mjs
+ENV OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw-runtime-deps
+ENV npm_config_cache=/tmp/npm-cache
+RUN --mount=type=cache,target=/tmp/npm-cache,sharing=locked \
+    mkdir -p /opt/openclaw-runtime-deps && \
+    node /app/warm-runtime-deps.mjs && \
+    chown -R shadow:shadow /opt/openclaw-runtime-deps
+
+# Copy entrypoint (small, changes often → last COPY for cache)
+COPY --chown=shadow:shadow apps/cloud/images/openclaw-runner/entrypoint.mjs ./entrypoint.mjs
+
+# Health check
+HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:3100/health || exit 1
+
+EXPOSE 3100
+
+ENV NODE_ENV=production
+ENV HOME=/home/shadow
+ENV OPENCLAW_HEALTH_PORT=3100
+ENV OPENCLAW_GATEWAY_PORT=3101
+ENV OPENCLAW_NO_RESPAWN=1
+ENV OPENCLAW_MODEL_PRICING_FETCH_TIMEOUT_MS=2500
+ENV OPENCLAW_SKIP_STARTUP_MODEL_PREWARM=1
+ENV OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw-runtime-deps
+ENV CHROME_BIN=/usr/bin/chromium
+ENV CHROMIUM_PATH=/usr/bin/chromium
+ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
+
+# Run as non-root
+USER shadow
+
+# Use tini as PID 1 for proper signal handling
+ENTRYPOINT ["tini", "--"]
+CMD ["node", "entrypoint.mjs"]

package/images/openclaw-runner/RUNNER.md

@@ -0,0 +1,170 @@
+# OpenClaw Runner Research
+
+Research date: 2026-05-14.
+
+## Target role
+
+`openclaw-runner` remains the one runner whose native process boundary is the
+OpenClaw gateway. It should keep using the ShadowOB OpenClaw plugin and the
+OpenClaw configuration adapter. The refactor should isolate this path rather
+than letting it define the config contract for every other runner.
+
+## Current repository state
+
+The current image already follows this model more closely than the ACP runners:
+
+- Dockerfile installs OpenClaw, the ShadowOB OpenClaw plugin, ShadowOB CLI, and
+  ShadowOB connector CLI.
+- `entrypoint.mjs` reads `/etc/openclaw/config.json`.
+- Runtime extensions are read from `/etc/openclaw/runtime-extensions.json`.
+- The generated OpenClaw config is written outside mutable state by default.
+- File logging goes to `/var/log/openclaw/entrypoint.log`.
+- Shadow slash command artifacts are surfaced through
+  `SHADOW_SLASH_COMMANDS_PATH`.
+
+## Native configuration surfaces
+
+OpenClaw configuration is broad and should remain represented as native
+OpenClaw config when this runner is selected:
+
+| Concern | OpenClaw config area |
+| --- | --- |
+| Gateway process | `gateway.*` for port, bind mode, auth, TLS, push, reload, remote access. |
+| Channels | `channels.*` plus plugin channels such as `channels.shadowob`. |
+| Agents and workspaces | `agents.defaults`, `agents.list`, routing, workspace, sandbox, heartbeat. |
+| Models | `agents.defaults.model`, `agents.defaults.models`, `models.providers`, failover and dynamic discovery. |
+| Skills | `skills.*`, `agents.defaults.skills`, `agents.list[].skills`. |
+| MCP | `mcp.*` and tool-related config. |
+| Automation | `cron.*`, `hooks.*`, tasks, standing orders, and background task config. |
+| Plugins | `plugins.*`, plugin entries, plugin resources, runtime extensions. |
+| Logs | `openclaw logs`, gateway logs, and container logs under `/var/log/openclaw`. |
+
+## Schema and type anchors
+
+- Static schema URL: none found in the official docs.
+- Official schema source: `openclaw config schema` prints the live JSON Schema
+  used by validation and Control UI.
+- Official drill-down source: gateway `config.schema.lookup` returns
+  path-scoped schema nodes.
+- Cloud type anchor: `OpenClawConfig` and related types under
+  `apps/cloud/src/config/schema/openclaw.schema.ts`.
+- Test rule: adapter unit tests should run a generated config through OpenClaw's
+  schema command or a checked-in fixture generated by the same command.
+
+## Provider and authentication notes
+
+- OpenClaw is the only phase-1 runner that should consume OpenClaw-native
+  `models.providers`, failover, and dynamic discovery config.
+- Provider secrets must remain env-backed or secret-file backed. ConfigMaps may
+  contain `${env:...}` references but not raw API keys.
+- Any subscription/OAuth provider support is OpenClaw-provider specific; it must
+  not become the compatibility path for Claude Code, Codex, OpenCode, Gemini, or
+  Hermes adapters.
+- Cost/audit should continue to use OpenClaw's status and usage surfaces for
+  OpenClaw only. Native runners collect their own usage/log surfaces.
+
+## Security, audit, cost, network, and tools
+
+- Permissions: `tools.profile`, `tools.allow`, `tools.deny`, per-agent
+  `agents.list[].tools.*`, and `tools.exec.*`; deny must win over allow.
+- Tool surface: built-in tool groups, plugin tools, MCP tools, and bundled tools
+  must resolve before model invocation. An explicit allowlist that resolves to
+  zero tools should fail closed.
+- Sandbox: `agents.defaults.sandbox.*` and `agents.list[].sandbox.*` decide
+  where tool execution runs; gateway process itself is not sandboxed.
+- Elevated mode: `tools.elevated.*` is an exec-only escape hatch and cannot
+  override tool policy.
+- Exec approvals: host exec approval state combines OpenClaw config and
+  host-local `~/.openclaw/exec-approvals.json`.
+- Network: sandbox Docker network defaults to no network; browser sandbox has
+  separate CDP and container network controls.
+- Cost/audit: OpenClaw `/status` and API usage/cost docs expose token/cost
+  estimates for API-key auth paths; runner logs must keep those events while
+  redacting credentials.
+- Logs: collect OpenClaw gateway logs, entrypoint logs, sandbox explain output,
+  and plugin load warnings.
+
+## Shadow integration
+
+Keep ShadowOB integration as an OpenClaw plugin concern:
+
+- plugin package: `@shadowob/openclaw-shadowob`
+- config section: `channels.shadowob`
+- runtime artifacts: slash commands, credential files, plugin resources, and
+  verification checks from Cloud plugin runtime extensions
+- official OpenClaw slash commands are generated into
+  `/etc/shadowob/slash-commands.json` with `dispatch=passthrough`, registered
+  with Shadow for the input picker, and then forwarded to OpenClaw as the
+  original standalone `/...` message instead of being rewritten into a prompt
+- plugin-provided slash command indexes are loaded as additional runtime
+  artifacts after the official OpenClaw catalog. Duplicate command names keep
+  the first loaded definition, so plugin commands do not replace OpenClaw's
+  official commands.
+
+The OpenClaw command catalog is owned by
+`apps/cloud/src/runtimes/slash-commands/openclaw.ts`. The researched official
+list includes `/new`, `/compact`, `/stop`, `/session`, `/think`, `/verbose`,
+`/fast`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/models`, `/queue`,
+`/help`, `/commands`, `/tools`, `/status`, `/tasks`, `/context`,
+`/export-session`, `/whoami`, `/skill`, `/allowlist`, `/approve`, `/btw`,
+`/subagents`, `/acp`, `/focus`, `/unfocus`, `/agents`, `/kill`, `/steer`,
+`/config`, `/mcp`, `/plugins`, `/debug`, `/usage`, `/tts`, `/restart`,
+`/activation`, `/send`, and `/bash`.
+
+This runner can continue to support OpenClaw-native slash commands, skills,
+cron jobs, hooks, and channels. No cc-connect bridge is needed.
+
+## Migration implications
+
+- `buildOpenClawConfig` should move behind, or be invoked only by, the OpenClaw
+  runner adapter.
+- OpenClaw plugin fragments should not be merged into non-OpenClaw runner
+  packages.
+- Existing `openclaw-runner` health checks and log redaction should be kept as
+  the baseline for the OpenClaw image only.
+- Any Cloud API field named `openclaw` should be documented as OpenClaw-specific
+  instead of generic runtime configuration.
+
+## Adapter and smoke tests
+
+Unit tests:
+
+- Generated config validates with OpenClaw schema.
+- Tool profile, allow, deny, sandbox, elevated, and exec approval fields map
+  exactly from Cloud policy inputs.
+- Plugin runtime extensions still materialize slash command artifacts,
+  credential files, MCP servers, skills, and subagents.
+- Secret refs stay out of `configData` snapshots.
+
+Container smoke:
+
+- Start image with a minimal ShadowOB config and confirm gateway health.
+- Run `openclaw config schema` and `openclaw config validate` inside the
+  container.
+- Inspect `/var/log/openclaw` for startup logs and redaction.
+- Assert workspace write behavior for `workspaceAccess` modes.
+
+## Open questions
+
+- Whether Cloud should continue to accept legacy top-level OpenClaw config for a
+  non-OpenClaw runtime and translate a small safe subset, or reject it early.
+- Whether OpenClaw runtime extensions should have a parallel runner-extension
+  schema for cc-connect and Hermes.
+
+## Sources
+
+- OpenClaw docs index: https://docs.openclaw.ai/llms.txt
+- Gateway configuration:
+  https://docs.openclaw.ai/gateway/configuration
+- Configuration reference:
+  https://docs.openclaw.ai/gateway/configuration-reference
+- Sandboxing: https://docs.openclaw.ai/gateway/sandboxing
+- Tools: https://docs.openclaw.ai/tools
+- Slash commands: https://docs.openclaw.ai/tools/slash-commands
+- Exec approvals: https://docs.openclaw.ai/tools/exec-approvals
+- API usage and costs:
+  https://docs.openclaw.ai/reference/api-usage-costs
+- Cron jobs: https://docs.openclaw.ai/automation/cron-jobs
+- Hooks: https://docs.openclaw.ai/automation/hooks
+- Skills: https://docs.openclaw.ai/tools/skills
+- Logs CLI: https://docs.openclaw.ai/cli/logs