
这篇能帮你做什么
本篇指南面向准备使用 linger 工具快速搭建与运行任务的开发者,旨在提供一套清晰、可实操的上手路径。
通过本文,你可以系统掌握以下内容:
- 核心架构与机制:理解 linger 的基本工作原理与运行逻辑,明确其在任务处理中的定位。
- 环境搭建与安装:完成前置环境检查,掌握标准化安装流程与依赖准备。
- 初始化与参数配置:熟悉关键配置项的作用与调优方法,完成项目的初始化落地。
- 运行验证与异常排查:通过入门示例验证运行结果,并掌握常见运行报错的定位与解决方法。
linger 工作原理与核心架构
Linger 是一款完全在用户个人电脑本地运行的开源个人智能体,其核心工作原理是通过模型与运行框架的高效协同设计,使日常电脑即可承载本地 AI 能力。其底层核心技术架构主要由以下开源组件构成:
- 本地推理引擎(PolyStrata 与 Strata):Strata 作为底层推理引擎负责运行 Qwen3.8-Flash-Next;PolyStrata 构建于 Strata 之上,负责运行本地模型,并将模型最常用的专家网络保留在 GPU 中加速执行。
- 记忆与事实检索(Hindsight):为智能体的记忆模块提供事实提取(Fact Extraction)与搜索能力。
- 桌面应用交互(Cua):赋予智能体在本地桌面环境中调用并操作各类应用程序的能力。
- 协同文档编辑(BlockNote、Yjs 与 Hocuspocus):三者共同为用户与智能体之间的文档实时协同编辑提供底层技术支持。
- 实时音频通信(LiveKit):负责承载语音交流与会议场景中的音频传输流。
- 后台任务调度(River):用于运行 TeamHub 的后台处理作业。

linger 核心模块与开源组件协同关系
安装 linger 与环境准备
在本地部署与运行 linger,可根据单人单机桌面体验或多机协同开发场景选择对应的安装方式:
步骤 1:确认操作系统支持并下载对应安装包
从 GitHub Releases 获取适配当前操作系统的安装包:
- macOS:要求 macOS 14.0 或更高版本且为 Apple silicon 架构,下载
Linger-<version>-macos-arm64.dmg。 - Windows:x64 架构支持通过安装包
Linger-<version>-windows-x64-setup.exe安装,或下载免安装的Linger-<version>-windows-x64-portable.zip直接运行。 - Linux:x64 架构需要 glibc 2.35 或更高版本,下载
Linger-<version>-linux-x64.tar.gz。
步骤 2:启动应用并完成单机快速安装
打开桌面端应用后,应用会自动连接本机并准备运行相关智能体。如果需要在同一台电脑上同时部署服务,直接在设置界面点击 Quick Install,即可一键在当前电脑配置并拉起 Linger 服务端。
步骤 3:多机或服务端场景下运行引导安装脚本
在团队共享服务端或从源码构建场景下(涉及 Docker Compose 服务端环境构建及参数配置的具体步骤见“配置参数与初始化项目”),模型与智能体实际运行于接入的计算节点上。需在对应机器上执行引导安装脚本以完成硬件检测、本地模型安装验证及服务端连接:
- macOS (Apple silicon) 或 Linux:
./scripts/install/install.sh
- Windows (x64 普通非提权 PowerShell):
powershell -ExecutionPolicy Bypass -File .\scripts\install\install.ps1
配置参数与初始化项目
对于多台计算机共享服务或从源码构建的部署场景,可以通过 Docker Compose 进行参数配置与项目初始化。环境准备与初始化步骤如下:
- 确认硬件与运行时环境:运行环境需要配备 Docker 与 Docker Compose,且分配给虚拟机的内存至少为 5 GiB。
- 获取源码并配置环境变量:克隆官方代码仓库并基于示例模板生成环境配置文件:
git clone https://github.com/simplexai-labs/linger.git
cd linger
cp .env.example .env
- 构建并启动服务容器:在包含配置文件的目录下执行启动指令,拉取依赖并等待后台就绪:
docker compose up --build --detach --wait
服务启动完成后,所有者账号的创建及具体运行命令详见“运行入门示例与结果验证”章节。
运行入门示例与结果验证
在完成服务端容器启动后,开发者可通过以下步骤运行初始化示例并验证节点连通性:
创建服务所有者账号:在运行 Compose 容器的环境中,执行以下指令为 Linger 创建初始所有者账户:
printf '%s\n' 'test1234' | docker compose exec -T teamhub \ teamhub-account create-owner --email owner@linger.local --password-stdin执行引导脚本完成连接与验证:Compose 容器仅运行 Linger 服务端,实际的模型与智能体需要部署在连接的工作计算机上。运行对应平台的安装脚本(具体安装参数参见“安装 linger 与环境准备”):
- macOS / Linux:
./scripts/install/install.sh - Windows:
powershell -ExecutionPolicy Bypass -File .\scripts\install\install.ps1脚本在用户确认后将自动执行硬件检查、本地模型安装与验证,并最终将linger-computer节点接入 Linger 服务端完成链路联通。
- macOS / Linux:
常见运行报错与排查处理
在部署与运行 Linger 的过程中,macOS 平台常见的拦截报错及排查方法如下:
macOS 拦截未签名应用首次启动
- 现象:在 macOS 上安装包尚未签名,导致应用拖入“应用程序”文件夹后,系统拦截首次启动。
- 排查与解决:将 Linger 拖入 Applications 后,打开终端执行以下命令清除隔离属性,随后再启动 Linger:
xattr -dr com.apple.quarantine /Applications/Linger.app
执行清除隔离属性时提示
Operation not permitted- 现象:在终端执行上述清除隔离属性命令时,终端输出
Operation not permitted权限错误。 - 排查与解决:进入系统的“系统设置 › 隐私与安全性 › App 管理”(System Settings › Privacy & Security › App Management),开启终端(Terminal)的权限;设置完成后重新打开终端并再次执行清除隔离属性命令即可。此外,官方文档中的 Start Linger on macOS 也说明了无需终端直接允许启动的方式。
- 现象:在终端执行上述清除隔离属性命令时,终端输出
常见误区
在搭建与运行 Linger 的过程中,开发者容易在架构认知、资源划定与系统安全机制上产生理解偏差。厘清工具的适用场景与边界,有助于避免不必要的试错:
- 架构边界与分工认知:Linger 支持将服务协调与模型计算节点分离。误将所有重度推理负载直接压在日常办公轻量端,会导致本地响应迟滞。应明确控制层与算力承载层的边界,通过引导脚本接入合适规格的节点。
- 资源底线约束:容器化部署并非完全轻量化无门槛,基础协调组件与相关运行时存在固定开销,必须预留满足规范的虚拟机内存配额。
| 常见症状 | 根本原因 | 边界考量与应对建议 |
|---|---|---|
| 容器构建或启动中途崩溃退出 | 虚拟机分配的运行内存低于 5 GiB 门槛 | 确保 Docker 运行环境满足最低内存要求,避免因隐性资源耗尽引发中断 |
| 运行期间宿主机严重卡顿与负载过高 | 混淆服务控制端与算力节点,在低配环境直接硬抗重度计算 | 将模型推理与智能体操作分流至满足硬件检测要求的专用计算节点 |
| 安装后提示损坏或无法执行而反复重装 | 操作系统内置的安全隔离机制或终端管理权限未放行 | 识别为系统权限与隔离拦截而非二进制文件损坏,按规范核对权限并清除隔离属性 |
常见问题
Linger 在单机运行和多机共享场景下的部署方式有何不同?
单机使用可直接从 GitHub Releases 下载对应系统的安装包(如 macOS arm64、Windows x64 或 Linux x64),启动桌面应用并在设置界面通过 Quick Install 一键完成本地服务端部署;若用于多台计算机共享或源码构建,则需通过 Docker Compose 启动服务端,并要求虚拟机拥有至少 5 GiB 内存。
Docker Compose 部署完成后,模型和智能体是在容器内运行吗?
通过 Docker Compose 启动的容器仅运行 Linger 服务端本身。模型与智能体实际运行在连接到该服务端的计算机上,需在对应计算节点上执行引导安装脚本(macOS/Linux 执行 install.sh,Windows 执行 install.ps1),由脚本完成硬件检查、模型安装验证并将 linger-computer 连接至服务端。
macOS 首次打开 Linger 提示被拦截或权限报错如何解决?
这是因为 macOS 安装包尚未签名导致被系统安全拦截。可打开终端执行 xattr -dr com.apple.quarantine /Applications/Linger.app 清除隔离属性;如果终端提示 Operation not permitted,需前往系统设置的“隐私与安全性 › App 管理”中为终端授予权限后重新执行该命令。
Linger 的核心智能体能力由哪些开源组件支撑?
Linger 基于多个开源项目协同实现:由 PolyStrata 和 Strata 负责本地模型推理,BlockNote、Yjs 与 Hocuspocus 支持人机协同编辑文档,Hindsight 提供事实提取与搜索等记忆能力,Cua 支持操作桌面应用,LiveKit 负责语音传输,River 负责后台任务队列。
参考资料
(2 条)
- github.com/simplexai-labs/linger/blob/main/README.mdgithub.com · 查阅于 2026-11-20
- github.com/simplexai-labs/lingergithub.com · 查阅于 2026-11-20
本文由 AI 辅助生成,经编辑审核后发布。
本文相关产品
AI 大模型推理七牛云 AI 大模型平台,提供大模型推理 API 与模型广场查看产品AI 智能体面向开发者与企业的智能体开发与编排能力查看产品


