Keural Duo
在您的电脑上工作的常驻智能体。涵盖安装、对话、例行任务、Telegram、电脑使用以及 Mate & Morph。
Duo 是桌面应用在本机（或已连接的 DGX Spark）上安装的常驻智能体。它在隔离的沙箱中运行，可通过侧边栏的 Duo 或 Telegram 与其对话，并执行您登记的例行任务。基于 NVIDIA NemoClaw 和 OpenClaw。
Duo 仅适用于桌面应用。
安装
在 设置 → Duo → 运行环境 中选择模型，然后点击要运行的位置所在行的 安装。未选定模型或磁盘空间不足时，安装按钮会被禁用。
运行位置与要求
| 运行位置 | 要求 |
|---|---|
| 本机（macOS） | Apple 芯片，16GB 或以上内存。容器运行时由应用直接安装，因此无需 Docker Desktop、Homebrew 或管理员密码。 |
| 本机（Windows） | WSL 2。首次请点击 准备 Windows，系统会安装所需组件。可能会要求您重启电脑或允许管理员权限。若虚拟化已关闭，请在 BIOS 中开启。 |
| 远程设备（DGX Spark） | 请先连接 Spark并启动模型。若 Spark 防火墙已开启，请输入一次 Spark 账户密码以开放两个端口（密码不会被保存）。 |
安装需要至少 20GB 磁盘空间，建议 40GB 以上。空间不足时，安装按钮会被锁定，并显示“需要 {need} GB · 剩余 {free} GB”。
模型
| 选项 | 说明 |
|---|---|
| 本机模型 | 使用已下载的本地模型中正在运行的模型。显示为“{model} · 与对话使用相同的模型”。 |
| DGX Spark | 已连接的 Spark 正在运行的模型。 |
| 云端 | 套餐包含的 Duo 模型。需登录后才会显示。 |
| 网关 | 使用在 设置 → 模型 → 网关 中连接的服务器模型。需要该服务器的地址和 API 密钥。 |
安装后，仍可在 模型 行更换模型。同一类型之间可通过“切换”立即更换；在本机、云端、网关之间更换类型时，需要重新安装。重新安装不会删除例行任务。若要更换运行位置，请先删除，再安装到其他位置。
安装步骤
安装按以下顺序进行：确认本机 → 准备容器运行时 → 安装 NemoClaw → 启动模型（云端或网关则准备模型使用权限）→ 创建沙箱 → 设置 Duo → 检查运行状态。当前步骤显示在按钮和进度卡片中。出现“耗时稍长，请保持应用打开。”时，也请勿关闭应用。
安装停止时，请在安装失败时中根据屏幕提示确认原因。
其他账户或工作区的 Duo
Duo 每台设备只能有一个，并归属于安装时的账户和工作区。若您登录其他账户或切换到其他工作区，设置中的 Duo 会显示为“未安装”，侧边栏的 Duo 和 Mate & Morph 也会隐藏。此状态下点击 安装，会弹出确认窗口，提示现有 Duo 及其对话和例行任务将被删除。点击 重新安装 后，现有 Duo 会被删除并重新创建。回到原账户或工作区时，该 Duo 会重新显示。
若残留之前安装的 Duo，会先清理再安装。清理失败时，将显示“无法删除现有的 Duo。请重新安装。”
安装失败时
安装停止时，设置 → Duo 会显示错误文字。请同时确认文字后括号内的代码。解决原因后，再次点击安装。
| 屏幕提示 | 原因 | 解决方法 |
|---|---|---|
磁盘空间不足，安装已停止。请确保至少有 {need} GB 可用空间后重新安装 | 主文件夹所在磁盘的可用空间不足 20GB。 | 释放 20GB 以上空间（建议 40GB）。 |
| 无法准备容器运行时。请检查网络连接后重试 | 无法下载安装文件。多数情况是公司防火墙或代理导致。 | 检查网络连接。若在公司网络中，请向 IT 人员申请允许下载来源中的地址。 |
| 无法删除先前的 Duo。请重新安装。 | 无法清理此设备上残留的旧 Duo。 | 完全退出应用后重新打开，再点击安装。仍然失败时，请查看 macOS 标签页中的相同提示。 |
| 存在其他账户或其他工作区的 Duo。 | 此设备上的 Duo 属于其他账户或工作区。 | 点击重新安装会删除该 Duo 并重新安装。若要继续使用原 Duo，请切换到原账户或工作区。 |
| 您的套餐不支持 Duo 使用云端模型。 | 当前工作区的套餐不包含云端 Duo。 | 将模型改为此设备模型、DGX Spark 或网关，或确认套餐。 |
| 登录后即可使用云端模型。 | 当前未登录。 | 登录后再次安装。 |
| Duo 的模型未运行。请先启动，然后重新应用。 | 此设备上的模型未运行。 | 在设置 → 模型中运行模型，然后安装。 |
| 耗时稍长，请保持应用打开。 | 首次安装需要下载的文件较多。 | 保持应用打开并等待。笔记本电脑请勿进入睡眠模式。 |
仍无法解决的，请在设置 → 支持中联系支持。请一并提供屏幕提示、括号中的代码和设备类型（macOS、Windows 或 Spark），以便更快找到原因。
设置 → Duo 界面
| 区域 | 内容 |
|---|---|
| 状态 | “在 {位置} 运行中” · 已停止 · 启动中 · 未安装 · 无服务器（Spark 连接断开时） |
| 运行环境 | 模型选择，本机 / 远程设备行中的安装、启动、停止、删除，沙箱 ID 与 NemoClaw 版本 |
| 聊天应用 | Telegram 连接 |
| 连接 | GitHub、网络搜索 |
| 电脑使用 | 权限、可读取的文件夹、行动前规则、始终允许的应用、Mate & Morph |
| 对话记忆 | 上下文用量、对话压缩、新对话 |
| 新功能（Windows） | Windows 电脑连接、共享文件夹、应用访问确认、最近任务 |
进行耗时较长的操作（安装、切换模型、应用聊天应用设置、删除）时，其他区域会被锁定。所有确认窗口均在应用内。只有在开启电脑使用或扩大规则时，才会出现操作系统的确认窗口。
对话
点击侧边栏的 Duo（代码模式下不显示）。输入框提示为“向 Duo 发送消息”。连接断开期间发送的消息会显示为“{n} 条等待发送”，连接恢复后再投递。在输入框中发送 /new 时，会询问是否开始新对话。
开启顶部的 Duo 信息 后，侧边面板中会显示以下卡片。
| 卡片 | 内容 |
|---|---|
| 当前任务 | 休息中或进行中的任务、已用时间、使用过的工具 |
| Duo 设置已更改 | 仅当沙箱设置与 Keural 最后确认的内容不一致时显示。会列出已更改的部分（聊天应用及可与其对话的人 · 工具与权限 · 已连接的服务 · 模型连接 · 其他）。若更改是您自己做的，请点击 接受更改。 |
| 沙箱 | 就绪 / 错误，模型响应正常 / 无响应，GPU（CUDA）使用情况，容量 |
| 模型 | 模型名称、位置（本机 · DGX Spark · 云端）、上下文用量 |
| 例行任务 | 参见下方的例行任务 |
| 连接 · Telegram | 连接摘要，点击后直接进入设置。 |
| 工作文件 | Duo 在沙箱工作文件夹中创建的文件 |
点击 后台任务 按钮，可查看 Duo 运行子智能体时的列表。
对话记忆
在 设置 → Duo → 对话记忆 中，可以以令牌数和百分比查看“当前使用的上下文”。点击 压缩 可精简对话，点击 新建 可开始新对话。当前对话会被保留。若 Duo 正在工作，需等其完成后再操作。若对话长到模型无法处理，会显示“对话过长，模型无法处理，因此 Duo 无法回答。”此时请压缩或开始新对话。
例行任务
您可以对 Duo 说“每天早上 9 点……”之类的话，Duo 会提出建议，应用会以 要创建此例行任务吗？ 卡片（任务、日程、运行位置）进行确认。点击 创建例行任务 即可登记。修改或删除时，同样会以该卡片确认。
| 项目 | 内容 |
|---|---|
| 周期 | 一次（最多 365 天后）· 每天 · 工作日 · 每周 · 每 N 分钟（5 到 1,440 分钟） |
| 运行位置 | Keural 应用中的 Duo 对话，或 发送到 Telegram |
| 数量 | 启用 10 个，共 50 个 |
| 有效期 | 默认 7 天，最长 30 天。过期后显示“已过期”。 |
| 错过 | 若应用已关闭，导致比预定时间晚 10 分钟以上，则不会运行，并标记为“已错过”。 |
| 失败 | 连续失败 3 次后，显示“因失败已暂停”。 |
在 Duo 信息面板的 例行任务 卡片中可以开启或关闭任务。点击 更多 可执行 立即运行 或 删除。每行都会显示下次运行时间和状态（已发送 · 已错过 · 失败 · 已暂停 · 已过期）。例行任务的结果会发送到 Duo 对话或 Telegram，并同时弹出桌面通知（立即运行 会静默执行）。例行任务仅在应用打开时运行。
聊天应用（Telegram）
在 设置 → Duo → 聊天应用 → Telegram → 连接 中按照指引操作。
- 在 Telegram 中打开 @BotFather，发送
/newbot，然后为机器人设定名称和用户名。 - 粘贴 BotFather 提供的 机器人令牌，然后点击 确认。请妥善保管令牌，任何拥有它的人都可以控制该机器人。
- 用手机扫描二维码打开机器人，然后点击 开始。若没有收到消息，请将屏幕上的代码发送给机器人。
- 出现“仅
{名称}可以通过私信与机器人对话”后，点击 添加，再点击 应用。
应用后 Duo 会重新启动（对话和文件保持不变）。此后，从手机发送的消息会在 Duo 对话中以“来自 Telegram”的形式显示。只有连接的那一个人可以通过私信与机器人对话。若要断开，请点击 断开连接，然后点击 应用。连接 Telegram 后，例行任务的审批也会通过 Telegram 接收（在此功能推出之前连接的，请在“在 Telegram 中批准例行任务”行中重新粘贴令牌并开启）。
在 BotFather 获得的令牌，每个账号只能在一台设备（Duo）上启用。要连接其他设备，请先解除原设备的注册，再重新使用该令牌。
即使对话是从 Telegram 发起的，应用操作的审批也只能在 Keural 应用窗口中进行。
连接
位于 设置 → Duo → 连接。
| 服务 | 方法 |
|---|---|
| GitHub | 粘贴 个人访问令牌（提供创建精细令牌的链接）并确认，或点击 使用 GitHub CLI 继续，使用本机 gh 的登录状态。若未安装 CLI，会显示安装链接；若未登录，会打开登录窗口。连接或更改后，Duo 会重新启动。 |
| 网络搜索 | Duo 会使用您在 设置 → 通用 → 网络搜索 中选择的方式（快速搜索 · Keural 搜索 · 您自己的搜索服务中的 Tavily、Brave 或 SearXNG）。 |
令牌和密钥仅在确认时一次性传递给应用，并会立即从界面中清除。Duo 的网络搜索需要开启 电脑使用。
电脑使用
在 设置 → Duo → 电脑使用 → 允许 Duo 使用此电脑 中开启后，Duo 可以打开并使用本机应用、读取您指定的文件夹，以及创建例行任务。开启时会确认：“Duo 将重新启动约一分钟。共享的文件夹会立即可读，应用在使用前会询问您。”
| 项目 | 内容 |
|---|---|
| macOS 权限 | 辅助功能（用于在应用中点击和输入）和 屏幕录制（用于查看屏幕）。若未允许，请前往 打开系统设置。 |
| Duo 可读取的文件夹 | 仅限通过 添加文件夹 指定的文件夹。整个主文件夹或系统文件夹等范围过大的文件夹无法添加。 |
| Duo 行动前 | 每次询问（默认）· 无需询问直接执行 · 交给您来做。切换为无需询问直接执行时，会再次确认。 |
| 始终允许的应用 | 在审批窗口中选择 始终允许 的应用列表。点击行中的 × 可移除。 |
即使是 无需询问直接执行，发送、删除、覆盖、付款、提交、登录、发布、取消等敏感步骤，以及 Enter、Backspace、⌘Q 等按键，仍会先行询问。始终允许同样不适用于敏感步骤。
当 Duo 在等待许可时，输入框上方会显示“Duo 正在等待批准”，点击 确认 即可打开审批窗口。审批窗口中的选项为 拒绝 · 仅允许一次 · 始终允许。Mate & Morph 也会显示“正在等待批准”。审批只能在该窗口中进行。
Duo 打开网页时，应用只会在不询问的情况下打开其返回的搜索结果和链接地址。对于 Duo 自己编写或修改的地址，审批窗口会显示完整地址并进行询问。
Mate & Morph
这是 Duo 的桌面角色。在 设置 → Duo → 电脑使用 → Mate & Morph → 在桌面上显示 中开启后，它会出现在屏幕上。然后选择 角色（Mate · Morph · 两者）和 大小（小 · 中等 · 大）。
- 仅在 Duo 运行且对话已准备好时显示。若切换到其他账户或工作区，或套餐不允许使用 Duo，则会隐藏。
- 单击角色一次会打开输入框，可以直接与其对话；快速双击则会打开应用。角色旁边会显示状态（待机中 · 工作中 · 已完成 · 受阻 · 需要输入 · 正在等待批准）以及上一次回答失败的原因。
- 右键菜单：隐藏 · 标记为已读 · 打开 Duo · Duo 设置。菜单栏（托盘）菜单中也有 显示 / 隐藏 Mate & Morph。
在 Windows 上
Windows 版应用中的 Duo 运行在 WSL 发行版内，对话、例行任务、Telegram、审批、Mate & Morph 和电脑使用的支持与 macOS 相同。应用操作使用 Windows UI 自动化，因此部分应用以及密码输入框、UAC、终端等安全窗口，Duo 不会直接操作，而是交由您自行处理。
在 设置 → Duo → 新功能（Windows 电脑）中，可以确认 Duo 连接、共享文件夹（Duo 只读取您选择的文件夹）、检查 应用访问，以及查看 最近任务。在 Windows 上，除应用操作外，Duo 还可以进行 软件安装（仅限准确的包 ID）和 Wi‑Fi 连接（已保存的配置文件）。发送、删除、覆盖、安装和网络更改，始终会先询问。
删除
在 设置 → Duo → 运行环境 中，点击已安装位置行的 删除，然后在“要从此设备删除 Keural Duo 吗？”中点击 删除。对话记录、例行任务和工作文件会与沙箱一同被删除。在 macOS 上，Duo 专用的容器虚拟机也会被删除。DGX Spark 上的 Duo 只有在 Spark 连接时才能删除。
常见提示
| 提示 | 含义 |
|---|---|
| Duo 未在运行 | 在 设置 → Duo 中点击 启动。 |
| 需要最新版桌面应用 | 请更新应用。 |
| 模型未在运行。请先启动模型，然后再应用。 | 本机或 Spark 模型已关闭。请先运行模型。 |
| 模型连接已断开。请检查登录状态。 | 云端模型 Duo 的访问权限已断开。请重新登录。 |
| 此工作区的套餐无法使用 Duo。 | 云端模型 Duo 需要套餐。请切换到本地模型或检查套餐。 |
| 存在其他账户或其他工作区的 Duo。 | 安装会删除该 Duo。回到原账户或工作区即可继续使用。 |
| 无法删除现有的 Duo。请重新安装。 | 无法清理之前安装的 Duo。请再次点击安装。 |
IT 管理员详细信息
要求
| 运行位置 | 标准 |
|---|---|
| macOS | Apple 芯片（arm64），16GB 或以上内存。Duo 专用虚拟机（Colima，vz）使用 4 个 CPU、9GiB 内存和 40GiB 磁盘（按需占用）。 |
| Windows | WSL 2（内核 5.15 或以上），x64 或 ARM64。以 Keural-Duo 名称安装 Ubuntu 24.04 发行版，并在其中使用 rootless Podman。无需 Docker Desktop。 |
| DGX Spark | Docker 正在运行，剩余磁盘 20GB，可用内存 8GB 以上 |
| 通用 | 主文件夹所在磁盘需有 20GB 以上可用空间（建议 40GB） |
在 Windows 上，安装时会在 %USERPROFILE%\.wslconfig 的 [wsl2] 中使用 networkingMode=nat。使用镜像网络（mirrored）的电脑无法安装。
安装位置
| 运行位置 | 路径 |
|---|---|
| macOS 运行时 | ~/.keural-runtime/（Colima、Lima、Docker CLI、日志） |
| macOS 开机自启 | ~/Library/LaunchAgents/kr.mkd.keural-duo-colima.plist、kr.mkd.keural-duo-gateway.plist、kr.mkd.keural-duo-sweeper.plist |
| NemoClaw CLI | ~/.local/bin/nemoclaw |
| Windows | WSL 发行版 Keural-Duo |
| 应用记录 | 应用数据文件夹中的 keural-duo@<服务器>.json、keural-duo-routines@<服务器>.json、keural-duo-rules@<服务器>.json |
| 日志 | ~/.keural/logs/、~/.keural-runtime/colima.log、gateway.log，以及应用数据文件夹中的 keural-duo-install.log |
下载来源
请在防火墙或代理中开放以下地址。下载的文件为固定版本，并通过 SHA-256 校验。
| 地址 | 下载内容 |
|---|---|
github.com | Colima v0.10.3、Lima v2.2.1、buildx v0.38.2（macOS），Podman 工具（Windows） |
download.docker.com | Docker CLI 29.9.3（macOS） |
www.nvidia.com | NemoClaw 安装脚本（v0.0.134） |
ghcr.io | OpenClaw 沙箱镜像 |
api.telegram.org | Telegram 连接 |
Keural 服务器（api.keural.ai 等） | 云端模型、登录 |
若使用网络搜索或 GitHub 连接，还会访问 api.tavily.com、api.search.brave.com、api.github.com、api.githubcopilot.com。
网络与端口
| 位置 | 端口 | 用途 |
|---|---|---|
| macOS | 127.0.0.1:8080 | OpenShell 网关 |
| macOS · Windows | 127.0.0.1:8766 | 本机模型服务器（Windows 为 WSL 内的中继）。若冲突则使用 8768 |
| DGX Spark | 18080 到 18099 中的空闲端口 | Spark 专用网关 |
| DGX Spark | 18081 | 从沙箱到 Spark 模型（8000）的中继 |
| DGX Spark | 22 | 应用的 SSH 连接 |
若 Spark 上开启了 ufw 防火墙，安装过程中会开放网关和中继两个端口，此时会要求输入一次 Spark 账户密码。
沙箱不会直接访问互联网。网络搜索和网页读取由应用代为完成，GitHub 以只读方式连接。
模型地址
| 模型 | 沙箱调用的地址 |
|---|---|
| 本机模型 | http://localhost:<端口>/v1。默认模型 qwen3-8-27b，上下文 262,144 |
| DGX Spark 模型 | 经 Spark 中继到 Spark 的 127.0.0.1:8000/v1 |
| 云端模型 | Keural 服务器的 /core/v1/bot/v1。使用为每个 Duo 签发的令牌。 |
| 网关 | 在 设置 → 模型 → 网关 中连接的服务器地址 |
网关地址若使用 https，可以是任意地址；若使用 http，则仅接受内网 IP 或内部名称（.local、.lan、.internal、.intranet、.home.arpa，或不含点的名称）。包含 localhost 或 user:pass@ 的地址不被接受。
Telegram
- 机器人令牌通过 BotFather 的
/newbot获取，格式为数字:字母数字。 - 应用生成连接代码后，请在 10 分钟内用手机打开机器人，并在 5 分钟内发送第一条消息。发送该消息的账户将被允许。
- 群组对话中不会回复。
例行任务限制
| 项目 | 值 |
|---|---|
| 检查间隔 | 每 30 秒查找需要运行的例行任务。 |
| 错过 | 比预定时间晚 10 分钟以上，则不运行，并标记为错过。 |
| 暂停 | 连续失败 3 次后停止。 |
| 重复间隔 | 5 到 1,440 分钟 |
| 单次运行 | 最多 365 天后 |
| 有效期 | 默认 7 天，最长 30 天 |
| 数量 | 开启的例行任务 10 个，共 50 个 |
| 时区 | 创建例行任务的电脑所在时区 |
添加文件夹的规则
以下文件夹无法添加。
| 类别 | 文件夹 |
|---|---|
| 通用 | 磁盘根目录、主文件夹本身及其上级 |
| 主文件夹下 | .ssh、.aws、.gnupg、.kube、.docker、.config、Library、.Trash、AppData |
| macOS | /System、/Library、/usr、/bin、/sbin、/etc、/var、/private、/dev、/Volumes、/Applications、/opt、/cores |
| Windows | Windows、Program Files、Program Files (x86)、ProgramData |
电脑使用权限
| 操作系统 | 所需权限 |
|---|---|
| macOS | 系统设置 → 隐私与安全性中的 辅助功能、屏幕录制 |
| Windows | 无需单独权限，使用 Windows UI 自动化。 |
发送、删除、付款、购买、提交、登录、转账、发布、取消等按钮，以及 Enter、Delete、关闭窗口、退出应用等按键，均视为敏感步骤，每次都会确认。
卸载时删除的内容
点击 删除 后，会删除沙箱、Duo 对话记录、例行任务、Telegram、GitHub 和搜索连接，以及云端模型令牌。若此设备上没有其他 Duo，macOS 还会删除 ~/.keural-runtime/ 和开机自启项。Mate & Morph 设置和 Spark 连接记录属于设备设置，会保留。