fix: standardize messaging integrations with host-side bridge framework

bin/lib/onboard.js

@@ -443,9 +443,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) {
@@ -455,6 +461,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

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/bridges/messaging/discord.yaml

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+bridge:
+  name: discord
+  type: messaging
+  adapter: discord
+  description: "Discord bot bridge"
+
+  credentials:
+    token_env: DISCORD_BOT_TOKEN
+    allowed_env: ALLOWED_CHANNEL_IDS
+
+  messaging:
+    session_prefix: dc
+    max_chunk_size: 1900

nemoclaw-blueprint/bridges/messaging/slack.yaml

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+bridge:
+  name: slack
+  type: messaging
+  adapter: slack
+  description: "Slack bot bridge (Socket Mode)"
+
+  credentials:
+    token_env: SLACK_BOT_TOKEN
+    extra_env:
+      - SLACK_APP_TOKEN
+    allowed_env: ALLOWED_CHANNEL_IDS
+
+  messaging:
+    session_prefix: sl
+    max_chunk_size: 3000

nemoclaw-blueprint/bridges/messaging/telegram.yaml

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+bridge:
+  name: telegram
+  type: messaging
+  adapter: telegram
+  description: "Telegram Bot API bridge"
+
+  credentials:
+    token_env: TELEGRAM_BOT_TOKEN
+    allowed_env: ALLOWED_CHAT_IDS
+
+  messaging:
+    session_prefix: tg
+    max_chunk_size: 4000