refactor(kiloclaw): use per-sandbox KILOCHAT_SANDBOX_TOKEN, drop x-kilo-sandbox-id

Pair with the kilo-chat backend's per-sandbox token rewrite. Each Fly
machine now carries its own KILOCHAT_SANDBOX_TOKEN (minted by the
kilo-chat admin API at provisioning time) instead of the shared
KILOCHAT_API_TOKEN. The per-sandbox token identifies the caller on its
own, so the controller no longer sends x-kilo-sandbox-id upstream and
KiloChatRouteOptions no longer carries a sandboxId field.

Touched files:
  - Rename KILOCHAT_API_TOKEN → KILOCHAT_SANDBOX_TOKEN across
    kiloclaw-secret-catalog, gateway/env, controller/config-writer,
    and controller/index.
  - Drop x-kilo-sandbox-id header from all five kilo-chat proxy
    routes; tests assert the header is NOT present in the upstream
    call.
  - Update openclaw plugin manifest channelEnvVars to advertise the
    new var name.
  - Update README / LOCAL_E2E docs (sample fake upstream server, env
    tables, the Docker run example).

Author: iscekic

packages/kiloclaw-secret-catalog/src/__tests__/catalog.test.ts

@@ -470,7 +470,7 @@ describe('Secret Catalog', () => {
     });
 
     it('contains Kilo Chat operator-provisioned tokens', () => {
-      expect(INTERNAL_SENSITIVE_ENV_VARS.has('KILOCHAT_API_TOKEN')).toBe(true);
+      expect(INTERNAL_SENSITIVE_ENV_VARS.has('KILOCHAT_SANDBOX_TOKEN')).toBe(true);
     });
 
     it('does not overlap with catalog-derived ALL_SECRET_ENV_VARS', () => {
@@ -533,7 +533,7 @@ describe('Secret Catalog', () => {
       expect(isValidCustomSecretKey('NEXTAUTH_SECRET')).toBe(false);
       expect(isValidCustomSecretKey('NODE_OPTIONS')).toBe(false);
       expect(isValidCustomSecretKey('STREAM_CHAT_API_KEY')).toBe(false);
-      expect(isValidCustomSecretKey('KILOCHAT_API_TOKEN')).toBe(false);
+      expect(isValidCustomSecretKey('KILOCHAT_SANDBOX_TOKEN')).toBe(false);
       expect(isValidCustomSecretKey('KILOCHAT_ANYTHING')).toBe(false);
     });
 

packages/kiloclaw-secret-catalog/src/catalog.ts

@@ -280,10 +280,11 @@ export const ALL_SECRET_ENV_VARS: ReadonlySet<string> = new Set(
  */
 export const INTERNAL_SENSITIVE_ENV_VARS: ReadonlySet<string> = new Set([
   'KILOCLAW_GOG_CONFIG_TARBALL',
-  // Kilo Chat — operator-provisioned, not user-configurable. Pushed from
-  // worker env via buildEnvVars; the KILOCHAT_ prefix is reserved in
-  // DENIED_ENV_VAR_PREFIXES to keep users from shadowing them.
-  'KILOCHAT_API_TOKEN',
+  // Kilo Chat — operator-provisioned per-sandbox token. Minted via the
+  // kilo-chat admin API, distributed to each Fly machine as a Fly secret.
+  // The KILOCHAT_ prefix is reserved in DENIED_ENV_VAR_PREFIXES to keep
+  // users from shadowing it.
+  'KILOCHAT_SANDBOX_TOKEN',
 ]);
 
 /**

services/kiloclaw/controller/src/config-writer.test.ts

@@ -764,11 +764,11 @@ describe('generateBaseConfig', () => {
 
   // ─── Kilo Chat ───────────────────────────────────────────────────────────
 
-  it('configures kilo-chat channel and plugin when both KILOCHAT_API_TOKEN and KILOCHAT_BASE_URL are set', () => {
+  it('configures kilo-chat channel and plugin when both KILOCHAT_SANDBOX_TOKEN and KILOCHAT_BASE_URL are set', () => {
     const { deps } = fakeDeps();
     const env = {
       ...minimalEnv(),
-      KILOCHAT_API_TOKEN: 'tok',
+      KILOCHAT_SANDBOX_TOKEN: 'tok',
       KILOCHAT_BASE_URL: 'https://chat.example.test',
     };
     const config = generateBaseConfig(env, '/tmp/openclaw.json', deps);
@@ -786,7 +786,7 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps();
     const env = {
       ...minimalEnv(),
-      KILOCHAT_API_TOKEN: 'tok',
+      KILOCHAT_SANDBOX_TOKEN: 'tok',
       KILOCHAT_BASE_URL: 'https://chat.example.test',
       KILOCHAT_REACTION_LEVEL: 'extensive',
     };
@@ -798,7 +798,7 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps();
     const env = {
       ...minimalEnv(),
-      KILOCHAT_API_TOKEN: 'tok',
+      KILOCHAT_SANDBOX_TOKEN: 'tok',
       KILOCHAT_BASE_URL: 'https://chat.example.test',
     };
     const config = generateBaseConfig(env, '/tmp/openclaw.json', deps);
@@ -809,7 +809,7 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps();
     const env = {
       ...minimalEnv(),
-      KILOCHAT_API_TOKEN: 'tok',
+      KILOCHAT_SANDBOX_TOKEN: 'tok',
       KILOCHAT_BASE_URL: 'https://chat.example.test',
       KILOCHAT_REACTION_LEVEL: 'bogus',
     };
@@ -822,7 +822,7 @@ describe('generateBaseConfig', () => {
       const { deps } = fakeDeps();
       const env = {
         ...minimalEnv(),
-        KILOCHAT_API_TOKEN: 'tok',
+        KILOCHAT_SANDBOX_TOKEN: 'tok',
         KILOCHAT_BASE_URL: 'https://chat.example.test',
         KILOCHAT_REACTION_LEVEL: level,
       };
@@ -831,7 +831,7 @@ describe('generateBaseConfig', () => {
     }
   });
 
-  it('leaves kilo-chat channel unconfigured when KILOCHAT_API_TOKEN is missing', () => {
+  it('leaves kilo-chat channel unconfigured when KILOCHAT_SANDBOX_TOKEN is missing', () => {
     const { deps } = fakeDeps();
     const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
 
@@ -840,7 +840,7 @@ describe('generateBaseConfig', () => {
 
   it('leaves kilo-chat channel unconfigured when KILOCHAT_BASE_URL is missing (token-only is not enough)', () => {
     const { deps } = fakeDeps();
-    const env = { ...minimalEnv(), KILOCHAT_API_TOKEN: 'tok' };
+    const env = { ...minimalEnv(), KILOCHAT_SANDBOX_TOKEN: 'tok' };
     const config = generateBaseConfig(env, '/tmp/openclaw.json', deps);
 
     expect(config.channels?.['kilo-chat']).toBeUndefined();

services/kiloclaw/controller/src/config-writer.ts

@@ -448,7 +448,7 @@ export function generateBaseConfig(
   // section has a key other than `enabled`. Without that, the plugin loads in
   // `setup-runtime` mode instead of `full`, and registerFull (which registers
   // the webhook HTTP route) is never called.
-  if (env.KILOCHAT_API_TOKEN && env.KILOCHAT_BASE_URL) {
+  if (env.KILOCHAT_SANDBOX_TOKEN && env.KILOCHAT_BASE_URL) {
     config.channels['kilo-chat'] = config.channels['kilo-chat'] ?? {};
     config.channels['kilo-chat'].enabled = true;
     config.channels['kilo-chat'].baseUrl = env.KILOCHAT_BASE_URL;

services/kiloclaw/controller/src/index.ts

@@ -364,11 +364,13 @@ export async function startController(env: NodeJS.ProcessEnv = process.env): Pro
   registerPairingRoutes(honoApp, pairingCache, config.expectedToken);
   registerEnvRoutes(honoApp, supervisor, config.expectedToken);
   registerGmailPushRoute(honoApp, gmailWatchSupervisor ?? null, config.expectedToken);
-  if (env.KILOCHAT_API_TOKEN && env.KILOCHAT_BASE_URL) {
+  if (env.KILOCHAT_SANDBOX_TOKEN && env.KILOCHAT_BASE_URL) {
+    // The per-sandbox token identifies the caller on the kilo-chat backend —
+    // no x-kilo-sandbox-id header is sent, and the shared KILOCHAT_API_TOKEN
+    // concept no longer exists.
     const kiloChatOpts = {
       expectedToken: config.expectedToken,
-      sandboxId: env.KILOCLAW_SANDBOX_ID ?? '',
-      apiToken: env.KILOCHAT_API_TOKEN,
+      apiToken: env.KILOCHAT_SANDBOX_TOKEN,
       baseUrl: env.KILOCHAT_BASE_URL,
     };
     registerKiloChatSendRoute(honoApp, kiloChatOpts);

services/kiloclaw/controller/src/routes/kilo-chat.test.ts

@@ -10,13 +10,11 @@ import {
 } from './kilo-chat';
 
 const TOKEN = 'expected-gateway-token';
-const SANDBOX_ID = 'sbx_test';
 
 function makeApp(fetchImpl: typeof fetch) {
   const app = new Hono();
   registerKiloChatSendRoute(app, {
     expectedToken: TOKEN,
-    sandboxId: SANDBOX_ID,
     apiToken: 'api_token',
     baseUrl: 'https://chat.example.test',
     fetchImpl,
@@ -52,7 +50,7 @@ describe('POST /_kilo/kilo-chat/send', () => {
     expect(res.status).toBe(401);
   });
 
-  it('forwards authorized requests with sandbox id header and api token', async () => {
+  it('forwards authorized requests with api token only; no x-kilo-sandbox-id header', async () => {
     let capturedUrl = '';
     let capturedInit: RequestInit | undefined;
     const fetchImpl = (async (url: string | URL, init?: RequestInit) => {
@@ -80,7 +78,7 @@ describe('POST /_kilo/kilo-chat/send', () => {
     expect(capturedUrl).toBe('https://chat.example.test/v1/messages');
     const headers = new Headers(capturedInit?.headers);
     expect(headers.get('authorization')).toBe('Bearer api_token');
-    expect(headers.get('x-kilo-sandbox-id')).toBe(SANDBOX_ID);
+    expect(headers.get('x-kilo-sandbox-id')).toBeNull();
     const body = JSON.parse((capturedInit?.body as string) ?? '{}');
     expect(body).toEqual({ conversationId: 'c1', text: 'hi' });
   });
@@ -106,7 +104,6 @@ function makeEditApp(fetchImpl: typeof fetch) {
   const app = new Hono();
   registerKiloChatEditRoute(app, {
     expectedToken: TOKEN,
-    sandboxId: SANDBOX_ID,
     apiToken: 'api_token',
     baseUrl: 'https://chat.example.test',
     fetchImpl,
@@ -156,7 +153,7 @@ describe('PATCH /_kilo/kilo-chat/messages/:id', () => {
     expect(capturedInit?.method).toBe('PATCH');
     const headers = new Headers(capturedInit?.headers);
     expect(headers.get('authorization')).toBe('Bearer api_token');
-    expect(headers.get('x-kilo-sandbox-id')).toBe(SANDBOX_ID);
+    expect(headers.get('x-kilo-sandbox-id')).toBeNull();
     expect(JSON.parse((capturedInit?.body as string) ?? '{}')).toEqual({
       conversationId: 'c1',
       text: 'Hel',
@@ -186,7 +183,6 @@ function makeDeleteApp(fetchImpl: typeof fetch) {
   const app = new Hono();
   registerKiloChatDeleteRoute(app, {
     expectedToken: TOKEN,
-    sandboxId: SANDBOX_ID,
     apiToken: 'api_token',
     baseUrl: 'https://chat.example.test',
     fetchImpl,
@@ -227,15 +223,14 @@ describe('DELETE /_kilo/kilo-chat/messages/:id', () => {
     expect(capturedInit?.method).toBe('DELETE');
     const headers = new Headers(capturedInit?.headers);
     expect(headers.get('authorization')).toBe('Bearer api_token');
-    expect(headers.get('x-kilo-sandbox-id')).toBe(SANDBOX_ID);
+    expect(headers.get('x-kilo-sandbox-id')).toBeNull();
   });
 });
 
 function makeTypingApp(fetchImpl: typeof fetch) {
   const app = new Hono();
   registerKiloChatTypingRoute(app, {
     expectedToken: TOKEN,
-    sandboxId: SANDBOX_ID,
     apiToken: 'api_token',
     baseUrl: 'https://chat.example.test',
     fetchImpl,
@@ -296,7 +291,7 @@ describe('POST /_kilo/kilo-chat/typing', () => {
     expect(capturedUrl).toBe('https://chat.example.test/v1/conversations/c1/typing');
     const headers = new Headers(capturedInit?.headers);
     expect(headers.get('authorization')).toBe('Bearer api_token');
-    expect(headers.get('x-kilo-sandbox-id')).toBe(SANDBOX_ID);
+    expect(headers.get('x-kilo-sandbox-id')).toBeNull();
     expect(capturedInit?.method).toBe('POST');
   });
 
@@ -363,7 +358,6 @@ describe('POST /_kilo/kilo-chat/messages/:id/reactions', () => {
 
     registerKiloChatReactionPostRoute(app, {
       expectedToken: 'gw',
-      sandboxId: 'sbx',
       apiToken: 'api',
       baseUrl: 'http://svc',
       fetchImpl,
@@ -380,7 +374,7 @@ describe('POST /_kilo/kilo-chat/messages/:id/reactions', () => {
     expect(calls[0].url).toBe('http://svc/v1/messages/MID/reactions');
     const headers = calls[0].init.headers as Record<string, string>;
     expect(headers.authorization).toBe('Bearer api');
-    expect(headers['x-kilo-sandbox-id']).toBe('sbx');
+    expect(headers['x-kilo-sandbox-id']).toBeUndefined();
     expect(calls[0].init.method).toBe('POST');
     expect(calls[0].init.body).toBe(JSON.stringify({ conversationId: 'C', emoji: '\u{1F44D}' }));
   });
@@ -391,7 +385,6 @@ describe('POST /_kilo/kilo-chat/messages/:id/reactions', () => {
       new Response(JSON.stringify({ id: 'RXULIDXXX' }), { status: 200 })) as typeof fetch;
     registerKiloChatReactionPostRoute(app, {
       expectedToken: 'gw',
-      sandboxId: 's',
       apiToken: 'a',
       baseUrl: 'http://svc',
       fetchImpl,
@@ -410,7 +403,6 @@ describe('POST /_kilo/kilo-chat/messages/:id/reactions', () => {
     const app = new Hono();
     registerKiloChatReactionPostRoute(app, {
       expectedToken: 'gw',
-      sandboxId: 's',
       apiToken: 'a',
       baseUrl: 'http://svc',
       fetchImpl: (async () => new Response()) as typeof fetch,
@@ -429,7 +421,6 @@ describe('POST /_kilo/kilo-chat/messages/:id/reactions', () => {
     const app = new Hono();
     registerKiloChatReactionPostRoute(app, {
       expectedToken: 'gw',
-      sandboxId: 's',
       apiToken: 'a',
       baseUrl: 'http://svc',
       fetchImpl: (async () => new Response()) as typeof fetch,
@@ -456,7 +447,6 @@ describe('DELETE /_kilo/kilo-chat/messages/:id/reactions', () => {
 
     registerKiloChatReactionDeleteRoute(app, {
       expectedToken: 'gw',
-      sandboxId: 'sbx',
       apiToken: 'api',
       baseUrl: 'http://svc',
       fetchImpl,
@@ -474,14 +464,13 @@ describe('DELETE /_kilo/kilo-chat/messages/:id/reactions', () => {
     expect(calls[0].url).toBe('http://svc/v1/messages/MID/reactions');
     const headers = calls[0].init.headers as Record<string, string>;
     expect(headers.authorization).toBe('Bearer api');
-    expect(headers['x-kilo-sandbox-id']).toBe('sbx');
+    expect(headers['x-kilo-sandbox-id']).toBeUndefined();
   });
 
   it('401 on missing bearer', async () => {
     const app = new Hono();
     registerKiloChatReactionDeleteRoute(app, {
       expectedToken: 'gw',
-      sandboxId: 's',
       apiToken: 'a',
       baseUrl: 'http://svc',
       fetchImpl: (async () => new Response()) as typeof fetch,
@@ -498,7 +487,6 @@ describe('body size limits', () => {
     const app = new Hono();
     register(app, {
       expectedToken: TOKEN,
-      sandboxId: SANDBOX_ID,
       apiToken: 'api_token',
       baseUrl: 'https://chat.example.test',
       fetchImpl,

services/kiloclaw/controller/src/routes/kilo-chat.ts

@@ -3,8 +3,13 @@ import { timingSafeTokenEqual } from '../auth';
 import { getBearerToken } from './gateway';
 
 export type KiloChatRouteOptions = {
+  /** Expected controller-gateway token (inbound from the plugin). */
   expectedToken: string;
-  sandboxId: string;
+  /**
+   * Per-sandbox token for the kilo-chat backend. The backend derives the
+   * caller's sandbox identity from this token alone — no x-kilo-sandbox-id
+   * header is sent upstream.
+   */
   apiToken: string;
   baseUrl: string;
   fetchImpl?: typeof fetch;
@@ -56,7 +61,6 @@ export function registerKiloChatSendRoute(app: Hono, options: KiloChatRouteOptio
       headers: {
         'content-type': c.req.header('content-type') ?? 'application/json',
         authorization: `Bearer ${options.apiToken}`,
-        'x-kilo-sandbox-id': options.sandboxId,
       },
       body: rawBody,
     });
@@ -94,7 +98,6 @@ export function registerKiloChatEditRoute(app: Hono, options: KiloChatRouteOptio
         headers: {
           'content-type': c.req.header('content-type') ?? 'application/json',
           authorization: `Bearer ${options.apiToken}`,
-          'x-kilo-sandbox-id': options.sandboxId,
         },
         body: rawBody,
       }
@@ -141,7 +144,6 @@ export function registerKiloChatTypingRoute(app: Hono, options: KiloChatRouteOpt
         headers: {
           'content-type': 'application/json',
           authorization: `Bearer ${options.apiToken}`,
-          'x-kilo-sandbox-id': options.sandboxId,
         },
       }
     );
@@ -179,7 +181,6 @@ export function registerKiloChatReactionPostRoute(app: Hono, options: KiloChatRo
         headers: {
           'content-type': c.req.header('content-type') ?? 'application/json',
           authorization: `Bearer ${options.apiToken}`,
-          'x-kilo-sandbox-id': options.sandboxId,
         },
         body: rawBody,
       }
@@ -219,7 +220,6 @@ export function registerKiloChatReactionDeleteRoute(
         headers: {
           'content-type': c.req.header('content-type') ?? 'application/json',
           authorization: `Bearer ${options.apiToken}`,
-          'x-kilo-sandbox-id': options.sandboxId,
         },
         body: rawBody || undefined,
       }
@@ -256,7 +256,6 @@ export function registerKiloChatDeleteRoute(app: Hono, options: KiloChatRouteOpt
         headers: {
           'content-type': c.req.header('content-type') ?? 'application/json',
           authorization: `Bearer ${options.apiToken}`,
-          'x-kilo-sandbox-id': options.sandboxId,
         },
         body: rawBody || undefined,
       }

services/kiloclaw/plugins/kilo-chat/LOCAL_E2E.md

@@ -48,7 +48,7 @@ Save this as `/tmp/fake-kilo-chat-upstream.mjs`:
 ```js
 import { createServer } from 'node:http';
 
-const EXPECTED_BEARER = process.env.KILOCHAT_API_TOKEN ?? 'upstream-token';
+const EXPECTED_BEARER = process.env.KILOCHAT_SANDBOX_TOKEN ?? 'upstream-token';
 const msgs = new Map();
 let counter = 0;
 
@@ -68,11 +68,10 @@ const j = (res, status, obj) => {
 createServer(async (req, res) => {
   const url = new URL(req.url, 'http://x');
   const auth = req.headers['authorization'];
-  const sandbox = req.headers['x-kilo-sandbox-id'];
   const body = await readBody(req);
-  console.log(
-    `[upstream] ${req.method} ${url.pathname} sandbox=${sandbox} auth=${auth} body=${body}`
-  );
+  // The per-sandbox token in Authorization is the sole identity — the real
+  // backend looks it up in the sandbox registry. No x-kilo-sandbox-id.
+  console.log(`[upstream] ${req.method} ${url.pathname} auth=${auth} body=${body}`);
 
   if (auth !== `Bearer ${EXPECTED_BEARER}`) return j(res, 401, { error: 'bad token' });
 
@@ -108,7 +107,7 @@ createServer(async (req, res) => {
 Run it in a second terminal and leave it running:
 
 ```bash
-KILOCHAT_API_TOKEN=upstream-token node /tmp/fake-kilo-chat-upstream.mjs
+KILOCHAT_SANDBOX_TOKEN=upstream-token node /tmp/fake-kilo-chat-upstream.mjs
 ```
 
 ## 3. Start the container (Terminal 1)
@@ -125,7 +124,7 @@ docker run -d --rm --name kiloclaw-test \
   -e KILOCLAW_FRESH_INSTALL=true \
   -e KILOCODE_DEFAULT_MODEL='kilocode/kilo-auto/free' \
   -e REQUIRE_PROXY_TOKEN=false \
-  -e KILOCHAT_API_TOKEN=upstream-token \
+  -e KILOCHAT_SANDBOX_TOKEN=upstream-token \
   -e KILOCHAT_WEBHOOK_SECRET=webhook-secret-xyz \
   -e KILOCHAT_BASE_URL=http://host.docker.internal:9999 \
   -v "$ROOTDIR:/root" \
@@ -141,7 +140,7 @@ Required env, summarised:
 | `KILOCLAW_FRESH_INSTALL=true` | forces onboard even if `/root` is non-empty                                         |
 | `KILOCODE_DEFAULT_MODEL`      | default model; `kilocode/kilo-auto/free` is free-tier                               |
 | `REQUIRE_PROXY_TOKEN=false`   | skip `x-kiloclaw-proxy-token` on the catch-all proxy so webhook curls don't need it |
-| `KILOCHAT_API_TOKEN`          | controller → upstream Bearer                                                        |
+| `KILOCHAT_SANDBOX_TOKEN`      | controller → upstream Bearer                                                        |
 | `KILOCHAT_WEBHOOK_SECRET`     | HMAC-SHA256 key for inbound webhooks                                                |
 | `KILOCHAT_BASE_URL`           | upstream for the controller's PATCH/POST/DELETE routes                              |