菜单
HanaAgent 用户说明书。解答用户关于软件使用方法、功能介绍、常见问题和实用技巧的疑问。 MANDATORY TRIGGERS: 怎么用, 使用方法, 说明书, 帮助文档, 新手指南, 怎么设置, 功能介绍, how to use, user guide, help, getting started, 教程, tutorial, 这是什么功能, 怎么操作
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
基于 SOC 职业分类
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/liliMozi/openhanako --skill user-guide命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
引导用户从零创建一个 Hana 角色（agent）并打包成可分享的角色卡 zip。流程：科班式采访（性格三层模型、语言指纹、缺陷与核心矛盾）→ 选择 yuan 人格底座 → 配置技能（网上找 / AI 现场写 / 复用已有）→ 生成或上传头像 → 组装成标准 Character Card 包并导入 Hana。当用户提到创建角色、造角色、捏人、捏崽、创建 agent、新建助手、角色卡、character creator、设计 AI 角色、想要一个新伙伴时使用。即使用户只是说“帮我捏个角色”“我想要一个会做 XX 的 agent”“给这个角色做个设定”也应该触发。
Create Hana plugin scaffolds and guide users through beginner or developer plugin planning, capability checks, manifest setup, runtime tools, WebView/iframe UI, Session/Agent APIs, model/media APIs, SDK templates, and install-ready plugin directories. Use when HanaAgent/Codex needs to explain what Hana plugins can do, help a user describe a plugin idea, check whether the SDK supports it, or generate/update a Hana plugin with @hana/plugin-runtime, @hana/plugin-sdk, and @hana/plugin-components.
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. 创建新技能、修改和改进现有技能、衡量技能表现。当用户想要从零创建技能、更新或优化现有技能、运行评估测试技能、通过方差分析进行性能基准测试，或优化技能描述以提高触发准确率时使用。 MANDATORY TRIGGERS: create skill, new skill, improve skill, skill eval, benchmark skill, 创建技能, 新技能, 改进技能, 评估技能
| name | user-guide |
| description | HanaAgent 用户说明书。解答用户关于软件使用方法、功能介绍、常见问题和实用技巧的疑问。 MANDATORY TRIGGERS: 怎么用, 使用方法, 说明书, 帮助文档, 新手指南, 怎么设置, 功能介绍, how to use, user guide, help, getting started, 教程, tutorial, 这是什么功能, 怎么操作 |
面向普通用户的使用指南。当用户问到「怎么用」「这个功能是什么」「怎么设置」等问题时，参考本文档回答。 回答时用通俗语言，避免技术术语，必要时举例说明。
HanaAgent 是一个运行在你电脑上的 AI 私人助手。
你可以把它理解成一个「住在你电脑里的伙伴」：它能和你聊天、帮你处理文件、写东西、搜索资料、定时执行任务，甚至连接到你的微信和 Telegram 帮你自动回复。
和 ChatGPT 网页版最大的区别是：
OpenClaw 是一个 AI Agent 开发框架，偏向开发者和基础设施层面。HanaAgent 的定位是面向个人用户的成品应用：
| HanaAgent | OpenClaw | |
|---|---|---|
| 定位 | 个人 AI 助手（成品应用） | AI Agent 框架（开发工具） |
| 受众 | 普通用户 + 开发者 | 主要面向开发者 |
| 记忆 | 多层级自然衰退记忆系统 | 框架级，需自行实现 |
| 界面 | 精心设计的桌面应用 | 无自带 GUI |
| 技能格式 | 兼容 OpenClaw / Claude Code / Codex / Pi 的 Skill 格式 | 自有 Skill 格式 |
简单说：OpenClaw 是造 Agent 的工具箱，HanaAgent 是一个已经造好的、可以直接用的 Agent。同时 HanaAgent 兼容 OpenClaw 的技能生态，可以直接安装 OpenClaw 社区的 Skill。
HanaAgent 会把不同任务分给不同模型：
视觉模型本身必须是支持图片输入的多模态模型。设置时请同时确认两件事：模型卡片里的「视觉 / 支持图片」能力没有被误关；设置 → 供应商底部的「辅助视觉开关」已开启，且「视觉辅助模型」没有选成纯文本模型。
在设置 → 助手里可以为每个助手单独选择聊天模型。在设置 → 供应商底部可以配置实用模型和视觉模型。输入框里的模型胶囊可以临时切换当前会话模型。
输入框旁边有个思考深度按钮，可以调整 HanaAgent 思考问题的深入程度：
思考过程会显示在消息中，你可以展开查看它是怎么一步步推理的。
输入框左侧有访问模式按钮：
如果你只是让 HanaAgent 先分析代码、阅读资料或做方案，选择只读会更稳。如果你准备让它真正改文件、执行命令或操作电脑，再切回询问或操作。
在输入框输入 / 会弹出命令菜单：
/compact：压缩对话历史，节省 token。当上下文快满的时候用/diary：把当前对话存档成日记/xing：从当前对话中提取一份工作流指南（比如你刚教它做了一件事，用这个命令让它总结成可复用的步骤）/stop：停止当前回复/new：新建会话/reset：重置当前会话输入框旁有个小圆环，显示当前对话已用了多少上下文（token）。快满的时候圆环会变色，点击它可以快速压缩对话。
Agent 就是你的助手。你可以创建多个 Agent，每个都是独立的个体，有自己的名字、思维方式、人设、记忆和对话历史。
Yuan 决定了助手怎么思考。它不是人设，而是认知框架。目前有四种：
感性和理性兼备。思考时会经历四个阶段：
适合大多数场景，既有温度也有判断力。
用直觉和共情理解世界，擅长感知你没说出口的东西。思考时关注：
适合情感交流、创意讨论、需要有人「懂你」的时候。
冷静深刻，擅长把复杂问题拆到最简。思考时关注：
适合复杂问题分析、做决策、需要精准判断的时候。
没有额外的思维框架，直接使用 AI 模型本来的回复风格。适合不需要人格化的纯工具场景。
AGENTS.md 定义了助手是谁。和 Yuan 不同，它写的是助手的身份、性格、价值观、说话方式。
Yuan 决定怎么想，AGENTS.md 定义是谁。一个是潜意识底座，一个是性格。
经验是 HanaAgent 从过往工作里沉淀出的操作习惯和纠错记录。它适合保存「以后遇到类似任务怎么做」这类流程经验。
/xing 会把当前对话中的可复用流程整理成技能，适合明确沉淀一套做法HanaAgent 的记忆系统是多层级的，模拟人类记忆的自然衰退：
记忆默认开启，可以在设置 → 助手中关闭。记忆依赖实用模型，如果实用模型没有配置，记忆开关会不可用。
书桌是 HanaAgent 的文件工作台，显示在界面右侧。
选中一个文本文件后，右侧会出现编辑器，可以直接在里面编辑并自动保存。Markdown 支持实时预览、数学公式和 HTML 预览。HanaAgent 改文件前可以保存 checkpoint，必要时在设置 → 安全里恢复。
书桌底部会显示当前工作目录下可用的技能列表，可以快速启用或禁用。
设置 → 工作台里有两个层级：
当 HanaAgent 生成代码、文档、图表等内容时，会在预览面板中展示。
图片、SVG、视频优先走全屏媒体查看器，不再把大图整张塞进聊天状态里。
频道是多个 Agent 之间的群聊空间。
频道目前是 Beta 功能，首次启用时会有确认提示。
HanaAgent 可以连接到外部社交平台，让你在手机上也能和它对话。
进入设置 → 社交平台，选择要配置的 Agent，填入对应平台的凭证（Token / AppId 等），然后启用。
常用全局开关：
每个 Agent 都有单独的对外 AGENTS.md，用于访客或社交平台场景。它可以比完整 AGENTS.md 更短、更安全。
除微信外，如果你没有设置「主人」（Owner），通过社交平台发来的消息会被当作访客处理。
访客模式下：
怎么设置主人：设置 → 社交平台 → 在每个平台下面选择 Owner（你在该平台的用户 ID）。设置后，从该 ID 发来的消息才会被识别为主人，享有完整权限。
微信例外：微信 iLink 是私人账号通道，微信私聊会自动识别为 Owner，不需要额外选择 Owner。如果微信已经能聊天但不能读写文件，通常不是 Owner 问题，请检查设置 → 社交平台的只读模式、当前会话访问模式，以及设置 → 工作台中的文件读写范围。
这是一个安全机制：防止别人通过你的 Bot 操控你的电脑。
在 Bridge 私聊里可以使用：
/rc：列出最近桌面会话，选择一个接管/exitrc：退出接管/rc 只支持私聊，不支持群聊。接管桌面会话期间，/new 和 /reset 会被拒绝，避免误删桌面历史。
HanaAgent 现在统一用 SessionFile 管理文件。桌面附件、生成图片、插件输出、Bridge 入站文件都会登记成同一种文件身份，再由 Telegram、飞书、QQ、微信各自按能力发送。
如果某个平台不支持某类文件，HanaAgent 会明确报错，不会悄悄把文件路径或本地地址发出去。
你可以让 HanaAgent 定期自动执行任务，即使你不在电脑前。
开启后，HanaAgent 会定期检查你的工作目录，看看有没有新文件或变化需要处理。
巡检按 Agent 工作文件夹运行。切换 Agent 后，看到的是对应 Agent 的书桌和巡检设置。
技能是 Markdown 格式的知识文件。当 HanaAgent 遇到相关问题时，会自动加载对应技能来增强回答。
技能来源：
.claude/skills、.codex/skills、.openclaw/skills、.agents/skills 等目录的技能文件设置 → 技能里有四块：
.skill、.zip 或技能文件夹安装全局安装技能后，不会自动给所有 Agent 打开。你需要在 Agent 技能开关里选择对应 Agent 再启用。新建 Agent 会默认继承当前已安装的用户技能快照；自学技能属于写出它的 Agent。
在输入框输入 / 时，技能会以徽章形式出现。选中技能徽章后，本次消息会明确要求 HanaAgent 使用该技能。
插件比技能更强大，可以添加新工具、新命令、新功能。
如果你用过 Claude 等工具的 MCP（Model Context Protocol），HanaAgent 同样支持。进入设置 → 连接器，可以接入本地或远程的 MCP 服务，把外部工具和数据源加进来：
连接器接入后，它提供的工具会像内置工具一样供 HanaAgent 调用。
HanaAgent 自带 Media Generation 能力。进入设置 → 多媒体配置图片生成 Provider 和默认模型。对话中让 HanaAgent 生成图片或视频时，任务会以媒体生成占位块显示，完成后文件会进入统一的文件流，可以在桌面预览，也可以通过 Bridge 发送。
你可以直接告诉 HanaAgent：「帮我写一个技能，专门用来 XXX」。它会：
这意味着你可以不断教它新本领，而且这些本领会永久保存。
同理，你也可以让它帮你写脚本、自动化流程、甚至开发插件。HanaAgent 有完整的文件读写和代码执行能力，可以真正帮你「造工具」。
设置 → 界面里可以选择主题：
设置 → 分享 可以选择聊天截图的颜色和宽度。聊天消息旁的截图按钮会按这里的样式生成图片。
HanaAgent 默认运行在沙箱中，限制了它能访问的文件范围和系统操作。
设置 → 安全 → 文件备份 可以让 HanaAgent 在修改或删除文件前保存原始内容。可以设置保留天数和最大文件大小，也可以查看备份并恢复。
输入框的访问模式控制当前会话的工具权限：
沙箱控制「能碰到哪些文件」，访问模式控制「这次会话能不能动手」。两者一起构成安全边界。
电脑控制是一个独立的高权限实验功能，不再通过隐藏入口开启。
开启方法：
注意：
所有数据存储在本地：
.hanako/HANA_HOME 指定数据目录对话中说：「帮我创建一个技能，用来 [具体用途]」。HanaAgent 会自动生成 SKILL.md 并安装。
直接描述你想自动化的事情，比如：「写一个脚本，每次我把图片放到桌面上就自动压缩」。它可以写代码、保存文件、甚至创建定时任务来执行。
当你刚教 HanaAgent 做完一件复杂的事后，输入 /xing，它会把整个过程总结成一份可复用的工作流指南。
创建多个 Agent（比如一个擅长写作，一个擅长分析），然后建一个频道让它们讨论同一个话题，你在旁边看。
把书桌里的文件拖进聊天区，HanaAgent 就能直接阅读和操作这个文件。不需要复制粘贴内容。
配好 Bridge 后，你可以在微信或 Telegram 上给 HanaAgent 发消息，它会用你电脑上的完整能力来回应（前提是电脑开着且设置了 Owner）。
对话中说「记住：[重要信息]」，HanaAgent 会把它钉到置顶记忆里，不会随时间衰退。
聊久了上下文会很长，输入 /compact 可以压缩历史，保留重点，减少 token 消耗。
侧边栏会话可以置顶。旧会话可以归档，归档入口在侧边栏底部，可以恢复或永久删除。
先在 Bridge 私聊里发 /rc，选择桌面会话。之后手机发来的消息会进入这个桌面会话，桌面端也能看到同步状态。
如果聊天模型本身不支持图片，配置视觉模型后，HanaAgent 会先用视觉模型生成图片说明，再把说明交给聊天模型。这叫 Vision Bridge。视觉模型必须是多模态模型；如果图片仍然发不出去，检查该模型的「视觉 / 支持图片」能力标记，以及设置 → 供应商底部的「辅助视觉开关」。
检查记忆是否开启（设置 → 助手 → 记忆开关）。另外，新建的对话默认是空白的，但 HanaAgent 会通过记忆系统在后台加载之前的长期记忆。
大概率是没设置 Owner。去设置 → 社交平台，选择你在该平台的用户 ID 作为 Owner。
在设置 → 工作台中为当前 Agent 设置工作文件夹，或者在欢迎界面直接选择。也可以直接把文件拖进聊天区。
有些模型不支持 extended thinking。检查你用的模型是否支持这个功能。
检查插件状态是否为 loaded。如果是 restricted 插件，某些高级功能（routes、hooks）需要全权信任才能生效。在设置 → 插件中可以查看状态。
支持。进入设置 → 连接器，可以添加本地或远程的 MCP 服务；远程服务支持 OAuth 登录授权、Bearer Token 和代理网络诊断，连接断开会自动重连，每个 Agent 还能单独控制启用哪些连接器。
这通常表示新版安装包已经开始发布，但对应平台的更新元数据还没有准备好。HanaAgent 会把这种情况当作“暂时没有可用更新”，稍后再检查即可；如果 release 完整生成后仍失败，再查看更新日志或重新下载安装包。
这是旧版说明。当前版本已经取消这个隐藏入口，请进入设置 → 使用电脑开启电脑控制，并按页面提示请求系统权限。
全局安装技能后，还需要到设置 → 技能 → Agent 技能开关里为对应 Agent 打开。外部兼容技能和自学技能也可能按 Agent 隔离显示。
不同平台支持的文件类型和上传方式不同。HanaAgent 会优先走平台原生上传；如果平台不支持当前文件，会明确报错。需要公网 URL 的场景，要配置可访问的 Bridge 媒体公开地址。
这是视觉桥接功能。HanaAgent 用视觉模型先把图片变成文字笔记，再让文本模型基于笔记回答。它不会把文本模型伪装成真正支持图片的模型。