跳到主要内容

桌面应用

Kopi Agent 桌面应用是一款原生应用,围绕与 CLI 和 gateway(网关)完全相同的 agent 构建——相同的配置、相同的 API key、相同的会话、相同的 skill、相同的记忆。它不是独立的产品,也不是轻量级克隆;它使用相同的 KOPI AI AGENT 核心与设置,并通过现代且精心设计的 UI 来驱动它。如果你在终端中使用过 kopi,你在那里做的一切设置都已经在这里了,而你在这里做的任何事也都会出现在那里。

它可在 macOS、Windows 和 Linux 上运行。

哪个界面对应哪个?

Kopi Agent 有多个前端,它们连接的都是同一个 agent:

  • 桌面应用(本页面)——一款原生应用,配备专为聊天、配置和管理打造的 UI。
  • CLI (kopi) 和 TUI (kopi --tui)——终端界面。
  • Web Dashboard (kopi dashboard)——浏览器端的管理面板;其可选的 Chat 标签页通过伪终端嵌入了 TUI。

选择当下最适合你的即可。它们共享状态,所以你可以在一个界面中开始会话,在另一个界面中继续。

安装​

请按照 Kopi Agent Desktop 的安装说明操作。

如果你已经安装了 Kopi Agent,只需运行

kopi desktop

它会使用你当前的配置、key、会话和 skill。

应用包含哪些内容​

桌面应用采用聊天优先的窗口布局,左侧是用于导航的侧边栏。它的设计目标是:管理多个并行的 agent 会话、配置消息服务提供商、创建 artifacts、浏览项目文件夹结构,以及同时处理多个项目。

聊天​

这是应用的核心区域。你可以获得:

  • 流式响应,在 agent 工作时实时显示工具活动以及结构化的工具调用摘要。
  • 与其他所有 Kopi Agent 界面一致的会话历史 —— 在这里启动的会话可以在 CLI/TUI 中恢复,反之亦然。
  • 拖放文件到聊天区域的任意位置,即可将其附加到你的下一条消息中。
  • 右侧预览栏 —— 在继续聊天的同时,并排渲染网页、文件和工具输出。
  • 输入框历史与队列编辑 —— 在空白输入框中按上下方向键可调出并复用之前的提示词,并且在消息发送前可以编辑已排队的消息。

状态栏​

聊天窗口底部的横条显示实时会话状态,并提供快捷控制,无需打开设置:

  • 按会话切换 YOLO —— 仅为当前会话开启或关闭 YOLO(与 TUI 中的行为一致)。YOLO 会跳过危险命令的批准提示,因此请清楚你关闭的是什么 —— 参见安全 → YOLO 模式。

如果你连接的是另一台机器上的 Kopi Agent 实例,而非内置的本地后端?请参阅下文的连接到远程后端 —— 而关于远程托管的仪表板连接如何工作的完整说明(认证闸门、/api/ws 聊天 socket,以及 WebSocket 关闭码排查),请参阅 Web 仪表板 → 将 Kopi Agent 桌面版连接到远程后端。

选择模型​

模型选择器位于输入框中,就在麦克风按钮的左侧。点击它可以在这个下拉菜单中切换模型、推理强度(reasoning effort)和快速模式。

  • 输入框中的选择器是粘性 UI 状态,绝不会更改你的默认设置。它会在本地记住(按设备),并在新建聊天和重启后延续,而不是重置回默认值 —— 选一次模型,之后每次 Cmd/Ctrl+N 都会以它打开。在进行中的聊天里切换模型,该更改仅作用于该当前聊天;无论哪种方式,选择都会随会话的创建/切换一起带过去,并且绝不会写入 profile 的默认值。(切换 profile 会重置为该 profile 自己的默认值。)
  • 在设置 → 模型中设置默认模型。那个"主"模型是你的按 profile 的全局默认值 —— 新聊天、定时任务、子 agent 和辅助任务都从它开始,并且只有那里才会写入它。每个 profile 都保留各自的默认值。
  • **按模型保存强度/快速预设。**每个模型在桌面应用中会记住各自的推理强度和快速模式选择,每当选择该模型时会重新应用到会话中。这些预设是桌面端的便利功能,不会更改定时任务或子 agent。
  • **聊天中途切换模型会重置提示词缓存。**在进行中的聊天里切换模型,意味着下一条消息会以完整输入价格重新读取整个对话(provider 的提示词缓存是以模型为键的)。偶尔这样做没问题;在长对话中,在新模型上开一个新聊天通常比来回切换更省钱。

文件浏览器​

无需离开应用即可浏览和预览工作目录 —— 在 agent 读取、写入和编辑文件时便于跟随查看。使用 kopi desktop --cwd <path>(或 KOPI_DESKTOP_CWD 环境变量)设置初始项目目录。

语音​

与 Kopi Agent 对话并聆听它的回复,与其他地方可用的语音模式相同。在 macOS 上,系统会一次性提示麦克风访问权限。

设置与入门引导​

通过真正的 UI 管理服务提供商、模型、工具和凭据,而不用编辑 YAML。首次运行的入门引导能让你在几秒内发出第一条消息。设置面板涵盖服务提供商/密钥、模型选择、工具集配置、MCP 服务器、网关和会话管理。

  • 服务提供商设置面板 —— 一个专门管理推理服务提供商(inference provider)的地方,提供账户/API 密钥交互方式,用于按提供商登录并存储凭据。
  • 菜单中包含每个提供商和每个模型 —— GUI 展示完整的提供商列表以及 kopi model 了解的每一个模型,因此你可以从 CLI 所见的同一目录中选择,而不是经过筛选的子集。
  • xAI Grok OAuth —— Grok 在启动器中是一等的 OAuth provider;像其他 OAuth provider 一样通过浏览器流程登录。
  • 从 GUI 安装工具后端 —— 直接在应用内运行工具后端的安装后步骤,而无需切换到终端。
  • 辅助模型警告 —— 如果你把主模型切换到新的 provider,而辅助任务(生成标题、摘要以及类似的辅助工作)仍固定在另一个 provider 上,应用会发出警告,避免你在不知情的情况下把工作拆分到两个 provider 上。

首次运行的入门引导已在统一的覆盖层设计系统上重新设计,你可以选择稍后选择服务提供商,跳过 provider 设置,先进入应用。

管理面板​

应用还展示了更广泛的 Kopi Agent 管理界面,让你无需切换到终端:

  • Skills —— 浏览、安装和管理 skills。
  • Cron —— 查看和管理定时任务。
  • Profiles —— 在 Kopi Agent profiles 之间切换(相互隔离的 config/skills/sessions)。
  • Messaging —— 设置网关通道。
  • Agents 与 Command Center —— 用于多 agent 协作的编排界面。

键盘与导航​

  • 命令面板 —— 按 Cmd+K(Windows/Linux 上为 Ctrl+K)即可跳转到各项操作并通过键盘导航应用。
  • 可重新绑定的快捷键 —— 设置中的快捷键面板允许你将应用的键盘快捷键重新映射为自己的按键。
  • 自定义缩放快捷键 —— 以半档为增量缩放界面,更精细地控制文字大小。
  • UI 语言切换器 —— 在应用内更改界面语言,包括简体中文(zh-Hans)。

会话与 profiles​

  • 会话列表大改版 —— 重新设计的会话列表,支持归档和常规的会话整理功能,让列表在增长时仍保持可管理。
  • 按 id 搜索会话 —— 直接通过 id 查找特定会话。
  • 多 profile 并发会话 —— 同时在多个 profiles 中运行会话,并通过跨 profile 的 @session 链接引用另一个 profile 中的会话。

更新​

应用会在后台检查更新,并在有可用更新时提供一键更新。

手动更新流程同样适用于图形界面。

卸载​

打开 Settings → About → Danger zone,选择要移除的内容:

  • Uninstall Chat GUI only — 移除桌面应用及其数据;Kopi Agent、你的配置和聊天记录会保留。(与 kopi uninstall --gui 相同。)
  • Uninstall GUI + agent, keep my data — 移除应用和 agent,但保留配置、聊天记录和 secrets,供将来重新安装时使用。(与 kopi uninstall 相同。)
  • Uninstall everything — 移除应用、agent 以及所有用户数据。(与 kopi uninstall --full 相同。)

应用会关闭以完成操作(清理工作在应用退出后运行,这样才能移除正在运行的应用包及其自身的 venv)。当未安装本地 agent 时(例如仅含 GUI 的 "lite" 客户端连接到远程后端),涉及移除 agent 的选项会自动隐藏。

你也可以在终端中执行相同操作 — kopi uninstall --gui 仅针对 GUI,或 kopi uninstall / kopi uninstall --full 同时处理 agent。

备注

在源码检出(kopi desktop 开发构建)中运行 kopi uninstall --gui 时,还会移除工作区中的 node_modules 和 apps/desktop/{dist,release} 构建输出,因为这些是 GUI 构建产物。它们可以通过 kopi desktop(或 npm install 加重新构建)恢复 — 但如果你正在积极开发桌面应用,请做好操作后重新安装依赖的准备。

CLI 参考:kopi desktop​

要通过 CLI 启动,只需运行 kopi desktop。默认情况下,它会安装工作区的 Node 依赖、构建当前操作系统的未打包 Electron 应用,然后启动该打包产物。

FlagDescription
--skip-build跳过 npm install/package,直接从 apps/desktop/release 启动现有的未打包应用
--force-build即使内容戳(content stamp)匹配也强制进行完整重建
--build-only构建桌面应用但不启动它(由 kopi update 使用)
--source通过 electron . 对 apps/desktop/dist 启动,而不是启动打包后的应用
--cwd PATH桌面聊天会话的初始项目目录(设置 KOPI_DESKTOP_CWD)
--kopi-root PATH覆盖应用使用的 Kopi Agent 源码根目录(设置 KOPI_DESKTOP_KOPI_ROOT)
--ignore-existing在后端解析过程中强制应用忽略 PATH 上已有的任何 kopi CLI
--fake-boot启用确定性的启动延迟,用于验证启动界面

工作原理​

打包后的应用包含 Electron 外壳和原生 React 聊天界面。首次启动时,它可以将 KOPI AI AGENT 运行时安装到 KOPI_HOME(~/.kopi,Windows 上为 %LOCALAPPDATA%\kopi)— 与 CLI 安装使用的目录结构完全相同,这也是两者可以互换的原因。后端解析的优先顺序是:首先遵循 KOPI_DESKTOP_KOPI_ROOT,其次是已完成的托管安装,然后是探测 PATH 上的 kopi(除非设置了 --ignore-existing / KOPI_DESKTOP_IGNORE_EXISTING=1),最后是面向 Nix 等打包者的显式 KOPI_DESKTOP_HERMES 命令覆盖。React 渲染器与应用为你启动的无头后端通信 — 一个提供 tui_gateway JSON-RPC/WebSocket API 的 kopi serve 进程 — 并复用 agent 运行时,而不是嵌入 kopi --tui。桌面应用是自包含的:它运行自己的 kopi serve 后端,从不打开也不依赖 web dashboard。(早于 serve 命令的运行时会自动回退到无头的 dashboard --no-open,因此应用更新永远不会领先于其后端。)安装、后端解析和自更新逻辑都位于 Electron 主进程中。

连接到远程后端​

默认情况下,应用会启动并管理自己的本地后端。你也可以让它连接到运行在另一台机器上的 Kopi Agent 后端——比如一台 VPS、一台家用服务器,或一台位于 Tailscale 之后的 Mini。

远程后端是一个正在运行的 kopi serve 进程

"远程后端"指的是运行在远程机器上的 kopi serve 服务器——也就是桌面应用所连接的那个进程。除非该后端确实在运行且可达,否则本节中的任何操作都无法生效。桌面应用不会替你启动它;需要由你(或一个 systemd 服务)在远程主机上保持 kopi serve 运行,应用只是接入它。如果你还使用消息通道(Telegram、Discord 等),那么gateway 是一个独立的长期运行进程,需要你单独启动——参见设置步骤之后的说明。

连接包含两个部分:在后端侧,你需要通过 auth provider(身份验证提供方)来保护它;在应用侧,你需要输入后端的 URL 并登录。将后端绑定到非 loopback 地址会自动启用其身份验证门禁,而你配置的 provider 就是放行桌面应用的凭据。

根据后端所在位置选择 provider:

  • OAuth (KOPI Proxy) —— 适用于任何超出本机范围可达的场景。 登录会针对你的 Nous 账户进行验证,因此这是适合 VPS、公网主机或任何远程后端的选项。使用 kopi dashboard register(或 KOPI Proxy 的 /local-dashboards 页面)注册该 dashboard,以配置其 OAuth client,然后在应用中使用 Sign in with Kopi Ai Agent Pte Ltd 登录。如果你自建身份提供方,自托管的 OIDC provider 也是同样的用法。
  • 用户名/密码 —— 仅限本地/可信网络使用。 当后端位于同一可信局域网内,或只能通过 VPN(例如 Tailscale)访问时,这是最简单的选项。它只用一个共享凭据进行保护,不涉及外部身份提供方,因此不要将其用于暴露在公网上的 dashboard——那种场景请改用 OAuth。

本节余下部分展示用户名/密码流程,因为它在可信网络上搭建最快;OAuth 流程请参阅 Web Dashboard → 默认 provider:Kopi Ai Agent Pte Ltd。

在后端侧(远程机器上)​

设置用户名和密码,然后以绑定到可达地址的方式启动后端。凭据保存在 ~/.kopi/.env(secrets 文件,权限 0600)中:

# 1. Set the dashboard login credentials.
cat >> ~/.kopi/.env <<'EOF'
KOPI_DASHBOARD_BASIC_AUTH_USERNAME=admin
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
# Without it a random key is generated per boot and you'll be logged out
# on every restart.
KOPI_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.kopi/.env

# 2. Run the backend bound to a reachable address. The non-loopback bind
# engages the auth gate; the username/password provider handles login.
kopi serve --host 0.0.0.0 --port 9119

在你希望桌面应用能够连接的整个期间,都要保持该 kopi serve 进程运行——一旦它停止,应用就无法再访问后端。请使用 systemd、tmux 或你选用的进程管理器来运行它,使其在注销和重启后依然存活。

另外,如果你依赖消息通道,请确保远程主机上gateway 正在运行——桌面应用通信的是 kopi serve 后端,而你的 Telegram/Discord/Slack gateway 会话是另一个进程,需要你单独启动并保持运行。gateway 的设置请参阅 Messaging。

不想以明文形式保存密码?可以改为将 KOPI_DASHBOARD_BASIC_AUTH_PASSWORD_HASH 设置为 scrypt 哈希值——使用 python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))" 计算。完整的配置项(config.yaml 键、所有环境变量、速率限制器)请参阅:Web Dashboard → 用户名/密码 provider。

以 systemd service 方式运行后端?为该 unit 设置 EnvironmentFile=%h/.kopi/.env,以便在启动时将凭据放入环境变量中。

注意

后端会读写你的 .env(API key、secrets),并能执行 agent 命令。上面展示的用户名/密码设置仅适用于可信网络——切勿将密码保护的后端直接暴露在公网上;请将其置于 VPN 之后。Tailscale 是干净利落的选择:绑定到机器的 tailscale IP(--host <tailscale-ip>),并将 http://<tailscale-ip>:9119 作为 Remote URL,这样只有你的 tailnet 能够访问它。若要通过公网访问后端,请改用 OAuth (KOPI Proxy) provider。

在应用侧​

Settings → Gateway → Remote gateway:

  1. Remote URL —— http://<backend-host>:9119(如果前面有反向代理,/kopi 这类路径前缀也可以使用)
  2. Sign in —— 应用会检测后端所声明的 provider 并相应调整按钮。对于用户名/密码后端,会显示一个 Sign in 按钮,点击后打开凭据表单(填入第 1 步中的凭据)。对于 OAuth 后端,会显示 Sign in with <provider>(例如 Sign in with Kopi Ai Agent Pte Ltd),点击后执行 provider 的浏览器登录流程。无论哪种方式,最终应用都会获得一个针对后端的已认证会话。
  3. Save and reconnect —— 将桌面 shell 切换到远程后端。会话会自动刷新;当设置了 KOPI_DASHBOARD_BASIC_AUTH_SECRET 时,重启后仍保持登录状态。

你也可以不通过 UI,而是在启动应用前通过 KOPI_DESKTOP_REMOTE_URL 环境变量设置后端 URL(它会覆盖应用内设置);登录仍然在 Gateway 设置面板中完成。

按 profile 区分的远程主机

远程 gateway 主机是按 profile 配置的,因此每个 profile 都可以指向各自的远程后端(或继续使用本地后端)。切换 profile 即切换应用所连接的远程主机。

故障排查​

  • 登录失败,返回 401 / "Invalid credentials" —— 用户名或密码与后端的 KOPI_DASHBOARD_BASIC_AUTH_USERNAME / KOPI_DASHBOARD_BASIC_AUTH_PASSWORD 不匹配。后端对未知用户和错误密码返回相同的通用错误(不暴露用户枚举线索),因此请仔细核对两者。使用 curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' 确认门禁已启用——它应报告 true 并包含 "basic"。
  • 没有"Sign in"按钮——而是要求输入 session token —— 后端的用户名/密码 provider 未激活。/api/status 不会在 auth_providers 中列出 "basic"。请确保 ~/.kopi/.env 中同时设置了用户名和密码(或密码哈希),并且 dashboard 进程确实加载了它们。
  • 每次重启都被登出 —— 将 KOPI_DASHBOARD_BASIC_AUTH_SECRET 设置为一个稳定值。不设置的话,token 签名密钥会在每次启动时重新生成,导致所有会话失效。
  • Connection refused / 超时 —— 后端绑定到了 127.0.0.1(默认值),或防火墙/VPN 阻止了该端口。请绑定到 0.0.0.0 或 tailscale IP,并向你的可信网络开放该端口。

从 web-dashboard 角度了解同一设置,请参阅 Web Dashboard → 将 Kopi Agent Desktop 连接到远程后端;环境变量的完整列表见 Environment Variables → Web Dashboard 与 Kopi Agent Desktop。

故障排查​

启动日志会写入 KOPI_HOME/logs/desktop.log(其中包含后端输出和最近的 Python 追踪回溯)——如果应用报告启动失败,请先检查它。你也可以在 CLI 中实时查看它:

kopi logs gui -f

常见重置操作:

# Force a clean first-launch setup (macOS/Linux)
rm "$HOME/.kopi/kopi-ai-agent/.kopi-bootstrap-complete"

# Rebuild a broken Python venv (macOS/Linux)
rm -rf "$HOME/.kopi/kopi-ai-agent/venv"

# Reset a stuck macOS microphone prompt
tccutil reset Microphone com.nousresearch.kopi

"Build desktop app" 卡在 Electron 下载阶段​

构建过程中会从 github.com/electron/electron/releases 下载 Electron 运行时(约 114 MB)。如果安装程序卡在 Build desktop app 步骤,且实时输出反复显示 retrying attempt=…,说明你的网络屏蔽或限制了 GitHub(防火墙、代理或地区原因)。

安装程序会自动自愈:构建失败时,它会 (1) 清除损坏的 Electron 缓存 zip 并重试;然后 (2) 如果仍然失败且你未设置 ELECTRON_MIRROR,则通过 npmmirror.com 再重试一次,这是事实上的 Electron 社区镜像。@electron/get 会对下载进行 SHASUM 校验,但校验和来自同一个镜像——这只能发现损坏或不完整的下载,无法防范被篡改的镜像。如果你不愿信任第三方主机,请固定你自己的 ELECTRON_MIRROR(见下文);构建过程永远不会覆盖你已设置的镜像。

要选择你自己的镜像(例如企业内部或受信任的镜像),请在安装前设置 ELECTRON_MIRROR,或手动重新构建——构建过程会遵循它且不会覆盖它:

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
bash -c 'cd "$HOME/.kopi/kopi-ai-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack'

要手动清除损坏的缓存 zip:

rm -f "$HOME/Library/Caches/electron"/electron-*.zip   # macOS
rm -f "$HOME/.cache/electron"/electron-*.zip # Linux

从源代码构建​

如果你想自己开发这个应用,请先在仓库根目录一次性安装工作区依赖,然后从 apps/desktop 运行开发服务器:

npm install          # from repo root — links apps/desktop, web, apps/shared
cd apps/desktop
npm run dev # Vite renderer + Electron, which boots the Python backend

让应用指向特定的代码检出目录,或将其与你的真实配置隔离(沙箱):

KOPI_DESKTOP_KOPI_ROOT=/path/to/clone npm run dev
KOPI_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot # exercise the startup overlay with deterministic delays

构建安装程序:

npm run dist:mac     # DMG + zip
npm run dist:win # NSIS + MSI
npm run dist:linux # AppImage + deb + rpm
npm run pack # unpacked app under release/ (no installer)

当环境中存在相应凭据时,macOS/Windows 的签名和公证会自动执行(macOS 为 CSC_LINK / CSC_KEY_PASSWORD / APPLE_*,Windows 为 WIN_CSC_*)。

另请参阅​

  • CLI 指南 —— 终端界面
  • TUI —— kopi --tui 和控制台聊天标签页所使用的现代终端 UI
  • Web 控制台 —— 带内嵌聊天标签页的浏览器管理面板
  • 配置 —— 桌面应用读取和写入的配置
  • Windows(原生) —— 原生 Windows 安装路径