osaurus-ai/osaurus · 上手攻略

  • 仓库：osaurus-ai/osaurus
  • 链接：https://github.com/osaurus-ai/osaurus
  • 分类：AI Agent / 本地 AI harness（macOS native）
  • 作者：spark
  • 更新：2026-08-25

自检：双轨 ✓（机制 + 工程路径）/ ⚠️ 数字核验 2 处（macOS 15.5+/26+ 版本号与隐私分类器规格未独立复测）/ 私域污染 SUM=0 / CJK 估算 ~1700 / verifiability：核心 URL 已 fetch。

是什么

Osaurus 是 macOS 原生的 AI Agent harness：把模型、上下文、记忆、工具、身份这一整套"AI 个人化层"装进你 Mac，而不是别人服务器。仓库标语是 "Own your AI. The native macOS harness for AI agents -- any model, persistent memory, autonomous execution, cryptographic identity. Built in Swift. Fully offline. Open source."

定位关键词：

  • AI 推理是 commodity，harness 才是护城河——README 反复强调 "The models are interchangeable. The harness is what compounds."
  • Native Swift on Apple Silicon——不是 Electron，没有"前端套网页"
  • MIT 开源 + 完全离线——可选接云端模型，但默认数据不出本机
  • Sandbox-first Agent——agent 在隔离 Linux VM 或 Seatbelt 沙箱里执行真实代码

解决什么问题

Mac 上跑本地 LLM 的人通常面临三层痛点：

  1. 模型是"换皮"层——同一套 Llama / Qwen / Step 模型，今天在 LM Studio，明天在 Ollama，后天在厂商应用里，"我是谁、我跟模型的历史、我的偏好"全要重头来
  2. Agent 缺"真沙箱"——agent 想跑 pip install / npm i / 编译代码，要么污染宿主机，要么必须装 Docker
  3. 云端 AI 应用"什么都记"——记忆、工具调用历史、身份信息都托管在服务商，撤了就没了

Osaurus 的回答：

  • Harness 层常驻本机：agent、memory、tools、identity 都在 ~/.osaurus/（明文，依赖 FileVault；可选 SQLCipher）
  • 真隔离执行：macOS 26+ 用 Apple Containerization 框架开 Alpine Linux VM，每个 agent 独立 Linux user；macOS 15.5 退回 Seatbelt sandbox-exec
  • 隐私前置过滤：调用云端模型前，本地用 openai/privacy-filter (1.5B / 50M active sparse-MoE，Apache-2.0) + MLX bf16 (~2.8 GB) 分类识别 PII
  • 接口开放：OpenAI / Anthropic / Ollama API 兼容，本地模型走 Apple Foundation Models 也支持

快速安装

要求：macOS 15.5+ 且 Apple Silicon。 macOS 26+ (Tahoe) 才用 Linux VM 沙箱；15.5 用 Seatbelt fallback。

# 方式 1：Homebrew
brew install --cask osaurus

# 方式 2：手动下载 DMG
# https://github.com/osaurus-ai/osaurus/releases/latest

启动：

osaurus ui       # 打开聊天 UI
osaurus serve    # 启动 server（OpenAI 兼容端点）
osaurus status   # 查看状态

或 Spotlight ⌘ Space → "Osaurus"。

⚠️ 仓库 README 顶部版本号引用的是 GitHub Release latest tag，建议安装前 brew info --cask osaurus 或访问 Releases 页面看具体版本（写稿时未独立复核具体版本字符串）。

核心用法

1. Agent 概念

每个 agent 拥有自己的 prompts / memory / 视觉主题。tools 和 skills 通过 RAG 自动选择——不需要手工配置文件。

两类可选附加：

  • Private local DB：agent 私有的 SQLite 库
  • Self-Scheduled next run：单一的下一次自动运行

详见 docs/AGENT_DB.md。

2. Agent Loop

每次聊天都是 agent loop：

  1. 选一个 working folder → agent 拿到 file / search / git 工具
  2. 开关 sandbox → 拿到隔离 shell
  3. 模型写 markdown todo list → 执行 → 关闭时给 verified summary

详见 docs/AGENT_LOOP.md。

3. 沙箱机制

┌────────────────┐       ┌────────────────────────────┐
│    Osaurus     │       │   Linux VM (Alpine)        │
│                │       │                            │
│  Sandbox Mgr ──┼───────┤→ /workspace  (VirtioFS)    │
│  Host API   ←──┼─vsock─┤→ osaurus-host bridge       │
│                │       │                            │
│                │       │  agent-alice  (Linux user) │
│                │       │  agent-bob    (Linux user) │
└────────────────┘       └────────────────────────────┘
  • macOS 26+ → Apple Containerization 框架 → 完整 Linux 环境（shell / Python / Node / 编译器 / 包管理器）
  • macOS 15.5 → Seatbelt sandbox-exec fallback：写到限制在 workspace；允许 pip / npm 但不允许 apk；网络是"全开 / 全关"二选一（没有 per-domain allowlist）
  • VM 通过 vsock 回连 Osaurus（推理 / 记忆 / secrets 都从 host 走）

详见 docs/SANDBOX.md。

4. 三层记忆

identity (永久)
pinned facts (用户钉住)
per-session episodes (对话摘要)
   ↓ fallback
transcript (全文，仅在以上都不够时回退)

关键设计：

  • 会话末才蒸馏一次（不是每个 turn）
  • 按 salience 评分，每个请求最多注入 一个紧凑切片
  • 后台 consolidator 衰减 / 合并 / 淘汰
  • 大多数 turn 注入 ≤ 800 token，很多 turn 注入 0 token

详见 docs/MEMORY.md。

5. 隐私过滤（出云前本地预处理）

调用云端模型时，Osaurus 跑一个本地分类器：

  • 模型：openai/privacy-filter（Apache-2.0，1.5B 参数 / 50M active sparse-MoE）
  • MLX 转换：mlx-community/openai-privacy-filter-bf16，约 2.8 GB ⚠️
  • 识别类别：names / emails / phones / URLs / addresses / dates / account numbers / free-form secrets
  • 配合确定性正则识别 SSN 等强结构 PII

⚠️ 模型规格与磁盘占用未独立复测，建议安装后 ls ~/.osaurus/models/ 看实际落盘大小。

6. 加密身份

仓库标语里有 "cryptographic identity" 但 docs/IDENTITY.md / 类似页面本次未深入抓取；建议跑起来后看 osaurus status 输出和 docs 站 https://docs.osaurus.ai 的"Identity"章节。

7. 协议兼容

Osaurus 同时支持 OpenAI / Anthropic / Ollama 三种 API 兼容端点，外加 MCP server、Apple Foundation Models。可以把任意"会调 OpenAI 接口"的前端直接指向 osaurus serve。

典型适用场景

  1. 个人长期 AI 助手：模型换来换去，但你的记忆 / agent / 偏好始终在 Mac 上
  2. 本地 Agent 沙箱研究：给 agent 真实代码执行权，又不污染宿主
  3. 多 agent 并行实验：每个 agent 一个 Linux user，互不干扰
  4. 云端模型 + 本地隐私层：用最强云模型，但 PII 先在本地过滤
  5. Apple Silicon 推理 / Apple Foundation Models 的本地 UI 壳

坑与注意

  1. 平台硬限制——只支持 Apple Silicon + macOS 15.5+；Intel Mac / Windows / Linux 全部不在范围内
  2. Linux VM 沙箱要 macOS 26+——15.5 上退化为 Seatbelt，网络是 all-or-nothing，无法 per-domain allowlist
  3. 隐私分类器不是免费——openai/privacy-filter MLX 版 ~2.8 GB 落盘，首次运行有一次性下载 + 每次出云前本地推理开销
  4. 存储默认明文——README 明确说"plaintext by default (protected by FileVault)"；要加密需手动开 SQLCipher
  5. Hugging Face 模型源：官方 huggingface.co/OsaurusAI 是默认模型源，离线 / 内网环境要自己改
  6. CLI 子命令集：ui / serve / status 是 README 头部列出的；完整子命令要看 osaurus --help 或 docs 站
  7. "cryptographic identity" 细节未抓取——README 提了但本次没拉具体 spec；落地前应看 docs.osaurus.ai 的 Identity 章节
  8. 插件生态独立仓库：osaurus-tools 是 plugin registry；不是 monorepo，先看主仓库 README 不要去找 plugin 代码

与同类对比

工具 定位 与 Osaurus 的关键差异
LM Studio 桌面 LLM 推理 UI 不做 harness / memory / agent sandbox
Ollama 本地模型 server OpenAI 兼容 API 强；不做 agent loop / 沙箱
Open WebUI 聊天前端 通用前端；不做 macOS native 沙箱
Claude Code 终端 Agent 云端为主；沙箱策略由 Anthropic 控制
Codex CLI 终端 Agent 同上
Letta / MemGPT 长期记忆层 云 / 本地都有；不绑 macOS
Docker Desktop + Dev Container 通用沙箱 不是 AI harness；记忆 / 工具层要自己接

Osaurus 的独特位置："macOS-native AI harness + 真沙箱 + 本地隐私过滤 + 三协议兼容"——把"模型之上的层"做成一等公民，且只在 Apple Silicon 上做深。

一句话推荐结论

如果你是 Apple Silicon 用户，想要"模型随便换、AI 个人化层（记忆 / 工具 / agent）留在本机"的体验，Osaurus 是目前最完整的 macOS native 方案；如果不是 Apple Silicon、或需要 Linux 沙箱 per-domain 网络控制、或不想本地跑 ~2.8 GB 隐私分类器，需要另选路径。安装前先看 docs.osaurus.ai 的 Identity / Sandbox / Memory 三章节，再决定是否要"全开"。