# Telos 安装与使用排障先确定失败发生在下载、插件安装、模型连接、微信登录、Apple 授权还是消息收发。保留已成功的步骤，无需一遇到错误就重装或重新扫码。安装步骤见 [AI 安装指南](install-for-ai.md)，功能说明见 [详细配置](../packaging/README.md)。 ## 仓库或 Release 打不开，找不到安装包 - 从仓库 Releases 页面进入当前版本；如果旧版本附件不可见，使用当前发布包。公开附件无需 GitHub 账号。 - 本版安装包与校验文件位于 [0.4.19 Release](https://github.com/lucifersteps/telos-harness/releases/tag/v0.4.19)。仍看不到附件时，核对版本和下载状态，联系维护者；不拼接猜测的下载链接。 - 下载的是 `.tgz` Release 附件；GitHub 自动提供的 Source code ZIP/tar.gz 不能当作自包含插件包安装。 - SHA256 不匹配时停止安装并重新下载。缺少校验附件可核对 GitHub 资产 `digest` 或维护者提供的值；不要把自己刚算出的哈希作为期望值。 - `gh` 未安装、未登录或 GitHub API 返回限流错误时，使用 [无需账号的直接下载命令](install-for-ai.md#download)。API 的 403 不代表公开 Release 必须登录。 ## 插件装不上，或者提示宿主缺少服务 | 现象 | 检查与处理 | | --- | --- | | 系统或 CPU 不匹配 | 当前包只支持 macOS 14+ arm64。Apple Silicon 上若显示 x86_64，检查 Rosetta 终端 | | `dsh: command not found` | 桌面用户使用应用内插件页或桌面内置 CLI；Node CLI 用户检查安装及 PATH | | 普通 Node CLI 拒绝管理 `desktop` | 使用该桌面应用的 `Contents/Resources/runtime/cli/bin/dsh`，不要修改它的管理限制 | | 缺少 agents、credentials、skills 等服务 | CLI profile 必须包含 `@deepseek-ai/dsh-base`，旧 sdk-minimal 不适用 | | 命令选项不支持 | Telos 支持的首次配置参数为 `--telos-setup`、`--telos-login`、`--telos-authorize`、`--telos-status`；桌面使用页面按钮 | | 安装后找不到 Telos 页面 | 检查是否装到当前桌面的 DSH_HOME / desktop profile、是否已启用，再重启 DSH | | `不支持此配置版本` | 保留原文件，查对应版本升级说明，不删除配置“重置解决” | 不要从仓库根目录直接执行 `npm install` 替代 Release 安装；源码中的插件元数据用于开发构建，分发包由构建流程生成。 ## 模型无法连接，或微信没有回复 1. 桌面版先在 Telos 页“测试连接”。模型 ID、provider、协议和服务地址应匹配，凭据应保存在这个 DSH 实例中。 2. CLI 检查当前 DSH_HOME/profile 与安装时一致；新建独立目录不会自动继承另一个目录的账号登录。默认 `deepseek-official / deepseek-flash` 路径需要相应 API 凭据。 3. `--telos-status` 的 `model` 只说明选择了哪个模型，不能证明密钥有效、网络可达或配额充足。 4. 查看实际模型错误：认证失败检查凭据，模型不存在检查 ID，网络超时检查本机连通性和实际代理配置。不要在日志或聊天中输出 Key。 5. 模型正常后，检查微信登录、通道运行状态，以及发消息的账号是否为扫码绑定的允许用户。Telos 不会自动回复所有联系人。原生执行失败且没有模型回复内容时，微信可能没有固定错误回复，需要查看本机日志。不要连续重复发送同一个创建日程请求来测试，以免形成多个草稿。 ## 二维码过期、登录失败或提示已有实例重新扫码前先停止 Telos。二维码过期后重新发起登录，用户用自己的微信扫描并确认；保持页面或 CLI 登录进程运行至成功。提示“该 Telos 数据目录已有运行实例”时，检查正在运行的桌面或 CLI 实例，通过原页面的停止按钮或原终端 `Ctrl+C` 正常停止。不要删除锁文件、抢占账号或同时启动两套轮询。切换微信账号后，旧账号的会话或任务不会自动发给新账号；这是收件人校验的结果。使用新账号建立会话并管理自己的任务，不修改历史映射来绕过检查。 ## Apple 日历或提醒事项权限不正常首次配置默认开启 Apple，但开启工具不等于 macOS 已授权。 1. 确认 Telos 的 Apple 开关开启；CLI `config.json` 中 `tools.apple` 为 `true`。 2. 停止 Telos，点击“授权日历与提醒事项”，或在原 CLI 环境执行 `dsh --profile telos --telos-authorize`。 3. 用户分别允许“Telos Apple”的日历、提醒事项权限；两项都检查，不能用其中一项代替另一项。 4. 若以前拒绝过且不再弹窗，打开“系统设置 → 隐私与安全性 → 日历 / 提醒事项”，允许 Telos Apple，再刷新状态并启动 Telos。 5. 在微信分别查询今天日程和未完成提醒事项。返回空列表可以是正常结果，权限错误则不是。当前 ad-hoc 签名组件内容变化后可能需要重新授权。相同应用名称不能保证授权保留。不要重置系统权限数据库或修改 DSH 签名。暂不授权时可先用聊天，报告中保留“Apple 待授权”。 ## macOS 提示无法验证开发者、应用损坏或阻止启动当前安装包未完成 Developer ID 公证。先确认下载来源和 SHA256，再记录系统提示及被拦截的具体组件。用户可以在 macOS “系统设置 → 隐私与安全性”中查看是否有对应应用的允许入口，并由本人决定是否允许。界面没有可用入口或仍然失败时，向维护者提供系统版本及错误文字，等待受支持的分发包。不要默认执行批量删除 quarantine、关闭 Gatekeeper、重新签名或修改权限数据库的命令。当前文档不将未经验证的绕过方式当作标准安装步骤。 ## 能聊天，但无法搜索或打开网页先确认安装的是具有网页工具的版本（0.4.8 起；0.4.7 没有本次接入的原生网页工具）。搜索和网页读取分开检查： - 搜索失败：查看 DSH 的搜索供应商、凭据和原生错误。第三方聊天模型或账号模型可用，并不能证明搜索后端已配置。 - 搜索有结果但正文打不开：检查目标网页是否需登录、是否限制抓取，以及 DSH 抓取服务的网络错误。换一个公开网页测试，不能用搜索摘要代替“正文已读取”。 - 终端可以联网但桌面不能：检查桌面实际使用的环境与代理配置。不要直接套用别人的代理端口，也不要把带凭据的代理地址贴进聊天。 Telos 复用 DSH 网页服务，不另存一套搜索密钥；具体后端可能仍需要 DSH 对应凭据。私有、登录后或限制访问的网页不保证能读取。 ## 定时任务没有收到，或桌面任务列表里看不到仅 0.4.10 及后续包含本次定时任务接入的版本适用。 - 在微信中询问“列出当前会话的定时任务”，确认任务确实创建成功、时间和时区正确。它们与桌面普通任务列表分开管理。 - 电脑保持唤醒，DSH 与 Telos 保持运行。退出、禁用插件或关闭 CLI 进程会停止调度；当前没有系统常驻服务。 - 重启使用相同 DSH_HOME、TELOS_HOME 和 profile。换目录不等于迁移任务。 - 查看任务执行时的模型错误和消息发送错误。任务已完成但发送失败时，发件箱会重试发送，无需重新创建任务来“补发”。 - 任务不能代替人工确认执行 Apple 写入。需要保存日程时，仍要用户对具体预览进行文字确认。重启后由原生调度处理到期任务，但不要承诺停止期间每个重复周期都会逐条补发。网络中断也不能保证消息严格只送达一次。 ## 地图、语音或历史回查不可用地图需开启工具并在同一 DSH 凭据环境中配置 `BAIDU_MAP_AUTH_TOKEN`；DeepSeek 账号不包含百度授权。请到 [百度地图 Agent Plan](https://lbs.baidu.com/apiconsole/agentplan) 获取 **SK**，不是到普通地图 API 控制台申请 AK。完整步骤见 [百度地图配置](install-for-ai.md#baidu)。 - 提示未配置 Token：桌面检查是否点击“保存到 DSH”；CLI 检查是否写入当前实例的 DSH_HOME，并在修改后重启。 - 提示认证失败：确认填写的是 Agent Plan SK，未误填 AK、未带多余空白或 `Bearer ` 前缀。需要检查或更换密钥时由用户在本机操作，不把密钥发到聊天。 - 提示额度或服务错误：登录 Agent Plan 页面检查服务状态及可用额度，费用以官方当前说明为准。 - 提示超时或网络失败：检查 DSH 进程访问百度接口的网络连接；不要把所有错误都当作密钥错误。不使用地图时关闭地图即可，不影响聊天与已授权的 Apple 功能。语音由 DSH 自身准备服务和模型。Telos 没有 `--telos-prepare-voice`，只开启模块不等于语音模型已下载。文字聊天正常时可稍后配置语音。历史回查从 0.4.9 起接入，只能检索当前微信会话，支持压缩前消息。全文检索可先用短关键词；没有结果不一定代表日志已丢失，也可能是关键词未匹配。不要改成搜索其他用户会话来绕过限制。 ## 微信文件无法读取先核对安装版本：文件读取需要 0.4.12 或更新版本，重新启动旧版本不会获得此功能。Telos 接入原生文件与执行工具，不需要安装微软 Office；独立 CLI 可能需要先准备 DSH 的 Office Python 环境。 - 下载/解密失败：重新发送文件；不要把本机路径当作微信附件发送。 - 旧版 DOC/XLS、加密文件：另存为未加密的 DOCX/XLSX/PDF。 - 扫描 PDF 或图片内容：发送需要识别的页面截图，文件解析本身不做 OCR。 - 提示缺少 Python 库或 `load_workspace_dependencies`：按 [CLI Office 环境](install-for-ai.md#cli-office) 准备官方运行环境后重启。 - 超限、超时或内容截断：按页、字符偏移或工作表分段读取；遇到 DSH 沙箱/授权拒绝时不要绕过，检查当前宿主权限。 - 重启后无法读取旧文件：核对是否切换了数据目录，或清理了 `users/*/documents/`。不要把此目录划分误认为原生 bash 的文件读取隔离边界。完整限制和数据保存方式见[文件读取说明](../packaging/README.md#微信文件读取)。 ## DSH 升级后提示 Telos 不兼容 0.4.15 及 0.4.16-dev.2 的 `engines.dsh` 精确锁定 `0.2.1-rc.2`，升级 DSH 到 rc.3 会被宿主拒绝加载；该兼容性提示本身不表示已经发生崩溃或数据损坏。升级 Telos 到 0.4.16，保留原 profile、数据目录、配置及微信登录状态，无需先卸载或清空数据。 0.4.16 声明范围 `>=0.2.1-rc.2 <0.3.0-0`，已验证 rc.2 / rc.3；更高版本超出此范围时应查看新版本兼容说明，不手动移除宿主的兼容性检查。 ## 升级后还是旧行为，重启后像全新安装插件列表显示新版本，只能证明文件已更新。退出并重新打开 DSH，或正常停止、重启 CLI，使旧进程和已加载模块换代。重启后配置或登录消失时，先核对启动入口、DSH_HOME、TELOS_HOME 和 profile 是否改变；不要立刻重新扫码。CLI 新终端不会自动继承上次临时 `export` 的变量。恢复原目录后再检查。升级和迁移详见 [升级与恢复](install-for-ai.md#upgrade)。 ## 向维护者提供什么提供：Telos/DSH 版本、macOS 版本与芯片、桌面或 CLI、失败步骤、错误文字、脱敏后的相关日志片段，以及实际通过了哪些检查。 CLI 可在正确环境运行 `dsh --profile telos --telos-status`；它不是完整健康检查，分享输出前仍应检查路径等个人信息。桌面可提供 Telos 状态页中对应错误。不要上传 `.env`、DSH 凭据文件、微信登录文件、二维码、完整会话日志或整个数据目录。带认证参数的本地页面 URL 也应删去认证值后再分享。 ## 升级后不再要求回复 1 确认 0.4.13 默认开启直接写入：普通单项新增/修改保存后发送完整卡片，回复【1】撤销；删除、批量等仍先确认。桌面版在“写入方式”关闭“直接写入”并保存应用；CLI 使用 `dsh --profile telos --telos-direct-write off` 后重新启动。已有显式关闭设置会保留。撤销失败时，先查询对象是否已被后续修改或删除，不反复重放写入。最新回复不是保存卡片时，数字 `1` 不会寻找旧卡片；可回复“撤销”处理最近一次直接保存。详情见 [写入模式](install-for-ai.md#direct-write)。 ## 文字回复重复或只收到前半段 0.4.18 修复普通文字分段投递的恢复机制。升级时保留原数据目录并完整重启 DSH，不要删除业务数据库或回执来强制重发。已确认发送的段落会跳过；明确拒收可在恢复时从失败段继续。结果未知及旧版没有分段进度的回复会暂停自动重放，原文保留；反复重启不会使这些回复重新发送。需要内容时，可在微信明确指出缺少哪部分，请助手重新提供。 ## 预览收到补充后无法确认 0.4.19 修复旧预览暂停确认后仍被提示回复【1】的问题。草稿会保留；请发送纯文字“重新预览”，核对新卡后再回复【1】确认。重新预览会重新校验对象及草稿，不会直接写入 Apple。过期草稿同样可以重新预览。如提示校验未通过，请说明需要修改的内容，或回复“取消”后重新提出安排。不要通过修改数据库的投递标记来强行批准旧卡。