ドキュメント · ガイド

OpenHanako を任意のモデルで

OpenHanako（HanaAgent）はデスクトップの個人エージェントで、データを ~/.hanako、または $HANA_HOME のフォルダーに置きます。magpie がそこに magpie というプロバイダーを加え、選んだモデルをプライマリエージェントのチャットモデルにすると、OpenHanako が DeepSeek、GLM、Kimi、Qwen、Claude、ChatGPT サブスクリプションなど magpie の任意のモデルで動きます。

OpenHanako の設定

  1. magpie にプロバイダーを追加プロバイダー ページで API キーを追加するか、サブスクリプションにサインインします。
  2. OpenHanako を一度開く初回に起動したときにエージェントが作られます。まだないうちは、magpie が先に開くよう案内します。
  3. エージェント ページで OpenHanako のモデルを選ぶvia magpie のモデルを選ぶと、プライマリエージェントがそのモデルで話します。
ターミナル
magpie hanako deepseek/deepseek-v4-pro

書き込まれる内容

ターミナル
~/.hanako/                       （または $HANA_HOME）
  provider-catalog.json          providers.magpie: ゲートウェイの /v1、
                                 api openai-completions、magpie のキーとモデル
  provider-plugins/magpie/...    OpenHanako が移した後の同じプロバイダー
  agents//config.yaml        models.chat: {id, provider: magpie}

magpie は OpenHanako のプロバイダーの一つ magpie として、ゲートウェイの /v1 に Chat Completions（openai-completions）で話し、モデルは magpie のカタログです。各モデルにコンテキスト長、最大出力、画像と推論の対応が付きます。OpenHanako は Pi の SDK で動くので、推論の強さは reasoning_effort で送られます。

設定するのはプライマリエージェントの models.chat です：user/preferences.json の primaryAgent、なければ設定を持つ最初のエージェントで、OpenHanako の起動時の選び方と同じです。

起動中の変更

OpenHanako の起動中は、magpie がそのローカル API でプロバイダーを加えチャットモデルを替えます。OpenHanako は保存してすぐモデルを読み直すので、再起動は要りません。起動していないときは magpie がファイルに書き、次の起動時に読まれます。

暗号化されたカタログ

1.0 から OpenHanako は、システムのキーチェーンにある鍵でプロバイダーカタログを暗号化します。ファイルは JSON ではなく HANA-SECRET-1.AES-256-GCM.… になり、magpie は読むことも書くこともできず、上書きもしません。

プロバイダーの定義は provider-plugins/magpie のプラグインファイルにあってカタログの外なので、magpie はそれを最新に保ちます。キーは暗号化されたままです。magpie を加える・外すには OpenHanako が起動している必要があり、API を通して行います。起動していないときは、OpenHanako を開いてもう一度試すよう magpie が伝えます。

元に戻す

magpie は最初に入るときプライマリエージェントのモデルを控え、外れるときに戻します。控えがない、または OpenHanako にそのモデルがもうないときは、OpenHanako 自身の最初のモデルにします。1.0 から API はモデルのないエージェントを受け付けないためです。そのあと magpie のプロバイダーを外します。

ターミナル
magpie hanako default

よくある質問

OpenHanako で DeepSeek、GLM、Kimi を使えますか？

使えます。magpie のエージェントページで OpenHanako に via magpie のモデルを選ぶと、magpie のプロバイダーが加わり、プライマリエージェントのチャットモデルになります。

「OpenHanako keeps its providers encrypted」と出ます。

1.0 から OpenHanako はカタログを暗号化しているので、magpie は起動中に API を通してしか変えられません。OpenHanako を開いてもう一度試してください。

反映に再起動は要りますか？

起動中は要りません。magpie がローカル API を通し、モデルはすぐ読み直されます。起動していなければ、次に開いたときに反映されます。

元に戻すと前のモデルに戻りますか？

戻ります。magpie が控えたモデルを戻します。OpenHanako にもうなければ、OpenHanako 自身の最初のモデルになります。

同じモデルを他のデスクトップアプリでも：DS Bot を任意のモデルで、Tuanjie Cowork を任意のモデルで、OpenBot を任意のモデルで、Kun を任意のモデルで。エラーが出るときは よくあるエラーの直し方、または Discord で質問してください。