claw-alexa/README.md

OpenClaw Alexa Skill

Voice-control your personal AI assistant through Amazon Alexa

Features • Architecture • Quick Start • Usage • Troubleshooting

---

Connect your OpenClaw gateway to Alexa and interact with your personal AI using voice commands. Ask questions, read files from your workspace, execute commands, and more — all hands-free.

Features

Feature	Description
Voice-Activated AI	Talk to your OpenClaw assistant through any Alexa device
Local File Access	Read and interact with files on your computer
Secure Tunneling	Uses Tailscale Funnel for encrypted, stable connections
Personal & Private	Each user connects to their own OpenClaw instance
Fallback Support	Optional Grok API fallback when gateway is unavailable

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           OpenClaw Alexa Architecture                        │
└─────────────────────────────────────────────────────────────────────────────┘

    ┌──────────────┐          ┌──────────────┐          ┌──────────────┐
    │              │          │              │          │              │
    │    Alexa     │  ─────▶  │  AWS Lambda  │  ─────▶  │  Tailscale   │
    │    Device    │  ◀─────  │              │  ◀─────  │   Funnel     │
    │              │          │              │          │              │
    └──────────────┘          └──────────────┘          └──────────────┘
           │                                                    │
           │                                                    │
           ▼                                                    ▼
    ┌──────────────┐                                   ┌──────────────┐
    │   "Alexa,    │                                   │   OpenClaw   │
    │  ask claw    │                                   │   Gateway    │
    │    bot..."   │                                   │   (Local)    │
    └──────────────┘                                   └──────────────┘
                                                               │
                                                               ▼
                                                       ┌──────────────┐
                                                       │  Your Files  │
                                                       │  & Commands  │
                                                       └──────────────┘

Prerequisites

Before you begin, ensure you have:

• OpenClaw installed and configured
• Tailscale account with Funnel enabled
• AWS Account for Lambda deployment
• Alexa Developer Account
• Node.js 18+ (Lambda) / Node.js 22+ (OpenClaw)

Quick Start

Step 1: Configure OpenClaw Gateway

Add the following to your ~/.openclaw/openclaw.json:

{
  "gateway": {
    "port": 18789,
    "auth": {
      "mode": "password",
      "password": "your-secure-password"
    },
    "tailscale": {
      "mode": "funnel"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

Step 2: Start OpenClaw Gateway

openclaw gateway --force

Note your Tailscale Funnel URL from the output:

[tailscale] funnel enabled: https://your-machine.tailnet.ts.net/

Step 3: Deploy Lambda Function

# Clone the repository
git clone https://github.com/Pavelevich/openclaw-alexa.git
cd openclaw-alexa

# Set environment variables
export OPENCLAW_GATEWAY_URL="https://your-machine.tailnet.ts.net"
export OPENCLAW_GATEWAY_PASSWORD="your-secure-password"

# Create deployment package
cd lambda
zip -r ../lambda.zip .

# Deploy to AWS Lambda
aws lambda update-function-code \
  --function-name openclaw-alexa \
  --zip-file fileb://../lambda.zip \
  --region us-east-1

# Configure environment
aws lambda update-function-configuration \
  --function-name openclaw-alexa \
  --environment "Variables={OPENCLAW_GATEWAY_URL=$OPENCLAW_GATEWAY_URL,OPENCLAW_GATEWAY_PASSWORD=$OPENCLAW_GATEWAY_PASSWORD}" \
  --region us-east-1

Step 4: Create Alexa Skill

1. Navigate to Alexa Developer Console
2. Click Create Skill → Choose Custom model
3. Set invocation name: claw bot
4. Go to JSON Editor and paste contents of interactionModels/custom/en-US.json
5. Click Build Model
6. Under Endpoint, select AWS Lambda ARN and paste your function ARN
7. Save and Build the skill

Usage

Voice Commands

Command	What it does
"Alexa, open claw bot"	Start a conversation session
"Alexa, ask claw bot tell me a joke"	Quick one-shot question
"Alexa, ask claw bot what files are in my workspace"	List your workspace files
"Alexa, ask claw bot read my notes file"	Read file contents aloud
"Alexa, ask claw bot summarize the readme"	Get document summaries

Example Interactions

You:    "Alexa, ask claw bot what's the weather like"
Alexa:  "I don't have direct weather access, but I can help you
         with files and tasks on your computer..."

You:    "Alexa, ask claw bot list files in my documents"
Alexa:  "I found 5 files in your documents folder: notes.txt,
         project-plan.md, budget.xlsx..."

Project Structure

openclaw-alexa/
├── lambda/
│   ├── index.js              # Lambda handler with OpenAI-compatible API
│   └── package.json          # Lambda dependencies
├── interactionModels/
│   └── custom/
│       └── en-US.json        # Alexa interaction model (38 utterances)
├── skill.json                # Alexa skill manifest
├── .env.example              # Environment variables template
├── .gitignore
├── LICENSE
└── README.md

Configuration

Environment Variables

Variable	Description	Required
OPENCLAW_GATEWAY_URL	Your Tailscale Funnel URL	✅
OPENCLAW_GATEWAY_PASSWORD	Gateway authentication password	✅
XAI_API_KEY	Grok API key for fallback	❌

Lambda Settings

Setting	Recommended Value
Runtime	Node.js 18.x
Memory	256 MB
Timeout	30 seconds
Region	us-east-1 (required for Alexa)

Security

Layer	Protection
Transport	HTTPS via Tailscale Funnel (end-to-end encryption)
Authentication	Password-based Bearer token authentication
Infrastructure	No shared servers — each user runs their own instance
Credentials	Environment variables only — never committed to code

Important

: Never commit credentials or API keys. Use .env files locally and Lambda environment variables in production.

Troubleshooting

Common Issues

"I'm not quite sure how to help you with that"

The utterance didn't match a known pattern. Try rephrasing:

• ✅ "tell me about {topic}"
• ✅ "what is {query}"
• ✅ "show me {something}"
• ❌ Single-word queries

Gateway timeout errors

1. Verify OpenClaw gateway is running:

   openclaw gateway --force
   

2. Check Tailscale Funnel status:

   tailscale funnel status
   

3. Test the endpoint directly:

   curl https://your-machine.tailnet.ts.net/health
   

401 Unauthorized

• Verify OPENCLAW_GATEWAY_PASSWORD matches your openclaw.json config
• Ensure auth mode is set to password (not token)
• Check the password doesn't have special characters that need escaping

Skill not responding on phone

• Ensure skill is enabled in the Alexa app
• Check you're using the same Amazon account as the developer console
• Try: Alexa app → Skills → Your Skills → Dev → Enable

API Reference

The Lambda uses the OpenAI-compatible chat completions endpoint:

POST /v1/chat/completions
Authorization: Bearer {password}
Content-Type: application/json

{
  "model": "openclaw",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "user query"}
  ],
  "stream": false
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• OpenClaw Documentation
• Tailscale Funnel Guide
• Alexa Skills Kit Documentation
• AWS Lambda Developer Guide

---

Built with OpenClaw