openclaw-zero-token

# OpenClaw Zero Token > Skill by [ara.so](https://ara.so) — Hermes Skills collection. OpenClaw Zero Token is a TypeScript-based gateway that lets you use major AI models (Claude, ChatGPT, Gemini, DeepSeek, Qwen, Kimi, Doubao, Grok, GLM, Xiaomi MiMo, Manus) **completely free** by automating browser-based authentication instead of requiring paid API tokens. It drives official web UIs using Chrome DevTools Protocol (CDP) and Playwright to capture credentials, then proxies requests through a unified OpenAI-compatible API gateway. ## What It Does - **Zero-cost LLM access**: Log in via browser once, reuse credentials for API calls - **Unified gateway**: OpenAI-compatible API endpoint on port 3001 - **11 web models with tool calling**: `web_search`, `web_fetch`, `exec`, `read`, `write`, `message` - **AskOnce multi-model queries**: Broadcast one question to all configured providers - **Web UI + CLI + Gateway**: Multiple interaction modes (Lit 3.x UI, TUI, REST API) ### Supported Providers | Provider | Status | Auth Method | |----------------|--------|------------------| | DeepSeek | ✅ | Browser login | | Qwen (intl/cn) | ✅ | Browser login | | Kimi | ✅ | Browser login | | Claude Web | ✅ | Browser login | | ChatGPT Web | ✅ | Browser login | | Gemini Web | ✅ | Browser login | | Grok Web | ✅ | Browser login | | Doubao | ✅ | Browser login | | GLM/GLM Intl | ✅ | Browser login | | Xiaomi MiMo | ✅ | Browser login | | Manus API | ✅ | API key (free) | ## Installation ### Prerequisites ```bash # Check versions node --version # >= 22.12.0 pnpm --version # >= 9.0.0 # Install Node.js 22+ if needed curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs # Install pnpm npm install -g pnpm ``` ### Clone and Build ```bash git clone https://github.com/linuxhsj/openclaw-zero-token.git cd openclaw-zero-token # Install dependencies pnpm install # Build backend + frontend pnpm build pnpm ui:build ``` ## Configuration ### Environment Setup Create `.env` file: ```bash # Gateway settings PORT=3001 NODE_ENV=production # Browser debugging (DO NOT expose publicly) CHROME_DEBUG_PORT=9222 # Optional: workspace for agent file access AGENT_WORKSPACE=/home/user/agent-workspace # Optional: logging LOG_LEVEL=info ``` ### First-Time Authentication Flow OpenClaw uses a three-step process: 1. **Start debug Chrome** → Opens browser on port 9222 2. **Login to web models** → Manual browser login (scan QR / password) 3. **Run onboard wizard** → Captures credentials automatically ```bash # Terminal 1: Start Chrome in debug mode (keep running) ./start-chrome-debug.sh # This opens Chrome with tabs for: # - DeepSeek: https://chat.deepseek.com # - Qwen intl: https://hf.co/chat # - Qwen cn: https://tongyi.aliyun.com # - Kimi: https://kimi.moonshot.cn # - Claude: https://claude.ai # etc. # LOG IN to each site manually in the browser ``` ```bash # Terminal 2: Run authentication wizard ./onboard.sh webauth # Interactive menu: # [1] deepseek-web # [2] qwen-web # [3] qwen-cn # [4] kimi # [5] claude-web # ... etc # Select provider → wizard captures auth automatically # Saved to: data/auth/<provider>.json ``` The `onboard.sh` script uses Playwright CDP to intercept network requests and extract: - Cookies - Bearer tokens - User-Agent headers ### Starting the Gateway ```bash # Start server (daemon mode) ./server.sh start # Other commands ./server.sh stop ./server.sh restart ./server.sh status # Manual start (foreground, for debugging) pnpm start ``` Gateway runs on **http://localhost:3001** with OpenAI-compatible endpoints. ## Key Commands and Scripts ### Core Scripts | Script | Purpose | |----------------------------|-------------------------------------------| | `./start-chrome-debug.sh` | Launch Chrome on port 9222 for logins | | `./onboard.sh webauth` | Run auth wizard to capture credentials | | `./server.sh [start|stop]` | Manage gateway daemon | | `pnpm build` | Build TypeScript backend | | `pnpm ui:build` | Build Lit 3.x frontend | | `pnpm test` | Run test suite | ### pnpm Scripts (package.json) ```bash # Build pnpm build # Compile TypeScript pnpm ui:build # Build frontend pnpm build:all # Both backend + UI # Development pnpm dev # Watch mode with hot reload pnpm start # Production server # Testing pnpm test # Run tests pnpm lint # ESLint check pnpm format # Prettier format ``` ## API Usage ### OpenAI-Compatible Endpoints OpenClaw exposes a standard OpenAI API format on port 3001: ```bash # List available models curl http://localhost:3001/v1/models # Chat completion (non-streaming) curl http://localhost:3001/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-web/deepseek-chat", "messages": [{"role": "user", "content": "Hello!"}] }' # Streaming curl http://localhost:3001/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-web/qwen-turbo", "messages": [{"role": "user", "content": "Count to 5"}], "stream": true }' ``` ### TypeScript Client Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'http://localhost:3001/v1', apiKey: 'not-needed', // Zero Token doesn't require keys }); async function chat() { const response = await client.chat.completions.create({ model: 'deepseek-web/deepseek-chat', messages: [ { role: 'user', content: 'Explain TypeScript generics' } ], }); console.log(response.choices[0].message.content); } chat(); ``` ### Streaming Response ```typescript async function streamChat() { const stream = await client.chat.completions.create({ model: 'kimi/moonshot-v1-8k', messages: [{ role: 'user', content: 'Write a haiku' }], stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || ''); } } ``` ## Tool Calling (Web Models) OpenClaw injects tool definitions into prompts for 11/13 web models. Tools are only injected when user message contains keywords like "search", "read", "execute". ### Available Tools | Tool | Function | Provider Support | |--------------|-----------------------------------|------------------| | `web_search` | DuckDuckGo search | 11/13 models | | `web_fetch` | Fetch webpage content | 11/13 models | | `exec` | Execute shell command | 11/13 models | | `read` | Read file (workspace restricted) | 11/13 models | | `write` | Write file (workspace restricted) | 11/13 models | | `message` | Structured output | 11/13 models | ### Tool Calling Example ```typescript const response = await client.chat.completions.create({ model: 'deepseek-web/deepseek-chat', messages: [{ role: 'user', content: 'Search for TypeScript 5.4 release notes and summarize' }], }); // Model automatically: // 1. Detects "search" keyword // 2. Calls web_search tool // 3. Fetches results // 4. Summarizes content ``` ### Agent File Access Configuration Tools like `read`/`write` are restricted to the configured workspace: ```bash # In .env AGENT_WORKSPACE=/home/user/projects/safe-zone ``` ```typescript // Attempting to read outside workspace fails const badRead = await client.chat.completions.create({ model: 'kimi/moonshot-v1-32k', messages: [{ role: 'user', content: 'Read /etc/passwd' // ❌ Blocked }], }); // Within workspace succeeds const goodRead = await client.chat.completions.create({ model: 'kimi/moonshot-v1-32k', messages: [{ role: 'user', content: 'Read project-notes.md' // ✅ Allowed if in workspace }], }); ``` ## AskOnce: Multi-Model Queries Query all configured providers simultaneously: ```bash # CLI usage (if implemented) pnpm ask-once "What is the capital of France?" # Returns responses from: # - DeepSeek: "Paris..." # - Qwen: "The capital is Paris..." # - Kimi: "Paris, established in..." # etc. ``` ```typescript // Programmatic AskOnce import { askOnce } from './src/zero-token/ask-once'; const results = await askOnce({ query: 'Explain quantum entanglement in one sentence', providers: ['deepseek-web', 'qwen-web', 'kimi', 'claude-web'], }); results.forEach(({ provider, response, duration }) => { console.log(`[${provider}] (${duration}ms): ${response}`); }); ``` ## Common Patterns ### 1. Multi-Provider Failover ```typescript const providers = [ 'deepseek-web/deepseek-chat', 'qwen-web/qwen-turbo', 'kimi/moonshot-v1-8k', ]; async function chatWithFailover(message: string) { for (const model of providers) { try { const response = await client.chat.completions.create({ model, messages: [{ role: 'user', content: message }], }); return response.choices[0].message.content; } catch (error) { console.warn(`${model} failed, trying next...`); } } throw new Error('All providers failed'); } ``` ### 2. Model Routing by Task ```typescript function selectModel(task: string): string { if (task.includes('reasoning') || task.includes('logic')) { return 'deepseek-web/deepseek-reasoner'; } if (task.includes('code')) { return 'qwen-web/qwen-plus'; } return 'kimi/moonshot-v1-8k'; // default } const model = selectModel('Write a sorting algorithm'); const response = await client.chat.completions.create({ model, messages: [{ role: 'user', content: 'Implement quicksort in Python' }], }); ``` ### 3. Workspace-Safe Agent ```typescript import * as path from 'path'; const WORKSPACE = process.env.AGENT_WORKSPACE || '/tmp/agent-workspace'; async function safeAgentTask(instruction: string) { // Ensure workspace exists await fs.promises.mkdir(WORKSPACE, { recursive: true }); const response = await client.chat.completions.create({ model: 'kimi/moonshot-v1-32k', messages: [{ role: 'system', content: `You are a helpful agent. All file operations must be within ${WORKSPACE}.` }, { role: 'user', content: instruction }], });