快速上手:从下载到接模型
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 连接本地端点,模型请求由本地推理处理。注意本地模式下服务端能力不可用(官方口径),远程访问类功能按边界判定。