設定リファレンス

@metatell/bot-sdkの接続設定と、公式サンプルで使う環境変数をまとめます。

SDKのオプションとサンプル固有の環境変数は別の設定です。環境変数の名前や読み込み方はアプリケーション側で決められるため、利用するサンプルの.env.exampleも確認してください。

`createMetatellClient`のオプション

import { createMetatellClient } from "@metatell/bot-sdk";

const client = createMetatellClient({
  serverUrl: "wss://metatell.app",
  roomId: "YOUR_ROOM_ID",
  authToken: process.env.METATELL_AUTH_TOKEN,
  username: "GuideBot",
  debug: false,
});

オプション	必須	説明	既定値
`serverUrl`	必須	接続先のWebSocket URLです。	なし
`roomId`	必須	入室するルームのIDです。	なし
`authToken`	任意	入室時に送るOIDCアクセストークンです。	なし
`username`	任意	ルーム内に表示するボット名です。	`MetatellBot`
`avatarId`	任意	使用するアバターのIDです。	組織のアバターから解決
`avatarSrc`	任意	組織アバターを使う場合に送るGLTFのURLです。	なし
`defaultAvatarId`	任意	アバターを解決できない場合に使うIDです。	`default`
`debug`	任意	SDKのデバッグログを有効にします。	`false`

serverUrlまたはroomIdが空の場合、クライアントを作成できません。認証が必要なルームではauthTokenを指定してください。

警告

アクセストークンやAPIキーをソースコードへ直接書かないでください。 .envはバージョン管理から除外し、本番環境ではシークレット管理機能を利用してください。

ルームURLから接続情報を作る

CLIと公式サンプルの多くは、https://metatell.app/<room-id>形式のURLを受け取ります。独自の起動処理を作る場合は、URLからルームIDを取り出し、接続先に対応するWebSocket URLと組み合わせてください。

公式サンプルの環境変数

次の表は、公式リポジトリ内のサンプルで使われる主な環境変数です。すべてのボットへ一括で設定するものではありません。

metatellへの接続

環境変数	使用例	説明
`METATELL_ROOM_URL`	`bt-bot`	入室先のルームURLです。起動引数で渡せるサンプルもあります。
`METATELL_AUTH_TOKEN`	`bt-bot`	認証が必要なルームへ入るためのOIDCアクセストークンです。
`METATELL_USERNAME`	`voice-bot`、`voice-ai-bot`、`speech-to-speech-bot`	ボットの表示名です。
`METATELL_REALTIME_URL`	`bt-bot`など	標準環境以外で音声接続先を明示するときに使うLiveKit URLです。

LLMと外部サービス

環境変数	使用例	説明
`LLM_API_KEY`	`bt-bot`	OpenAI互換チャットAPIのキーです。
`LLM_BASE_URL`	`bt-bot`	OpenAI互換APIまたは中継プロキシのベースURLです。
`LLM_MODEL`	`bt-bot`	利用するモデル名です。
`GEMINI_API_KEY`	`voice-ai-bot`、`speech-to-speech-bot`	Gemini APIのキーです。
`DIFY_API_URL`	`dify-bot`、`speech-to-speech-bot`	Dify APIのベースURLです。
`DIFY_API_KEY`	`dify-bot`、`speech-to-speech-bot`	Dify APIのキーです。
`DIFY_APP_ID`	`dify-bot`、`speech-to-speech-bot`	DifyアプリのIDです。
`GOOGLE_APPLICATION_CREDENTIALS`	`bt-bot`、`speech-to-speech-bot`	Google CloudサービスアカウントJSONのパスです。
`STT_LANGUAGE_CODE`	`bt-bot`	Speech-to-Textの認識言語です。
`TTS_LANGUAGE_CODE`	`bt-bot`	Text-to-Speechの発話言語です。
`TTS_VOICE_NAME`	`bt-bot`	Text-to-Speechで使う音声名です。

運用設定

環境変数	使用例	説明
`OPERATOR_SESSION_IDS`	`bt-bot`	`/killall`を実行できる運営の接続セッションIDをカンマ区切りで指定します。

セッションIDはアカウントIDではなく、接続状況によって変わる可能性があります。値が変わった場合は設定を更新してボットを再起動してください。

createMetatellClientのオプション​

ルームURLから接続情報を作る​

公式サンプルの環境変数​

metatellへの接続​

LLMと外部サービス​

運用設定​