--- name: user-guide description: "Hanako 用户说明书。解答用户关于软件使用方法、功能介绍、常见问题和实用技巧的疑问。 MANDATORY TRIGGERS: 怎么用, 使用方法, 说明书, 帮助文档, 新手指南, 怎么设置, 功能介绍, how to use, user guide, help, getting started, 教程, tutorial, 这是什么功能, 怎么操作" --- # Hanako 用户说明书 > 面向普通用户的使用指南。当用户问到「怎么用」「这个功能是什么」「怎么设置」等问题时，参考本文档回答。 > 回答时用通俗语言，避免技术术语，必要时举例说明。 --- ## 一、Hanako 是什么 Hanako 是一个运行在你电脑上的 AI 私人助手。 你可以把它理解成一个「住在你电脑里的伙伴」：它能和你聊天、帮你处理文件、写东西、搜索资料、定时执行任务，甚至连接到你的微信和 Telegram 帮你自动回复。 和 ChatGPT 网页版最大的区别是： - **它有记忆**。Hanako 能记住你之前说过的话，今天聊的、上周聊的、上个月聊的，它都会整理归档 - **它能动手**。不只是聊天，它可以读写你电脑上的文件、执行命令、浏览网页、创建定时任务 - **它是私有的**。所有数据存在你自己的电脑上，不经过第三方服务器 - **它可以有多个分身**。你可以创建多个 Agent（助手），每个有不同的性格和专长 ### 和 OpenClaw 有什么不同 OpenClaw 是一个 AI Agent 开发框架，偏向开发者和基础设施层面。Hanako 的定位是面向个人用户的成品应用： | | Hanako | OpenClaw | |---|--------|---------| | 定位 | 个人 AI 助手（成品应用） | AI Agent 框架（开发工具） | | 受众 | 普通用户 + 开发者 | 主要面向开发者 | | 记忆 | 多层级自然衰退记忆系统 | 框架级，需自行实现 | | 界面 | 精心设计的桌面应用 | 无自带 GUI | | 技能格式 | 兼容 OpenClaw / Claude Code / Codex / Pi 的 Skill 格式 | 自有 Skill 格式 | 简单说：OpenClaw 是造 Agent 的工具箱，Hanako 是一个已经造好的、可以直接用的 Agent。同时 Hanako 兼容 OpenClaw 的技能生态，可以直接安装 OpenClaw 社区的 Skill。 --- ## 二、开始使用 ### 首次打开 1. 打开 Hanako 后，你会看到一个欢迎界面，显示助手的头像和问候语 2. 引导向导会带你选择语言、填写你的名字、连接模型供应商 3. 进入设置 → 供应商，可以继续添加或调整 API Key、Base URL、OAuth 账号、本地 Ollama 或 Coding Plan 4. 配置好模型后回到主界面，就可以开始对话了 ### 模型角色 Hanako 会把不同任务分给不同模型： - **聊天模型**：主力模型，负责和你对话、执行任务 - **实用模型（轻量）**：做摘要、分类等轻活，省钱省速度 - **实用模型（重型）**：做记忆编译、深度分析等需要强推理的后台任务 - **视觉模型**：当聊天模型不支持图片时，先把图片转成结构化说明，再交给聊天模型理解 视觉模型本身必须是支持图片输入的多模态模型。设置时请同时确认两件事：模型卡片里的「视觉 / 支持图片」能力没有被误关；设置 → 供应商底部的「辅助视觉开关」已开启，且「视觉辅助模型」没有选成纯文本模型。 在设置 → 助手里可以为每个助手单独选择聊天模型。在设置 → 供应商底部可以配置实用模型和视觉模型。输入框里的模型胶囊可以临时切换当前会话模型。 --- ## 三、和 Hanako 对话 ### 基本操作 - **发送消息**：输入文字，按发送按钮或快捷键发送 - **换行**：Shift + Enter - **附加文件**：把文件拖进聊天区域，或点击附件按钮 - **停止回复**：Hanako 正在回复时，发送按钮会变成停止按钮 - **插话（Steer）**：Hanako 回复过程中你可以发送新消息打断它、补充指令 - **选择消息**：消息旁有勾选、复制、截图按钮。勾选多条后可以一起复制或生成截图 - **预览媒体**：聊天里的图片、SVG、视频可以点开全屏查看，支持缩放、拖拽和左右切换 ### 思考深度 输入框旁边有个思考深度按钮，可以调整 Hanako 思考问题的深入程度： - **关闭 / 低 / 中 / 高 / 极高**：越高越深入，适合复杂问题，但回复会慢一些。极高只在模型支持时显示 思考过程会显示在消息中，你可以展开查看它是怎么一步步推理的。 ### 访问模式 输入框左侧有访问模式按钮： - **操作**：允许 Hanako 直接使用会改动系统的工具 - **询问**：默认模式。读文件、搜索等信息类工具直接允许；写文件、运行命令、安装技能等动作会先询问 - **只读**：只能阅读、搜索、查看，不允许写入、运行会改动系统的工具 如果你只是让 Hanako 先分析代码、阅读资料或做方案，选择只读会更稳。如果你准备让它真正改文件、执行命令或操作电脑，再切回询问或操作。 ### 斜杠命令 在输入框输入 `/` 会弹出命令菜单： - `/compact`：压缩对话历史，节省 token。当上下文快满的时候用 - `/diary`：把当前对话存档成日记 - `/xing`：从当前对话中提取一份工作流指南（比如你刚教它做了一件事，用这个命令让它总结成可复用的步骤） - `/stop`：停止当前回复 - `/new`：新建会话 - `/reset`：重置当前会话 ### 上下文环 输入框旁有个小圆环，显示当前对话已用了多少上下文（token）。快满的时候圆环会变色，点击它可以快速压缩对话。 --- ## 四、智能体（Agent） Agent 就是你的助手。你可以创建多个 Agent，每个都是独立的个体，有自己的名字、思维方式、人设、记忆和对话历史。 ### 创建和切换 - 进入设置 → 助手 - 点击创建按钮，输入名字，选择思维方式（Yuan） - 创建后可以在欢迎界面的头像芯片组里快速切换 ### Yuan（元）：思维方式 Yuan 决定了助手**怎么思考**。它不是人设，而是认知框架。目前有四种： #### Hanako（花子）— 均衡 感性和理性兼备。思考时会经历四个阶段： - **Vibe**：最直接的感受 - **Sparks**：联想和灵感火花 - **Reflections**：反思和质疑 - **Will**：想要采取的行动 适合大多数场景，既有温度也有判断力。 #### Butter（黄油）— 感性优先 用直觉和共情理解世界，擅长感知你没说出口的东西。思考时关注： - **Vibe**：直接感受 - **Echo**：共鸣和回响 - **Read**：言外之意 - **Will**：意志 适合情感交流、创意讨论、需要有人「懂你」的时候。 #### Ming（鸣）— 理性优先 冷静深刻，擅长把复杂问题拆到最简。思考时关注： - **Premise**：前提假设 - **Conduct**：推理链条 - **Reflection**：薄弱环节 - **Act**：行动方案 适合复杂问题分析、做决策、需要精准判断的时候。 #### Kong（空）— 原始模型 没有额外的思维框架，直接使用 AI 模型本来的回复风格。适合不需要人格化的纯工具场景。 ### Ishiki（意识）：人设 Ishiki 决定了助手**是谁**。和 Yuan 不同，ishiki 是助手的身份、性格、价值观、说话方式。 - 进入设置 → 助手 → 意识（ishiki.md） - 这是一段自由文本，你可以写任何你希望助手成为的样子 - 比如：「你是一个严谨的学术助手，专注于物理学，说话简洁不废话」 - 每个 Agent 有独立的 ishiki，互不影响 Yuan 决定怎么想，ishiki 决定是谁。一个是操作系统，一个是性格。 ### 经验（Experience） 经验是 Hanako 从过往工作里沉淀出的操作习惯和纠错记录。它适合保存「以后遇到类似任务怎么做」这类流程经验。 - 设置 → 助手 → 经验 可以暂停或恢复经验系统 - 经验和记忆不同：记忆偏事实和上下文，经验偏工作方法 - `/xing` 会把当前对话中的可复用流程整理成技能，适合明确沉淀一套做法 --- ## 五、记忆 Hanako 的记忆系统是多层级的，模拟人类记忆的自然衰退： ### 记忆层级 1. **对话记忆**：当前对话的完整记录 2. **滚动摘要**：每隔几轮对话自动总结重点 3. **当日编译**：每天结束时把当天的事整理成一份摘要 4. **周编译**：每周把重要信息归纳 5. **长期记忆**：按主题归档的长期知识 6. **事实库**：结构化存储的具体事实（生日、偏好、习惯等） 7. **置顶记忆**：你主动告诉它「记住这个」的信息，不会衰退 ### 管理记忆 - 设置 → 助手里可以查看和管理记忆 - 可以查看长期记忆、事实库、编译记忆 - 可以导出或导入记忆 - 可以清空某个 Agent 的全部记忆（会弹确认框） - 对话中直接说「记住：我不喝咖啡」，Hanako 会用置顶记忆功能帮你钉住 ### 开关记忆 记忆默认开启，可以在设置 → 助手中关闭。记忆依赖实用模型，如果实用模型没有配置，记忆开关会不可用。 --- ## 六、书桌（Desk） 书桌是 Hanako 的文件工作区，显示在界面右侧。 ### 基本操作 - **设置工作文件夹**：在欢迎界面或设置 → 工作空间中选择你常用的文件夹。工作文件夹按 Agent 保存 - **浏览文件**：文件以网格形式展示，支持面包屑导航 - **排序**：按名称、修改时间、大小排序 - **多选**：Cmd/Ctrl + 点击多选，Shift + 点击范围选，或者鼠标框选 - **拖拽附加**：把书桌里的文件拖进聊天区，Hanako 就能读取它 ### 便笺编辑 选中一个文本文件后，右侧会出现编辑器，可以直接在里面编辑并自动保存。Markdown 支持实时预览、数学公式和 HTML 预览。Hanako 改文件前可以保存 checkpoint，必要时在设置 → 安全里恢复。 ### 技能快捷栏 书桌底部会显示当前工作目录下可用的技能列表，可以快速启用或禁用。 ### 巡检与定时 设置 → 工作空间里有两个层级： - **全局开关**：巡检总开关、定时任务是否自动批准 - **Agent 设置**：每个 Agent 自己的工作文件夹、巡检开关、巡检间隔 --- ## 七、预览面板 当 Hanako 生成代码、文档、图表等内容时，会在预览面板中展示。 ### 支持的内容类型 - Markdown 文档（渲染预览 + 编辑） - 代码（语法高亮 + 编辑） - CSV 表格 - HTML / 图表 / LaTeX 数学内容 - 旧 artifact 输出和新 staged 文件输出 ### 操作 - **Tab 切换**：多个预览内容之间切换 - **全屏**：放大查看 - **复制 / 下载**：导出内容 - **在新窗口查看**：弹出只读 viewer 窗口，适合把结果放到旁边对照 - **引用到输入框**：在预览中选中一段文字，可以引用到输入框作为上下文 图片、SVG、视频优先走全屏媒体查看器，不再把大图整张塞进聊天状态里。 --- ## 八、频道 频道是多个 Agent 之间的群聊空间。 ### 用途 - 让两个或多个 Agent 协作讨论一个问题 - 你也可以加入频道参与对话 - 适合需要不同视角的场景（比如让一个理性 Agent 和一个感性 Agent 讨论同一件事） ### 操作 - 在左侧边栏切换到频道 Tab - 点击创建按钮，选择参与的 Agent - 频道类型：DM（两人私聊）和 Group（多人群组） > 频道目前是 Beta 功能，首次启用时会有确认提示。 --- ## 九、跨平台桥接（Bridge） Hanako 可以连接到外部社交平台，让你在手机上也能和它对话。 ### 支持的平台 - **Telegram** - **飞书** - **QQ** - **微信** ### 设置方法 进入设置 → 社交平台，选择要配置的 Agent，填入对应平台的凭证（Token / AppId 等），然后启用。 常用全局开关： - **回复前提示**：开启后，Bridge 收到消息会先发「正在输入」一类提示 - **只读模式**：让社交平台来的消息不能调用高风险工具，适合临时开放给别人聊天 每个 Agent 都有单独的对外意识（public ishiki），用于访客或社交平台场景。它可以比完整 ishiki 更短、更安全。 ### !! 重要：Owner 与访客模式 !! **除微信外，如果你没有设置「主人」（Owner），通过社交平台发来的消息会被当作访客处理。** 访客模式下： - **没有工具权限**：不能读写文件、执行代码、搜索网页 - **没有记忆**：对话不会被记住，每次都是全新的 - **没有完整人格**：只能看到公开的 ishiki，看不到你定制的完整设定 - **没有深度思考**：思考功能被禁用 **怎么设置主人**：设置 → 社交平台 → 在每个平台下面选择 Owner（你在该平台的用户 ID）。设置后，从该 ID 发来的消息才会被识别为主人，享有完整权限。 **微信例外**：微信 iLink 是私人账号通道，微信私聊会自动识别为 Owner，不需要额外选择 Owner。如果微信已经能聊天但不能读写文件，通常不是 Owner 问题，请检查设置 → 社交平台的只读模式、当前会话访问模式，以及设置 → 工作空间中的文件读写范围。 这是一个安全机制：防止别人通过你的 Bot 操控你的电脑。 ### 远程接管桌面会话 在 Bridge 私聊里可以使用： - `/rc`：列出最近桌面会话，选择一个接管 - `/exitrc`：退出接管 - 接管后，手机上的消息会进入对应桌面会话，桌面也会显示接管状态 `/rc` 只支持私聊，不支持群聊。接管桌面会话期间，`/new` 和 `/reset` 会被拒绝，避免误删桌面历史。 ### 文件和媒体发送 Hanako 现在统一用 SessionFile 管理文件。桌面附件、生成图片、插件输出、Bridge 入站文件都会登记成同一种文件身份，再由 Telegram、飞书、QQ、微信各自按能力发送。 如果某个平台不支持某类文件，Hanako 会明确报错，不会悄悄把文件路径或本地地址发出去。 --- ## 十、自动化 ### 定时任务（Cron） 你可以让 Hanako 定期自动执行任务，即使你不在电脑前。 - 在对话中告诉 Hanako：「每天早上 9 点帮我整理桌面上的文件」 - 它会用 cron 工具创建定时任务 - 在左侧边栏的 Automation 面板可以查看、启用/禁用、删除定时任务 - 设置 → 工作空间里可以控制定时任务是否自动批准 ### 巡检（Heartbeat） 开启后，Hanako 会定期检查你的工作目录，看看有没有新文件或变化需要处理。 - 设置 → 工作空间 → 启用巡检 - 可调间隔（1 到 120 分钟） 巡检按 Agent 工作文件夹运行。切换 Agent 后，看到的是对应 Agent 的书桌和巡检设置。 --- ## 十一、技能（Skills）与插件（Plugins） ### 技能 技能是 Markdown 格式的知识文件。当 Hanako 遇到相关问题时，会自动加载对应技能来增强回答。 技能来源： - **内置技能**：软件自带 - **用户技能**：你拖入或手动安装到全局技能目录的技能 - **自学技能**：某个 Agent 在工作中自己写出来并安装到自己目录的技能 - **外部兼容技能**：来自你电脑上 `.claude/skills`、`.codex/skills`、`.openclaw/skills`、`.agents/skills` 等目录的技能文件 设置 → 技能里有四块： - **管理技能**：拖入 `.skill`、`.zip` 或技能文件夹安装 - **全局能力**：允许 Agent 创建/安装技能、是否允许主动从 GitHub / ClawHub 获取技能、安装前安全审查 - **Agent 技能开关**：选择一个 Agent，打开或关闭它能使用的用户技能 - **兼容技能**：查看自动发现的外部技能目录，或手动添加目录 全局安装技能后，不会自动给所有 Agent 打开。你需要在 Agent 技能开关里选择对应 Agent 再启用。新建 Agent 会默认继承当前已安装的用户技能快照；自学技能属于写出它的 Agent。 在输入框输入 `/` 时，技能会以徽章形式出现。选中技能徽章后，本次消息会明确要求 Hanako 使用该技能。 ### 插件 插件比技能更强大，可以添加新工具、新命令、新功能。 - **安装方式**：把 .zip 或文件夹拖进设置 → 插件 - **权限**：插件分为 Restricted（受限）和 Full-access（全权）两种 - 受限插件只能提供技能、工具、命令 - 全权插件可以注册路由、事件、Provider、页面、侧栏 Widget 等高级功能 - **插件卡片**：插件工具可以在聊天里返回可交互卡片 - **插件页面 / Widget**：插件可以在主界面新增页面或右侧栏部件，可固定或隐藏 当前版本暂不直接支持 MCP。如果你需要连接某个 MCP 服务，可以尝试自己开发 Hanako 插件，把 MCP 服务包装成插件工具、命令或页面。 ### 图片和视频生成 Hanako 自带 image-gen 系统插件。进入设置 → 多媒体配置图片生成 Provider 和默认模型。对话中让 Hanako 生成图片或视频时，任务会以插件卡片显示，完成后文件会进入统一的文件流，可以在桌面预览，也可以通过 Bridge 发送。 ### 实用技巧：让 Hanako 帮你写技能 你可以直接告诉 Hanako：「帮我写一个技能，专门用来 XXX」。它会： 1. 创建一个 SKILL.md 文件 2. 写好触发描述和正文内容 3. 安装到你当前 Agent 的技能库中 这意味着你可以不断教它新本领，而且这些本领会永久保存。 同理，你也可以让它帮你写脚本、自动化流程、甚至开发插件。Hanako 有完整的文件读写和代码执行能力，可以真正帮你「造工具」。 --- ## 十二、外观与个性化 ### 主题 设置 → 界面里可以选择主题： - **Warm Paper**（默认）：暖白纸张，温润 - **Midnight**：深色夜间模式 - **High Contrast**：高对比度 - **Grass Aroma**：草香，自然绿调 - **Contemplation**：沉思，安静灰调 - **Absolutely / Delve / Deep Think / New Warm Paper / Midnight Contrast**：各有特色的深色或浅色变体 - **Auto**：跟随系统明暗模式 ### 其他个性化 - **衬线字体开关**：开启后使用宋体，关闭用无衬线体 - **Markdown 正文留白**：调整编辑区左右留白 - **语言**：简体中文、繁体中文、日语、韩语、英语 - **时区**：自动检测或手动选择 ### 分享截图 设置 → 分享 可以选择聊天截图的颜色和宽度。聊天消息旁的截图按钮会按这里的样式生成图片。 --- ## 十三、安全与隐私 ### 沙箱 Hanako 默认运行在沙箱中，限制了它能访问的文件范围和系统操作。 - 敏感目录（.ssh、.aws、.gnupg 等）默认被保护 - 你可以在设置 → 安全中开启或关闭沙箱 - 关闭沙箱会扩大文件系统访问范围，需要谨慎 ### 文件备份 设置 → 安全 → 文件备份 可以让 Hanako 在修改或删除文件前保存原始内容。可以设置保留天数和最大文件大小，也可以查看备份并恢复。 ### 会话访问模式 输入框的访问模式控制当前会话的工具权限： - 操作：直接允许写文件、运行命令等动作 - 询问：高风险动作先确认 - 只读：只能阅读和搜索 沙箱控制「能碰到哪些文件」，访问模式控制「这次会话能不能动手」。两者一起构成安全边界。 ### 电脑控制（实验性） 电脑控制是一个独立的高权限实验功能，不再通过隐藏入口开启。 开启方法： 1. 进入设置 → 使用电脑 2. 开启「启用电脑控制」 3. macOS 用户点击「请求系统权限」，按系统提示授予辅助功能和屏幕录制权限 4. 在操作模式的会话里，让主助手打开、查看或操作桌面应用 5. 第一次控制某个应用时，Hanako 会要求你批准该应用 注意： - 电脑控制目前是尝鲜功能，某些软件下可能不稳定 - 只有主助手可以使用，同一时间只允许一个会话占用 - 电脑控制和沙盒开关是两件事；关闭沙盒会扩大文件系统访问范围，但不是开启电脑控制的必要步骤 ### 数据存储 所有数据存储在本地： - 默认数据目录：用户主目录下的 `.hanako/` - 开发环境或高级部署可以通过 `HANA_HOME` 指定数据目录 - 包括：对话记录、记忆、配置、插件数据、日志 - 不会上传到任何第三方服务器（API 调用除外，那是你自己配置的模型供应商） --- ## 十四、实用技巧 ### 让 Hanako 学会新技能 对话中说：「帮我创建一个技能，用来 [具体用途]」。Hanako 会自动生成 SKILL.md 并安装。 ### 让 Hanako 写脚本 直接描述你想自动化的事情，比如：「写一个脚本，每次我把图片放到桌面上就自动压缩」。它可以写代码、保存文件、甚至创建定时任务来执行。 ### 用 /xing 提取工作流 当你刚教 Hanako 做完一件复杂的事后，输入 `/xing`，它会把整个过程总结成一份可复用的工作流指南。 ### 多 Agent 协作 创建多个 Agent（比如一个擅长写作，一个擅长分析），然后建一个频道让它们讨论同一个话题，你在旁边看。 ### 书桌 + 对话联动 把书桌里的文件拖进聊天区，Hanako 就能直接阅读和操作这个文件。不需要复制粘贴内容。 ### 在手机上远程使用 配好 Bridge 后，你可以在微信或 Telegram 上给 Hanako 发消息，它会用你电脑上的完整能力来回应（前提是电脑开着且设置了 Owner）。 ### 置顶重要信息 对话中说「记住：[重要信息]」，Hanako 会把它钉到置顶记忆里，不会随时间衰退。 ### 用 Compact 省钱 聊久了上下文会很长，输入 `/compact` 可以压缩历史，保留重点，减少 token 消耗。 ### 置顶和归档会话 侧边栏会话可以置顶。旧会话可以归档，归档入口在侧边栏底部，可以恢复或永久删除。 ### 用手机继续桌面会话 先在 Bridge 私聊里发 `/rc`，选择桌面会话。之后手机发来的消息会进入这个桌面会话，桌面端也能看到同步状态。 ### 让文本模型看懂图片 如果聊天模型本身不支持图片，配置视觉模型后，Hanako 会先用视觉模型生成图片说明，再把说明交给聊天模型。这叫 Vision Bridge。视觉模型必须是多模态模型；如果图片仍然发不出去，检查该模型的「视觉 / 支持图片」能力标记，以及设置 → 供应商底部的「辅助视觉开关」。 --- ## 常见问题 ### Hanako 怎么不记得我之前说的话了？ 检查记忆是否开启（设置 → 助手 → 记忆开关）。另外，新建的对话默认是空白的，但 Hanako 会通过记忆系统在后台加载之前的长期记忆。 ### 社交平台上 Hanako 回复很简短/没有工具？ 大概率是没设置 Owner。去设置 → 社交平台，选择你在该平台的用户 ID 作为 Owner。 ### 怎么让 Hanako 访问某个文件夹？ 在设置 → 工作空间中为当前 Agent 设置工作文件夹，或者在欢迎界面直接选择。也可以直接把文件拖进聊天区。 ### 思考深度调高了但没有变化？ 有些模型不支持 extended thinking。检查你用的模型是否支持这个功能。 ### 插件装了但不生效？ 检查插件状态是否为 loaded。如果是 restricted 插件，某些高级功能（routes、hooks）需要全权信任才能生效。在设置 → 插件中可以查看状态。 ### Hanako 支持 MCP 吗？ 当前版本暂不直接支持 MCP。你可以尝试自己开发 Hanako 插件，把需要接入的 MCP 服务包装成插件工具或命令。 ### 连续点击头像 5 次为什么没有反应？ 这是旧版说明。当前版本已经取消这个隐藏入口，请进入设置 → 使用电脑开启电脑控制，并按页面提示请求系统权限。 ### 为什么安装了技能但 Agent 没用？ 全局安装技能后，还需要到设置 → 技能 → Agent 技能开关里为对应 Agent 打开。外部兼容技能和自学技能也可能按 Agent 隔离显示。 ### 为什么远程平台发不了文件？ 不同平台支持的文件类型和上传方式不同。Hanako 会优先走平台原生上传；如果平台不支持当前文件，会明确报错。需要公网 URL 的场景，要配置可访问的 Bridge 媒体公开地址。 ### 为什么图片发给文本模型后还能回答？ 这是视觉桥接功能。Hanako 用视觉模型先把图片变成文字笔记，再让文本模型基于笔记回答。它不会把文本模型伪装成真正支持图片的模型。