Docker Compose上で動かしているOpenClawに、Telegramから音声メッセージを送ってみました。
すると「音声を処理できません」という返答が返ってきました。
設定さえすれば動くはずなのに、なぜ？という疑問がきっかけです。
調べてみると、音声文字起こし機能の有効化には単純な設定追加だけでなく、
ツール独自のauthプロファイル管理への登録も必要でした。
あわせてAIモデルの動的切り替え機能も追加したので、その手順をまとめます。
こんな人におすすめ
- Docker Compose上でTelegramボットを運用している方
- Telegramの音声メッセージをAIに処理させたい方
- コンテナ再起動なしでAIモデルを切り替えたい方
- 「環境変数を設定したのに反映されない」と悩んでいる方
音声処理の流れ
設定後の動作を先に整理しておきます。
sequenceDiagram
participant U as ユーザー（Telegram）
participant B as OpenClaw
participant W as OpenAI Whisper
participant AI as AIモデル
U->>B: 音声メッセージ（.ogg）
B->>W: 音声文字起こしリクエスト
W-->>B: テキスト化結果
B->>AI: テキストで質問
AI-->>B: 回答
B-->>U: テキスト返答
目次
要件
- Telegramの音声メッセージ（.ogg）をOpenAI Whisper APIで文字起こしする
- コンテナ再起動なしでAIモデル（GLM 4.7 / Gemini 3 Flash）を切り替えられるようにする
makeコマンドで簡単に操作できるようにする
実装方針
1. 音声文字起こし設定
設定ファイルの tools セクションに media.audio を追加します。
"media": {
"audio": {
"enabled": true,
"maxBytes": 20971520,
"maxChars": 10000,
"timeoutSeconds": 120,
"models": [
{
"provider": "openai",
"model": "gpt-4o-mini-transcribe",
"language": "ja"
}
]
}
}
2. OpenAI authプロファイル登録
設定ファイルだけでなく、ツール独自のauthプロファイルにもOpenAIを登録する必要がありました。
- 設定ファイルの
auth.profilesにopenai:defaultを追加 - authプロファイル設定ファイルに実際のAPIキーを含むプロファイルを追加
環境変数 OPENAI_API_KEY だけでは不十分で、ツール独自のauth管理への登録が必要でした。
3. AIモデル動的切り替え
docker-compose.yml の環境変数はツールの設定ファイルを直接上書きしません。
CLIの models set コマンドで切り替える必要があります。
entrypoint.shに起動時の自動適用処理を追加- Makefileに
make model-glm/make model-geminiを追加（再起動不要で即時切り替え）
ポイント
- authプロファイルは2箇所に登録が必要: 設定ファイル（参照）とauthプロファイルファイル（実体）
- 環境変数はそのままでは反映されない:
entrypoint.shでモデル切替コマンドを呼ぶ必要があります - セッションロック問題: コンテナ再起動後に
.lockファイルが残ると「session file locked」エラーが発生します。手動でrm ~/.bot/agents/main/sessions/*.lockが必要です - コスト:
gpt-4o-mini-transcribeは約$0.006/分、月10回×30秒で約$0.90/月
学び
- ツールは環境変数よりも自身の設定ファイルを優先する設計です。Dockerの環境変数で制御するにはentrypointでのブリッジ処理が必要です
- 音声文字起こし機能は設定ファイルの追加だけでなく、authプロファイルの登録が不可欠です。エラーログに出ないため原因特定が難しいです
- Makefileにモデル切り替えコマンドを用意しておくと運用が楽になります
まとめ
今回の設定で得られた効果を整理します。
- 音声→テキスト変換が自動化: Telegramから音声メッセージを送るだけで、AIが内容を理解して回答できるようになりました
- コスト予測が立てやすい:
gpt-4o-mini-transcribeは約$0.006/分と低コストで、月$1未満の運用が現実的です - モデル切り替えが簡単に:
make model-gemini一発でコンテナ再起動なしに切り替えられるようになりました
特に「環境変数を設定したのに反映されない」という問題は、ツール独自の設定管理の仕組みを理解することで解決できました。
同じような構成でBotを運用している方の参考になれば幸いです。
