deepclaw-voice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

deepclaw Voice Setup

Deepclaw 语音功能设置

Use this skill when the user wants to call you on the phone, set up voice calling, or talk to OpenClaw via phone.

当用户想要通过电话联系你、设置语音呼叫或通过电话与OpenClaw对话时，可使用本技能。

What This Sets Up

本设置实现的功能

Phone calls to OpenClaw using:

Deepgram Voice Agent API - STT, TTS, turn-taking, barge-in
Twilio - Phone number routing
OpenClaw - Your AI (via chat completions proxy)

通过以下组件实现向OpenClaw的电话呼叫：

Deepgram Voice Agent API - 语音转文字（STT）、文字转语音（TTS）、话轮转换、插话功能
Twilio - 电话号码路由
OpenClaw - 你的AI（通过聊天补全代理）

Setup Process

设置流程

Step 1: Clone the repo

步骤1：克隆仓库

bash

git clone https://github.com/deepgram/deepclaw.git ~/deepclaw
cd ~/deepclaw
pip install -r requirements.txt

bash

git clone https://github.com/deepgram/deepclaw.git ~/deepclaw
cd ~/deepclaw
pip install -r requirements.txt

Step 2: Get Deepgram API Key

步骤2：获取Deepgram API密钥

Go to https://console.deepgram.com/
Sign up (free $200 credit)
API Keys → Create API Key → Name: "deepclaw", Full Access
Copy key immediately

Ask: "What's your Deepgram API key?"

访问https://console.deepgram.com/
注册账号（赠送200美元免费额度）
进入API Keys → Create API Key → 命名为“deepclaw”，选择完全访问权限
立即复制密钥

提示：“请提供你的Deepgram API密钥？”

Step 3: Get Twilio Credentials

步骤3：获取Twilio凭证

Go to https://www.twilio.com/ and sign up
Copy Account SID and Auth Token from dashboard
Phone Numbers → Buy a number with Voice (~$1/month)

Ask: "What's your Twilio phone number, Account SID, and Auth Token?"

访问https://www.twilio.com/并注册账号
从控制台复制Account SID和Auth Token
进入Phone Numbers → Buy a number购买一个带语音功能的号码（约1美元/月）

提示：“请提供你的Twilio电话号码、Account SID和Auth Token？”

Step 4: Get OpenClaw Gateway Token

步骤4：获取OpenClaw网关令牌

Run this to get the token from their OpenClaw config:

bash

grep -A2 '"auth"' ~/.openclaw/openclaw.json | grep token

Or generate a new one:

bash

openssl rand -hex 24

If generating new, tell them to add it to

~/.openclaw/openclaw.json

under

gateway.auth.token

运行以下命令从OpenClaw配置中获取令牌：

bash

grep -A2 '"auth"' ~/.openclaw/openclaw.json | grep token

或者生成新令牌：

bash

openssl rand -hex 24

如果生成新令牌，请告知用户将其添加到

~/.openclaw/openclaw.json

的

gateway.auth.token

字段下。

Step 5: Create .env file

步骤5：创建.env文件

Create

~/deepclaw/.env

with their values:

DEEPGRAM_API_KEY=<their_deepgram_key>
TWILIO_ACCOUNT_SID=<their_sid>
TWILIO_AUTH_TOKEN=<their_token>
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_GATEWAY_TOKEN=<their_gateway_token>

在

~/deepclaw/

目录下创建

.env

文件并填入以下值：

DEEPGRAM_API_KEY=<你的deepgram密钥>
TWILIO_ACCOUNT_SID=<你的sid>
TWILIO_AUTH_TOKEN=<你的token>
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_GATEWAY_TOKEN=<你的网关令牌>

Step 6: Ensure OpenClaw Gateway has chat completions enabled

步骤6：确保OpenClaw网关已启用聊天补全功能

Check their

~/.openclaw/openclaw.json

has:

json

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

If not, add it and restart the gateway:

openclaw daemon restart

检查

~/.openclaw/openclaw.json

文件是否包含以下配置：

json

{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

如果没有，添加该配置并重启网关：

openclaw daemon restart

Step 7: Start ngrok

步骤7：启动ngrok

bash

ngrok http 8000

Note the HTTPS URL (e.g.,

https://abc123.ngrok-free.app

bash

ngrok http 8000

记录HTTPS地址（例如：

https://abc123.ngrok-free.app

）。

Step 8: Configure Twilio Webhook

步骤8：配置Twilio Webhook

https://console.twilio.com/
Phone Numbers → Active Numbers → Click their number
Voice Configuration:
- A Call Comes In: Webhook
- URL:
```
https://<ngrok-url>/twilio/incoming
```
- Method: POST
Save

访问https://console.twilio.com/
进入Phone Numbers → Active Numbers → 点击你的号码
Voice Configuration:
- 来电处理：Webhook
- URL：
```
https://<ngrok地址>/twilio/incoming
```
- 方法：POST
保存设置

Step 9: Start Server

步骤9：启动服务器

bash

cd ~/deepclaw
python -m deepclaw.voice_agent_server

bash

cd ~/deepclaw
python -m deepclaw.voice_agent_server

Step 10: Test

步骤10：测试

Tell them: "Call your Twilio number now!"

Watch the server logs for:

"Connected to Deepgram Voice Agent API"
"Agent settings applied"
"LLM proxy request received"

告知用户：“现在拨打你的Twilio号码！”

查看服务器日志，确认出现以下信息：

"Connected to Deepgram Voice Agent API"
"Agent settings applied"
"LLM proxy request received"

Customizing Voice

自定义语音

Edit

~/deepclaw/deepclaw/voice_agent_server.py

, find

get_agent_config()

, change the

model

speak

python

"speak": {"provider": {"type": "deepgram", "model": "aura-2-orion-en"}},

编辑

~/deepclaw/deepclaw/voice_agent_server.py

，找到

get_agent_config()

函数，修改

speak

中的

model

参数：

python

"speak": {"provider": {"type": "deepgram", "model": "aura-2-orion-en"}},

Voice Options

语音选项

English: thalia (F, default), orion (M), apollo (M), athena (F), luna (F), zeus (M), draco (M, British), pandora (F, British), hyperion (M, Australian)

Spanish: estrella (F, Mexican), javier (M, Mexican), alvaro (M, Spain), celeste (F, Colombian)

German: fabian (M), aurelia (F), lara (F)

French: hector (M), agathe (F)

Italian: cesare (M), livia (F)

Dutch: lars (M), daphne (F)

Japanese: ebisu (M), izanami (F)

Format:

aura-2-<name>-<lang>

(e.g.,

aura-2-estrella-es

)

英语： thalia（女性，默认）、orion（男性）、apollo（男性）、athena（女性）、luna（女性）、zeus（男性）、draco（男性，英式）、pandora（女性，英式）、hyperion（男性，澳式）

西班牙语： estrella（女性，墨西哥）、javier（男性，墨西哥）、alvaro（男性，西班牙）、celeste（女性，哥伦比亚）

德语： fabian（男性）、aurelia（女性）、lara（女性）

法语： hector（男性）、agathe（女性）

意大利语： cesare（男性）、livia（女性）

荷兰语： lars（男性）、daphne（女性）

日语： ebisu（男性）、izanami（女性）

格式：

aura-2-<名称>-<语言代码>

（例如：

aura-2-estrella-es

）

Troubleshooting

故障排除

When something goes wrong, check the server logs first. Here's how to diagnose common issues:

出现问题时，请先查看服务器日志。以下是常见问题的诊断方法：

No server logs when calling

呼叫时无服务器日志

Symptom: You call, phone hangs up, but no logs appear in the server terminal.

Cause: Twilio webhook URL doesn't match your ngrok URL.

Fix:

Check your current ngrok URL in the ngrok terminal
Go to Twilio Console → Phone Numbers → Your Number → Voice Configuration
Make sure the webhook URL matches exactly:
```
https://<your-ngrok-url>/twilio/incoming
```
Save and try again

症状： 拨打电话后，电话挂断，但服务器终端无日志显示。

原因： Twilio Webhook URL与ngrok地址不匹配。

解决方法：

在ngrok终端中查看当前的ngrok地址
进入Twilio控制台 → 电话号码 → 你的号码 → 语音配置

确保Webhook URL完全匹配：

https://<你的ngrok地址>/twilio/incoming

保存设置后重试

"Check your think provider settings" error

出现“Check your think provider settings”错误

Symptom: Call connects, you hear the greeting, then Deepgram says "Check your think provider settings" and hangs up.

Cause: Deepgram can't reach the LLM proxy endpoint, or it's returning an error.

Fix:

Test the proxy endpoint directly:

bash

curl -X POST https://<your-ngrok-url>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"hi"}]}'

If you get
```
401 Unauthorized
```
, the auth is blocking requests. This shouldn't happen with the latest code.
If you get connection refused, the server isn't running or ngrok isn't forwarding.
Check that OpenClaw gateway is running:
```
curl http://127.0.0.1:18789/health
```

症状： 呼叫接通后，你听到问候语，随后Deepgram提示“Check your think provider settings”并挂断电话。

原因： Deepgram无法连接到LLM代理端点，或端点返回错误。

解决方法：

直接测试代理端点：

bash

curl -X POST https://<你的ngrok地址>/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"hi"}]}'

如果返回
```
401 Unauthorized
```
，说明认证阻止了请求。最新代码已修复此问题。
如果返回连接被拒绝，说明服务器未运行或ngrok未转发请求。
检查OpenClaw网关是否运行：
```
curl http://127.0.0.1:18789/health
```

Call works once then hangs up

呼叫可正常工作一次后挂断

Symptom: First exchange works (greeting + one response), then call drops with "FAILED_TO_THINK" in logs.

Cause: SSE stream formatting issue—usually fixed in latest code.

Fix:

Make sure you have the latest code:
```
cd ~/deepclaw && git pull
```
Restart the server

症状： 首次交互正常（问候语+一次响应），随后呼叫中断，日志中显示“FAILED_TO_THINK”。

原因： SSE流格式问题——最新代码通常已修复此问题。

解决方法：

确保使用最新代码：
```
cd ~/deepclaw && git pull
```
重启服务器

Words running together in speech

语音中词语连读

Symptom: TTS says "Whydo you want" instead of "Why do you want"

Cause: Markdown stripping was removing spaces between streaming chunks.

Fix:

Update to latest code:
```
cd ~/deepclaw && git pull
```
Restart the server

症状： TTS将“Why do you want”读成“Whydo you want”

原因： Markdown剥离操作移除了流块之间的空格。

解决方法：

更新到最新代码：
```
cd ~/deepclaw && git pull
```
重启服务器

Inbound calls don't work, but everything else does

呼入呼叫无法工作，但其他功能正常

Symptom: Server responds to curl, ngrok works, but calling from your phone gets immediate disconnect with no logs.

Cause: Your carrier may be blocking calls to the Twilio number, or you're dialing wrong.

Fix:

Verify you're dialing the exact Twilio number (with country code if needed)
Try calling from a different phone

Test with an outbound call from Twilio to you:

python

# Run this in Python with your .env loaded
import requests
requests.post(
    f'https://api.twilio.com/2010-04-01/Accounts/{TWILIO_ACCOUNT_SID}/Calls.json',
    auth=(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN),
    data={
        'To': '+1YOURNUMBER',
        'From': '+1TWILIONUMBER',
        'Url': 'https://<your-ngrok-url>/twilio/incoming'
    }
)

If this works, the issue is your carrier blocking outbound calls to Twilio.

症状： 服务器响应curl请求，ngrok正常工作，但用手机拨打立即挂断且无日志。

原因： 你的运营商可能阻止了向Twilio号码的呼叫，或拨号错误。

解决方法：

确认拨打的是完整的Twilio号码（必要时添加国家代码）
尝试用另一部手机拨打

测试从Twilio向你发起呼出呼叫：

python

# 在加载.env环境变量的Python环境中运行
import requests
requests.post(
    f'https://api.twilio.com/2010-04-01/Accounts/{TWILIO_ACCOUNT_SID}/Calls.json',
    auth=(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN),
    data={
        'To': '+1YOURNUMBER',
        'From': '+1TWILIONUMBER',
        'Url': 'https://<你的ngrok地址>/twilio/incoming'
    }
)

如果此操作有效，说明问题是你的运营商阻止了向Twilio号码的呼出呼叫。

OpenClaw returns errors

OpenClaw返回错误

Symptom: Logs show errors from OpenClaw like "No API key found for provider"

Fix:

Make sure OpenClaw is configured with your Anthropic API key
Run
```
openclaw configure --section model
```
to set it up
Restart OpenClaw gateway:
```
openclaw daemon restart
```

症状： 日志显示OpenClaw返回错误，例如“No API key found for provider”

解决方法：

确保OpenClaw已配置你的Anthropic API密钥
运行
```
openclaw configure --section model
```
进行设置
重启OpenClaw网关：
```
openclaw daemon restart
```

ngrok URL keeps changing

ngrok地址频繁变化

Symptom: Every time you restart ngrok, you get a new URL and have to update Twilio.

Fix: Use a fixed ngrok domain (requires ngrok account):

bash

ngrok http 8000 --domain=your-chosen-name.ngrok-free.app

症状： 每次重启ngrok都会获得新地址，需要重新更新Twilio设置。

解决方法： 使用固定的ngrok域名（需要ngrok账号）：

bash

ngrok http 8000 --domain=your-chosen-name.ngrok-free.app

Still stuck?

仍无法解决？

Check the server logs carefully—they usually tell you what's wrong

Test each component individually:

Server health:
```
curl http://localhost:8000/health
```
ngrok forwarding:
```
curl https://<ngrok-url>/health
```
OpenClaw gateway:
```
curl http://127.0.0.1:18789/health
```

LLM proxy:

curl -X POST https://<ngrok-url>/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}'

Open an issue at https://github.com/deepgram/deepclaw/issues

仔细检查服务器日志——通常会提示问题所在

单独测试每个组件：

服务器健康状态：
```
curl http://localhost:8000/health
```
ngrok转发：
```
curl https://<ngrok地址>/health
```
OpenClaw网关：
```
curl http://127.0.0.1:18789/health
```

LLM代理：

curl -X POST https://<ngrok地址>/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}'

在https://github.com/deepgram/deepclaw/issues提交问题",