TopxAI 桌面客户端：它解决什么问题，一条消息在里面怎么走

2026-11-06 · desktop, agent, claude-code, codex, topxai

浏览器登录，不用配密钥；目录里的模型和 Claude Code、Codex 在同一个会话里切换；难任务先拆开再做。这篇讲能力和架构，也列出目前的限制。

TopxAI Desktop 是 TopxAI 的桌面客户端，当前版本 1.55.0，运行在 Apple 芯片的 Mac 上，要求 macOS 15 及以上。在浏览器里登录账号后，不用配 API 密钥，就能用模型目录里的模型聊天、改代码、处理文件。这台电脑上装了 Claude Code 或 Codex 的话，也能接进来，和目录里的模型在同一个会话里切换。

这篇写给正在考虑安装的人，后面有一节单独列出现在还做不到的事。

它解决什么问题

用 TopxAI 的模型，原来要先建一把密钥、选好线路，再到每个工具里改接口地址。站上的接入指南有十几篇，基本是一个工具一篇。桌面客户端去掉了这一步：第一次打开时跳到网站的授权页，确认后应用用账号内置的 auto 密钥发请求，余额、充值和用量也都在应用里看。

选了某个工具，常常也就选了它背后的模型，想换一家得换窗口。这里每个会话有一个主模型，随时可以换，目录里的模型和 Claude Code、Codex 之间也能换。

有些活一次回答做不完，比如写一份研报，或者改一个跨很多文件的功能。客户端会先判断任务难度，难的拆开做，计划和进度存在运行记录里，恢复后从停下的地方接着跑。在 TopxAI 模型上运行的回合，重载窗口也不会中断。

让 Agent 改 Word 或操作浏览器，通常要先装 Python、Node.js、LibreOffice 和浏览器。安装包把这些都带上了，内置工具不用另外装。代价是体积：下载约 1.7 GB，装好约 4.2 GB。

提供方和模型

提供方是模型的来源。TopxAI 是其中一个，模型目录来自网站的 /api/pricing，网站上了新模型，应用不用更新就能看到。Claude Code 和 Codex 走原生驱动：应用运行电脑上装好的程序，登录状态也用那个程序自己的。Grok 有专用驱动，其他兼容 ACP 的程序也能接。

子 Agent 的模型单独选。可以自动选择（快速模型先评估任务难度，再由 Jev 挑模型或 Agent），可以跟随主会话，可以指定模型，也可以委派给这台电脑上的 Agent。设置里的 Agent 库存放自定义的 Agent，每个有角色、模型和系统提示词。

切换模型有一条限制。在 1.55.0 里，用过 GLM 或 Abliterated 模型的会话，上下文只留在那个模型上，不能切到别的模型，也不能委派出去。下一个版本会放宽：只有两个 Abliterated 模型这样，它们在同一提供方内可以互切，官方 GLM 不再受限。

用自己的密钥接入 OpenAI 或 Anthropic 接口的 API 提供方，也会随下一个版本发布。

难任务怎么跑

新请求进来时，一个便宜的模型先写一份简报，Jev 据此给工作量打 1 到 5 分。回合最多为这个评分等 2 秒，等不到就按普通方式跑。

打到 4 分及以上就走编排：主控模型做计划，执行 Agent 把各步当作委派任务并行去做，主控逐步检查结果，需要时重新规划，最后写总结。这套分诊只在 TopxAI 自己的循环上运行。Claude Code 和 Codex 有自己的循环，不经过这里。

运行中可以在计划侧栏暂停、修改或停止。「执行情况」面板列出跑过哪些模型、花了多少。面板上的金额是本机估算，实际扣费以账户里的用量为准。

长任务默认有 240 分钟的时间阈值，不设消费上限，成本未知也不会让它停下来，所以开跑前要自己看余额。

到点回来继续

Agent 可以用 check_back_later 让会话等待，最长 30 天，到点后用原来的提供方、模型和权限模式恢复。

值守 Agent 是长期版本：把 Agent 库里的一个 Agent 绑定到一个长期会话上，设好目标、完成标准和每次唤醒的 token 预算。浏览器、文件、shell、屏幕控制、外部账户五个能力开关在创建时全部关闭，用到哪个开哪个。约好的时间、定时计划和事件收件箱都能唤醒它。配对 Telegram 后，可以用 @值守名 或 /duty 发消息过去，回复和工具审批也在 Telegram 里完成。

这些都要电脑醒着。笔记本合盖或睡眠，上面的值守就停了。

工具和记忆

内置技能覆盖 Word、Excel、PDF、PowerPoint、Blender、数据分析和设计。公共目录里还能装更多，下载经过校验，更新失败时保留原版本。连接器目录可以用 OAuth 连第三方服务，也可以加本机的 MCP 服务器。

配套扩展从应用导出后装到 Chrome 或 Edge，每个会话操作自己的标签页。要操作 Mac，得先在系统设置里授予辅助功能和屏幕录制权限，打开应用本身不会授权。图片和视频生成在会话里显示进度和预览，结果存到本机。设计画布在会话旁边生成界面。

记忆基于 Claude-Mem，只存在这台电脑上。自动记录默认关闭，可以在设置里打开，也可以在那里查看和删除已保存的内容。来自 ECC 的编码工作流已内置，在「设置 > 高级」里管理。应用不发送产品遥测。

一条消息怎么走

下图从上到下跟着一条消息走。字太小的话，可以打开原图。

窗口是 Electron，每个窗口启动自己的 topxai serve 后端，两边用 ACP 通信。后端用 Rust 写，基于一个 Apache-2.0 开源 agent。

发出一条消息后，ACP 服务先去重、查权限，再交给 Agent::reply。这一步打检查点、保存用户消息，然后运行状态机。

状态机是 21 个操作排成的一列，从钩子、斜杠命令、插话、上下文压缩，到工具审批、工具执行、重试和编排，依次检查有没有事要做。任何一个做了事，就从头再走一遍。都没事，才发起一次模型请求。客户端只有这一条循环，新的循环行为都写成其中一个操作。

不是所有动作都经过状态机。重试和编辑先删掉后面的消息再重发；停止、工具审批和恢复检查点直接写 sessions.db。

发起模型请求之前要组提示词：基座 system.md（或用户覆盖的版本）、Agent 附加内容、项目信息、技能清单、记忆、扩展、钩子上下文，再加上 AGENTS.md。工具调用走另一条管线：审批和检查、权限判断、PreToolUse 钩子、执行、PostToolUse 钩子。

然后在驱动这里分开。TopxAI 和 API 提供方走 HTTPS，每次请求重组系统提示词。Claude Code 走 stdio 的 stream-json，Codex 走 stdio 的 app-server JSON-RPC，Grok 和其他 ACP Agent 走 stdio 的 ACP。后面这三类有自己的循环，只有桥接的工具才回到 TopxAI 这边的管线。

会话和记忆都存在本机：sessions.db 存消息、用量账本和运行记录，memory.sqlite3 存记忆，提示词、技能和 Agent 是配置目录下的普通文件。

现在还做不到的

没有 Intel 版和 Windows 版。实机测试只在 macOS 27 上做过，macOS 15 这个下限来自构建设置，还没在 macOS 15 的机器上验证。

登录凭据存在一个权限受限的本地文件里，不是系统钥匙串。

怎么开始

到下载页下载 DMG，打开后拖进「应用程序」。应用用 Apple Developer ID 签名并经过公证，第一次打开时 macOS 会问要不要打开从互联网下载的应用，确认名字是 TopxAI Desktop，点「打开」。然后选界面语言，在浏览器里登录。

想校验下载文件，每个版本都附 SHA256SUMS，步骤在安装说明里。遇到问题发邮件到 support@topxea.com，写上应用版本、macOS 版本和错误信息。