Mori

DOCS

Providers

Mori 啟動時自動建 ~/.mori/config.json(第一次跑會看到 stub)。 從 Config tab 編,或直接改檔案。下面四種組合任選 — 改完不需要重啟,下一次熱鍵會即時讀新設定。

組合 A — 純雲(預設)

設好 Groq key 就能用。Free tier 涵蓋 Whisper(每天 7,200 秒)+ chat,個人用足夠。

{
  "provider": "groq",
  "stt_provider": "groq",
  "providers": {
    "groq": {
      "api_key": "gsk_...",
      "model": "openai/gpt-oss-120b",
      "stt_model": "whisper-large-v3-turbo"
    }
  }
}

從 console.groq.com → API Keys 拿 key。

組合 A+ — 加 Gemini

Gemini API 走 OpenAI-compat 端點,差別只在 base_url 跟 key。適合丟給「便宜 + 創意寫作 + 翻譯」這類 profile。

{
  "provider": "groq",
  "stt_provider": "groq",
  "api_keys": {
    "GEMINI_API_KEY": "AIza..."
  },
  "providers": {
    "groq":   { "api_key": "gsk_...", "model": "openai/gpt-oss-120b", "stt_model": "whisper-large-v3-turbo" },
    "gemini": { "model": "gemini-3.1-flash-lite-preview" }
  }
}

Profile 寫 provider: gemini 即啟用該模型。Key 從 OS env GEMINI_API_KEY 或 api_keys.GEMINI_API_KEY 取(env 優先)。

組合 B — 100% 本機(離線、不依賴雲)

{
  "provider": "ollama",
  "stt_provider": "whisper-local",
  "providers": {
    "ollama": {
      "base_url": "http://localhost:11434",
      "model":    "qwen3:8b"
    },
    "whisper-local": {
      "model_path":    "/home/<user>/.mori/models/ggml-small.bin",
      "server_binary": "/home/<user>/.mori/bin/whisper-server",
      "language":      "zh"
    }
  }
}

需要先:

• ollama serve + ollama pull qwen3:8b(本機 LLM,支援 tool calling)
• 下載 whisper 模型 + 引擎(Linux 從 Deps tab 一鍵下載;Windows 暫時手動):

  # 模型(.bin)
  mkdir -p ~/.mori/models
  wget -O ~/.mori/models/ggml-small.bin \
    https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin
  
  # 引擎(whisper-server[.exe])— 從 whisper.cpp 官方 release 抓
  # https://github.com/ggml-org/whisper.cpp/releases/latest
  # 解壓後把 whisper-server[.exe] 放到 ~/.mori/bin/

中文模型大小取捨(Intel CPU 實測):base 142MB(快但常分不清同音字)/ small 466MB(夠用)/ medium 1.5GB(更準但慢)。

架構:Mori 不編 whisper.cpp,改 shell-out 子程序

v0.2 之後,Mori 不再 in-process 編 whisper.cpp C++ source 進 binary,改成 spawn 官方 whisper-server 子程序,HTTP POST WAV 給它。 Mori 第一次按 Ctrl+Alt+Space 時 lazy spawn,之後常駐;Mori 結束時 SIGKILL 收尾。

好處:

• 引擎跟模型都可自選 + 隨時換(下一節)
• 不需要 cmake / libclang 才能 build Mori — Linux contributor setup 從 5 min 變 1 min
• 跨平台統一 — Windows / Linux / macOS 用同一條 path
• 引擎 crash 不會帶死 Mori — Mori 抓 exit code 報錯,下次自動重啟 server

替換引擎(GPU 加速 / 自編變體)

whisper.cpp releases 提供多種預編 binary:

替換流程:

1. 從 whisper.cpp release 頁下載你要的變體 zip
2. 解壓後找出 whisper-server(Linux)或 whisper-server.exe(Win)
3. 整套(binary + 相依 .dll / .so)複製到 ~/.mori/bin/(Win 是 %USERPROFILE%\.mori\bin\)
4. (Unix)chmod +x whisper-server
5. 重啟 Mori — 下次 Ctrl+Alt+Space 起來的就是 GPU 版,Mori 程式碼一行都不用改

想同時保留多版本(CPU + GPU 切換)?把 GPU 版放別處,在 config.json 寫絕對路徑:

"providers": {
  "whisper-local": {
    "server_binary": "/opt/whisper-cuda/whisper-server",
    "model_path":    "~/.mori/models/ggml-large-v3-turbo.bin",
    "language":      "zh"
  }
}

替換模型

同檔 .bin 在 Linux / Windows / macOS 通用 — 不依平台。Hugging Face ggerganov/whisper.cpp 有所有 ggml 格式 whisper 模型:

下載任意 .bin 丟 ~/.mori/models/,在 config 把 providers.whisper-local.model_path 指到那個檔即可。

組合 C — Bash CLI proxy(claude / gemini / codex 當 agent)

用 user 自己的 Pro/Max quota,透過 Bash tool 呼叫本機 mori CLI dispatch skill。

{
  "provider": "claude-bash",
  "stt_provider": "whisper-local",
  "providers": {
    "claude-bash": {
      "binary": "claude",
      "model": null,
      "mori_cli_path": null
    },
    "whisper-local": {
      "model_path":    "/home/<user>/.mori/models/ggml-small.bin",
      "server_binary": "/home/<user>/.mori/bin/whisper-server",
      "language":      "zh"
    }
  }
}

需要:

• claude CLI 已用 claude /login 完成 OAuth
• 下載 whisper 模型 + 引擎(同組合 B)
• cargo build -p mori-cli 確保 target/debug/mori 存在

流程:Ctrl+Alt+Space → STT(whisper-local)→ claude-bash 啟動 claude --print 子程序 → claude 看 system prompt 知道有 mori CLI → 透過 Bash tool 跑 mori skill <name> → mori CLI HTTP 到主程式 dispatch skill → 結果回 claude → claude 給最終回應。

類似的還有 gemini-bash / codex-bash,把 "binary" 換成 "gemini" / "codex" 即可。

Codex 在 Windows 注意:@openai/codex npm package 0.7 系列是 @native release(`use-native` 旗標),只有 Linux / macOS native binary,**Windows 不支援會 直接拒絕跑**(`Unsupported platform: win32`)。v0.130+ 改純 JS impl 才跨平台。 npm install -g @openai/codex 後若 codex --version 報錯,升級到 0.130+ 試試。

進階:per-skill provider 路由

agent 跟個別 skill 可走不同 provider 省 Groq TPD:

{
  "provider": "groq",
  "routing": {
    "agent": "groq",
    "skills": {
      "translate": "claude-cli",
      "polish":    "claude-cli",
      "summarize": "claude-cli",
      "compose":   "ollama"
    }
  }
}

沒設 routing 整套退回頂層 provider。

還有 chat-only 變體 gemini-cli / codex-cli — 可用在 routing.skills, 省略 agent 旗標(--yolo / --dangerously-bypass-approvals-and-sandbox), non-TTY 下 tool 執行無法被核准 → 實質純文字 in/out。

{
  "providers": {
    "gemini-cli": { "binary": "gemini" },
    "codex-cli":  { "binary": "codex" }
  }
}

binary 選填,預設靠 PATH 找。

進階:自訂 OpenAI-compat 端點

Azure OpenAI / OpenRouter / 自家代理 / 任意 OpenAI-compat 端點都能掛進 mori 當「具名 provider」用 — 端點細節集中在 ~/.mori/config.json,profile 內 只寫 provider: <custom-name>:

{
  "api_keys": {
    "AZURE_OPENAI_API_KEY": ""
  },
  "providers": {
    "azure-gpt41": {
      "api_base":     "https://your-resource.openai.azure.com/openai/v1",
      "api_key_env":  "AZURE_OPENAI_API_KEY",
      "model":        "gpt-4.1"
    },
    "openrouter-sonnet": {
      "api_base":     "https://openrouter.ai/api/v1",
      "api_key_env":  "OPENROUTER_API_KEY",
      "model":        "anthropic/claude-sonnet-4"
    }
  }
}

規則:

• providers.<name> 內有 api_base → 自動視為 OpenAI-compat, 取代過去 voice profile 內散置的 ZEROTYPE_AIPROMPT_* frontmatter 鍵
• api_key_env 指向 OS env var 名(或 api_keys.<name>); 也可改用 api_key 直接寫死(不建議,key 進 repo 風險)
• 沒設 model → mori warn,call API 多半會被拒
• 失敗(key 缺、api_base 沒填)→ fallback 到 groq + log warn, 讓 user 看見哪段沒填齊

Profile 內怎麼用:

---
provider: azure-gpt41    # 對應上面 providers.azure-gpt41
stt_provider: groq
enable_read: true
---
profile body...

同 mechanism 也能塞進 routing.skills:某個 skill 走 Azure、其他走 Groq:

{
  "routing": {
    "agent": "groq",
    "skills": {
      "polish": "azure-gpt41"
    }
  }
}

進階:語音輸入 cleanup_level

從 tray / UI 切到「輸入模式」後,熱鍵語意變 dictation。Cleanup 三級可挑:

{
  "voice_input": {
    "cleanup_level": "smart"
  },
  "routing": {
    "skills": {
      "voice_input_cleanup": "groq"
    }
  }
}

• cleanup_level: "smart"(預設):LLM 加標點 + 程式 post-process。 Whisper 不出標點,LLM 是必須的;但 prompt 嚴格鎖在「加標點 / 修幻聽 / 切段」不准改詞
• cleanup_level: "minimal":跳 LLM,純程式處理(strip 幻聽 + 半→全形 + normalize)。 ~ms 級延遲、0 token,但沒標點
• cleanup_level: "none":raw whisper 直貼

voice_input_cleanup provider 推薦 groq(gpt-oss-120b 1-2 秒 + 中文標點品質好)。釘 claude-cli 跑 user 自己 quota 也行。

進階:Fallback chain

主 provider 失敗(429 quota / timeout / network / 5xx 都算)時自動切下一個 provider 重試 — opt-in,沒設就維持「error + cancel 該次行為」的安全預設。

{
  "routing": {
    "agent": "groq",
    "fallback_chain": {
      "agent":               ["ollama", "claude-bash"],
      "voice_input_cleanup": ["gemini"]
    }
  }
}

規則:

• Key 是 context 名:目前認得 agent(Agent 模式 LLM call)、voice_input_cleanup(VoiceInput cleanup LLM call)。其他 key 視同沒設(typo 不會 panic)
• Value 是 依序試的 provider list。主失敗 → 試第一個 fallback → 失敗 → 試第二個 → 全失敗才回 error(取最後 attempt 的訊息)
• Provider 名同 routing 規格:built-in(groq / gemini / ollama / claude-bash / claude-cli / gemini-bash / codex-bash / gemini-cli / codex-cli)或 config.json `providers.<name>` 內定的自訂 OpenAI-compat 名
• 觸發條件:任何 provider.chat() 回 Err — quota 429 / timeout / network / 5xx 都吃
• 不觸發:user 按 Ctrl+Alt+Esc 中斷 — 那是 user intent,直接砍整個 pipeline,不會 fallback
• Transparency:fallback 觸發時 ChatPanel 出現一行系統訊息「groq 失敗,自動改用 ollama 重試 — <原因>」;FloatingMori chip 即時改顯示新 provider 名;log 同步寫 warn
• Agent 模式的特殊性:走 option (a)— fallback 觸發後整個 respond_with_mode 在新 provider 從頭重跑(避免 tool_call_id 跨 provider 認不得)。所以 fallback 在 agent 模式只 cover「第一次 LLM call 失敗」場景,multi-turn 中途失敗時 fallback 不會 mid-turn 接續
• Build 失敗的 fallback:啟動時若某個 fallback provider build 失敗(例 ollama 沒裝 binary),warn 後從 chain 拔掉,其他 fallback 仍可用 — 不擋整個 routing build

Key 探測順序

1. OS 環境變數(如 GROQ_API_KEY)
2. ~/.mori/config.json 的 providers.<name>.api_key
3. ~/.mori/config.json 的 api_keys.<NAME>_API_KEY

Profile 層覆蓋

個別 profile 可在 frontmatter 覆寫全域設定:

---
provider: gemini          # 這個 profile 用 gemini,即使全域是 groq
stt_provider: groq        # STT 仍走 groq(覆蓋 whisper-local)
cleanup_level: minimal
enabled_skills: [translate, polish]   # 留空 = 全開
---

profile body 內容(人格 / 行為指示)...