文档 · 指南

让 OpenHanako 用任意模型

OpenHanako（HanaAgent）是一款桌面个人 Agent，数据放在 ~/.hanako，或 $HANA_HOME 指定的目录。magpie 在它的供应商里加一个 magpie，再把主 Agent 的聊天模型设成你选的模型，OpenHanako 就能用 DeepSeek、GLM、Kimi、Qwen、Claude 或 ChatGPT 订阅等 magpie 里的任意模型。

接入 OpenHanako

  1. 在 magpie 里添加供应商在 供应商 页添加 API Key，或登录一个订阅。
  2. 先打开一次 OpenHanako它第一次打开时创建 Agent。还没有 Agent 时，magpie 会提示先打开它。
  3. 在 Agent 页给 OpenHanako 选模型选一个 via magpie 的模型，主 Agent 就用它聊天。
终端
magpie hanako deepseek/deepseek-v4-pro

写了哪些内容

终端
~/.hanako/                       （或 $HANA_HOME）
  provider-catalog.json          providers.magpie: 网关的 /v1，
                                 api openai-completions，magpie 的 Key 和模型
  provider-plugins/magpie/...    OpenHanako 挪过去后的同一个供应商
  agents//config.yaml        models.chat: {id, provider: magpie}

magpie 是 OpenHanako 里的一个供应商，id 为 magpie，以 Chat Completions（openai-completions）连到网关的 /v1，模型就是 magpie 的模型目录，带上上下文长度、最大输出、是否能看图和是否会思考。OpenHanako 基于 Pi 的 SDK，思考强度以 reasoning_effort 发出。

magpie 设置的是主 Agent 的 models.chat：user/preferences.json 里的 primaryAgent；没有的话，就是第一个有配置的 Agent，和 OpenHanako 启动时挑的一样。

运行中立即生效

OpenHanako 在运行时，magpie 通过它的本地 API 加供应商、换聊天模型，OpenHanako 保存后立刻重新加载模型，不用重启。没在运行时，magpie 直接写文件，OpenHanako 下次启动时读取。

加密的供应商目录

从 1.0 起，OpenHanako 用存在系统钥匙串里的密钥加密供应商目录，文件变成 HANA-SECRET-1.AES-256-GCM.…，不再是 JSON。magpie 读不了也写不了它，也绝不覆盖它。

供应商的定义在 provider-plugins/magpie 的插件文件里，不在加密目录中，magpie 仍会保持它最新；Key 留在加密目录里。所以加入或去掉 magpie 需要 OpenHanako 正在运行，通过它的 API 来做。没运行时 magpie 会提示：打开 OpenHanako 再试一次。

切回

magpie 第一次接入时记下主 Agent 原来的模型，切回时放回去。如果没有记下的模型，或者那个模型已经没了，就换成 OpenHanako 自己的第一个模型，因为 1.0 起它的 API 不接受没有模型的 Agent。然后去掉 magpie 的供应商。

终端
magpie hanako default

常见问题

OpenHanako 能用 DeepSeek、GLM 或 Kimi 吗？

能。在 magpie 的 Agent 页给 OpenHanako 选一个 via magpie 的模型，magpie 会加上 magpie 供应商，并把主 Agent 的聊天模型设成它。

提示“OpenHanako keeps its providers encrypted”怎么办？

OpenHanako 1.0 起加密了供应商目录，magpie 只能在它运行时通过它的 API 改动。打开 OpenHanako，再试一次。

要重启 OpenHanako 才生效吗？

运行中不用，magpie 走它的本地 API，模型立刻重新加载。没运行时，下次打开就生效。

切回后会回到我原来的模型吗？

会。magpie 记下了原来的模型并放回去；如果那个模型已经没了，就用 OpenHanako 自己的第一个模型。

更多桌面应用用同样的模型：让 DS Bot 用任意模型、让团结 Cowork 用任意模型、让 OpenBot 用任意模型、让 Kun 用任意模型。遇到报错？见 常见错误排查，或到 Discord 提问。