@oceanswave/openclaw-tescmd 0.3.1 → 0.3.9

package/index.ts

@@ -37,7 +37,6 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerCliCommands } from "./commands/cli.js";
 import { registerSlashCommands } from "./commands/slash.js";
 import { type TescmdConfig, tescmdConfigSchema } from "./config.js";
-import { registerPlatform } from "./platform.js";
 import { registerCapabilitiesTool } from "./tools/capabilities.js";
 import { registerChargeTools } from "./tools/charge.js";
 import { registerClimateTools } from "./tools/climate.js";
@@ -68,9 +67,6 @@ export default {
 			api.logger.info("openclaw-tescmd: debug mode enabled");
 		}
 
-		// Register the Tesla platform + command whitelist
-		registerPlatform(api);
-
 		// Register all agent-callable tools by domain
 		registerCapabilitiesTool(api);
 		registerStatusTool(api);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oceanswave/openclaw-tescmd",
-	"version": "0.3.1",
+	"version": "0.3.9",
 	"description": "OpenClaw platform plugin for Tesla vehicle control and telemetry via tescmd",
 	"type": "module",
 	"license": "MIT",

package/platform.ts

@@ -10,7 +10,7 @@
  * `CommandDispatcher` handler map (src/tescmd/openclaw/dispatcher.py).
  */
 
-import type { OpenClawPluginApi, PlatformCommand } from "openclaw/plugin-sdk";
+import type { PlatformCommand } from "openclaw/plugin-sdk";
 
 // ---------------------------------------------------------------------------
 // Read commands (8)
@@ -328,34 +328,8 @@ const WRITE_COMMANDS: PlatformCommand[] = [
 export const ALL_COMMANDS: PlatformCommand[] = [...READ_COMMANDS, ...WRITE_COMMANDS];
 
 // ---------------------------------------------------------------------------
-// Registration
+// Command metadata helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Register the Tesla platform with the OpenClaw Gateway.
- *
- * This whitelists all 34 commands so the Gateway will dispatch
- * `node.invoke.request` events to connected tescmd nodes.
- */
-export function registerPlatform(api: OpenClawPluginApi): void {
-	api.registerPlatform({
-		id: "tesla",
-		label: "Tesla Vehicle",
-		description:
-			"Tesla vehicle control and real-time telemetry via tescmd. " +
-			"Supports 34 commands across vehicle status, charging, climate, " +
-			"security, trunk, sentry mode, navigation, and trigger subscriptions. " +
-			"The tescmd node connects to the Tesla Fleet API and streams " +
-			"telemetry data including GPS location, battery, temperature, " +
-			"speed, charge state, and security events.",
-		nodeRole: "node",
-		scopes: ["node.telemetry", "node.command"],
-		commands: ALL_COMMANDS,
-	});
-
-	api.logger.info(
-		`Registered tesla platform with ${ALL_COMMANDS.length} whitelisted commands ` +
-			`(${READ_COMMANDS.length} reads, ${WRITE_COMMANDS.length} writes, ` +
-			`including system.run meta-dispatch)`,
-	);
-}
+/** All command method names, useful for documentation and config generation. */
+export const ALL_COMMAND_METHODS: string[] = ALL_COMMANDS.map((cmd) => cmd.method);

package/skill.md

@@ -1,37 +1,33 @@
 ---
 name: openclaw-tescmd
-version: 0.3.1
-description: Agent handbook for Tesla vehicle control and telemetry via the tescmd node — covers 37 tools, 34 commands, 8 slash commands, and 14 telemetry event types.
+slug: openclaw-tescmd
+displayName: OpenClaw Tesla (tescmd)
+version: 0.3.9
+description: Installation and setup guide for Tesla vehicle control and telemetry via the tescmd node.
 homepage: https://github.com/oceanswave/openclaw-tescmd
 metadata: {"category":"platform","platform":"tesla","node":"tescmd"}
 ---
 
-# OpenClaw Tesla (tescmd) — Agent Handbook
+# OpenClaw Tesla (tescmd) — Setup Guide
 
-This plugin gives agents full control of a Tesla vehicle through the OpenClaw Gateway. It registers **37 agent-callable tools**, **34 whitelisted commands**, **8 slash commands**, and **14 telemetry event types** backed by real-time Fleet Telemetry streaming.
+This plugin connects Tesla vehicles to the OpenClaw Gateway via the [tescmd](https://github.com/oceanswave/tescmd) node. Once installed and paired, the plugin automatically registers all tools, commands, slash commands, and telemetry event types.
+
+This document covers **installation and setup only**. Runtime tool usage, workflows, and error handling are provided by the plugin's registered tools (call `tescmd_help` for the full reference).
 
 **Repositories:**
-- Plugin (this repo): https://github.com/oceanswave/openclaw-tescmd
+- Plugin: https://github.com/oceanswave/openclaw-tescmd
 - tescmd node (Python CLI): https://github.com/oceanswave/tescmd
 
-This document is an installation and configuration reference. Once installed, the plugin will automatically register tools, commands, and events.
-
 ---
 
 ## Architecture
 
-### System Layers
-
 ```
 Agent (you)
   ↓  tool calls
 OpenClaw Gateway
   ↓  node.invoke.request
 openclaw-tescmd Plugin
-  ├─ 37 Tools (schema + routing)
-  ├─ 34 Whitelisted Commands
-  ├─ 8 Slash Commands
-  └─ 14 Telemetry Event Types
   ↓  WebSocket dispatch
 tescmd Node (Python)
   ├─ Tesla Fleet API (REST)
@@ -41,21 +37,7 @@ tescmd Node (Python)
 Tesla Vehicle
 ```
 
-### Three Operating Modes
-
-| Mode | What It Does | Flag |
-|------|-------------|------|
-| **Full** (default) | MCP server + telemetry + OpenClaw bridge | `tescmd serve <VIN> --openclaw <url>` |
-| **Bridge only** | Telemetry + OpenClaw, no MCP server | `--no-mcp` |
-| **Dry run** | Log events as JSONL, no Gateway connection | `--dry-run` |
-
-### Data Flow
-
-**Read path:** Agent calls read tool → Plugin routes to Gateway → Gateway dispatches `node.invoke.request` to tescmd node → Node checks in-memory telemetry store first (instant, free) → Falls back to Fleet API if telemetry unavailable (may need vehicle wake, slower).
-
-**Write path:** Agent calls write tool → Plugin routes to Gateway → Gateway dispatches to node → Node sends command to vehicle via Fleet API or Vehicle Command Protocol (VCSEC for security commands) → Vehicle executes → Node returns result. Write commands auto-wake sleeping vehicles (billable API call).
-
-**Telemetry path:** Vehicle → Tesla Fleet Telemetry stream → tescmd node filters/throttles → Node emits `req:agent` frames to Gateway → Gateway broadcasts to agents. Agents receive real-time events without polling.
+The plugin is the **Gateway-side counterpart** to the tescmd node. It defines tool schemas and routes invocations. The tescmd node handles all direct communication with Tesla.
 
 ---
 
@@ -137,14 +119,6 @@ Wait for the user to confirm before continuing.
 openclaw plugins install @oceanswave/openclaw-tescmd
 ```
 
-#### Development install (symlink, editable):
-
-```bash
-git clone https://github.com/oceanswave/openclaw-tescmd.git
-cd openclaw-tescmd && bun install && cd ..
-openclaw plugins install -l ./openclaw-tescmd
-```
-
 #### Verify installation:
 
 ```bash
@@ -225,34 +199,68 @@ Note the VIN — it is needed for the serve command.
 
 ---
 
-### Step 6: Start the tescmd Node
+### Step 6: Start the tescmd Node and Pair with the Gateway
 
-The node bridges the Tesla Fleet API to the OpenClaw Gateway. It needs:
-- The vehicle's VIN
-- The Gateway's WebSocket URL
-- A Gateway authentication token
+The tescmd node bridges the Tesla Fleet API to the OpenClaw Gateway. The first connection requires a one-time pairing approval.
 
-#### Full mode (MCP server + telemetry + OpenClaw bridge):
+#### First-time pairing:
+
+Start the node with just the Gateway URL (no token needed):
 ```bash
-tescmd serve <VIN> --openclaw <gateway_ws_url> --openclaw-token <gateway_token>
+tescmd serve <VIN> --openclaw <gateway_ws_url>
 ```
 
-#### OpenClaw bridge only (no MCP server):
+The node sends a `node.pair.request` to the Gateway and waits for approval. The pending request expires after **5 minutes**, so approve it promptly.
+
+**In a separate terminal**, approve the pairing:
 ```bash
-tescmd serve <VIN> --no-mcp --openclaw <gateway_ws_url> --openclaw-token <gateway_token>
+openclaw nodes pending                # View waiting pair requests
+openclaw nodes approve <requestId>    # Approve the node
 ```
 
-#### With Tailscale (exposes MCP via Tailscale Funnel):
+On approval the Gateway issues an authentication token. The node receives it, saves it to `~/.config/tescmd/bridge.json`, and establishes the authenticated connection. No manual token handling is needed.
+
+**Tell the user:** "Start the tescmd node with `tescmd serve <VIN> --openclaw <gateway_url>`, then in another terminal run `openclaw nodes pending` and `openclaw nodes approve <requestId>` to complete pairing."
+
+**Wait for the user to confirm pairing is complete before continuing.**
+
+#### Subsequent connections (already paired):
+
+Once paired, the node reconnects automatically using the stored token:
+```bash
+tescmd serve <VIN> --openclaw <gateway_ws_url>
+```
+
+You can also pass the token explicitly if needed:
 ```bash
-tescmd serve <VIN> --tailscale --openclaw <gateway_ws_url> --openclaw-token <gateway_token>
+tescmd serve <VIN> --openclaw <gateway_ws_url> --openclaw-token <gateway_token>
 ```
 
+#### Node management commands:
+
+| Command | Purpose |
+|---------|---------|
+| `openclaw nodes pending` | View pending pair requests |
+| `openclaw nodes approve <id>` | Approve a node |
+| `openclaw nodes reject <id>` | Reject a node |
+| `openclaw nodes status` | List paired nodes and their status |
+
+#### Operating modes:
+
+| Mode | Command | Description |
+|------|---------|-------------|
+| **Full** (default) | `tescmd serve <VIN> --openclaw <url>` | MCP server + telemetry + OpenClaw bridge |
+| **Bridge only** | `tescmd serve <VIN> --no-mcp --openclaw <url>` | Telemetry + OpenClaw, no MCP server |
+| **With Tailscale** | `tescmd serve <VIN> --tailscale --openclaw <url>` | Exposes MCP via Tailscale Funnel |
+| **Dry run** | `tescmd serve <VIN> --dry-run` | Log events as JSONL, no Gateway connection |
+
 #### Key flags reference:
+
 | Flag | Description |
 |------|-------------|
 | `<VIN>` | Vehicle Identification Number (positional) |
 | `--openclaw <ws_url>` | Gateway WebSocket URL (e.g. `ws://host:18789`) |
-| `--openclaw-token <token>` | Gateway authentication token |
+| `--openclaw-token <token>` | Gateway authentication token (auto-stored after pairing) |
 | `--openclaw-config <path>` | Bridge config JSON (default: `~/.config/tescmd/bridge.json`) |
 | `--transport <type>` | MCP transport: `streamable-http` (default) or `stdio` |
 | `--port <num>` | MCP HTTP port (default: 8080) |
@@ -269,6 +277,7 @@ tescmd serve <VIN> --tailscale --openclaw <gateway_ws_url> --openclaw-token <gat
 | `--client-secret <secret>` | MCP OAuth client secret |
 
 #### Environment variables (alternative to flags):
+
 These can be set in `~/.config/tescmd/.env`:
 ```bash
 TESLA_CLIENT_ID=your-client-id
@@ -284,7 +293,7 @@ TESLA_COMMAND_PROTOCOL=auto        # auto, signed, or unsigned
 
 ### Step 7: Verify the Connection
 
-Once the node is running, confirm it connected to the Gateway:
+Once the node is running and paired, confirm it connected to the Gateway:
 ```bash
 openclaw tescmd status
 ```
@@ -292,392 +301,42 @@ openclaw tescmd status
 Or use the agent tool:
 - Call `tescmd_node_status` to check connection status
 
-If connected, you now have access to all 37 Tesla vehicle tools.
+If connected, the plugin's tools are ready. Call `tescmd_help` for the full runtime reference including tool usage, workflows, and error handling.
 
 ---
 
-## Agent Behavior Guide
-
-### Session Start Protocol
-
-**Always call `tescmd_node_status` first** before invoking any vehicle command in a new conversation. If the node is offline, all other vehicle tools will fail. Suggest starting one:
-```
-tescmd serve <VIN> --openclaw <gateway_url> --openclaw-token <token>
-```
-
-### Read Before Write
-
-Always check current state before sending write commands:
-- Before `tescmd_start_charge` → call `tescmd_get_charge_state` (is cable connected?)
-- Before `tescmd_climate_on` → call `tescmd_get_temperature` (what's the current temp?)
-- Before `tescmd_sentry_on` → call `tescmd_get_battery` (is battery too low for sentry?)
-- Before `tescmd_homelink` → call `tescmd_get_location` (need lat/lon for proximity check)
-- Before `tescmd_nav_supercharger` → call `tescmd_get_battery` (does the user actually need to charge?)
-
-### Confirm Before Sensitive Actions
-
-These actions require explicit user confirmation before executing:
-- **`tescmd_unlock_doors`** — Grants physical access to the vehicle. Never unlock proactively.
-- **`tescmd_open_frunk`** — Cannot be closed remotely; must be physically pushed down.
-- **`tescmd_honk_horn`** — Audible alert in public; may disturb others.
-- **Starting charge** when battery is above 90% — User may not want to charge to 100% daily.
-
-### Escalation Rules
-
-Escalate to the user (ask, don't act) when:
-- Any security-related action (unlock, sentry off) without explicit request
-- Node is offline and cannot auto-recover
-- Vehicle is asleep and the action would trigger a billable wake-up
-- Rate limits are hit — suggest waiting rather than retrying
-- Auth tokens are expired — user needs to re-authenticate manually
-
-### Proactive Monitoring via Triggers
-
-When the user asks you to "keep an eye on" something, set up triggers instead of polling:
-- "Watch my battery" → `tescmd_battery_trigger` with operator='lt', value=20
-- "Alert if the cabin gets hot" → `tescmd_cabin_temp_trigger` with operator='gt', value=100
-- "Tell me if the car moves" → `tescmd_location_trigger` with operator='leave'
-- Then periodically call `tescmd_poll_triggers` to check for fired notifications.
-
-### Battery-Aware Decision Making
-
-Before enabling battery-draining features:
-1. Check battery level with `tescmd_get_battery`
-2. If battery < 20%, warn the user before enabling Sentry Mode (~1-2%/hr drain)
-3. If battery < 10%, strongly advise against Sentry Mode and suggest charging
-4. Climate pre-conditioning uses battery too — mention this on low charge
-
----
-
-## Tool Reference
-
-### System & Meta Tools
-
-| Tool | Use When... | Parameters | Returns |
-|------|------------|------------|---------|
-| `tescmd_node_status` | **Session start**, diagnostics, before first command | _none_ | `{connected, node_id?, platform, commands_available?, last_seen?}` |
-| `tescmd_help` | Need detailed workflow recipes, error handling reference, or tescmd CLI commands | `topic?` (tools, workflows, triggers, errors, telemetry, setup, cli, all) | Markdown reference text |
-| `tescmd_run_command` | Need a command without a dedicated tool, or method name is dynamic | `method` (string), `params?` (object) | Varies by command |
-
-### Reading Vehicle State (no side effects, safe to call anytime)
-
-| Tool | Use When... | Parameters | Returns |
-|------|------------|------------|---------|
-| `tescmd_get_location` | "Where is my car?", need GPS, proximity checks, before HomeLink | _none_ | `{latitude, longitude, heading, speed}` |
-| `tescmd_get_battery` | Charge level, range, "do I need to charge?", trip planning | _none_ | `{battery_level, range_miles}` |
-| `tescmd_get_speed` | "Is the car moving?", verify parked before commands | _none_ | `{speed_mph}` |
-| `tescmd_get_charge_state` | "Is it charging?", before start/stop charge | _none_ | `{charge_state}` — Charging, Complete, Stopped, Disconnected |
-| `tescmd_get_temperature` | "Is the car hot/cold?", before climate decisions | _none_ | `{inside_temp_c, outside_temp_c}` |
-| `tescmd_get_security` | "Is my car locked?", sentry status, before lock/unlock | _none_ | `{locked, sentry_mode}` |
-
-**Data source priority:** All reads check in-memory telemetry first (instant, zero cost when streaming). Falls back to Fleet API (may require vehicle wake, slower, cached 30s-1h TTL).
-
-### Vehicle Control (side effects — confirm intent when appropriate)
-
-| Tool | Use When... | Parameters | Returns |
-|------|------------|------------|---------|
-| `tescmd_lock_doors` | User wants to lock; part of parking workflow | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_unlock_doors` | **User explicitly asks** — always confirm first | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_climate_on` | Precondition cabin, "warm up/cool down the car" | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_climate_off` | Stop climate, save battery | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_set_climate_temp` | "Set it to 72 degrees" — takes **Fahrenheit** | `temp` (number, °F) | `{result: true, reason: 'ok'}` |
-| `tescmd_start_charge` | Start charging — verify cable connected first | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_stop_charge` | Stop an active charge session | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_set_charge_limit` | "Charge to 80%" — 50-100 range | `percent` (50-100) | `{result: true, reason: 'ok'}` |
-| `tescmd_open_trunk` | Open/close rear trunk (toggles on power liftgate models) | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_open_frunk` | Open front trunk — **cannot close remotely** | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_flash_lights` | Locate vehicle, visual signal | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_honk_horn` | Locate vehicle, audible signal | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_sentry_on` | Camera monitoring — uses ~1-2% battery/hr | _none_ | `{result: true, reason: 'ok'}` |
-| `tescmd_sentry_off` | Stop camera monitoring, reduce battery drain | _none_ | `{result: true, reason: 'ok'}` |
-
-### Navigation (send destinations to the vehicle)
-
-| Tool | Use When... | Parameters | Returns |
-|------|------------|------------|---------|
-| `tescmd_nav_send` | "Navigate to [place]", send address/place name | `address` (string) | Destination sent |
-| `tescmd_nav_gps` | Have exact lat/lon coordinates | `lat`, `lon`, `order?` (waypoint order) | Coordinates sent |
-| `tescmd_nav_supercharger` | "Find a Supercharger", low battery | _none_ | Routing to nearest |
-| `tescmd_nav_waypoints` | Multi-stop road trip with Google Place IDs | `waypoints` (comma-separated refIds) | Route sent |
-| `tescmd_homelink` | "Open the garage" — needs vehicle GPS | `lat`, `lon` (from `tescmd_get_location`) | HomeLink triggered |
-
-### Triggers (telemetry subscriptions)
-
-| Tool | Use When... | Parameters | Returns |
-|------|------------|------------|---------|
-| `tescmd_create_trigger` | Subscribe to any telemetry condition | `field`, `operator`, `value?`, `once?`, `cooldown_seconds?` | `{id, field, operator}` |
-| `tescmd_battery_trigger` | Low battery alert shortcut | `operator`, `value?`, `once?`, `cooldown_seconds?` | `{id, field, operator}` |
-| `tescmd_cabin_temp_trigger` | Hot/cold cabin alert shortcut | `operator`, `value?`, `once?`, `cooldown_seconds?` | `{id, field, operator}` |
-| `tescmd_outside_temp_trigger` | Weather/freezing alert shortcut | `operator`, `value?`, `once?`, `cooldown_seconds?` | `{id, field, operator}` |
-| `tescmd_location_trigger` | Geofence (enter/leave area) | `operator` (enter/leave), `lat?`, `lon?`, `radius?`, `value?`, `once?`, `cooldown_seconds?` | `{id, field, operator}` |
-| `tescmd_list_triggers` | Check what triggers are active | _none_ | `{triggers: [{id, field, operator, value, once, cooldown_seconds}]}` |
-| `tescmd_poll_triggers` | Check for fired trigger notifications | _none_ | `{notifications: [{trigger_id, field, value, fired_at}]}` |
-| `tescmd_delete_trigger` | Remove a trigger no longer needed | `id` (string) | `{deleted, id}` |
-
-**Trigger fields:** Soc, BatteryLevel, InsideTemp, OutsideTemp, VehicleSpeed, ChargeState, DetailedChargeState, Locked, SentryMode, Location, Gear, EstBatteryRange
-
-**Trigger operators:** `lt`, `gt`, `lte`, `gte`, `eq`, `neq` (numeric); `changed` (any change); `enter`, `leave` (geofence)
-
----
-
-## Workflows & Decision Trees
-
-### Intent-Based Routing
-
-When the user mentions... → Start with:
-
-| User Intent | First Tool | Then... |
-|-------------|-----------|---------|
-| Charging | `tescmd_get_charge_state` | Assess → start/stop/set limit |
-| Temperature, comfort | `tescmd_get_temperature` | Assess → climate on/off/set temp |
-| Security, locking | `tescmd_get_security` | Assess → lock/unlock/sentry |
-| Location, directions | `tescmd_get_location` | Report or navigate |
-| Battery, range | `tescmd_get_battery` | Report or suggest charging |
-| "Watch the car" | `tescmd_lock_doors` | Then sentry + geofence trigger |
-| "Status", "how's the car" | `tescmd_get_battery` | Then charge_state + temperature + security + location |
-
-### Workflow 1: "Is my car ready to go?"
-
-1. `tescmd_get_battery` → check charge level and range
-2. `tescmd_get_charge_state` → check if still charging
-3. `tescmd_get_temperature` → check cabin comfort
-4. `tescmd_get_security` → verify doors are locked
-5. Summarize: battery %, range, charging status, cabin temp, lock state
-
-### Workflow 2: "Precondition the cabin"
-
-1. `tescmd_get_temperature` → check current cabin temp
-2. `tescmd_climate_on` → start climate control
-3. Optionally: `tescmd_set_climate_temp` → set specific temperature
-4. Confirm: "Climate control is on, targeting X°F"
-
-### Workflow 3: "Set up for overnight charging"
-
-**Pre-check:** Call `tescmd_get_charge_state` to verify cable is connected. If 'Disconnected', tell the user to plug in first.
-
-1. `tescmd_set_charge_limit` → set to user's desired limit (typically 80%)
-2. `tescmd_start_charge` → begin charging
-3. Optionally: `tescmd_battery_trigger` → alert when charge reaches target
-
-### Workflow 4: "Keep an eye on the car" (parking/security)
-
-1. `tescmd_lock_doors` → ensure locked
-2. `tescmd_sentry_on` → enable camera monitoring (warn about ~1-2%/hr battery drain)
-3. `tescmd_location_trigger` → geofence alert if car moves
-4. Confirm setup
-
-### Workflow 5: "Navigate somewhere"
-
-1. `tescmd_nav_send` → pass the address or place name
-2. Or: `tescmd_nav_gps` → if you have exact lat/lon coordinates
-3. For multi-stop: `tescmd_nav_waypoints` → comma-separated Place IDs
-
-### Workflow 6: "Open the garage"
-
-1. `tescmd_get_location` → get the vehicle's current GPS
-2. `tescmd_homelink` → pass lat/lon to trigger HomeLink
-
-### Workflow 7: "Find my car"
-
-1. `tescmd_get_location` → get GPS coordinates
-2. `tescmd_flash_lights` → visual signal
-3. Optionally: `tescmd_honk_horn` → audible signal
-
-### Workflow 8: "Hot car alert"
-
-1. `tescmd_cabin_temp_trigger` with operator='gt', value=100 → alert over 100°F
-2. When triggered: `tescmd_climate_on` → auto-start climate
-3. `tescmd_get_temperature` → verify cooling
-
----
-
-## Error Handling & Recovery
-
-### Node Offline
-
-If commands fail with "no node connected" or similar:
-1. Call `tescmd_node_status` to confirm the node is offline
-2. Tell the user: "No tescmd node is connected. Start one with:"
-   `tescmd serve <VIN> --openclaw <gateway_url> --openclaw-token <token>`
-3. Do not retry vehicle commands — they will all fail until the node reconnects
-
-### Vehicle Asleep
-
-Write commands auto-wake the vehicle, but this is a **billable API call**.
-- If a read returns `{pending: true}`, data is being fetched. Wait 3-5 seconds and retry.
-- If wake fails (rare), suggest the user wake from the Tesla app (free).
-- Avoid unnecessary write commands to sleeping vehicles — check state with reads first.
-- Reads from telemetry are instant and don't require a wake.
-
-### Authentication Expired
-
-If commands fail with auth/token errors:
-- The tescmd node handles token refresh automatically.
-- If refresh fails, the user needs to re-authenticate: `tescmd auth login`
-- Check auth status: `tescmd auth status`
-- If persistent, re-run: `tescmd setup`
-
-### Rate Limiting
-
-Tesla's API has rate limits (429 responses). tescmd caches read responses to minimize API calls:
-- Static data (specs, warranty): cached 1 hour
-- Fleet lists: cached 5 minutes
-- Standard queries: cached 1 minute
-- Location/speed: cached 30 seconds
-- If you get rate limit errors, **wait and avoid rapid repeated calls**. Do not retry immediately.
-
-### Command Failures
-
-If a write command fails:
-- Check if the vehicle is in a valid state (e.g., charge cable connected for `charge.start`)
-- Check if the vehicle is online (call `tescmd_node_status`)
-- Try `tescmd_run_command` as a fallback — it accepts both dot-notation and Fleet API names
-
-### Trigger Failures
-
-If triggers aren't working:
-- "Triggers not available" → Node started without telemetry. Restart with telemetry enabled (remove `--no-telemetry`).
-- Triggers require the telemetry stream to be active to detect condition changes.
-- Check `tescmd_list_triggers` to verify the trigger was created.
-
-### Common Error Pattern Table
-
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| "no node connected" | tescmd node is not running or disconnected | Start node: `tescmd serve <VIN> --openclaw <url> --openclaw-token <token>` |
-| "no handler configured" | Node has no dispatcher registered | Restart node with full serve command |
-| "unknown command: X" | Command not in the 34-command whitelist | Check tool reference or use `tescmd_run_command` |
-| "handler timeout (30s)" | Vehicle/API unresponsive | Retry after brief wait; vehicle may be in a dead zone |
-| `{pending: true}` | Data being fetched from API | Retry in 3-5 seconds — vehicle is waking or API is slow |
-| "Triggers not available" | Node started without telemetry | Restart with `--fields all` or remove `--no-telemetry` |
-| Auth/token errors | OAuth2 token expired and refresh failed | User runs `tescmd auth login` |
-| 429 / rate limit | Too many API calls | Wait 30-60 seconds; reduce call frequency |
-| "vehicle offline" | Vehicle has no cellular connectivity | User must move vehicle to an area with signal |
-| "charge cable not connected" | Attempted `charge.start` without cable | Tell user to plug in the charge cable |
-| "not signed in" | No Tesla account linked | User runs `tescmd setup` from scratch |
-| "command protocol mismatch" | Signed command failed, unsigned fallback needed | Set `TESLA_COMMAND_PROTOCOL=unsigned` in `.env` or pass flag |
-
----
-
-## Cost & Impact Awareness
-
-### Wake-Ups Are Billable
-
-Every write command to a sleeping vehicle triggers a wake-up API call. Tesla counts these. Minimize unnecessary wake-ups by:
-- Checking state with reads first (reads from telemetry don't wake)
-- Batching multiple write commands in one session rather than waking for each
-- Using triggers instead of polling for condition changes
-
-### Sentry Mode Drains Battery
-
-Sentry Mode uses ~1-2% battery per hour. Before enabling:
-1. Check battery with `tescmd_get_battery`
-2. If below 20%, warn the user about the drain
-3. If below 10%, strongly advise against it
-
-### Telemetry Reads Are Free When Streaming
-
-When the telemetry stream is active, all read tools pull from the node's in-memory store — no API calls, no wake-ups, instant response. This is the optimal operating mode.
-
-When telemetry is offline (node started with `--no-telemetry`), reads fall back to the Fleet API which:
-- May require waking the vehicle
-- Are subject to rate limits
-- Are cached (30s-1h TTL depending on data type)
-
-### Rate Limit Budget
-
-Tesla's Fleet API rate limits apply per-vehicle. Approximate budget:
-- ~200 requests/day for most endpoints
-- Location/speed endpoints have tighter limits
-- Cached reads don't count (served from node memory)
-- Write commands always hit the API
-
----
-
-## Anti-Patterns
-
-| Don't Do This | Why | Do This Instead |
-|---------------|-----|-----------------|
-| Call `tescmd_start_charge` without checking charge state | Will fail if cable is not connected | Call `tescmd_get_charge_state` first |
-| Call `tescmd_unlock_doors` without user confirmation | Grants physical access — security risk | Always confirm: "Do you want me to unlock the doors?" |
-| Call `tescmd_open_frunk` without warning | Cannot be closed remotely | Warn: "The frunk can only be closed by hand. Open it?" |
-| Enable Sentry Mode on low battery (<20%) | Sentry drains ~1-2%/hr — could kill the battery | Check battery first, warn about drain |
-| Repeatedly wake a sleeping vehicle | Each wake is a billable API call | Batch commands, use telemetry for reads |
-| Ignore `{pending: true}` responses | Data is still loading | Wait 3-5 seconds and retry once |
-| Set temperature in Celsius | `tescmd_set_climate_temp` takes **Fahrenheit** | Convert to °F: `(C × 9/5) + 32` |
-| Read temperature expecting Fahrenheit | `tescmd_get_temperature` returns **Celsius** | Convert to °F if user expects it |
-| Poll in a loop instead of using triggers | Wastes API calls and may hit rate limits | Use `tescmd_create_trigger` + `tescmd_poll_triggers` |
-| Send multiple nav destinations rapidly | Only the last one takes effect | Send one destination, confirm it appeared |
-| Skip `tescmd_node_status` at session start | All commands will fail silently if node is offline | Always check connectivity first |
-| Assume `tescmd_get_location` returns before `tescmd_homelink` | HomeLink needs lat/lon from location | Chain: get_location → extract lat/lon → homelink |
-
----
-
-## Troubleshooting
+## Troubleshooting Setup
 
 | Problem | Solution |
 |---------|----------|
-| "no node connected" | Start the node: `tescmd serve <VIN> --openclaw <url> --openclaw-token <token>` |
+| "no node connected" | Start the node: `tescmd serve <VIN> --openclaw <url>` |
+| Pairing request not visible | Check `openclaw nodes pending` — requests expire after 5 minutes. Restart the node to generate a new request. |
+| Node connects then disconnects | Check Gateway URL. Run `tescmd auth status` to verify Tesla auth. |
 | Auth/token errors | Re-authenticate: `tescmd auth login` |
-| Vehicle asleep / pending responses | Write commands auto-wake. If wake fails, wake from Tesla app. Wait 3-5s and retry reads. |
-| Rate limit (429) | Wait 30-60s and reduce call frequency. Reads are cached (30s-1h TTL). |
-| "no handler configured" | Restart node with full `tescmd serve` command |
 | Setup wizard issues | Re-run `tescmd setup` or check https://github.com/oceanswave/tescmd |
-| Triggers not firing | Verify telemetry is enabled (no `--no-telemetry` flag). Check `tescmd_list_triggers`. |
-| Triggers say "not available" | Restart node with telemetry: remove `--no-telemetry` or add `--fields all` |
-| Commands return "unknown command" | Command not in whitelist. Use `tescmd_run_command` with the correct method name. |
-| Temperature values seem wrong | Reads return °C, set_climate_temp takes °F. Convert as needed. |
-| Frunk won't close | The frunk **cannot** be closed remotely. Must be physically pushed down. |
-| HomeLink won't trigger | Vehicle must be near the programmed device. Get location first, pass lat/lon. |
 | Plugin not loading | Run `openclaw plugins doctor`. Check `openclaw plugins list` for the plugin entry. |
-| Node connects then disconnects | Check Gateway URL/token. Run `tescmd auth status` to verify Tesla auth. |
+| Triggers say "not available" | Restart node with telemetry: remove `--no-telemetry` or add `--fields all` |
 
 ---
 
-## Telemetry Events
-
-The tescmd node streams these events to the Gateway via `req:agent` frames. Each event includes `event_type`, `source` (client_id), `vin`, `timestamp` (ISO 8601), and `data`.
-
-### Data Events (11)
-
-| Event Type | Data Fields | Filter Threshold | Throttle |
-|------------|------------|-----------------|----------|
-| `location` | latitude, longitude, heading, speed | 50m movement | 1s |
-| `battery` | battery_level, range_miles | Soc: 5% / BatteryLevel: 1% / EstBatteryRange: 5mi | 10s / 10s / 30s |
-| `inside_temp` | inside_temp_f | 5°F change | 30s |
-| `outside_temp` | outside_temp_f | 5°F change | 30s |
-| `speed` | speed_mph | 5mph change | 2s |
-| `charge_started` | state | Immediate | None |
-| `charge_complete` | state | Immediate | None |
-| `charge_stopped` | state | Immediate | None |
-| `charge_state_changed` | state | Immediate | None |
-| `security_changed` | field (locked/sentrymode), value | Immediate | None |
-| `gear_changed` | gear (P/R/N/D) | Immediate | None |
-
-### Lifecycle Events (3)
-
-| Event Type | Data Fields | When |
-|------------|------------|------|
-| `node.connected` | client_id | Node connects to Gateway |
-| `node.disconnecting` | client_id | Node is shutting down |
-| `trigger.fired` | trigger_id, field, value | A trigger condition was met |
-
-### Tesla Telemetry Field → Event Mapping
-
-| Fleet Telemetry Field | OpenClaw Event |
-|----------------------|----------------|
-| Location | `location` |
-| Soc | `battery` |
-| BatteryLevel | `battery` |
-| EstBatteryRange | `battery` |
-| InsideTemp | `inside_temp` |
-| OutsideTemp | `outside_temp` |
-| VehicleSpeed | `speed` |
-| ChargeState | `charge_started` / `charge_complete` / `charge_stopped` |
-| DetailedChargeState | `charge_state_changed` |
-| Locked | `security_changed` |
-| SentryMode | `security_changed` |
-| Gear | `gear_changed` |
+## Configuration
+
+Minimal — the tescmd node handles all vehicle-specific configuration.
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-tescmd": {
+        "enabled": true,
+        "config": {
+          "debug": false
+        }
+      }
+    }
+  }
+}
+```
 
 ---
 
@@ -694,44 +353,12 @@ openclaw tescmd events     # List telemetry event types
 ### tescmd CLI Commands
 
 ```bash
-tescmd serve <VIN> --openclaw <url> --openclaw-token <token>   # Start node
+tescmd serve <VIN> --openclaw <url>                              # Start node (uses stored token)
+tescmd serve <VIN> --openclaw <url> --openclaw-token <token>     # Start node (explicit token)
 tescmd setup                        # Interactive setup wizard
 tescmd auth status                  # Check auth token status
 tescmd auth login                   # Re-authenticate with Tesla
 tescmd vehicle list                 # List vehicles on account
 tescmd vehicle info                 # Full vehicle data snapshot
-tescmd vehicle location             # Get GPS coordinates
-tescmd charge status                # Battery and charging state
-tescmd charge start --wake          # Start charging (wakes vehicle)
-tescmd charge limit 80              # Set charge limit to 80%
-tescmd climate on --wake            # Turn on climate
-tescmd climate set 72 --wake        # Set temperature to 72°F
-tescmd climate status               # Check climate state
-tescmd security lock --wake         # Lock doors
-tescmd security status              # Check lock/sentry state
-tescmd security flash --wake        # Flash headlights
-tescmd security honk --wake         # Honk horn
-tescmd security sentry on --wake    # Enable Sentry Mode
-tescmd trunk open --wake            # Open rear trunk
-tescmd trunk frunk --wake           # Open frunk
 tescmd cache status                 # Check cache stats
 ```
-
-All read commands are cached (tiered TTLs: 30s-1h). Write commands auto-invalidate the cache. The `--wake` flag is required for commands that need the vehicle awake. Use `--format json` for structured output.
-
----
-
-## Slash Commands
-
-Quick-action shortcuts users can type directly in chat. All require authentication.
-
-| Command | Arguments | Description |
-|---------|-----------|-------------|
-| `/battery` | _none_ | Check battery level and range |
-| `/charge` | `start`, `stop`, or a number (e.g. `80`) | Charge status, start/stop, or set limit |
-| `/climate` | `on`, `off`, or a number (e.g. `72`) | Temperature check, HVAC on/off, or set °F |
-| `/lock` | _none_ | Lock all doors |
-| `/unlock` | _none_ | Unlock all doors |
-| `/sentry` | `on` or `off` | Check or toggle Sentry Mode |
-| `/location` | _none_ | Get GPS location |
-| `/vehicle` | _none_ | Full status: battery + charge + temp + security + location |

package/types/openclaw.d.ts

@@ -36,17 +36,7 @@ declare module "openclaw/plugin-sdk" {
 		name: string;
 	}
 
-	/** Platform definition for node registration. */
-	interface PlatformDefinition {
-		id: string;
-		label: string;
-		description: string;
-		nodeRole: string;
-		scopes: string[];
-		commands: PlatformCommand[];
-	}
-
-	/** A whitelisted command for a platform. */
+	/** A command descriptor for a platform (used in plugin metadata and documentation). */
 	interface PlatformCommand {
 		method: string;
 		label: string;
@@ -89,18 +79,37 @@ declare module "openclaw/plugin-sdk" {
 
 	/** The main plugin API surface. */
 	interface OpenClawPluginApi {
+		id: string;
+		name: string;
+		version: string;
+		description: string;
+		source: string;
+		config: Record<string, unknown>;
 		pluginConfig: unknown;
+		runtime: unknown;
 		logger: PluginLogger;
 		registerTool(tool: ToolDefinition, options: ToolOptions): void;
+		registerHook(
+			events: string | string[],
+			handler: (...args: unknown[]) => unknown,
+			opts?: { name?: string; description?: string; register?: boolean },
+		): void;
+		registerHttpHandler(handler: (req: unknown, res: unknown) => void): void;
+		registerHttpRoute(params: {
+			path: string;
+			handler: (req: unknown, res: unknown) => void;
+		}): void;
+		registerChannel(registration: unknown): void;
+		registerProvider(provider: { id: string; [key: string]: unknown }): void;
 		registerCommand(command: CommandDefinition): void;
 		registerCli(
 			handler: (ctx: { program: unknown }) => void,
 			options?: { commands: string[] },
 		): void;
 		registerService(service: ServiceDefinition): void;
-		registerPlatform(platform: PlatformDefinition): void;
 		registerGatewayMethod(method: string, handler: (ctx: GatewayMethodContext) => void): void;
-		on(event: string, handler: (...args: unknown[]) => unknown): void;
+		resolvePath(input: string): string;
+		on(event: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }): void;
 	}
 
 	/** Helper to create TypeBox-compatible string enums. */