一份面向个人使用者的实践手册：从第一次配置，到把自己的 Agent 调成稳定、可靠、真正能协作的长期搭子。
OpenHanako 是项目仓库名，软件界面当前通常称为 HanaAgent。功能会随版本、模型 Provider、已安装插件和系统权限而变化；本文把已核实的能力按“可直接使用、需要配置、实验性”分开说明。
- 0. 先建立一张功能地图
- 1. 第一次用：先把地基搭稳
- 2. 调教 Agent：让它越来越趁手
- 3. 做真实工作：文件、任务和交付标准
- 4. Skills、插件与 MCP：把能力装成工具箱
- 5. 自动化、Bridge 与远程访问
- 6. 源码里挖到的隐藏与进阶能力
- 7. 安全边界与每周维护
- 8. 一条推荐学习路径
- 9. 界面、数据与个性化
- 10. 常见问题与排障
HanaAgent 不只是聊天窗口。把它看成六个彼此配合的抽屉，会更容易上手。
| 抽屉 | 解决什么问题 | 常用入口 |
|---|---|---|
| 对话与模型 | 聊天、附件、网页、思考深度、视觉理解 | 输入框、设置 → 供应商 |
| Agent 与记忆 | 人格、长期事实、经验、多个助手分工 | 设置 → 助手 |
| 书桌与文件 | 工作目录、文件预览、编辑、便笺 | 右侧书桌、设置 → 工作台 |
| Skills 与插件 | 专项流程、外部能力、工具扩展 | 设置 → 技能 / 插件 / 连接器 |
| 自动化与远程 | 定时任务、巡检、手机和社交平台 | Automation、设置 → 社交平台 / 访问 |
| 权限与安全 | 只读、询问、操作、沙箱、备份 | 输入框访问模式、设置 → 安全 |
flowchart TB
A[你的真实目标] --> B[你的 Agent / HanaAgent]
B --> C[人格与记忆]
B --> D[工作台与文件]
B --> E[Skills / 插件 / MCP]
B --> F[自动化与远程]
C --> G[稳定协作与可验证交付]
D --> G
E --> G
F --> G
最重要的一句：
人设决定她像谁，记忆决定她记得什么，技能决定她会怎么做，当前任务决定这一次交付什么。
第一次启动时，跟着欢迎向导完成四件事：选择语言、填写显示名称、连接模型 Provider、为当前 Agent 选择聊天模型。Provider 可以是 API Key + Base URL、OAuth 账号、本地 Ollama 或其他已支持的接入方式，具体选项以当前版本设置页为准。
三个“模型设置”容易混淆：
| 位置 | 影响范围 | 适合什么 |
|---|---|---|
| 设置 → 供应商 | 全局可用 Provider、实用模型和视觉模型 | 接入或调整模型来源 |
| 设置 → 助手 | 某个 Agent 的默认聊天模型 | 让不同 Agent 长期使用不同主力模型 |
| 输入框模型胶囊 | 当前会话的临时选择 | 临时比较模型，不改写该 Agent 的长期默认值 |
先确认当前 Agent 真的有可用聊天模型，再继续配置实用模型和视觉模型。只填了 Provider 并不等于每个 Agent 已经选好主模型。
HanaAgent 会把不同类型的工作交给不同模型。不要把它们全当成同一件事。
| 模型 | 负责什么 | 配置建议 |
|---|---|---|
| 聊天模型 | 主对话、分析、写作、调用工具 | 选择你最信任的主力模型 |
| 轻量实用模型 | 摘要、分类、轻量后台任务 | 优先速度与成本平衡 |
| 重型实用模型 | 记忆编译、深度处理 | 优先稳定性和推理质量 |
| 视觉模型 | 图片、截图、图片附件的理解 | 必须是真正支持图片输入的模型 |
视觉模型相关问题最常见的原因有两个：模型卡片里“视觉/支持图片”能力被误关，或设置 → 供应商里的辅助视觉开关没有打开。
flowchart TB
A[收到任务] --> B{按任务类型分工}
B --> C[聊天模型：主对话、分析、写作]
B --> D[轻量实用模型：摘要、分类、轻任务]
B --> E[重型实用模型：记忆编译、深度处理]
B --> F[视觉模型：图片、截图、附件理解]
C --> G[可验证的任务交付]
D --> G
E --> G
F --> G
在欢迎页或 设置 → 工作台 为当前 Agent 设置工作目录。这是她的书桌。
把资料、项目和输出分开会明显减少混乱：
我的工作台/
├─ inbox/ 收到但尚未处理的资料
├─ current/ 当前项目
├─ outputs/ Agent 生成的成品
└─ 00-工作约定.md 固定规则与项目入口
把文件拖进聊天区，比复制粘贴正文更可靠。Agent 也可以在书桌里预览 Markdown、代码、CSV、HTML、图表和媒体文件。
上图为 HanaAgent 官方公开主界面截图，便于将本手册中的“会话、书桌、文件和设置”入口对应到实际界面。
第一次不必挑战复杂项目。给她一个小而完整的任务：
读取工作台里的这份文档。
先用只读方式给我一页结构化摘要，标出不确定的地方。
确认后，再把摘要保存为 Markdown 到 outputs 文件夹。
这一次会同时验证：模型、文件范围、预览面板、访问模式和写入权限。
| 控制项 | 什么时候用 | 注意点 |
|---|---|---|
| 思考深度 | 日常用低/中；复杂决策、研究、排错再提高 | 越高越慢，模型不支持时不会真的生效 |
| 访问模式 | 分析用只读；准备改文件用询问；边界清楚且愿意直接执行再用操作 | 只读 禁止可变更工具；询问 会在高风险动作前请求确认；操作 可直接执行已获准的可变更工具。它控制本次会话，不是永久权限 |
| 上下文管理 | 一个项目尽量维持同一会话；彻底换题用 /new |
很长时用 /compact 保留重点并节省上下文 |
常用斜杠命令：
/new：新建会话。/compact：压缩当前长会话，保留重点。/diary：将当前对话存成日记。/xing：从成功流程中提炼可复用经验或工作流。/stop：停止当前回复。/reset：重置当前会话，谨慎使用。
- 换行：输入框里用
Shift + Enter换行，避免误发送。 - 插话（Steer）：回复还在生成时可直接发补充指令，适合纠正方向或补材料。
- 消息操作：可选择、复制多条消息，必要时生成聊天截图；媒体可进入全屏查看器，支持缩放、拖拽和相邻媒体切换。
- 上下文圆环：输入框旁的圆环显示本会话上下文占用。它接近上限时会变色，点击后可快速进入压缩相关操作。
在 设置 → 助手 创建 Agent 后，每个 Agent 都有独立的人设、记忆、经验、工作文件夹和会话历史；可在欢迎界面的 Agent 芯片组或设置中切换。创建时先选 Yuan，再写 ishiki，最后按需要启用记忆、经验与技能。
常用 Yuan 的定位：
| Yuan | 侧重 | 适合什么 |
|---|---|---|
| Hanako | 感性与理性均衡 | 日常长期协作 |
| Butter | 直觉、共情与创意 | 情感交流、创意讨论 |
| Ming | 前提、推理与行动 | 复杂分析、决策和排错 |
| Kong | 少额外人格框架 | 纯工具型任务 |
Yuan 决定“怎么想”，不替代 ishiki 里的身份和行为规则。
| 层 | 放什么 | 不该放什么 |
|---|---|---|
| Yuan | 思考方式：均衡、感性、理性或原始模型风格 | 临时任务和个人资料 |
ishiki.md |
身份、语气、价值排序、行为边界 | 今天的计划、项目全文 |
| 记忆与置顶 | 稳定偏好、长期目标、身份背景 | 一时情绪、临时待办 |
| Experience / Skill | 重复任务的工作方法、纠错经验 | 每次都不同的具体内容 |
Yuan 决定她怎么想，ishiki 决定她是谁。两者不要混在一起。
flowchart TB
A[Yuan：思考方式与人格底座] --> B[ishiki.md：身份、语气、价值与边界]
B --> C[记忆与置顶：稳定偏好和长期事实]
C --> D[Experience / Skill：重复任务的方法与纠错]
E[当前任务：目标、材料、交付、边界] --> F[本次协作行为]
A --> F
B --> F
C --> F
D --> F
下面的内容可以作为长期协作助手的起点，再按个人习惯精简。
你是一个长期协作 Agent。
优先目标：
1. 把模糊想法变成可执行的下一步。
2. 在学习、写作、整理与决策中保持事实、逻辑和节奏。
3. 发现风险、遗漏或矛盾时，直接说明原因。
回复方式：
- 先回答核心，再给必要依据。
- 信息不足时，说明缺什么，并给出可选方向。
- 复杂任务先确认目标、范围、交付物与限制。
- 区分事实、推测和建议。
- 默认简洁；需要展开时再系统说明。
工作边界：
- 涉及文件、命令、安装或外部发布前，先说明影响范围。
- 已有规则互相冲突时，指出冲突，不要静默猜测。人设写得太长常会让回答变得“像角色但不够会做事”。只保留真正会改变行为的规则。
适合置顶的内容：
- “沟通偏好：结论先行，发现问题请直接指出。”
- “长期目标：某项资格考试，知识题按考试框架定位。”
- “时间规则：每天从约定时刻开始计算。”
- “写作偏好：保留叙事感，少用模板腔。”
不适合置顶的内容：
- 今天临时要完成的任务。
- 尚未确定的计划。
- 一次情绪里的自我评价。
- 大段资料原文和项目全文。
每月做一次记忆体检：让 Agent 列出它认为与你有关的长期记忆，你逐条确认、修改或删除。
记忆不是只有一张“长期资料表”。它通常由当前对话、滚动摘要、日/周编译、长期记忆、事实库和置顶记忆共同组成；其中置顶记忆适合稳定且明确的信息。
在 设置 → 助手 可以查看长期记忆、事实库与编译内容，并按 Agent 管理、导入、导出或清空记忆。清空是高影响动作，应该先确认范围。对话里明确说“记住：……”也可以让 Agent 将信息作为置顶记忆处理。
若记忆开关不可用或长期信息始终不生效，先检查实用模型是否已经配置。记忆编译依赖实用模型；新建会话本身是空白的，但仍可能加载已确认的长期记忆。
- Experience：适合保存“以后遇到这类情况怎么做”。
- Skill：适合保存“什么时候触发、固定步骤是什么、输出长什么样、如何核验”。
/xing：适合把刚刚完成的一套成功流程提炼出来。
一个好 Skill 只做一件事，例如“论文精读”“错题复盘”“章节自检”“数据清洗”。
安装 Skill 后，别忘了到 设置 → 技能 → Agent 技能开关 为指定 Agent 启用。全局安装不等于每个 Agent 自动拥有。
Experience 可在 设置 → 助手 → 经验 暂停或恢复。它记录的是工作方法与纠错习惯，不应替代长期事实记忆。
Skill 可能来自内置目录、用户安装包、Agent 自学产物或兼容目录。兼容目录通常包括 .claude/skills、.codex/skills、.openclaw/skills、.agents/skills 等，具体发现结果以设置 → 技能的兼容技能页为准。
- 输入框中的技能徽章可显式要求本次消息使用某个 Skill。
- 新建 Agent 通常继承当时已安装的用户 Skill 快照；后续仍可按 Agent 单独开关。
- 自学 Skill 归创建它的 Agent 所有，迁移或共享前应检查内容是否含私有规则、路径或凭证。
高质量任务通常包含四件事：目标、材料、交付、边界。
flowchart LR
A[目标] --> E[执行任务]
B[材料] --> E
C[交付物] --> E
D[权限与边界] --> E
E --> F[验证动作]
F --> G[可检查的成品]
目标：你希望解决什么问题。
材料：文件、链接、背景和已有草稿在哪里。
交付：格式、长度、引用方式、判断标准。
边界：先只读还是直接编辑，能否联网，哪些动作必须先问。
例子：
阅读工作台里的三篇 PDF。
目标：提取与“指定研究主题”直接相关的方法和结论。
交付：一页结构化笔记；每条结论标来源页码；再列出 3 个待核验问题。
边界：先只读分析，不修改文件；不确定处标为“待核验”。
flowchart LR
A[工作文件夹 / 附件] --> B[只读诊断]
B --> C[计划与影响范围]
C --> D{确认后再动手}
D --> E[编辑、运行或生成文件]
E --> F[验证结果与剩余风险]
F --> G[交付到约定输出目录]
- 先让她诊断或阅读。
- 让她给出计划和影响范围。
- 你确认后，再让她编辑、运行命令或生成文件。
- 最后要求她说明验证动作和剩余风险。
对重要项目，开启 设置 → 安全 → 文件备份。沙箱控制“能接触哪些文件”，访问模式控制“这次会话能不能动手”，两层一起使用才稳。
- 浏览文件：书桌支持面包屑导航，并可按名称、修改时间或大小排序；
Ctrl/Cmd + 点击多选，Shift + 点击选范围，也可框选。 - 拖拽附加：把书桌文件拖进聊天区，通常比复制粘贴正文更可靠。
- 文本便笺：选中文本文件后可在右侧编辑器直接修改并自动保存；Markdown 支持预览，重要修改可结合安全设置里的 checkpoint/备份恢复。
- 预览面板：Markdown、代码、CSV、HTML、图表可在 Tab 之间切换；可全屏、复制、下载或打开只读查看窗口。选中文本可引用回输入框继续追问。
- 媒体：图片、SVG、视频优先走全屏媒体查看器，不必整张塞进聊天记录。
- 技能快捷栏：书桌底部会显示当前工作目录可用的 Skills，可快速启用或禁用；它不替代 Agent 技能开关的权限控制。
工作台设置有两层：全局层控制巡检总开关和定时任务是否自动批准；每个 Agent 则有自己的工作文件夹、巡检开关与巡检间隔。切换 Agent 时，你看到的是对应 Agent 的书桌和巡检范围，不是所有 Agent 共用一个目录。
| 类型 | 本质 | 适合什么 |
|---|---|---|
| Skill | Markdown 形式的知识与操作流程 | 论文阅读、错题整理、写作审稿、学习计划 |
| Plugin | 可带来工具、命令、页面、Provider 和后台任务的扩展 | 真正新增功能或界面 |
| MCP | 把外部服务接进 Hana 的标准连接器 | 数据库、知识库、第三方 API |
Plugin 分为 Restricted 和 Full-access。后者可以注册更深层能力，安装前要认真看权限。
flowchart TB
A[任务缺少某种能力] --> B{先判断缺什么}
B --> C[Skill：需要稳定流程或知识]
B --> D[Plugin：需要新工具、页面或 Provider]
B --> E[MCP：需要接入外部服务]
C --> F[为指定 Agent 启用]
D --> G[审查权限后安装]
E --> H[按需配置连接器与工具范围]
- Restricted 插件适合提供 Skills、工具和命令；Full-access 才能注册路由、Provider、页面、侧栏 Widget 等更深层能力。
- 插件可以在聊天中返回交互卡片；重新打开历史会话时，卡片会按可用能力回放。
- 安装、启用或 reload 后，空闲会话会重新绑定插件事件；正在回复或切换中的会话通常会在下一次安全重建后生效。
HanaAgent 有隐藏打包的 Office 工具，可通过 Agent 工具开关管理。
可读取：
.docx、.xlsx、.xlsm、.pdf.txt、.md、.csv、.tsv、.html
可转换：
- Word 转 HTML。
- Excel 转 JSON。
- PDF 按页范围续读。
- 静态 HTML 通过桌面 Chromium 打印引擎导出 PDF。
当前限制：
- 不支持
.doc、.xls、.ppt、.pptx。 - 扫描型 PDF 没有 OCR。
- 内置工具暂不编辑 Office/PDF 文件。
这不等于所有文件都只能只读：书桌里的文本和 Markdown 便笺可在编辑器中直接修改；Office/PDF 的读取限制是另一件事。
Beautify 也是内置系统插件，可以：
- 为 Markdown 文章提供封面风格规范。
- 将已有或生成的图片写入 Markdown frontmatter，作为 Notion 风格封面。
- 在生成整页 HTML 前提供颜色、排版、布局、组件、图像、动效等设计规范。
适合把“写一篇文章”做成“有统一视觉风格、可预览、可导出的文档”。
在 设置 → 多媒体 配好 Provider 和默认模型后，可以使用：
- 文生图。
- 图生图或图片换风格。
- 多张参考图融合。
- 文生视频。
- 图生视频。
- 语音条转录。
媒体生成是异步任务，提交后结果会自动进入统一的 SessionFile 文件流，可在桌面预览，并按各 Bridge 平台的文件能力投递。普通使用不必强行指定 Provider/模型，默认配置会自动选择；需要高级参数时再查询具体 Provider 的能力。
语音条转录 和 语音合成 是两项不同能力：前者可将语音条转成文本；后者目前仍是“coming soon”，不要当成已完成能力。
MCP 是将外部系统接入 Agent 的标准协议。HanaAgent 可以在设置中按需配置连接器；具体有哪些工具，取决于你主动接入的服务和对应权限，不是初始安装时默认拥有的能力。
- 本地连接器 通过命令启动本机 MCP 程序；远程连接器 通过 URL 接入在线服务。
- 远程服务可能使用 OAuth 或 Bearer Token 授权；连接意外断开时，系统可尝试自动重连。
- 设置 → 连接器可查看连接状态、代理诊断与连接器总开关；总开关关闭后，新会话不再加载连接器工具。
- 连接器启用和连接器内部工具的启用是两层控制，且可按 Agent 限制范围。
建议让每个 Agent 只启用完成当前任务所需的连接器和工具。先用只读权限验证，再按需要放开写入或执行能力；连接密钥、服务地址和任何专属配置都不要写进公开提示词、共享 Skill 或文档。
flowchart TB
A[HanaAgent Server：会话、Agent、文件与访问控制] --> B[本机桌面]
A --> C[手机 PWA / LAN 前端]
A --> D[Bridge：微信、QQ、飞书、Telegram]
B --> E[工作台与本地文件]
C --> F[设备密钥与可撤销访问]
D --> G[Owner 身份与远程接管]
你可以让 HanaAgent：
- 定时执行一个明确任务。
- 定期检查书桌工作目录的新增文件或变化。
- 在任务完成或出现异常时发通知。
好的自动化具备三个条件：频率明确、输入范围明确、输出位置明确。
每天 22:30 检查工作台 inbox 文件夹。
若有新 PDF，生成文件清单和一行摘要，保存到 outputs/daily-index.md。
只读分析，不移动、不删除原文件。
不要把“每天帮我想想”这类边界模糊的话直接变成无人监督的定时任务。
Automation 面板可查看、启用、暂停或删除定时任务。巡检按 Agent 的工作文件夹运行，间隔可在工作台中调整（当前常见范围为 1–120 分钟）；全局层还可控制巡检总开关与定时任务是否自动批准。暂停某个任务不等于删除它，删除前先确认是否仍有依赖输出。
Bridge 让你在手机上继续和 Agent 对话，但必须先处理 Owner。
| 身份 | 能力 |
|---|---|
| Owner | 完整人设、记忆、工具和深度思考 |
| 访客 | 默认没有文件工具、记忆和私有人设 |
除微信私人通道的特殊规则外，其他平台没有设置 Owner 时，收到的消息会被按访客处理。Bridge 的配置入口在 设置 → 社交平台；可按平台配置凭证、Owner、回复前提示、只读模式和对外 public ishiki。
Owner 不等于无限权限。 Owner 解决的是身份识别、访客隔离与完整人格/记忆的可用性；它仍受 Bridge 全局只读模式、当前会话访问模式、工作台文件范围、沙箱和平台文件能力限制。微信 iLink 私人通道的私聊有自动识别 Owner 的例外；若仍无法读写文件，应继续检查只读模式、会话访问模式与工作台范围。
远程接管桌面会话：
/rc：列出最近桌面会话，选择后接管。/exitrc：退出接管。- 接管期间，
/new和/reset会被拒绝，避免误删桌面历史。
在 设置 → 访问 可以：
- 从本机回环访问切换到 LAN 监听。
- 生成手机 PWA 的地址、二维码和设备密钥。
- 生成另一台桌面前端的凭证。
- 撤销某台设备或某个密钥。
- 连接远端 HanaAgent Server 并切换客户端。
这不是公网穿透功能。只在可信局域网开启，并为每台设备单独发放可撤销凭证。
频道是多个 Agent 与用户的群聊空间，适合让不同角色交叉讨论同一个问题。可在侧栏频道 Tab 创建：
- DM：两个参与者之间的私聊。
- Group：多个 Agent 和用户参与的群组。
频道是 Beta，首次启用会有确认提示。它适合多视角讨论，不应代替明确任务的主会话和最终交付链路。
以下内容来自当前 OpenHanako 主分支源码审计。它们并非“神秘 Skill 库”，更多是默认不突出、需要开关或只在特定入口可见的能力。
状态：需要主动启用。
入口：设置 → 助手 → 工具 → Workflow。
它让主 Agent 以受限脚本编排多个隔离子任务，支持：
- 并行检索与交叉核验。
- 流水线处理与循环处理。
- 为子节点指定模型、Agent 类型、只读/写入权限。
- Token 预算、并发上限、重试、节点/全局超时。
- 失败后按运行 ID 断点续跑，已完成节点可复用缓存。
flowchart LR
A[主 Agent：拆分目标与预算] --> B[资料检索：只读]
A --> C[反例检查：只读]
A --> D[结论整理：只读或受限写入]
B --> E[整合与分歧说明]
C --> E
D --> E
E --> F[可验证的最终交付]
它默认关闭是合理的：一次工作流可能并行启动多个 Agent，成本和工具调用量都会上升；写入节点必须指定受限的可写目录。
可以这样对 Agent 说：
把这件事拆成三个只读子任务：资料检索、反例检查、结论整合。
用 Workflow 并行完成，最后给我一份带分歧说明的结论。
状态：可用，按 Agent 工具管理。
Agent 可以列出、搜索、读取其他会话的摘要或精简记录，也可以为其他会话生成消息草稿、为指定 Agent 创建新会话。
关键安全设计：发送和创建不会直接执行，而是先生成一张可编辑、可确认、可拒绝的草稿卡。只有你确认后，才真正投递。
状态：已配置 Owner 的 Bridge 私聊可用。
普通 /compact 主要压缩上下文；/fresh-compact 会在压缩前额外刷新：
- 当前人设/系统提示词快照。
- 记忆状态。
- 当前可用工具快照。
刚改完 ishiki、技能、工具开关或重要记忆后，用它可以让较长的远程会话重新接上最新配置。
Bridge 中还可见：/apply、/confirm、/reject、/stop、/new、/reset 等命令，具体可用性取决于当前平台、Owner 和会话状态。
| 能力 | 状态 | 建议 |
|---|---|---|
| 上下文压缩模式 | Beta，低风险，立即生效 | 默认保持 auto；只有特定模型压缩异常时再测试其他模式 |
| 主动委派子 Agent | Beta，低风险，新会话生效 | 适合研究、代码审查、跨资料整理；日常聊天可能过度拆分 |
| DeepSeek V4 角色推理补丁 | Alpha，中风险，新会话生效 | 仅在对应 DeepSeek V4 模型下做对照测试 |
| 电脑控制 | 实验性 | 需要系统权限和逐应用批准；先从只读/询问模式小范围测试 |
以下两个源码痕迹不要硬开：
- “记忆快照反思”前端组件仍有残留，但运行时已退役并固定为关闭。
- 语音合成仍是未完成占位。
电脑控制是独立的高权限实验功能，不是关闭沙箱的副作用，也不是关闭沙箱的必要前提。
- 进入 设置 → 使用电脑，开启电脑控制。
- 按系统提示授权所需的系统权限；首次控制某个应用时，还需逐应用批准。
- 仅主助手可使用电脑控制，同一时间只允许一个会话占用。
- 优先从只读或询问模式的小范围操作开始，再逐步扩大可操作的应用范围。
它可能在部分软件中不稳定。需要处理文件时，仍应优先使用文件工具；电脑控制适合必须通过原生 GUI 才能完成的操作。
适合高级排障或 Headless Server 场景：
hana status
hana sessions
hana continue [序号|路径]
hana serve
hana bundle pull
hana bundle status
hana data diagnose
hana data checkpoints
hana data restore <transitionId>
其中 hana data diagnose 与 hana data checkpoints 适合只读检查数据状态；hana data restore 要求显式确认，避免误恢复覆盖较新的数据。
flowchart LR
A[识别任务动作] --> B{只读、编辑、命令或外部动作}
B --> C[最小权限分析]
C --> D[确认影响范围：输出路径、联网与副作用]
D --> E[执行]
E --> F[备份、验证与风险说明]
- 分析和阅读资料时，优先使用只读模式。
- 写文件、安装技能、运行命令前，先确认影响范围和输出目录。
- 给远程平台设置 Owner，不让访客触及私有数据与工具。
- 对重要项目开启文件备份。
- LAN 和设备密钥按最小范围发放，需要时可撤销。
- Full-access 插件只安装来源清楚、用途明确的包。
- 记下两次最不顺手的协作。
- 把“太啰嗦”“不够主动”改写成可执行规则。
- 检查置顶记忆是否过期、含混或互相冲突。
- 把重复两次以上的流程沉淀为 Experience 或 Skill。
- 关闭不再需要的 Skill、MCP 工具和自动化任务。
最实用的一条原则：
当结果不稳定时，先检查任务指令是否缺目标、材料、交付标准或权限边界；再检查人设、记忆和技能有没有各归其位。通常不需要立刻换模型，也不需要往 ishiki 里继续塞一大段设定。
HanaAgent 的对话、记忆、配置、插件数据和日志默认保存在本机数据目录，通常是用户主目录下的 ~/.hanako/；高级部署可通过 HANA_HOME 调整位置。模型 API 调用仍会发送到你自行配置的模型 Provider，因此本地存储和模型请求是两条不同的数据路径。
- 配好聊天、实用和视觉模型。
- 给 Agent 设置工作文件夹。
- 用一个“只读总结 → 确认 → 写 Markdown”的小任务验证链路。
- 写一版不超过 30 行的 ishiki 骨架。
- 建立置顶记忆和工作目录习惯。
- 用书桌和预览面板处理一份真实资料。
- 安装并启用一个与你最常做任务相关的 Skill。
- 把一次做得好的流程用
/xing沉淀下来。
- 配置一个经过审查、与当前任务相关的 MCP 连接器，并按 Agent 控制工具范围。
- 建立一个边界明确的自动化任务。
- 配置 Bridge，设置 Owner 后再用手机接管桌面会话。
- 只在需要并行核验的大任务中开启 Workflow。
在 设置 → 界面 可以选择主题、衬线字体、Markdown 正文留白和界面语言；支持的主题与语言会随版本更新，以当前设置页为准。阅读型任务可适当加大正文留白，密集操作时则更适合保持紧凑。
时区可使用自动检测或手动指定。它会影响定时任务、日记和部分记忆编译的日期归属，跨时区使用或夜间作息时尤其值得先确认。
在 设置 → 分享 可调整聊天截图的颜色和宽度，消息旁的截图功能会使用这些样式。分享前先检查：截图是否包含文件路径、账号、任务材料、会话历史或其他不适合公开的信息。
依次检查：记忆开关是否开启、实用模型是否已配置、你是否在查看另一个 Agent 或全新的会话。长期记忆和当前对话不是同一层；必要时到 设置 → 助手 查看事实库、长期记忆和编译内容。
这是视觉桥接在工作：视觉模型先把图片转为结构化说明，再交给聊天模型。若失败，检查视觉模型是否真支持图片输入、模型卡片的“视觉/支持图片”能力标记是否开启，以及 Provider 页的辅助视觉模型是否误选为纯文本模型。
全局安装不等于对当前 Agent 启用。到 设置 → 技能 → Agent 技能开关 为对应 Agent 打开；必要时在输入框选择该 Skill 徽章，明确要求本次消息使用它。再检查该 Skill 是否只属于另一个 Agent 的自学目录。
先查看插件状态是否为 loaded。Restricted 插件无法提供需要 Full-access 的深层能力；安装、启用或 reload 后，正在回复的会话可能要等到下一次安全重建才会重新绑定插件事件。
先确认平台 Owner 是否设置正确；然后检查 Bridge 全局只读模式、当前会话访问模式、工作台文件范围和该平台的文件能力。Owner 能识别你的身份，但不会绕过这些限制。
不同平台支持的文件类型、大小和上传方式不同。HanaAgent 会优先走平台原生上传；平台不支持时应出现明确错误。不要通过公开文档、聊天或提示词发送本地文件路径、私有 URL 或连接密钥。
检查连接器总开关、连接状态、OAuth/Bearer 授权、网络代理诊断，以及当前 Agent 是否启用了该连接器和具体工具。本地连接器还要确认启动命令与依赖可用；远程连接器则检查服务端状态和授权范围。
检查它是否已在 设置 → 使用电脑 启用、系统权限是否已授予、目标应用是否已单独批准，以及是否已有另一个会话正在占用电脑控制。它是实验性能力，和沙箱开关不是同一件事。
通常表示安装包发布流程已经开始，但该平台的更新元数据还没有准备好。此时可稍后再检查；若完整 Release 发布后仍持续失败，再查看更新日志或重新下载安装包。
- 官方项目：liliMozi/openhanako
- 配图来源：HanaAgent 官方公开资源 banner.jpg 与 screenshot-main.jpg，以外链方式引用，未复制二进制图片到本仓库。
- 图解：功能关系与操作流程使用 GitHub 原生 Mermaid 渲染，分别对应模型分工、Agent 分层、文件协作、扩展选择、远程入口、Workflow 与安全边界。
- 本手册依据 HanaAgent 内置用户说明、已核实的当前功能和一次本地源码审计整理。
- 源码审计对应提交：
427821a3c27a03e84370b285065d5fd9d56ddf98，当时与上游main分支一致。 - 本文不把已退役、仅调试或标为“coming soon”的源码路径视为可用功能。
