Persona 官方 Elgato Stream Deck 外掛將 外掛 API 對應至實體按鍵，支援一鍵切換模型、啟用場景、套用場景預設、觸發快速鍵、執行自動化流程、開關表情與動作、設定動態文字，以及在舞台上微調虛擬形象的位置與縮放。
外掛與 Web 控制台 基於相同的 API 建構。在桌面應用程式中啟用 API 功能並建立金鑰後即可直接連線。
前置條件
| 項目 | 說明 |
|---|---|
| Stream Deck | 7.1 或更新版本，執行於 macOS 12+ 或 Windows 10+ |
| LAPLACE Persona | 執行中，且已開啟 外掛 API |
| API 金鑰 | 在 設定 → 外掛 API 中產生並取得 |
安裝
點擊上方安裝按鈕即可透過 Stream Deck 應用程式自動安裝；亦可在 Stream Deck 內建的 Marketplace 中搜尋「LAPLACE Persona」安裝。安裝完成後，Stream Deck 動作清單中會新增 LAPLACE Persona 分類。
連線設定
將任意 Persona 動作拖放至按鍵上，在右側屬性面板底部設定連線參數：
| 欄位 | 說明 |
|---|---|
| Persona Address | 留空預設為 127.0.0.1:25034；支援輸入 主機、主機:連接埠 或完整的 ws:// URL |
| API Key | 在 Persona 中產生的 API Key 憑證 |
上述兩個連線參數為全域設定，在任意動作中填寫一次即可套用至所有按鍵動作。
建立連線後，Persona 的 已連線的用戶端 清單中會顯示 Elgato Stream Deck（開發者：LAPLACE）。
若需控制區域網路內其他電腦上的
Persona，須先在目標電腦上開啟允許區域網路存取，並將位址設定為對應的
主機:連接埠。Persona 原生 WebSocket 採用明文 ws:// 通訊（不內建
TLS）；在不可信的網路環境下，建議透過反向代理設定 TLS，並在位址欄填入完整的
wss:// 代理 URL。
動作清單
除 Activate Scene、Apply Preset、Run Automation 以及作用於選定文字圖層的 Set Text 外，其餘動作預設作用於目前場景的 主模型；Trigger Hotkey 動作則直接作用於選定快速鍵所屬的模型。
| 動作 | 功能說明 |
|---|---|
| Switch Model | 將主模型切換為指定模型；若目前場景中無模型，則直接新增該模型 |
| Activate Scene | 載入並套用已儲存的 場景 |
| Apply Preset | 將目前場景的圖層移至已儲存的 場景預設；若目前場景中沒有該預設，按鍵會提示錯誤 |
| Trigger Hotkey | 觸發舞台上指定模型的 快速鍵；下拉選單依模型歸類顯示快速鍵，主模型排在最前；快速鍵歸屬於個別模型 |
| Run Automation | 觸發指定的 自動化 流程，一鍵執行預設的全部操作，無需佔用鍵盤快速鍵 |
| Toggle Expression | 開啟或關閉目前模型的指定 表情 |
| Play Motion | 播放目前模型的指定 動作；若該動作正在播放，再次按下會立即停止 |
| Move Model | 沿指定方向微移模型位置；長按可持續移動 |
| Scale Model | 依指定比例縮放模型尺寸；長按可持續縮放 |
| Reset Transform | 將目前模型的位置、縮放與旋轉重設為初始預設值 |
| Set Text | 更新指定文字圖層的文字內容；預設以暫時（transient）方式顯示，勾選「Save to Scene」則會儲存至場景 |
模型、場景、預設、快速鍵、自動化、表情與動作等下拉選項均即時從執行中的 Persona 取得（預設清單取自目前場景）。屬性面板開啟期間，自動化清單會隨設定變更即時同步，已暫停的自動化以灰色顯示。若尚未連線，下拉選單會顯示目前的連線狀態或錯誤說明，而非空白清單。
Run Automation 適合將複雜的舞台變換整合至單一按鍵：只需在 Persona 中建立自動化流程（無需指派鍵盤快速鍵），即可直接透過 Stream Deck 按鍵觸發。
移動與縮放
移動與縮放動作均支援自訂步進值。長按按鍵會在約 300 毫秒後開始連續觸發（之後每 100 毫秒執行一次）；若執行出錯，連續步進會立即停止並在按鍵上顯示警告圖示。
| 動作 | 參數說明 |
|---|---|
| Move Model | 方向（上、下、左、右）、2D Step（像素）與 3D Step（世界單位） |
| Scale Model | 方向（放大、縮小）與 Factor（縮放係數，預設 1.1） |
2D 與 3D 步進值分別對應 Live2D（螢幕像素空間）與 VRM（世界座標空間），因此單一按鍵動作可同時適用於兩種格式的模型。縮放範圍受應用程式內建的安全界限限制，長按不會超出允許的縮放範圍。若 Factor 小於 1，無論方向為何都會依該比例縮小。
按鍵顯示與回饋
按鍵圖示由 Persona 圖示與對應動作圖示組合而成，動作名稱依 Stream Deck 用戶端的語言環境自動顯示。自訂按鍵標題會顯示在預設圖示上方；若設定了自訂圖片，則會完全取代預設圖示。
操作執行成功時按鍵會短暫顯示勾號，失敗時顯示警告圖示並記錄至外掛日誌。長按連續觸發期間不顯示成功標記，以免畫面頻繁閃爍。
外掛介面目前提供英文與簡體中文兩種語言，跟隨 Stream Deck 應用程式的語言設定；在繁體中文環境下會顯示英文，因此上表採用英文動作名稱。屬性面板中的參數欄位名稱目前均以英文顯示。
最後更新於 2026年11月3日