@oceanswave/openclaw-tescmd 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 oceanswave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# openclaw-tescmd
+
+OpenClaw platform plugin for Tesla vehicle control and real-time telemetry via [tescmd](https://github.com/oceanswave/tescmd).
+
+## What It Does
+
+This plugin registers the Tesla vehicle platform with the OpenClaw Gateway, enabling AI agents to control Tesla vehicles and consume telemetry through well-documented tools. It bridges the [tescmd](https://github.com/oceanswave/tescmd) node — a Python CLI for the Tesla Fleet API — to the OpenClaw agent ecosystem.
+
+**Plugin provides:**
+- **37 agent-callable tools** across vehicle status, charging, climate, security, trunk, navigation, triggers, and system commands
+- **34 whitelisted commands** so the Gateway can dispatch to tescmd nodes
+- **8 slash commands** for quick user actions (`/battery`, `/lock`, `/climate`, etc.)
+- **14 telemetry event types** documented with TypeScript interfaces
+- **Capabilities meta-tool** with workflow recipes, error handling guide, and CLI reference
+- **Node status tool** for connection health checks
+
+## Installation
+
+Install from npm:
+
+```bash
+openclaw plugins install @oceanswave/openclaw-tescmd
+```
+
+For development (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:
+
+```bash
+openclaw plugins list
+```
+
+## Prerequisites
+
+The tescmd node must be running and connected to the Gateway for vehicle commands to work.
+
+| Requirement | Required | Purpose |
+|---|---|---|
+| Python 3.11+ | Yes | Runs the tescmd node |
+| pip | Yes | Installs tescmd (`pip install tescmd`) |
+| Tesla account | Yes | OAuth2 access to the Fleet API |
+| Git | Yes | Key hosting setup |
+| GitHub CLI (`gh`) | Recommended | Auto-creates key hosting via GitHub Pages |
+| Tailscale | Recommended | Public HTTPS for telemetry streaming |
+
+### Node Setup
+
+```bash
+# Install tescmd
+pip install tescmd
+
+# First-time setup (interactive wizard)
+tescmd setup
+
+# Start the node with OpenClaw bridge
+tescmd serve <VIN> --openclaw <gateway_ws_url> --openclaw-token <token>
+```
+
+## Agent Tools
+
+### Reading Vehicle State
+| Tool | Description |
+|------|-------------|
+| `tescmd_node_status` | Check if the tescmd node is connected |
+| `tescmd_get_location` | GPS coordinates, heading, speed |
+| `tescmd_get_battery` | Battery level (%) and range (miles) |
+| `tescmd_get_speed` | Current speed (mph) |
+| `tescmd_get_charge_state` | Charging status |
+| `tescmd_get_temperature` | Inside/outside temperatures |
+| `tescmd_get_security` | Lock state, sentry mode |
+
+### Controlling the Vehicle
+| Tool | Description |
+|------|-------------|
+| `tescmd_lock_doors` / `tescmd_unlock_doors` | Door lock/unlock |
+| `tescmd_climate_on` / `tescmd_climate_off` | HVAC control |
+| `tescmd_set_climate_temp` | Set cabin temperature (F) |
+| `tescmd_start_charge` / `tescmd_stop_charge` | Charge control |
+| `tescmd_set_charge_limit` | Set charge limit (50-100%) |
+| `tescmd_open_trunk` / `tescmd_open_frunk` | Trunk/frunk |
+| `tescmd_flash_lights` / `tescmd_honk_horn` | Locator alerts |
+| `tescmd_sentry_on` / `tescmd_sentry_off` | Sentry Mode |
+
+### Navigation
+| Tool | Description |
+|------|-------------|
+| `tescmd_nav_send` | Send address/place to vehicle navigation |
+| `tescmd_nav_gps` | Send GPS coordinates to navigation |
+| `tescmd_nav_supercharger` | Route to nearest Supercharger |
+| `tescmd_nav_waypoints` | Multi-stop route via waypoint IDs |
+| `tescmd_homelink` | Trigger garage door (HomeLink) |
+
+### Triggers
+| Tool | Description |
+|------|-------------|
+| `tescmd_create_trigger` | Subscribe to telemetry conditions |
+| `tescmd_delete_trigger` | Remove a trigger |
+| `tescmd_list_triggers` | List active triggers |
+| `tescmd_poll_triggers` | Check for fired triggers |
+| `tescmd_battery_trigger` | Shortcut: battery level alert |
+| `tescmd_cabin_temp_trigger` | Shortcut: cabin temp alert |
+| `tescmd_outside_temp_trigger` | Shortcut: outside temp alert |
+| `tescmd_location_trigger` | Shortcut: geofence alert |
+
+### Meta
+| Tool | Description |
+|------|-------------|
+| `tescmd_help` | Capabilities reference, workflows, setup guide |
+| `tescmd_run_command` | Execute any command by name (meta-dispatch) |
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/battery` | Check battery level and range |
+| `/charge` | Charge status, or `/charge start` / `/charge stop` / `/charge 80` |
+| `/climate` | Temperature, or `/climate on` / `/climate off` / `/climate 72` |
+| `/lock` | Lock all doors |
+| `/unlock` | Unlock all doors |
+| `/sentry` | Check sentry, or `/sentry on` / `/sentry off` |
+| `/location` | Get GPS location |
+| `/vehicle` | Full vehicle status summary |
+
+## CLI Commands
+
+```bash
+openclaw tescmd status     # Plugin and node status
+openclaw tescmd commands   # List all whitelisted commands
+openclaw tescmd events     # List telemetry event types
+```
+
+## Telemetry Events
+
+The tescmd node streams these events to the Gateway in real-time:
+
+| Event | Data |
+|-------|------|
+| `location` | latitude, longitude, heading, speed |
+| `battery` | battery_level, range_miles |
+| `inside_temp` / `outside_temp` | temp_f |
+| `speed` | speed_mph |
+| `charge_started` / `charge_complete` / `charge_stopped` | state |
+| `charge_state_changed` | state |
+| `security_changed` | field, value |
+| `gear_changed` | gear |
+| `trigger.fired` | trigger_id, field, value |
+
+## Configuration
+
+Minimal — the tescmd node handles all vehicle-specific configuration.
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-tescmd": {
+        "enabled": true,
+        "config": {
+          "debug": false
+        }
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+bun install
+bun run check-types
+bun run lint
+```
+
+## License
+
+MIT

package/commands/cli.ts

@@ -0,0 +1,74 @@
+/**
+ * CLI subcommands — terminal commands under `openclaw tescmd`.
+ *
+ * Registered commands:
+ *   openclaw tescmd status     — show plugin and node connection status
+ *   openclaw tescmd commands   — list all whitelisted commands
+ *   openclaw tescmd events     — list all telemetry event types
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { ALL_COMMANDS } from "../platform.js";
+import { ALL_EVENT_TYPES, TELEMETRY_FIELD_MAP } from "../telemetry.js";
+
+interface CliCommand {
+	command(name: string): CliCommand;
+	description(desc: string): CliCommand;
+	action(fn: () => void): CliCommand;
+}
+
+export function registerCliCommands(api: OpenClawPluginApi): void {
+	api.registerCli(
+		({ program }: { program: unknown }) => {
+			const tescmd = (program as CliCommand)
+				.command("tescmd")
+				.description("Tesla vehicle platform (tescmd)");
+
+			tescmd
+				.command("status")
+				.description("Show plugin and node connection status")
+				.action(() => {
+					console.log("openclaw-tescmd plugin status");
+					console.log("─".repeat(40));
+					console.log(`  Platform:    tesla`);
+					console.log(`  Commands:    ${ALL_COMMANDS.length} whitelisted`);
+					console.log(`  Events:      ${ALL_EVENT_TYPES.length} telemetry types`);
+					console.log(`  Node:        https://github.com/oceanswave/tescmd`);
+					console.log(`  Plugin:      https://github.com/oceanswave/openclaw-tescmd`);
+				});
+
+			tescmd
+				.command("commands")
+				.description("List all whitelisted commands")
+				.action(() => {
+					console.log("Whitelisted commands:");
+					console.log("");
+					const reads = ALL_COMMANDS.filter((c) => c.direction === "read");
+					const writes = ALL_COMMANDS.filter((c) => c.direction === "write");
+					console.log(`  Reads (${reads.length}):`);
+					for (const cmd of reads) {
+						console.log(`    ${cmd.method.padEnd(22)} ${cmd.label}`);
+					}
+					console.log("");
+					console.log(`  Writes (${writes.length}):`);
+					for (const cmd of writes) {
+						console.log(`    ${cmd.method.padEnd(22)} ${cmd.label}`);
+					}
+				});
+
+			tescmd
+				.command("events")
+				.description("List all telemetry event types")
+				.action(() => {
+					console.log("Telemetry event types:");
+					console.log("");
+					for (const [field, eventType] of Object.entries(TELEMETRY_FIELD_MAP)) {
+						console.log(`  ${field.padEnd(22)} → ${eventType}`);
+					}
+				});
+		},
+		{ commands: ["tescmd"] },
+	);
+
+	api.logger.info("Registered CLI commands: openclaw tescmd {status,commands,events}");
+}

package/commands/slash.ts

@@ -0,0 +1,160 @@
+/**
+ * Slash commands — user-typed shortcuts in chat.
+ *
+ * These are quick-action commands the user can type directly
+ * (e.g. "/battery", "/lock") without needing the agent to
+ * interpret natural language.  Each command dispatches to the
+ * tescmd node and returns a formatted response.
+ *
+ * Registered commands:
+ *   /battery       — battery level + range
+ *   /charge        — full charge status
+ *   /climate       — temperature + climate state
+ *   /lock          — lock all doors
+ *   /unlock        — unlock all doors
+ *   /sentry        — toggle or check sentry mode
+ *   /location      — GPS coordinates
+ *   /vehicle       — comprehensive vehicle status summary
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export function registerSlashCommands(api: OpenClawPluginApi): void {
+	api.registerCommand({
+		name: "battery",
+		description: "Check vehicle battery level and estimated range",
+		acceptsArgs: false,
+		requireAuth: true,
+		async handler(_ctx) {
+			return {
+				text: "Checking battery status via tescmd node...\n" + "_Invoking: battery.get_",
+			};
+		},
+	});
+
+	api.registerCommand({
+		name: "charge",
+		description: "Check charging status, or start/stop with arguments",
+		acceptsArgs: true,
+		requireAuth: true,
+		async handler(ctx) {
+			const arg = ctx.args?.trim().toLowerCase();
+			if (arg === "start") {
+				return { text: "Starting charge via tescmd node...\n_Invoking: charge.start_" };
+			}
+			if (arg === "stop") {
+				return { text: "Stopping charge via tescmd node...\n_Invoking: charge.stop_" };
+			}
+			if (arg && /^\d+$/.test(arg)) {
+				return {
+					text: `Setting charge limit to ${arg}% via tescmd node...\n_Invoking: charge.set_limit_`,
+				};
+			}
+			return {
+				text:
+					"Checking charge state via tescmd node...\n" +
+					"_Invoking: charge_state.get + battery.get_\n\n" +
+					"**Usage:** `/charge` (status) | `/charge start` | `/charge stop` | `/charge 80` (set limit)",
+			};
+		},
+	});
+
+	api.registerCommand({
+		name: "climate",
+		description: "Check temperature or control climate (on/off/set)",
+		acceptsArgs: true,
+		requireAuth: true,
+		async handler(ctx) {
+			const arg = ctx.args?.trim().toLowerCase();
+			if (arg === "on") {
+				return { text: "Turning on climate via tescmd node...\n_Invoking: climate.on_" };
+			}
+			if (arg === "off") {
+				return { text: "Turning off climate via tescmd node...\n_Invoking: climate.off_" };
+			}
+			if (arg && /^\d+$/.test(arg)) {
+				return {
+					text: `Setting temperature to ${arg}°F via tescmd node...\n_Invoking: climate.set_temp_`,
+				};
+			}
+			return {
+				text:
+					"Checking temperature via tescmd node...\n" +
+					"_Invoking: temperature.get_\n\n" +
+					"**Usage:** `/climate` (check) | `/climate on` | `/climate off` | `/climate 72` (set °F)",
+			};
+		},
+	});
+
+	api.registerCommand({
+		name: "lock",
+		description: "Lock all vehicle doors",
+		acceptsArgs: false,
+		requireAuth: true,
+		async handler(_ctx) {
+			return { text: "Locking doors via tescmd node...\n_Invoking: door.lock_" };
+		},
+	});
+
+	api.registerCommand({
+		name: "unlock",
+		description: "Unlock all vehicle doors",
+		acceptsArgs: false,
+		requireAuth: true,
+		async handler(_ctx) {
+			return { text: "Unlocking doors via tescmd node...\n_Invoking: door.unlock_" };
+		},
+	});
+
+	api.registerCommand({
+		name: "sentry",
+		description: "Check or toggle Sentry Mode (on/off)",
+		acceptsArgs: true,
+		requireAuth: true,
+		async handler(ctx) {
+			const arg = ctx.args?.trim().toLowerCase();
+			if (arg === "on") {
+				return { text: "Enabling Sentry Mode via tescmd node...\n_Invoking: sentry.on_" };
+			}
+			if (arg === "off") {
+				return { text: "Disabling Sentry Mode via tescmd node...\n_Invoking: sentry.off_" };
+			}
+			return {
+				text:
+					"Checking security status via tescmd node...\n" +
+					"_Invoking: security.get_\n\n" +
+					"**Usage:** `/sentry` (check) | `/sentry on` | `/sentry off`",
+			};
+		},
+	});
+
+	api.registerCommand({
+		name: "location",
+		description: "Get vehicle GPS location",
+		acceptsArgs: false,
+		requireAuth: true,
+		async handler(_ctx) {
+			return {
+				text: "Getting vehicle location via tescmd node...\n_Invoking: location.get_",
+			};
+		},
+	});
+
+	api.registerCommand({
+		name: "vehicle",
+		description: "Comprehensive vehicle status summary",
+		acceptsArgs: false,
+		requireAuth: true,
+		async handler(_ctx) {
+			return {
+				text:
+					"Fetching full vehicle status via tescmd node...\n" +
+					"_Invoking: battery.get + charge_state.get + temperature.get + security.get + location.get_",
+			};
+		},
+	});
+
+	api.logger.info(
+		"Registered 8 slash commands: /battery /charge /climate /lock /unlock /sentry /location /vehicle",
+	);
+}

package/config.ts

@@ -0,0 +1,39 @@
+/**
+ * Configuration parsing for the openclaw-tescmd plugin.
+ *
+ * Minimal — the tescmd node handles all vehicle-specific configuration.
+ * The plugin only exposes a debug toggle for verbose logging.
+ */
+
+export interface TescmdConfig {
+	debug: boolean;
+}
+
+const DEFAULT_CONFIG: TescmdConfig = {
+	debug: false,
+};
+
+/**
+ * Parse and validate raw plugin configuration.
+ *
+ * Returns a fully resolved {@link TescmdConfig} with defaults applied.
+ */
+export function parseConfig(raw: unknown): TescmdConfig {
+	if (raw == null || typeof raw !== "object") {
+		return { ...DEFAULT_CONFIG };
+	}
+
+	const obj = raw as Record<string, unknown>;
+
+	return {
+		debug: typeof obj.debug === "boolean" ? obj.debug : DEFAULT_CONFIG.debug,
+	};
+}
+
+/**
+ * Config schema export for the plugin entrypoint.
+ * OpenClaw calls `configSchema.parse()` to validate config at load time.
+ */
+export const tescmdConfigSchema = {
+	parse: parseConfig,
+};

package/index.ts

@@ -0,0 +1,107 @@
+/**
+ * OpenClaw plugin: openclaw-tescmd
+ *
+ * Registers the Tesla vehicle platform with the OpenClaw Gateway,
+ * whitelists all 34 tescmd node commands, and exposes 37 richly-documented
+ * agent-callable tools for vehicle control and telemetry monitoring.
+ *
+ * The tescmd node (https://github.com/oceanswave/tescmd) connects to the
+ * Tesla Fleet API and streams real-time telemetry data.  This plugin
+ * (https://github.com/oceanswave/openclaw-tescmd) is the Gateway-side
+ * counterpart that enables agents to discover and invoke Tesla vehicle
+ * commands through the OpenClaw tool system.
+ *
+ * Architecture:
+ *   Agent → OpenClaw Gateway → [this plugin routes to] → tescmd node → Tesla Fleet API → Vehicle
+ *
+ * Tool categories (37 tools):
+ *   - Help (1):       capabilities reference and workflow guide (tescmd_help)
+ *   - Status (1):     node connection health check (tescmd_node_status)
+ *   - Vehicle (3):    location, battery, speed
+ *   - Charge (4):     charge state, start/stop/limit
+ *   - Climate (4):    temperature, HVAC on/off, set temp
+ *   - Security (7):   lock state, lock/unlock, flash, honk, sentry on/off
+ *   - Trunk (2):      trunk, frunk
+ *   - Navigation (5): send destination, GPS, supercharger, waypoints, homelink
+ *   - Triggers (8):   list, poll, create, delete, + 4 convenience aliases
+ *   - System (1):     meta-dispatch (system.run)
+ *
+ * Slash commands (8):
+ *   /battery, /charge, /climate, /lock, /unlock, /sentry, /location, /vehicle
+ *
+ * CLI subcommands:
+ *   openclaw tescmd status | commands | events
+ */
+
+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";
+import { registerNavigationTools } from "./tools/navigation.js";
+import { registerSecurityTools } from "./tools/security.js";
+import { registerStatusTool } from "./tools/status.js";
+import { registerSystemTools } from "./tools/system.js";
+import { registerTriggerTools } from "./tools/triggers.js";
+import { registerTrunkTools } from "./tools/trunk.js";
+import { registerVehicleTools } from "./tools/vehicle.js";
+
+export default {
+	id: "openclaw-tescmd",
+	name: "Tesla (tescmd)",
+	description:
+		"Tesla vehicle control and real-time telemetry via the tescmd node. " +
+		"Provides 37 agent-callable tools for vehicle status, charging, climate, " +
+		"security, trunk access, navigation, sentry mode, and trigger subscriptions. " +
+		"Streams telemetry events including GPS location, battery level, " +
+		"temperature, speed, charge state, and security changes.",
+	kind: "platform" as const,
+	configSchema: tescmdConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		const config = tescmdConfigSchema.parse(api.pluginConfig) as TescmdConfig;
+
+		if (config.debug) {
+			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);
+		registerVehicleTools(api);
+		registerChargeTools(api);
+		registerClimateTools(api);
+		registerSecurityTools(api);
+		registerTrunkTools(api);
+		registerNavigationTools(api);
+		registerTriggerTools(api);
+		registerSystemTools(api);
+
+		// Register slash commands and CLI subcommands
+		registerSlashCommands(api);
+		registerCliCommands(api);
+
+		// Register a service for lifecycle logging
+		api.registerService({
+			id: "tescmd-platform",
+			start() {
+				api.logger.info(
+					"openclaw-tescmd platform plugin active — " +
+						"34 commands whitelisted, 37 tools registered, " +
+						"8 slash commands, 3 CLI subcommands",
+				);
+			},
+			stop() {
+				api.logger.info("openclaw-tescmd platform plugin stopping");
+			},
+		});
+
+		api.logger.info("openclaw-tescmd plugin registered successfully");
+	},
+};

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+	"id": "openclaw-tescmd",
+	"kind": "platform",
+	"configSchema": {
+		"type": "object",
+		"properties": {
+			"debug": {
+				"type": "boolean",
+				"default": false,
+				"description": "Enable verbose debug logging"
+			}
+		},
+		"required": []
+	},
+	"uiHints": {
+		"debug": {
+			"label": "Debug Mode",
+			"help": "Enable verbose logging for troubleshooting node communication",
+			"advanced": true
+		}
+	}
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@oceanswave/openclaw-tescmd",
+	"version": "0.3.1",
+	"description": "OpenClaw platform plugin for Tesla vehicle control and telemetry via tescmd",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/oceanswave/openclaw-tescmd.git"
+	},
+	"homepage": "https://github.com/oceanswave/openclaw-tescmd",
+	"files": [
+		"index.ts",
+		"config.ts",
+		"platform.ts",
+		"telemetry.ts",
+		"tools/",
+		"commands/",
+		"types/",
+		"openclaw.plugin.json",
+		"skill.md"
+	],
+	"openclaw": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.1.29"
+	},
+	"dependencies": {
+		"@sinclair/typebox": "^0.34.47"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.8",
+		"typescript": "^5.7.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"check-types": "tsc --noEmit",
+		"lint": "biome ci .",
+		"format": "biome format --write ."
+	}
+}