桌面应用¶
Cortex 桌面应用是一个原生窗口程序（基于 Tauri v2 构建），
用于包装 Cortex 网页工作台。它通过 HTTP tRPC 传输和 clientToken 直连任何运行中的
Cortex 服务器——无需本地代理或 sidecar 进程。
安装¶
从 GitHub Releases 页面 下载适合你平台的最新版本。
Linux¶
AppImage（适用于任何发行版）：
Debian / Ubuntu (.deb)：
系统前置依赖（Ubuntu 22.04+）：
大多数 Ubuntu/Debian 桌面系统已预装这些库。如果应用因缺少库而无法启动， 请运行上述命令安装。
macOS¶
下载 Cortex_*_x64.dmg（Intel）或 Cortex_*_aarch64.dmg（Apple Silicon）。
- 打开
.dmg文件。 - 将 Cortex 拖入 应用程序 文件夹。
- 从应用程序或 Spotlight 打开 Cortex。
首次启动时 macOS 可能提示"Apple 无法验证此开发者"。在 系统设置 → 隐私与安全性 中点击 仍要打开。
Windows¶
下载 Cortex_*_x64-setup.exe，运行安装程序并按提示操作。
安装完成后，Cortex 出现在开始菜单中。
WebView2 依赖： Windows 10 / 11 通常已包含 WebView2 运行时。如果应用因 WebView2 错误 无法启动，请从 Microsoft 下载常青版引导程序并安装。
服务器端前置条件¶
桌面应用通过 HTTP 或 HTTPS 与 Cortex 服务器的 Web UI HTTP 端点 通信。 该端点是可选启用的——连接前必须先在服务器上启用它。
该端点由服务器内置的 Web UI 传输层提供，核心服务器仅在设置了 CORTEX_UI_HTTP 时才按需
加载它（它携带 @trpc/server + jose 与 SPA 托管——运行期惰性加载，因此仅 Slack/TUI 的
服务器永不加载它们）。启用它与此前一样只需一行标志——桌面应用不受任何影响，它仍以
Bearer clientToken 认证。同一端点也驱动浏览器工作台，见
浏览器访问与部署。
在运行 Cortex 服务器的机器的 ~/.cortex/config/.env 中添加以下内容：
然后重启 Cortex 守护进程：
如果通过隧道暴露该端点（推荐用于远程访问），将隧道指向上述端口， 在桌面应用中使用隧道的 HTTPS URL 进行连接。
首次启动：连接到你的服务器¶
首次启动 Cortex 桌面应用时，会出现连接配置界面：
┌─────────────────────────────────────────────────────────┐
│ cortex-desktop │
│ │
│ server url │
│ ┌──────────────────────────────────────────────────┐ │
│ │ https://cortex.example.com │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ client token │
│ ┌──────────────────────────────────────────────────┐ │
│ │ •••••••••••••••••• │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ [test connection] [connect →] │
└─────────────────────────────────────────────────────────┘
第一步 — 输入服务器 URL¶
输入 Cortex Web UI 端点可访问的 HTTP/HTTPS URL，例如：
- 同一台机器，无隧道：
http://localhost:3004 - 通过 Cloudflare 隧道访问远程服务器：
https://cortex-ui.your-domain.com
第二步 — 输入客户端令牌¶
客户端令牌是服务器用于验证 Cortex 客户端的共享密钥（与 ~/.cortex/config/.env 中
CORTEX_TOKEN 的值相同）。可以通过以下命令获取：
第三步 — 测试连接¶
点击 test connection。应用会向 <serverUrl>/trpc 发送一个携带令牌头的轻量探测请求。
- Connected（绿色）—— 服务器可达且令牌有效。
- Unauthorized（橙色）—— 服务器可达但令牌错误。
- Network error（红色）—— URL 不可达（服务器未运行、隧道未启动或 URL 错误）。
第四步 — 连接¶
点击 connect →。应用将：
- 把凭据保存到操作系统密钥链（macOS 钥匙串、Windows 凭据管理器或 Linux SecretService / GNOME 密钥环）。
- 打开工作台。
之后每次启动时，Cortex 都会读取存储的凭据并直接打开工作台，跳过连接配置界面。
使用说明¶
连接成功后，你可以使用完整的 Cortex 工作台。
主工作台¶
工作台采用三栏布局：
| 栏位 | 内容 |
|---|---|
| 左侧导航栏 | 项目/会话导航器，可切换项目和会话存档。 |
| 中央区域 | 对话内容：线程步骤、工具调用、助手输出、审批提示。 |
| 右侧面板 | 活跃线程/任务/机器；成本条；步骤详情树。 |
线程详情¶
点击右侧面板中的任意线程卡片，打开线程详情视图——包含智能体规划、执行过程和 子派发链的完整逐步追踪，以及每步的耗时和成本。
⌘K / Ctrl+K — 命令面板¶
按 ⌘K（macOS）或 Ctrl+K（Windows/Linux）打开命令面板。输入文字可在会话、线程和
任务中快速过滤。按 Enter 跳转，按 Escape 关闭。
执行日志抽屉¶
在右侧面板或线程详情中点击运行中的执行条目，打开执行日志抽屉—— 实时流式显示执行过程的标准输出/标准错误。日志通过 SSE 实时推送， Kill 按钮可取消执行。
项目与存档切换器¶
左侧导航栏显示当前项目。点击项目名称打开项目切换器，选择其他项目。 点击存档图标可切换到历史存档视图。
任务弹窗¶
点击右侧面板或命令面板中的任意任务行，打开任务弹窗，显示任务的完整描述、
done-when 完成条件、当前状态和依赖链。
概览¶
右侧面板的 Overview 标签页显示全系统的成本、定时任务、近期执行记录和吞吐量图表。
切换到其他服务器¶
在工作台窗口中移动鼠标时，右下角会出现 Switch 按钮。点击后：
- 从操作系统密钥链中清除已存储的凭据。
- 返回连接配置界面。
然后可以输入新的服务器 URL 和令牌。
连接机制¶
桌面应用通过以下方式绕过浏览器的同源限制：
- tRPC HTTP 批量请求：通过
POST <serverUrl>/trpc发送所有查询和变更， 每个请求携带x-cortex-token头。 - SSE 订阅：使用支持自定义请求头的 EventSource 腻子脚本（fetch-based）。 线程和执行的实时更新无需轮询即可到达。
这种架构使桌面应用可以连接到任意机器上的任意 Cortex 服务器——本地或远程—— 只要 Web UI 端点可访问即可。
故障排查¶
测试连接时显示"Unauthorized"
客户端令牌错误。请检查服务器上 ~/.cortex/config/.env 中的 CORTEX_TOKEN。
测试连接时显示"Network error"
- 确认服务器正在运行：
cortex daemon（或检查systemctl --user status cortex）。 - 确认服务器的
.env中已设置CORTEX_UI_HTTP=1，且添加后已重启服务器。 - 检查 URL 是否可访问：
curl <serverUrl>/trpc应返回 tRPC 错误（而非连接拒绝错误）。 - 如使用隧道，确认隧道正常运行且路由指向正确端口。
重启后凭据丢失（Linux 无头服务器）
在没有 SecretService 守护进程的 Linux 无头服务器上（例如未运行 GNOME 密钥环的服务器）， 操作系统密钥链不可用。凭据仅在当前会话中保留（存储在进程内存中）， 应用退出后即丢失。
解决方案：在启动应用前设置环境变量：
这些环境变量会在启动时初始化 AppState，跳过密钥链检查。
Wayland 下应用窗口不显示
Tauri v2 支持 Wayland。如果窗口未出现，可尝试强制使用 X11 兼容模式：