第 1 章 · 产品介绍

什么是 DeskWand？

DeskWand 是一款开源的 AI 桌面 Agent。不同于普通的聊天机器人，它不仅会回答问题，还会自主规划、调用工具、持续推进，直到完成你设定的目标。它运行在你的本地机器上，你可以自由选择使用的 AI 模型，数据留在本地，一切由你掌控。

核心能力

• 多模型支持 — 支持 OpenAI、Anthropic、Gemini、Ollama、DeepSeek、OpenRouter 以及任何 OpenAI/Anthropic/Gemini 兼容端点。使用你自己的 API Key。
• 工具调用 — Agent 自主读写文件、执行 Shell 命令、搜索网页、抓取内容。
• 技能与应用 — 安装和启用技能，注入专业知识和工具指令（PDF 处理、视频编辑、飞书操作等），与插件一起在「应用」视图中统一管理。
• MCP 连接器 — 通过 Model Context Protocol 连接外部工具和数据源（浏览器、数据库、第三方 API）。
• 定时自动化 — 设置单次或周期性任务，到点自动执行。
• 长期记忆 — Agent 会记住你的偏好和项目上下文，跨会话延续。
• 密库（Vault） — 把文件与同步的技能放进本地优先的加密密库，支持端到端加密云备份，服务端无法看到明文。
• Agent 原生 Office — 在任务过程中直接生成、编辑、读取、预览真实的 Word、Excel、PPT 文件，而不是事后导出。
• 用量与成本 — 本机用量看板，按模型、日期与时段拆解 token 与参考成本。反映的是你本机的用量，不是你实际的账单。

典型应用场景

• 代码开发 — 阅读代码库、编写和编辑文件、运行测试、修复 Bug
• 数据分析 — 处理表格数据、生成图表和报告
• 文档撰写 — 起草、编辑和格式化文档
• 网页调研 — 搜索互联网、提取页面内容、汇总调研结果
• 日常自动化 — 设置周期性任务，如日报生成、邮件摘要、数据同步

与普通聊天的区别

普通聊天机器人回答完问题就等你下一条消息。DeskWand 主动推进：它将你的目标拆解成步骤，为每个步骤选择合适的工具（读文件、跑命令、搜网页），执行后评估结果，然后继续。这个循环会一直运转，直到目标达成或你手动暂停。

第 2 章 · 安装与快速开始

系统要求

下载与安装

访问 deskwand.com/zh/#download 下载对应平台的最新版本：

• macOS — 打开 .dmg 文件，将 DeskWand 拖入 Applications 文件夹。
• Windows — 运行 .exe 安装程序，按向导完成安装。
• Linux — 使用 .AppImage、.deb 或 .rpm 包。

首次启动

首次启动时，欢迎页提供三种连接方式：

• DeskWand（登录即用 · 无需配 Key） — 登录后直接使用内置云端模型，无需自有 API Key。
• 连接订阅（账号授权 / 订阅 Key） — 使用已订阅的服务登录，走订阅计费而非按 token 付费。
• 填 API Key（自有 Key） — 选择服务商（OpenAI、Anthropic、Gemini、DeepSeek、OpenRouter、Ollama 等），粘贴 Key 并选择模型。

连接模型之前，输入框保持禁用。以上任一项都可以随时在设置 → API 中修改。

界面概览

主窗口分为五个区域：

第 3 章 · API 配置

支持的服务商

DeskWand 兼容任何遵循 OpenAI、Anthropic 或 Gemini 协议的 API。具体支持以下服务商：

你也可以连接任何暴露 OpenAI 或 Anthropic 兼容 API 的自定义端点。

配置流程

1. 打开 设置 → API。
2. 从列表中选择服务商，或选择「其他供应商」配置自定义端点。
3. 输入你的 API Key。
4. （可选）自定义 Base URL，用于连接代理或自托管端点。
5. 选择或手动输入 模型 ID。
6. 点击 测试连接 验证配置是否正确。
7. 点击 保存设置。

配置方案管理

你可以创建多套配置方案 — 例如工作用 OpenAI，个人项目用本地 Ollama 模型。在 API 设置页面顶部的下拉菜单中快速切换。每个方案独立存储服务商、密钥、Base URL 和模型列表。

视觉模型

如果你的主模型不支持图片理解（多模态），可以单独配置一个视觉模型。Agent 会通过 vision_describe 工具读图：先识别图片内容，再将描述传递给主模型进行推理。

在 设置 → API → 视觉模型 中配置。

搜索配置

在 设置 → API → 搜索 中，你可以为网页搜索和内容抓取配置专用模型。这与主模型分离，允许你为搜索类操作使用更快或更便宜的模型，而保留更强大的模型用于推理。

订阅接入

无需手动输入 API Key，可直接连接你已有的订阅。支持两类：

• 授权接入 — ChatGPT / Codex（OpenAI 账号）、Claude Max（Anthropic 账号，需 Max 订阅 + 额外用量额度，Pro 不支持）、GitHub Copilot、OpenRouter。
• 订阅 Key — 百炼 Coding Plan（阿里云百炼）与 火山方舟 Coding Plan（字节跳动火山方舟）。粘贴套餐 Key 即可，按订阅计费，不按 token 付费。

前往 设置 → API，滚动到订阅接入区域，点击对应服务商的 连接 按钮。

轻量任务模型

在 设置 → API → 轻量任务模型 中，可以为后台琐务指定一个模型——生成会话标题与记忆提取。默认跟随主模型；改指一个更便宜或更快的模型，可以让这些调用不占用主模型额度。

连接诊断

如果遇到连接问题，使用内置诊断工具：设置 → API → 诊断连接。它会逐步检查：

1. DNS 解析 — 能否解析 API 域名？
2. TCP 连接 — 能否到达服务器？
3. TLS 握手 — 连接是否安全？
4. API 认证 — Key 是否有效？
5. 模型验证 — 模型能否正常响应？

每个步骤会报告通过/失败，并提供可操作的修复建议。

第 4 章 · 项目与会话

项目

项目是一个绑定到磁盘目录的命名工作区。会话（对话）归属于某个项目，所有文件操作和工具执行都限定在该目录范围内。这让你可以清晰地区分不同工作流 — 例如一个「官网开发」项目和一个「数据分析」项目。

在侧边栏创建新项目：点击项目区域的 + 按钮，输入名称，DeskWand 会自动创建对应目录。

会话管理

• 新建会话 — 点击侧边栏的 新建 按钮开始全新对话。
• 切换会话 — 点击侧边栏中任意会话即可切换上下文。
• 搜索会话 — 使用侧边栏顶部的搜索栏按标题或项目名查找会话。
• 置顶 / 重命名 / 删除 — 打开会话的行菜单，可将其置顶、重命名或删除。
• 从此处分叉 — 在任意助手回复上选择从此处分叉，即可从该处派生一个新会话，携带到该消息为止的对话；原会话不受影响。

侧边栏组织

侧边栏包含两个可折叠的分组行：最近——所有会话，按时间分组（今天、昨天、最近 7 天、更早）；项目——提供打开项目与新建项目入口。置顶的会话固定在最顶部，运行中的会话显示状态标识。

归档与恢复

归档不再需要的会话以保持侧边栏整洁。右键（或长按）会话，选择 归档。在 设置 → 已归档 中查看和恢复已归档的会话。

上下文压缩

长时间对话可能超出模型的上下文窗口。此时 DeskWand 会自动压缩对话 — 将较早的消息总结压缩，释放空间。你也可以手动触发：输入 /compact 或从快捷菜单选择。

Goal 模式

Goal 模式让 Agent 围绕一个高层目标自主循环工作：

1. 设定目标 — 例如「调研并总结本周最热门的 5 篇 AI 论文」
2. Agent 规划 → 执行 → 评估 → 重复，直到目标达成。
3. 你可以随时暂停、继续或清除目标。
4. 状态栏显示进度：当前轮次、已用 Token、已用时间。

通过快捷菜单（/goal）或操作栏访问 Goal 模式。

第 5 章 · 聊天交互

发送消息

在底部输入框中输入指令，按 回车 发送。输入框下方的状态栏会实时显示本轮已运行的时间，结束后显示总耗时。你还可以：

• 粘贴剪贴板中的图片 — Agent 会识别图片内容（需主模型或视觉模型支持图片）。
• 使用 + 菜单从三个来源添加附件：上传本地文件、从工作区选择、从密库选择。工作区与密库选择器会打开可搜索的多选面板，显示每个文件的路径与大小。
• 输入 @ 引用文件，或直接附加文件 — 二者都会以行内令牌或磁贴的形式出现在输入框中，发送前就能看清这条消息带了什么。
• 展开输入框 — 点击展开按钮或按 Shift+Enter 实现多行输入。

Slash 快捷命令

在输入框中按 / 唤出快捷命令菜单。命令、插件命令与技能共用同一份列表，按最近使用排序（最多保留 20 条）。用标签页筛选：

• 全部 — 单一扁平列表，按召回度排序
• 命令 — 内置操作（compact、goal 等）以及你自己创建的命令
• 技能 — 已安装的技能，用于特定领域任务

技能与提示词命令也可以从 + 菜单进入：那里优先列出你星标的常用技能，并支持新建、编辑、删除提示词命令。

引导进行中的回合

Agent 忙碌时不必干等。你发送的消息会排在输入框上方的队列条中，每条都可以选择引导（注入正在运行的回合）或删除。

被引导的消息会出现在注入位置：投递途中显示引导中，送达后显示已引导。如果引导失败——会话已结束或已停止、消息类型不被支持——会给出原因，并把你的内容回填到输入框。

空闲会话会自动按先后顺序排空队列。手动停止会暂停一次自动排空；上下文压缩期间，队列发送会被阻塞。

活动与计划

输入框上方有一条常驻活动条，显示 Agent 当前在做的事。展开可以看到计划——Agent 为多步任务维护的任务清单——以及进度（如 2/5 完成），同时列出后台运行的子代理。

这份清单由 Agent 自己维护，有两条规则值得了解：同一时刻只能有一项处于进行中；存在未完成条目时，清单不能被标记为已完成。被拒绝的更新不会生效，也不会干扰已显示的进度。

拾取页面元素

在内置浏览器中，选择元素会进入拾取状态——点击页面上的任意元素，它就会成为一条附件，携带该元素的标识与快照。用它把 Agent 精确指向你要的按钮或输入框，而不必用文字描述。

注意时机：拾取的元素会随你的下一条消息发送，不支持即时引导。

流式输出与思考过程

Agent 工作时，回复会实时流式展示。Agent 还可能展示其思考过程 — 在采取行动前的推理步骤。思考过程以可折叠块的形式显示在每条回复上方，你可以展开查看或折叠隐藏。

工具调用卡片

Agent 使用工具时（读文件、跑命令、搜网页），聊天中会出现对应的卡片，显示：

• 工具名称和输入内容
• 输出或结果
• 执行耗时和 Token 用量

卡片按类型配色，紧凑展示 — 点击可展开查看完整细节。

预览面板

右侧面板用来查看 Agent 产出的内容。从标题栏打开产物列表 —— 它收集了本次会话新建或修改的所有文件，每行显示类型图标、文件名，悬停可见完整路径，另有按钮可用系统应用打开。

点击某一行会在应用内打开该文件。文本与图片文件以标签页打开，可以同时保留多个来回切换。Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）会渲染成应用内页面并在内置浏览器面板中显示 —— Agent 刚写完的报告一键就能看。渲染失败时会退回用系统应用打开，并给出提示。

用量与成本

DeskWand 在本机记录 token 用量，数据只存在这台设备。从账户菜单 → 用量统计打开看板，先选区间（今天 / 7 天 / 30 天 / 90 天 / 全部），页面包含：

• 汇总卡片 —— 输入、输出、缓存读、缓存写、调用次数、缓存命中率
• 参考成本 —— 按 pi 价目表折算；无价目的调用不计入，单独计数提示
• 热力图 —— 每日用量，以及「星期 × 小时」的 7×24 时段分布
• 按模型 —— 每个模型一行，可按输出或成本排序，子代理合计单独成行

金额本位始终是 USD，只在显示前按 ECB 每日参考汇率折算，汇率缓存 24 小时。在页头下拉里切换显示币种：USD、CNY、EUR、JPY、GBP、HKD。

这是估算，不是账单。看板只统计这台设备上发起的调用，并按公开价目表定价，不读取 provider 上报的金额 —— 订阅制账号上报的金额本来就不是实际扣费，自定义 relay 甚至可能恒为 0。把它当作自己用量的一个持续估算即可。

消息操作

鼠标悬停在任意消息上会显示其操作：

• 复制消息 — 复制文本到剪贴板。
• 在文件夹中定位 — 在文件管理器中打开消息引用的文件。
• 从此处分叉 — 在助手回复上，从该处派生新会话（见第 4 章）。

回答模型的问题

有时 agent 需要你拍板，它会直接在对话里提问。选择一个选项、回答是或否，或选其他…自己填。多个问题时，提问卡会显示待答数量，各题作答顺序不限。提交会送出你已填写的部分；跳过则把该题交回给 agent 自行决定。

权限审批

某些工具执行前需要你的授权 — 特别是写入文件和执行 Shell 命令。当工具需要权限时：

• 弹出对话框，显示工具名称、输入内容和警告。
• 你可以选择允许（本次）、始终允许（本次会话内）或拒绝。
• 需要管理员权限的命令会提示输入系统密码（不会存储）。

语音对话与朗读

DeskWand 能把话听进去、也能念出来，而且语音引擎跑在你的机器上 —— 音频不会发给任何语音服务。模型按需下载，所以在开启某个能力之前不会装任何东西。

听写。点输入栏里的麦克风，或按住提示里写的那个按键说话。文字落到输入栏里，发送前还能改。第一次使用会先问你要不要下载语音模型（约 140 MB）。

语音对话。应用栏上的语音按钮打开一个全屏语音界面。像平常那样说话：停顿一下就会把问题发出去，回答则逐句念回来。它正在说话时你开口，它会停下来听你说。键盘也一直可用 —— 同一个会话照样接受打字输入。

• 语音对话是一类独立的会话，从应用栏开始与继续，切走页面也会在后台继续跑。
• 语音轮次只保留只读检索类工具：它会查资料并跟你聊，不会改你的文件，也不会执行命令。
• 你停下说话后，转写会被自动清理一遍；回答也是按「听着顺」而不是「看着顺」写的 —— 短句，没有标题、列表、链接或文件路径。
• 随时可以插话，音频会立刻停下。

朗读。每条助手回复上都有一个播放按钮把它念出来，正在念的那几个字会高亮。可以暂停，也可以在它还在准备时取消；读失败可以重试。

选音色。音质、音色、语速与来源在设置 → 能力 → 语音里一处配置，朗读与语音对话共用这一份设置。语音可以跑在本机，也可以走你配置的云端音色 —— 见第 12 章。

只想要在任意应用里听写、不要整个 Agent？那是 DeskWand Voice。

第 6 章 · 工具系统

工具工作方式

Agent 会自动为每一步选择并使用最合适的工具 — 你不需要手动指定。只需描述你想做什么，Agent 会自行决定是读文件、跑命令、搜网页，还是组合使用多种工具。

文件工具

Shell 命令（Bash）

Agent 可以在你的工作目录中执行 Shell 命令。用于安装依赖、运行脚本、构建项目等操作。需要管理员权限的命令会提示输入密码。

浏览器工具

DeskWand 内置浏览器，Agent 可以直接驱动它——导航、读取页面、并与之交互：

网络工具

网络访问配置

在 设置 → 网络访问 中选择搜索供应商。可用选项：自动选择、OpenAI、DeepSeek、Exa、Brave、Parallel、Tavily、Perplexity、Gemini。每个供应商可使用独立的 API Key，也可以继承主 API 配置的密钥；自动选择会在某个供应商不可用时沿备用链回退。

Office 文档

Word、Excel、PPT 在这里是 Agent 原生能力：在任务过程中就地生成、编辑、读取，产出的是真正的 .docx / .xlsx / .pptx 文件，而不是一段还要你手动导出的文字。

读取。四个内置工具把文档内容交给模型：office_read_docx、office_read_xlsx（可指定单个 sheet）、office_read_pptx 返回 Markdown；office_read_pdf 对文本页返回文字，扫描页则渲染成图片交给视觉模型。

生成与编辑。DeskWand 内置了自己的文档引擎，已在 PATH 上 —— 单文件二进制，无依赖。它能产出 Word 报告、信函、备忘与提案（含模板、修订痕迹、批注、页眉页脚、目录）；带公式、图表、数据透视表的 Excel 工作簿；带版式和演讲者备注的 PowerPoint 演示文稿。还能拆分或合并幻灯片，以及把 CSV/TSV 数据导入表格。

预览。生成和修改后的文件直接在预览面板中打开 —— 见上文预览面板。

计划、记忆与视觉

还有几个工具负责 Agent 自身的账务：

子 Agent

面对大任务时，Agent 可以把活儿派给子 Agent —— 各自持有独立上下文、并行推进。内置四个：代码探索、编码实现、架构规划、审查；也可以在设置 → 子代理里新增自己的。

每个子 Agent 可以跟随主模型，也可以单独指定模型和思考强度。未配置全局默认子代理模型时，子代理工具不可用。子 Agent 的用量归因到它实际运行的模型，并在用量看板中单独成行汇总。

第 7 章 · 技能系统

什么是技能？

技能（Skill） 是一个可复用的扩展包，为 Agent 注入特定领域的专业知识、指令和工具配置。技能使 Agent 在处理 PDF、视频编辑、财务分析、天气查询、飞书/Slack 等任务时更加专业高效。

技能从哪来

每个技能都带来源标签，一眼就能看出它的出处：

设置 → 技能把它们分为三组：内置技能、自定义技能、插件与导入。

内置技能

DeskWand 预装了一套内置技能，覆盖常用任务场景。你可以在 设置 → 技能 中单独启用或停用每个技能。内置技能无需安装，开箱即用。

举两个内置技能的例子。officecli 系列驱动内置文档引擎生成、检查、修改 Word / Excel / PowerPoint 文件。image-ocr 用本地 OCR 引擎从图片、截图、扫描件中提取文字 —— 支持中英文，全程离线，不上传任何内容。

技能市场

在技能云中浏览、安装和更新社区贡献的技能：

1. 从侧边栏或设置 → 技能中打开 技能云。
2. 按分类浏览或搜索特定技能。
3. 点击技能卡片查看详情（描述、版本、下载量）。
4. 点击 安装 将其添加到你的技能库。

已安装的技能出现在 我的技能 列表中：可启用或停用、把常用的星标置顶，或删除。市场会在有新版本时显示更新标识。

插件是更大的单位，在 插件与导入 → 浏览插件 中查看。一个插件可以打包技能、命令、子代理、扩展、钩子和 MCP 服务的任意组合。

技能云（需登录）

登录 DeskWand 账号可解锁云端功能：

• 同步 — 在多台设备间同步技能
• 分享 — 与团队分享技能
• 发布 — 将自己的技能发布到市场

密库技能

密库同时是一个私有的技能通道：把技能上传到密库，它就会随端到端加密备份一起走，另一台机器解锁密库后即可恢复。列表中来源标为密库的技能就存放在那里。

上传成功后，本地原件会被删除——密库中的副本成为唯一来源。密库本身见第 11 章。

自定义技能

你可以从本地文件夹导入技能：前往 设置 → 技能 → 插件与导入，点击 从文件夹安装。适用于测试自己编写的技能，或使用同事直接分享的技能。

第 8 章 · MCP 连接器

什么是 MCP？

Model Context Protocol（MCP） 是一个开放标准，用于将 AI 模型连接到外部工具和数据源。MCP 连接器让你的 Agent 能够与浏览器、数据库、API 等服务交互 — 就像使用内置工具一样。

连接器在哪里

连接器在 应用视图的 连接 标签页里管理 —— 另外两个标签页是技能与插件。从应用栏的更多进入，见第 2 章。

连接器目录

目录里列着五十多个现成的服务 —— Notion、Linear、Sentry、Stripe、Cloudflare 等等 —— 按分类分组，分类芯片与「添加」收在吸顶工具栏里。点一张卡片即可添加该服务器，它会写进你 Agent 目录下的 mcp.json。

• 多数服务用 OAuth 登录：点卡片，在弹出的浏览器窗口里授权，卡片随即显示「已授权」。
• 用 API Key 的服务会在卡片上问你要密钥，并存进 mcp.json。
• 你自己的服务器始终排在最后，目录条目也不会认领或覆盖你自己添加的同名服务器。
• 添加连接器不等于启用它。想让它的工具可用时再打开。

添加自己的连接器

点添加，粘贴一段 mcpServers 配置，一次一台 —— 与 Claude Desktop、Cursor 用的是同一种格式。支持两类：DeskWand 以命令形式启动的本机服务器（command 配 args，可选 env），以及用 URL 访问的远程服务器。形如 ${VAR} 的占位符会被展开；一段里含多台服务器会被拒绝，因此你可以一台一台地贴。

内置连接器

有两个连接器是随 DeskWand 一起内置的，不出自目录：

• 邮箱把一个邮箱变成一套工具。填好账号（发信走 SMTP、收信走 IMAP）之后，Agent 就能列出账号、查找邮件、发送、回复（含全部回复与转发）以及保存附件。各邮件服务显示自己的厂商 logo。
• Computer Use 让 Agent 看见屏幕、并操作鼠标与键盘。它默认关闭，开启时会向你要需要的系统权限 —— 见第 12 章。

管理连接器

启用之后，连接器的工具即可在对话中被 Agent 调用。每张卡片自带状态 —— 已连接、已授权、未启用、已停用或连接失败 —— 并给出对应的操作：

• 连接、重新授权或断开该服务器。
• 测试连通性，不必先开一个对话。
• 它提供了多少工具，以及这些工具被调用过多少次。
• 管理或移除这个条目。

凭据与服务器定义本身都以明文存在本机的 mcp.json 里，因此那份文件有多私密，你贴进去的内容就有多私密。

第 9 章 · 定时任务

概述

定时任务让你可以设定指令在指定时间自动执行 — 就像一个为你 AI Agent 设置的闹钟。适用于日报生成、周期性数据检查、定期调研等场景。

日历视图

从应用栏的自动化进入定时任务管理。日历视图以日/周/月三种方式展示所有任务。点击空白区域创建新任务，点击已有任务进行编辑。

任务模式

配置任务

1. 选择模式（单次、每天、每周）。
2. 设置执行时间 — 点击添加时间点（格式：HH:MM）。
3. 输入指令 — 触发时 Agent 要执行的内容。
4. 可选指定工作目录（默认为当前项目目录）。
5. 切换 启用 开关激活任务。

监控与控制

• 查看每个任务的下次执行时间和最近执行状态。
• 暂停/恢复单个任务，无需删除。
• 运行中的任务会在侧边栏创建会话 — 进度像普通对话一样可见。

动态

动态是应用栏上的一个页面，它会替你去找。它读你最近的提问，以及记忆里记录下来的关注点，然后找出值得一读的东西，写成一份列表。它每天最多跑一次，用的是设置 → API 里配置的轻量任务模型。

一次运行不会创建会话，也不会发系统通知，所以它从不打断你。可以在欢迎页或动态页本身打开它，随时也可以再关掉自动更新。

每条都带来源的真实发布时间、一份本地化摘录和一张配图。点开一条会在右侧阅读器里展开：正文按 markdown 渲染，并提供一个「在浏览器中打开完整页面」的入口。不想看的条目可以单条剔除。

听动态。标题栏上的耳机图标会把动态当成口语稿念出来，并自动续到下一条 —— 一批条目可以像播客一样连着听。播放时图标会有动画。

• 立即更新马上跑一轮；页头会显示下次自动更新的时间。
• 暂停自动更新停掉计划，但不会丢弃已经收集到的内容。
• 未读筛选列表，全部已读清掉未读计数。
• 清空全部动态会删掉条目、正文与配图；运行记录本身保留。

第 10 章 · 记忆系统

记忆如何工作

DeskWand 会建立你的偏好、历史工作和项目上下文的长期记忆，让后续会话更加高效。记忆分为两种：

记忆不会自动注入会话。只有当当前任务可能依赖某些持久信息时——你声明过的偏好、做过的决定、这个项目的约定——Agent 才会通过记忆工具去检索。后台还会每 10 个用户回合审查一次稳定画像信息，并在你明确要求时写入。

启用或停用

本地记忆位于 设置 → 个性化，与全局 AGENTS.md 规则在同一页。新安装默认关闭。

关闭后会停止选择性后台学习、显式记忆写入与按需检索；已有数据会保留，重新开启后继续生效。

清除本地记忆

同一区域只有一个破坏性操作：删除本地记忆——它会移除这台电脑上存储的全部记忆。不再有单独的重建或按范围重置入口。

第 11 章 · 密库

什么是密库？

密库是你的个人加密存储：本地文件加上端到端加密的云备份。加密在你的机器上完成，数据离开前就已是密文，服务端拿到的只是它读不懂的内容。

打开密库

从应用栏的更多里打开密库（见第 2 章）。页头提供上传文件与同步，列表可按文件、技能、会话筛选（会话标记为敬请期待）。每行菜单提供在文件夹中显示、导出、删除。

上传与同步

上传的文件会先在本地加密、存储，配好云备份后再同步。同步按需触发，状态显示在页头：瞬时完成的同步不会闪出中间态，横幅区域只留给错误。

在对话中使用密库文件

密库也是附件的来源之一：在聊天输入框的 + 菜单里选择从密库选择，即可在可搜索的列表中挑选文件。见第 5 章。

加密与恢复

首次设置加密云备份时，DeskWand 会显示一段恢复码并要求你保存。如果机器和系统密钥链都不可用，这段恢复码是回到数据的唯一途径——请存放在你信任的地方。

恢复只在本地索引缺失、且密库中没有任何文件时可用。这个限制本身就是安全措施：你不会不小心把两个不同的密库合并到一起。

用量与限制

密库页面显示本地已用空间，以及云端备份的已用额度与配额。

• 单个文件必须不超过 20 MB。
• 云端配额用尽不会回滚本地副本——文件保留，只是同步失败。
• 同步需要登录；未登录时密库仍可离线使用。
• 符号链接、以点结尾的名称、保留名，以及模块之外的路径不会同步。
• 把技能上传到密库会删除本地原件——密库中的副本成为唯一来源（见第 7 章）。

随手记

随手记是应用栏上的一个页面，用来记下任何你想留着的东西 —— 一个念头、一条链接、还没想完的计划。每一条都以 markdown 文件存在 ~/.deskwand/vault/ideas 下，所以它就是普通文件：用任何编辑器打开、放进版本管理、或者在 DeskWand 之外改，都不会出问题。

可以在随手记页面里写，也可以直接让 Agent 记一笔，它会归到那里。页面按时间倒序列出；点开一条即可阅读或编辑，处理完可以归档。

因为它们是密库里的文件，Agent 能像读其他文档一样读取和搜索 —— 问它某个话题你写过什么，它可以去找。

第 12 章 · 设置与偏好

设置都有什么

设置分为九个标签页：通用、API、能力、子代理、个性化、远程控制、日志、已归档、关于。有三处特意不放在这里：连接器与技能共用应用视图，定时任务在自动化 —— 两者都在应用栏的更多里。

外观

在 设置 → 通用 中配置：

• 主题 — 浅色、深色或跟随系统。
• 调色板 — 七套基础调色板：Neutral、Stone、Zinc、Mauve、Olive、Mist、Taupe。
• 强调色 — 十七套强调色：Amber、Blue、Cyan、Emerald、Fuchsia、Green、Indigo、Lime、Orange、Pink、Purple、Red、Rose、Sky、Teal、Violet、Yellow。下拉框里会先以色卡显示颜色，再让你挑。
• 语言 — English 或 中文。
• UI 字号 — 12–20 px；整个界面按这个基准字号缩放。

能力

能力标签页里放的是需要先装东西、或先获得授权才能用的可选项。每一项在你打开之前都是关闭的，而且各自只下载自己需要的东西 —— 不会在后台替你拉取任何内容。

其中三项是完全跑在本机上的引擎：

• 语音输入 — 听写。第一次用麦克风时会下载语音识别模型（约 140 MB）。
• 语音 — 朗读与语音对话。音质、音色、语速与来源都在这里设置，两个功能共用这一份。本机音色分档，档位越高下载越大。
• 文字识别（OCR） — 从图片与截图里读出文字，图片不离开你的机器。

Computer Use 是第四项，也是唯一一项会「动手」而不只是「读」的能力：Agent 可以看见屏幕、并操作鼠标与键盘。它默认关闭；在 macOS 上，这个标签页会列出还缺哪些权限 —— 辅助功能与屏幕录制 —— 每一条都配一个按钮，直接打开系统设置里对应的面板。屏幕录制重启后生效；权限只有在真正核实通过之后，才会被报告为已授权。

自动技能学习

默认关闭。开启后，Agent 可以在对话中自动发现并学习新技能，并定期整理已有技能。项目模式下不支持自动学习。

匿名使用统计

DeskWand 收集匿名使用统计数据以帮助改进产品。仅包含随机设备标识和应用版本信息 — 不包含任何个人数据。可在 设置 → 通用 → 匿名使用统计 中关闭。

版本更新

在 设置 → 关于 中可以查看当前版本、按需检查更新，也可以打开手册或反馈问题。DeskWand 也会在后台自动检查；新版本下载完成后，应用栏底部的帮助按钮会变成更新按钮，点一下即可打开更新对话框。

第 13 章 · 常见问题与排障

API 连接失败 — 我该检查什么？

1. API Key 是否正确且未过期？
2. Base URL 是否正确？（尤其在使用代理或自托管端点时。）
3. 运行 设置 → API → 诊断连接 进行逐步排查。
4. 检查网络 — 防火墙或 VPN 可能阻止 API 连接。

我的模型不在列表中 — 如何使用？

切换到 手动输入 模式，直接输入模型 ID。确保选择的协议（OpenAI / Anthropic / Gemini）与模型 API 匹配。

Agent 执行命令时反复报错

• 确认工作目录存在且可访问。
• 对于系统级命令（安装、构建），检查是否需要管理员权限。
• 查看聊天中的工具调用卡片，找到具体错误信息。

如何导出日志用于求助？

前往 设置 → 日志，点击 导出诊断包。这会生成一个 ZIP 文件，包含应用日志、脱敏后的运行环境信息，以及最近会话和错误的元数据摘要。将此文件发送给 DeskWand 团队可加快排障速度。

可以离线使用 DeskWand 吗？

可以 — 通过 Ollama 使用本地模型。安装 Ollama，拉取模型（ollama pull llama3），然后在 DeskWand 中配置 Ollama 端点。本地模型不需要互联网连接。

我的数据存储在哪里？

所有数据均为本地优先。你的 API Key、对话记录、设置和记忆都存储在本地机器上。除非你明确使用云端功能（技能云同步、OAuth 订阅）或启用遥测（匿名且最小化），否则不会发送到 DeskWand 服务器。

如何获取帮助或报告 Bug？

• GitHub — github.com/deskwand/agent — 提交 Issue 或发起 Discussion
• 官网 — deskwand.com

本手册对应当前版本 DeskWand 1.0.46。