claw-alexa/README.md

<p align="center">
  <img src="logoalexa.png" alt="OpenClaw Alexa" width="400"/>
</p>

<h1 align="center">OpenClaw Alexa Skill</h1>

<p align="center">
  <img src="https://img.shields.io/badge/Alexa-00CAFF?style=for-the-badge&logo=amazon-alexa&logoColor=white" alt="Alexa"/>
  <img src="https://img.shields.io/badge/AWS_Lambda-FF9900?style=for-the-badge&logo=aws-lambda&logoColor=white" alt="Lambda"/>
  <img src="https://img.shields.io/badge/Tailscale-000000?style=for-the-badge&logo=tailscale&logoColor=white" alt="Tailscale"/>
  <img src="https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"/>
</p>

<p align="center">
  <strong>Voice-control your personal AI assistant through Amazon Alexa</strong>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#usage">Usage</a> •
  <a href="#troubleshooting">Troubleshooting</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"/>
  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node Version"/>
  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"/>
</p>

---

Connect your [OpenClaw](https://openclaw.ai) 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](https://openclaw.ai) installed and configured
- [Tailscale](https://tailscale.com) account with Funnel enabled
- [AWS Account](https://aws.amazon.com) for Lambda deployment
- [Alexa Developer Account](https://developer.amazon.com/alexa)
- Node.js 18+ (Lambda) / Node.js 22+ (OpenClaw)

## Quick Start

### Step 1: Configure OpenClaw Gateway

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

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

### Step 2: Start OpenClaw Gateway

```bash
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

```bash
# 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](https://developer.amazon.com/alexa/console/ask)
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

<details>
<summary><strong>"I'm not quite sure how to help you with that"</strong></summary>

The utterance didn't match a known pattern. Try rephrasing:
- ✅ "tell me about {topic}"
- ✅ "what is {query}"
- ✅ "show me {something}"
- ❌ Single-word queries

</details>

<details>
<summary><strong>Gateway timeout errors</strong></summary>

1. Verify OpenClaw gateway is running:
   ```bash
   openclaw gateway --force
   ```

2. Check Tailscale Funnel status:
   ```bash
   tailscale funnel status
   ```

3. Test the endpoint directly:
   ```bash
   curl https://your-machine.tailnet.ts.net/health
   ```

</details>

<details>
<summary><strong>401 Unauthorized</strong></summary>

- 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

</details>

<details>
<summary><strong>Skill not responding on phone</strong></summary>

- 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

</details>

## 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](LICENSE) file for details.

## Links

- [OpenClaw Documentation](https://docs.openclaw.ai)
- [Tailscale Funnel Guide](https://tailscale.com/kb/1223/funnel/)
- [Alexa Skills Kit Documentation](https://developer.amazon.com/en-US/alexa/alexa-skills-kit)
- [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/)

---

<p align="center">
  Built with <a href="https://openclaw.ai">OpenClaw</a>
</p>