fix: standardize messaging integrations with host-side bridge framework

bin/lib/onboard.js

@@ -555,9 +555,15 @@ async function createSandbox(gpu) {
 
   console.log(`  Creating sandbox '${sandboxName}' (this takes a few minutes on first run)...`);
   const chatUiUrl = process.env.CHAT_UI_URL || 'http://127.0.0.1:18789';
+  // Pass user-provided secrets into the sandbox as environment variables.
+  // All tokens follow the same pattern: getCredential() checks env first,
+  // then ~/.nemoclaw/credentials.json. OpenClaw auto-enables channels when
+  // it detects the corresponding env var (e.g., DISCORD_BOT_TOKEN).
+  // See docs/reference/architecture.md "Credential Handling" for the full inventory.
   const envArgs = [`CHAT_UI_URL=${shellQuote(chatUiUrl)}`];
-  if (process.env.NVIDIA_API_KEY) {
-    envArgs.push(`NVIDIA_API_KEY=${shellQuote(process.env.NVIDIA_API_KEY)}`);
+  const apiKey = getCredential("NVIDIA_API_KEY") || process.env.NVIDIA_API_KEY;
+  if (apiKey) {
+    envArgs.push(`NVIDIA_API_KEY=${shellQuote(apiKey)}`);
   }
   const discordToken = getCredential("DISCORD_BOT_TOKEN") || process.env.DISCORD_BOT_TOKEN;
   if (discordToken) {
@@ -567,6 +573,10 @@ async function createSandbox(gpu) {
   if (slackToken) {
     envArgs.push(`SLACK_BOT_TOKEN=${shellQuote(slackToken)}`);
   }
+  const tgToken = getCredential("TELEGRAM_BOT_TOKEN") || process.env.TELEGRAM_BOT_TOKEN;
+  if (tgToken) {
+    envArgs.push(`TELEGRAM_BOT_TOKEN=${shellQuote(tgToken)}`);
+  }
 
   // Run without piping through awk — the pipe masked non-zero exit codes
   // from openshell because bash returns the status of the last pipeline
@@ -1091,9 +1101,43 @@ async function onboard(opts = {}) {
   await setupInference(sandboxName, model, provider);
   await setupOpenclaw(sandboxName, model, provider);
   await setupPolicies(sandboxName);
+  startMessagingBridges(sandboxName);
   printDashboard(sandboxName, model, provider);
 }
 
+// ── Auto-start messaging bridges ────────────────────────────────
+// RISKY CHANGE: This is a migration path to standardize messaging
+// configuration. We auto-start host-side bridges when tokens are
+// detected, which takes over from the in-sandbox OpenClaw plugin
+// (Discord/Slack enforce single gateway connections per token).
+// The in-sandbox env var passthrough (#601) is kept for backwards
+// compatibility during this transition.
+
+function startMessagingBridges(sandboxName) {
+  // Rehydrate file-backed credentials into process.env so start-services.sh
+  // and bridge.js can see them (they only check process.env, not credentials.json).
+  const bridgeTokens = ["TELEGRAM_BOT_TOKEN", "DISCORD_BOT_TOKEN", "SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"];
+  for (const key of bridgeTokens) {
+    if (!process.env[key]) {
+      const val = getCredential(key);
+      if (val) process.env[key] = val;
+    }
+  }
+
+  const hasMessagingToken =
+    process.env.TELEGRAM_BOT_TOKEN ||
+    process.env.DISCORD_BOT_TOKEN ||
+    process.env.SLACK_BOT_TOKEN;
+
+  if (!hasMessagingToken) return;
+
+  console.log("");
+  console.log("  Starting messaging bridges...");
+  const safeName = sandboxName && /^[a-zA-Z0-9._-]+$/.test(sandboxName) ? sandboxName : null;
+  const sandboxEnv = safeName ? `SANDBOX_NAME=${shellQuote(safeName)}` : "";
+  run(`${sandboxEnv} bash "${SCRIPTS}/start-services.sh"`, { ignoreError: true });
+}
+
 module.exports = {
   buildSandboxConfigSyncScript,
   getFutureShellPathHint,

docs/reference/architecture.md

@@ -100,3 +100,31 @@ Agent (sandbox)  ──▶  OpenShell gateway  ──▶  NVIDIA Endpoint (build
 ```
 
 Refer to [Inference Profiles](../reference/inference-profiles.md) for provider configuration details.
+
+## Credential Handling
+
+All user-provided secrets follow the same pattern:
+
+1. Stored on the host in `~/.nemoclaw/credentials.json` (mode 0600) or as environment variables.
+2. Retrieved via `getCredential(key)` which checks env vars first, then the credentials file.
+3. Passed into the sandbox as environment variables at creation time.
+4. Never written to `openclaw.json` (immutable at runtime).
+
+### Credential Inventory
+
+| Credential | Passed to sandbox | Used inside sandbox | Used on host | Notes |
+|---|---|---|---|---|
+| `NVIDIA_API_KEY` | Yes (env var) | Yes — startup script writes `auth-profiles.json` | Yes — deploy, Telegram bridge | OpenClaw requires a specific JSON file format; `nemoclaw-start.sh` handles the translation |
+| `DISCORD_BOT_TOKEN` | Yes (env var) | Yes — OpenClaw reads env var directly, auto-enables Discord channel | No | |
+| `SLACK_BOT_TOKEN` | Yes (env var) | Yes — OpenClaw reads env var directly, auto-enables Slack channel | No | |
+| `TELEGRAM_BOT_TOKEN` | Yes (env var) | Available but unused — bridge runs on host | Yes — Telegram bridge (host-side) | Bridge uses SSH to relay messages into sandbox |
+| `GITHUB_TOKEN` | Deploy path only | No | Yes — private repo access | Not needed inside sandbox |
+| Gateway auth token | No — baked at build time | Yes — `openclaw.json` (root:root 444) | N/A | Per-build unique, immutable security boundary |
+
+### Why Telegram runs on the host
+
+The Telegram bridge (`scripts/telegram-bridge.js`) runs on the host and communicates with the sandbox via OpenShell SSH. This is intentional:
+
+- It avoids giving the sandbox direct Telegram API access beyond what the network policy allows.
+- It allows the bridge to manage multiple sandboxes from one host process.
+- The `TELEGRAM_BOT_TOKEN` is still passed into the sandbox for future OpenClaw channel plugin support.

nemoclaw-blueprint/blueprint.yaml

@@ -54,6 +54,33 @@ components:
         credential_env: "OPENAI_API_KEY"
         credential_default: "dummy"
 
+  bridges:
+    telegram:
+      type: messaging
+      adapter: telegram
+      credential_env: "TELEGRAM_BOT_TOKEN"
+      allowed_env: "ALLOWED_TELEGRAM_CHAT_IDS"
+      session_prefix: tg
+      max_chunk_size: 4000
+
+    discord:
+      type: messaging
+      adapter: discord
+      credential_env: "DISCORD_BOT_TOKEN"
+      allowed_env: "ALLOWED_DISCORD_CHANNEL_IDS"
+      session_prefix: dc
+      max_chunk_size: 1900
+
+    slack:
+      type: messaging
+      adapter: slack
+      credential_env: "SLACK_BOT_TOKEN"
+      extra_credential_env:
+        - "SLACK_APP_TOKEN"
+      allowed_env: "ALLOWED_SLACK_CHANNEL_IDS"
+      session_prefix: sl
+      max_chunk_size: 3000
+
   policy:
     base: "sandboxes/openclaw/policy.yaml"
     additions: