快速上手:从下载到接模型

Cindy 是心动网络(XD Inc.)出品的开源 AI Agent 桌面应用,官网 cindy.app,客户端 Apache-2.0,支持 macOS、Windows、Linux(Ubuntu/Arch/Omarchy)与 iOS/Android。本教程按“下载安装 → 选登录模式 → 接模型 → 跨设备共享”的顺序走一遍,覆盖四种模型接入方式(订阅授权、API key、本地模型、托管服务),并给出国内分区说明与故障排查思路。

总路径:装完客户端,Skip Sign-In 加本地模型能立刻干活,要完整托管体验再注册云账号。完整的产品与架构解读见Cindy 是什么。

下载与安装:桌面端、移动端与源码构建

桌面客户端从官网下载页 cindy.app/download 获取:macOS 与 Windows 直接装安装包,Linux 有 Ubuntu、Arch、Omarchy 的官方指南 docs/linux.md;iOS 与 Android 移动端带远程桌面。

Linux 指南 docs/linux.md 覆盖安装、更新、keyring 与迁移,细节以官方文档为准。想从源码构建的用户看官方 README:仓库是 TypeScript/pnpm monorepo,apps/desktop 是 Electron 桌面端,apps/mobile 是移动端(Expo/React Native),packages/* 拆出 auth、device-link、agent orchestration、model providers 等模块;claude-code、codex、ripgrep 二进制按平台由 pnpm install 下载;后端服务不在本仓库,是单独的仓库。构建前置:Node.js 22.x、pnpm 10.x(v11 尚未支持)、Git LFS。

开发模式的启动入口(README 原样)值得抄下来:

pnpm restart:desktop:remote --region=cn      # 中国大陆账号
pnpm restart:desktop:remote --region=global  # 其他账号

命令不依赖内部默认值,并暗示账号体系按中国大陆与全球分区,下文单独说;普通用户装官网安装包即可。

登录模式二选一:Hosted service 与 Skip Sign-In

首次启动,用户要在两种登录模式间二选一。注册 Cindy 云账号走完整托管服务(Hosted service);跳过登录用本地 agent(Skip Sign-In),客户端显示 Not signed in,服务端能力不可用(官方口径)。

模式做法可用能力数据路径
Hosted service注册 Cindy 云账号完整托管服务、跨设备同步云端 companions 同步经 Cindy 服务
Skip Sign-In不注册本地 agent 可用,服务端能力不可用对话与文件留在本机

选型口诀:要走远程桌面与跨设备同步就登录云账号,只用本地模型加本地文件就 Skip Sign-In。两模式下模型请求均由对应 provider 处理,计费照常(官方口径)。

四种模型接入方式怎么选

Cindy 的模型接入有四条并列路径。第一种,授权已订阅套餐:官网列举的示例包括 Claude、ChatGPT、SuperGrok、Kimi Code、MiniMax、GitHub Copilot,另有 Claude Code、Codex plan 这类 agent 订阅——授权后额度走原套餐,不新增计费。第二种,连自己的 API key:填入 key 即可,按量计费。第三种,本地模型:官网介绍明确提到 Ollama、llama.cpp、LM Studio,当前为 Beta 状态(官网口径)。第四种是 Cindy 托管模型:Plus 版每月 20 美元起,Team/Enterprise 另有名单制方案(SSO、集中管理、自托管 Gateway)。

接入方式前提计费典型场景
授权订阅套餐已有 Claude Code、Codex 等订阅计入原套餐订阅在手,开箱即用
自己的 API key各厂商 key按量计费用量可控
本地模型Ollama / llama.cpp / LM Studio本地算力,无 API 费隐私、离线、零 API 成本
Cindy 托管Plus 订阅,每月 20 美元起固定订阅不想自己管理 provider

本地模型 Beta:适合尝鲜与隐私优先场景,当生产依赖前先实测稳定性。免费客户端不意味着无限模型额度——provider 限制与计费照常(官网口径)。本地模型搭配 Ollama 的思路可参考本站DeepSeek 本地部署教程。接好模型后,多 agent 分工与 automations 自动化怎么排,见多代理与自动化篇。

国内使用注意:region=cn 与账号分区

从 README 开发入口看,Cindy 的账号体系按中国大陆与全球分区:--region=cn 对应中国大陆账号,--region=global 对应其他账号。这是开发者口吻的观察——该命令面向贡献者;普通用户照官网流程安装与登录即可。

实际影响:远程接入或同步异常时,先核对账号归属与设备所在区域是否一致。终端用户说明以官方文档为准。

跨设备共享模型:一台配好,多台复用

在别的电脑上用已配置好的模型 provider,对应官方跨设备三要点里的“Share more than a screen”。做法是允许对该 provider 的远程访问,另一台设备就能沿用同一套模型接入。这里共享的是 provider 配置与访问权,不是把模型文件复制过去。

权限链条汇总(官方口径):远程访问要求设备在线、同一账号登录、开启相应权限;模型共享要求允许对该 provider 的远程访问;远程桌面还要单独开启权限;项目文件留在各自的电脑上,远程访问不是整盘同步。实际用法:主力机配好 SuperGrok 或本地 Ollama,出差时笔记本、手机连回主力机全部复用。

Linux 安装要点

Linux 用户以官方文档 docs/linux.md 为准:Ubuntu、Arch、Omarchy 各有操作路径,覆盖安装、更新、keyring 与迁移。核对确认的要点如下,细节不替官方背书:

  • 发行版分流:按 Ubuntu、Arch、Omarchy 各自走对应路径,不跨发行版套用命令;
  • 更新:客户端的升级机制与桌面应用版本管理相关,按文档执行;
  • keyring:密钥环相关配置在 Linux 安装时常见,涉及签名与凭证校验;
  • 迁移:换机或换发行版的步骤,文档有对应章节。

源码构建与发行版差异的详细事项都按官方文档执行——Linux 发行版差异大,套错命令的代价比读十分钟文档高得多。

常见问题排查思路

多数连接故障按三层排查:provider 侧、Cindy 权限开关、账号与区域。症状与排查方向对应如下,具体报错以客户端实际输出为准:

症状排查方向
模型请求失败或被拒检查对应 provider 的余额、额度、订阅状态;provider 计费照常,不经 Cindy 兜底
远程访问看不到设备设备在线、同一账号登录、权限开启,三项逐项确认
手机远程桌面不可用确认远程桌面权限是否单独开启
跨设备会话不同步Skip Sign-In 无服务端能力;云端同步需登录云账号
换 harness 后行为异常切换会移交或重建引擎上下文,不保证内部状态一致,重启会话再试

排查顺序:先本地(网络、模型服务、权限开关),再账号(登录状态、区域),最后 provider(额度、订阅)。想横向对比同类桌面 agent 的接入与权限设计,看Cindy 与同类产品对比。

常见问题

“cindy 下载” 从哪里下?

官网 cindy.app/download 提供 macOS、Windows、Linux 桌面安装包,Linux 的 Ubuntu、Arch、Omarchy 有官方指南 docs/linux.md;iOS 与 Android 用移动端,源码构建需 Node.js 22.x、pnpm 10.x 与 Git LFS,按平台取对应安装包即可。

展开:桌面端是主力形态,移动端核心是远程接入——手机通过远程桌面连接同账号的电脑。首次启动二选一登录,再按需求接模型,明细见上文各节。

“cindy 接入模型” 支持哪些?

四种:授权已订阅套餐(Claude、ChatGPT、SuperGrok、Kimi Code、MiniMax、GitHub Copilot 等)、自己的 API key、本地模型(Ollama、llama.cpp、LM Studio)与 Cindy 托管(Plus 每月 20 美元起),额度与计费由对应 provider 决定。

展开:订阅授权最省事但要求已有套餐;API key 灵活按量;本地模型免 API 费且可离线,适合隐私场景;托管省心但按月付费。

“AI agent 本地模型” 怎么搭?

选 Skip Sign-In 进入本地模式,装好 Ollama(或 llama.cpp、LM Studio)并把本地 provider 配给 Cindy,即可不注册云账号、不产生 API 费用,项目文件留在本机。

展开:先把本地模型服务跑起来,再回 Cindy 连接本地端点,模型请求由本地推理处理。注意本地模式下服务端能力不可用(官方口径),远程访问类功能按边界判定。