OpenClaw Alexa Skill
Voice-control your personal AI assistant through Amazon Alexa
Features •
Architecture •
Quick Start •
Usage •
Troubleshooting
---
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
"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:
```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
```
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](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/)
---
Built with OpenClaw