PICOCLAW_GATEWAY_TOKEN env var does not control pico channel authentication

[bamnenim-permissionlabs]

Description

The PICOCLAW_GATEWAY_TOKEN environment variable is commonly assumed to control WebSocket authentication for the /pico/ws channel. However, this is misleading:

• PICOCLAW_GATEWAY_TOKEN only controls health check and reload endpoints (/health, /reload)
• The /pico/ws channel authentication is controlled by .security.yml, specifically the channels.pico.token field
• At runtime, PicoClaw applies a token override mechanism that prepends "pico-" plus a PID-based random token to the configured value
• This dual-token system is undocumented, making it extremely difficult to integrate PicoClaw with external orchestration systems

This caused significant debugging effort in our deployment because all documentation and typical usage patterns suggest PICOCLAW_GATEWAY_TOKEN should be the source of truth for gateway authentication.

Steps to Reproduce

1. Deploy PicoClaw with PICOCLAW_GATEWAY_TOKEN=my-secret-token set
2. Attempt to connect to /pico/ws using the token my-secret-token in the WebSocket handshake
3. Connection fails with 401 Unauthorized
4. Inspect .security.yml and .picoclaw.pid files
5. Observe that the actual required token is pico-{random-pid-token}{configured-channel-token}

Expected vs Actual Behavior

Expected: PICOCLAW_GATEWAY_TOKEN is the authoritative token for all gateway authentication (including /pico/ws), or the documentation clearly states which env vars control which endpoints.

Actual: PICOCLAW_GATEWAY_TOKEN only affects health/reload endpoints. The /pico/ws token is constructed at runtime from .security.yml plus a PID-based override, making it impossible to predict without reading generated files.

Suggested Fix

1. Update README and config examples to clearly document which env vars control which endpoints
2. Document the token override mechanism (overridePicoToken) and how it constructs the final token
3. Consider adding a config option to disable the PID-based token override for external orchestration use cases

[SiYue-ZO]

PicoClaw WebSocket External Client Connection Guide

Background

Starting from v0.2.5, PicoClaw WebSocket connections require dual authentication. Direct connections to the Gateway port (18790) or providing only the pico token will result in authentication failure.

---

Authentication Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Launcher (18800)                         │
├─────────────────────────────────────────────────────────────────┤
│  Layer 1: Dashboard Authentication                              │
│  - Session Cookie (picoclaw_launcher_auth)                      │
│  - Or Authorization: Bearer <dashboard_token>                   │
├─────────────────────────────────────────────────────────────────┤
│  Layer 2: Pico WebSocket Authentication                         │
│  - Sec-WebSocket-Protocol: token.<picoToken>                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Gateway (18790)                            │
│  Internal composed token: pico-{pidToken}{picoToken}            │
│  (Automatically converted by Launcher, clients don't need to    │
│   know about this)                                              │
└─────────────────────────────────────────────────────────────────┘

---

Browser Extension/Frontend Connection

Step 1: User Logs into Dashboard

The user must first visit the PicoClaw Dashboard in a browser and log in:

http://your-host:18800?token=<dashboard_token>

After successful login, the browser receives a session cookie (picoclaw_launcher_auth).

How to get Dashboard Token:

• Check the console output when Launcher starts
• Or set environment variable PICOCLAW_LAUNCHER_TOKEN
• Or configure it in ~/.picoclaw/launcher.json

Step 2: Get Pico Token

const response = await fetch('/api/pico/token');
const { token, ws_url, enabled } = await response.json();

console.log('Pico Token:', token);
console.log('WebSocket URL:', ws_url);

Step 3: Connect WebSocket

const ws = new WebSocket(ws_url, [`token.${token}`]);

ws.onopen = () => {
    console.log('WebSocket connected');
};

ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Received message:', message);
};

ws.onerror = (error) => {
    console.error('WebSocket error:', error);
};

ws.onclose = () => {
    console.log('WebSocket closed');
};

Complete Example

class PicoClawClient {
    constructor() {
        this.ws = null;
        this.picoToken = null;
        this.wsUrl = null;
    }

    async connect() {
        // Get pico token
        const response = await fetch('/api/pico/token');
        if (!response.ok) {
            throw new Error('Failed to get token. Please login to Dashboard first.');
        }
        
        const data = await response.json();
        this.picoToken = data.token;
        this.wsUrl = data.ws_url;

        // Connect WebSocket
        // Session cookie is automatically included
        this.ws = new WebSocket(this.wsUrl, [`token.${this.picoToken}`]);

        return new Promise((resolve, reject) => {
            this.ws.onopen = () => resolve();
            this.ws.onerror = (e) => reject(new Error('Connection failed'));
        });
    }

    send(content) {
        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
            throw new Error('WebSocket not connected');
        }
        
        this.ws.send(JSON.stringify({
            type: 'message.send',
            session_id: this.sessionId,
            timestamp: Date.now(),
            payload: { content }
        }));
    }

    close() {
        if (this.ws) {
            this.ws.close();
        }
    }
}

// Usage
const client = new PicoClawClient();
await client.connect();
client.send('Hello PicoClaw!');

---

Non-Browser Client Connection

For clients that cannot use cookies (e.g., Node.js, Python, Postman):

Method A: Using Authorization Header

// Node.js example (requires WebSocket library)
const WebSocket = require('ws');

const dashboardToken = 'your-dashboard-token';
const picoToken = 'your-pico-token';

const ws = new WebSocket('ws://your-host:18800/pico/ws', [`token.${picoToken}`], {
    headers: {
        'Authorization': `Bearer ${dashboardToken}`
    }
});

Method B: Using Query Token

ws://your-host:18800/pico/ws?token=<dashboard_token>

Also provide Sec-WebSocket-Protocol: token.<picoToken>.

---

Common Errors and Solutions

Error	Cause	Solution
302 Redirect to /launcher-login	Dashboard authentication failed	Login to Dashboard first to get session cookie
403 Forbidden "Invalid Pico token"	Incorrect or missing pico token	Call /api/pico/token to get the correct token
401 Unauthorized	Direct connection to Gateway port	Connect via Launcher port (18800) instead
503 Service Unavailable	Gateway not running	Start the Gateway service

---

Port Reference

Port	Purpose	Direct Connection
18800	Launcher (Web UI + Proxy)	✅ Recommended
18790	Gateway (Internal Service)	❌ Not supported

---

Token Types

Token Type	Purpose	How to Get
Dashboard Token	Access Web UI and API	Generated at startup or configure PICOCLAW_LAUNCHER_TOKEN
Pico Token	WebSocket connection authentication	Call GET /api/pico/token
PID Token	Internal Gateway use	Auto-generated, clients don't need to know

---

Security Recommendations

1. Don't expose Gateway port: Only expose Launcher port (18800)
2. Use HTTPS: Configure a reverse proxy (e.g., Nginx) with HTTPS in production
3. Rotate tokens regularly: Regenerate pico token via POST /api/pico/token
4. Restrict access IPs: Configure allowed_cidrs in launcher.json

---

Note on PICOCLAW_GATEWAY_TOKEN

The environment variable PICOCLAW_GATEWAY_TOKEN mentioned in some discussions does not exist in the codebase. The relevant environment variables are:

• PICOCLAW_CHANNELS_PICO_TOKEN - Sets the pico channel token
• PICOCLAW_LAUNCHER_TOKEN - Sets the Dashboard login token

---

For further questions, please open a GitHub Issue.

[axwfae]

This is my solution! You can refer to it! It's feasible at least for now on versions 0.2.5 to 0.2.6!

https://github.com/axwfae/picoclaw-token-proxy