OpenHanako 中文教程：下载安装、模型配置与安全沙盒
OpenHanako 已在官方仓库中以 HanaAgent 名称持续开发。它把记忆、人格、工具、多 Agent、定时任务、插件和桌面工作台放在一个本地应用里；首次运行的重点不是“聊天”，而是把模型、权限和数据目录配置清楚。
1. 下载和启动
官方 release 提供 macOS Apple Silicon / Intel 的 DMG、Windows EXE，以及 Linux AppImage / deb。不要从第三方下载站获取安装包，先打开官方 release 页面确认版本和校验信息。
2. 首次配置
首次启动向导需要选择语言、输入名称、连接模型 provider（API key + base URL），并选择三个用途不同的模型：主对话模型、轻量工具模型、记忆编译和深度分析模型。README 还提到可选择视觉模型，并支持 OpenAI 兼容、Anthropic 风格、OAuth provider 和 Ollama 本地模型。
3. 权限与数据目录
官方 README 描述了应用层 PathGuard 加操作系统沙盒：macOS Seatbelt、Linux Bubblewrap、Windows restricted token。生产数据目录由 HANA_HOME 控制，默认是 ~/.hanako；开发模式默认 ~/.hanako-dev。在允许 Agent 读写文件、执行命令或安装 Skill 前，先在安全设置中确认访问范围。
4. 验证
本轮只做了官方仓库和 release 核对，没有在当前 macOS 工作区安装 GUI。安装后建议依次验证：打开应用；检查模型 provider 的 base URL 和 key 是否生效；创建一个只读工作目录；用一个无敏感信息的文件测试读取、修改和撤销；最后检查 HANA_HOME 下的数据是否按预期写入。
同类对比
相比终端 Agent，OpenHanako 提供桌面工作台、记忆和权限设置；如果更看重脚本化、远程服务器和 CI，终端 Agent 更直接。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
想用桌面界面管理本地 Agent、记忆和 Skill，并希望明确限制文件/命令权限的用户。
采用建议
想用桌面界面管理本地 Agent、记忆和 Skill，并希望明确限制文件/命令权限的用户。采用前需要核对：版本迭代快，预发布功能不应当作稳定承诺。
原教程未展开的系统信息
核心功能
桌面安装包与多平台支持
release 页面提供 macOS、Windows 和 Linux 安装资产，Windows 在 README 中标为 Beta。
技术栈和运行条件
语言
TypeScript/React（官方 README 技术栈）
框架
Electron 42 + React 19 + Hono + better-sqlite3
关键依赖
- 桌面 release
- OpenAI-compatible/Anthropic/OAuth/Ollama provider
- HANA_HOME
运行环境
macOS、Windows Beta、Linux AppImage/deb
核验与使用边界
本轮核验记录
核验方式
official_repo_and_release_checked_not_locally_installed
核验日期
2026-09-22
核验环境
核对官方 README、仓库和 release；未在当前 macOS 工作区安装 GUI
本轮记录到的结果
release 页面显示 v0.450.0 为 Pre-release、v0.449.0 为 Latest；README 给出 HANA_HOME、provider 和平台沙盒说明
未覆盖范围
未验证安装包启动、OAuth、真实模型调用或跨平台差异
排错时先核对版本、运行环境和未覆盖范围。这里没有执行过的步骤不会写成实测结论。
常见问题
OpenHanako 现在叫什么？
官方仓库 README 的产品名是 HanaAgent，仓库 URL 仍是 liliMozi/openhanako。
v0.450.0 能直接用吗？
v0.450.0 在 release 页面标记为 Pre-release；普通用户优先确认 Latest 版本和对应说明。
支持哪些模型？
README 提到 OpenAI 兼容、Anthropic 风格、OAuth provider 和 Ollama；实际可用性取决于版本和 provider 配置。
数据存在哪里？
默认 HANA_HOME 是 ~/.hanako，开发模式是 ~/.hanako-dev；可以在启动环境中显式设置。
能让 Agent 执行命令吗？
项目支持终端和工具调用，但应先设置沙盒和工作目录权限，再用无敏感数据的测试任务验证。