本手册按常见任务组织。首次使用从“快速上手”开始；已有配置可直接通过目录定位操作。
企智盒在本机运行并管理业务数据。模型密钥、平台凭据和备份文件均属于敏感信息，应由授权人员妥善保管。
快速上手
打开企智盒
首次打开后，按照引导完成四项设置：
- 确认 Docker Desktop 已启动。
- 选择模型服务并填写 API Key。
- 完成助手人格设定。
- 绑定至少一个消息平台并应用配置。
若运行环境检查失败，先启动 Docker Desktop，再返回页面重新检测。
连接模型服务
以“百炼按量计费”为例：
- 在“连接模型服务”中选择“百炼按量计费”。
- 填写从阿里云百炼控制台获取的 API 密钥。
- 选择模型，点击“验证并拉取模型”确认可用列表。
- 使用“保存并测试模型”确认连接正常，然后进入下一步。
其他内置服务的操作相同。当前预设包括百炼按量计费、百炼 Coding Plan、百炼 Token Plan 团队版、智谱按量计费、智谱 Coding Plan、火山方舟 Coding Plan、火山方舟 Agent Plan、OpenCode Go、DeepSeek 和 Agnes AI。自定义服务需填写兼容接口地址、API Key 和模型名称。
火山方舟 Coding Plan 与 Agent Plan 是不同订阅，密钥不可共用。配置时请选择实际购买的服务。
设定人格
打开“人格设定”，填写助手的职责和工作方式。描述越具体，输出越稳定，建议至少说明：
- 负责哪些业务；
- 期望的表达风格；
- 必须遵守的流程；
- 需要避免的行为。
绑定个人微信
- 打开“平台绑定”，选择“个人微信”。
- 点击“扫码登录”，使用微信完成确认。
- 页面显示绑定成功后，返回配置页。
扫码凭据只写入本机数据目录，不会显示在网页中。重新扫码仅在成功后替换原有凭据。
应用配置
页面出现“配置已保存，应用后生效”时，点击“应用配置”。系统会校验配置并启动服务；模型、人格、技能或平台绑定变更会在应用后生效。
首次启动需要准备运行环境，耗时可能稍长。保持 Docker Desktop 运行并等待状态更新即可。
发起第一项任务
在已绑定的平台发送一条目标明确的消息，例如：
请整理今天收到的客户需求，按紧急程度分类，并列出需要跟进的事项。
能够正常回复，说明模型、助手和消息平台已经连通。
日常使用
看懂运行状态
| 状态 | 含义 | 处理方式 |
|---|---|---|
| 运行中 | 服务和助手可正常工作 | 无需处理 |
| 未应用 | 已保存新配置，运行中的服务尚未更新 | 点击“应用配置” |
| 未绑定平台 | 助手已启用，但没有可用消息入口 | 完成平台绑定后应用配置 |
| 启动较慢 | 服务仍在启动或等待组件就绪 | 查看日志并检查网络 |
| 失败 | 配置校验或运行过程出错 | 根据错误提示和日志处理 |
保存与应用
“保存”负责写入配置，“应用配置”负责让运行中的服务加载配置。可连续完成多项编辑，最后统一应用，减少不必要的重启。
启动、停止与重启
- 启动：运行已启用且已绑定平台的助手。
- 停止：暂停服务，保留全部配置和数据。
- 重启：重新加载当前运行环境。
企智盒只管理当前用户下的单个 ~/.hermes-dock 实例。所有助手都作为 profile 在同一个 Hermes 容器内运行，不会创建多个 Docker 实例或 Compose project。
服务启停和重启会同时作用于所有助手。遇到消息无响应时，先检查运行状态，再查看日志；不必反复点击重启。
查看日志
日志用于定位启动、模型连接和平台接入问题。重点关注最近一次操作后的错误，不要在截图或转发日志时暴露 API Key、Token 等敏感信息。
Hermes 原生 Dashboard 默认关闭，消息服务不向宿主机开放端口。运行问题统一通过“运行 → 日志诊断”排查。
管理助手
创建与切换
总览页展示助手运行摘要，“助手”页负责创建、切换和管理全部助手。创建助手时，需要设置唯一标识和显示名称；创建后可分别维护模型、人格、技能和平台绑定。
默认助手不可删除。其他助手删除前会停止服务并生成备份；停止或备份失败时，删除会中止。
启用与停用
启用表示助手参与运行，停用只暂停该助手，不影响编辑。调整后需要应用配置。
同一个平台身份不能同时绑定到多个已启用助手。出现身份冲突时，停用其中一个助手，或更换平台账号。
批量复制配置
在“助手”页点击“批量配置”，可将以下内容复制到多个目标助手：
- 主模型；
- 辅助模型与策略；
- 供应商定义；
- 人格设定；
- 指定技能。
API Key 默认不复制，避免密钥扩散。只有勾选“包含 API Key”并在页面内二次确认后才会复制密钥。复制完成后检查目标助手并应用配置。
需要更新官方人格或技能时，在“助手”页点击“选择助手同步”，选择目标助手和同步内容。操作会先联网获取最新官方 commit；联网失败时不会写入，也不会使用旧缓存继续同步。人格会先备份再覆盖，官方同名技能会在备份后更新，自定义技能和官方已移除的旧技能会保留。
配置能力
模型与辅助模型
“模型服务”管理供应商和 API Key，“模型配置”选择主模型与辅助模型。主模型负责对话和任务执行，辅助模型可跟随主模型，也可单独指定。
保存模型选择不代表连接成功。完成配置后使用“测试模型”，遇到失败时依次检查 API Key、模型名称、账户额度和网络代理。
人格与技能
人格定义助手的角色、边界和表达方式；技能提供可复用的工作流程。修改后保存，并通过“应用配置”加载到运行环境。
技能页支持：
- 查看技能详情，并按需打开本机目录编辑文件；
- 从 Skill Hub 安装新技能；
- 打开本机技能目录；
- 批量选择和删除技能；
- 重置全部技能。
同步官方技能统一从“助手 → 选择助手同步”进入。批量删除会逐个备份所选技能；“重置全部技能”会先备份整个技能目录，再删除全部现有技能并使用当前官方内容恢复，离线时使用已下载缓存或启动器内置快照。
图片文字识别
企智盒内置本地图片文字识别技能，可提取 PNG、JPG 和 JPEG 图片中的可见文字。技能本身不携带 OCR 模型；首次识别需要联网安装经过版本和 integrity 锁定的 light-ocr 运行时及模型，安装成功后可离线复用。图片不会发送到外部服务。
图片文字识别只负责读取文字，不能替代物体、人物、颜色、布局含义或图表趋势等视觉理解。缺少该技能时，在“助手 → 选择助手同步”中只勾选“内置技能”；首次依赖安装失败时，根据错误检查容器网络或代理设置后重试识别。
共享文件
所有助手可读写同一个共享目录，默认位于企智盒数据目录外的独立位置。可在“设置 → 访问与网络”中选择目录并配置局域网文件管理，适合存放待处理资料、交付物和跨助手协作文件。
建议按业务建立清晰目录，例如：
shared/
├── 待处理/
├── 资料库/
└── 已完成/
修改共享目录会改变运行环境，需要重新应用配置。不要将系统目录或包含大量无关文件的目录设为共享目录。
接入消息平台
选择平台
| 平台 | 接入方式 | 适用场景 |
|---|---|---|
| 个人微信 | 扫码绑定 | 个人沟通、客户跟进 |
| 企业微信 | AI Bot WebSocket | 企业内部协作、业务群 |
| 飞书 / Lark | 扫码创建或填写应用凭据 | 团队协作、海外团队 |
| 钉钉 | 扫码创建或填写 AppKey / AppSecret | 钉钉 Stream 机器人 |
一个助手可同时绑定多个平台。绑定完成后，应发送测试消息确认平台连接、默认通道和回复权限正常。
企业微信
进入“平台绑定”，填写 AI Bot 的 Bot ID 和 Secret，保存后应用配置。私聊和群聊可分别设置开放或关闭。
飞书与 Lark
优先使用扫码方式自动创建并绑定机器人；已有应用可在高级入口填写 App ID 和 App Secret。系统会根据扫码账号识别飞书或 Lark。
扫码期间保持页面打开。整个企智盒同一时间只进行一个微信、飞书 / Lark 或钉钉扫码会话。
钉钉
优先使用扫码方式创建并绑定 Stream 机器人；已有应用可在“使用已有应用（高级）”中填写 AppKey 和 AppSecret。默认允许所有钉钉用户访问。钉钉群聊需要在当前消息中 @机器人，这是钉钉平台的消息投递限制，无法在绑定页关闭。
重新扫码只在成功后替换当前助手的凭据，AppSecret 不会返回界面或写入日志。保存后需要应用配置。
钉钉支持助手在当前对话中发送不超过 20 MiB 的 JPG、JPEG、PNG、GIF 图片、音频、视频和带扩展名的普通文件，包括 PDF 和 Office 文档。音频或视频缺少原生消息所需的时长、封面等信息时，会作为普通文件附件发送；软件重启后缺少当前对话上下文的主动媒体发送暂不支持，可改用共享文件目录交付。
文件接收支持私聊；群聊仅支持钉钉实际投递给机器人的文件消息。群聊需要机器人处理文件时，请将文件发到机器人私聊，或者上传到 Hermes Dock 共享文件 / Dufs 后，在群里通过“@机器人 + 文件链接或路径”发送。
通道与测试消息
通道代表平台上的具体会话。可查看已有通道并向当前助手发送测试消息；个人微信和钉钉通道还可以设为默认通道。测试失败时，检查平台绑定、权限策略和服务状态。
局域网与权限
Web 管理
Web 管理允许同一局域网内的设备访问企智盒。开启后，可从总览页“访问入口”直接打开或复制局域网地址；桌面端退出后，Web 管理也会停止。开关、访问范围、端口和密码位于“设置 → 访问与网络”。
首次启用后立即修改初始访问密码。只允许可信局域网访问，不要直接暴露到公网。Web 管理具备编辑配置、查看敏感环境信息和执行高级操作的能力。
共享文件管理
共享文件管理提供浏览器上传、下载、搜索和删除文件的入口。首次启用后修改初始账号和密码，并限制在可信网络内使用。
宿主机控制
宿主机控制允许助手在授权范围内操作本机文件、通知、剪贴板、应用和桌面输入。该能力默认面向本机自动化场景，所有助手共用同一桌面会话。
macOS 可能需要“辅助功能”和“屏幕录制”权限；未授权时会返回明确错误。无需桌面自动化时，可在设置中关闭宿主机控制。
网络与消息策略
下载镜像或访问模型服务困难时，可在“设置 → 高级设置”中配置宿主机代理。平台绑定页的消息策略用于控制私聊和群聊是否接收消息；处理内部资料时，应按最小开放范围配置。
更新、迁移与排查
更新企智盒
“检查更新”用于获取公开发布的新版本。手动更新会校验安装包后退出应用并完成安装，安装阶段不停止正在运行的 Docker 服务。启动器更新只处理企智盒本身和随版本发布的运行依赖，不同步助手人格和技能。
静默自动更新默认关闭；启用后由系统定时检查。重要业务环境建议先导出快速迁移备份。
内置内容更新与软件更新相互独立。“同步全部助手”和“自动同步内置内容”都会联网获取最新官方 commit，并默认依次尝试 gh-proxy、ghfast 和 GitHub；全部来源失败时明确报错且不写入。自动同步默认关闭，开启时立即同步一次，以后在企智盒启动时和保持打开期间每 24 小时检查一次。
备份与迁移
| 操作 | 影响 | 注意事项 |
|---|---|---|
| 导出快速迁移备份 | 保留配置、凭据、业务数据和用户项目 | 跳过可重建依赖、缓存、临时文件和共享目录；仍包含敏感信息 |
| 导入迁移备份 | 覆盖当前实例配置和数据 | 导入前确认文件来源与目标设备 |
| 恢复出厂设置 | 删除实例配置和业务数据 | 仅保留默认共享目录，操作不可撤销 |
导出运行中的实例时，服务会短暂停止并在完成后恢复。导入前会校验备份，并以相同的快速策略生成当前设备的导入前备份；任一步失败都会中止。旧版生成的 .hdbackup 仍可导入。
常见问题
| 现象 | 优先检查 |
|---|---|
| Docker 检测失败 | Docker Desktop 是否启动、当前账户是否有访问权限 |
| 模型测试失败 | API Key、模型名称、账户额度、代理设置 |
| 平台消息无响应 | 助手是否启用、平台是否绑定、配置是否已应用 |
| 应用配置长时间未完成 | 首页状态、最近日志、网络连接和镜像下载 |
| Web 管理无法访问 | 桌面端是否运行、监听端口、防火墙和局域网地址 |
安全检查
- 修改 Web 管理和共享文件管理的初始密码；
- 不向公网直接开放管理端口；
- 不在聊天、截图或日志中传播 API Key 和平台凭据；
- 只为可信助手开启宿主机控制；
- 定期导出备份，并将备份存放在受控位置；
- 删除助手、导入备份和恢复出厂设置前，再次确认影响范围。