touri-ai/touri · 上手攻略
- 仓库：touri-ai/touri
- 链接：https://github.com/touri-ai/touri
- 分类：agent · desktop-app
- 作者：Tom
- 更新：2026-10-21
§0 速览
| 项目 | 内容 |
|---|---|
| 是什么 | 本地优先桌面应用，在隔离 VM 中运行持久化 AI teammate（bot） |
| 核心运行时 | Codex、Claude Code、OpenCode CLI |
| 隔离手段 | macOS Apple Container / Linux rootless Podman 或 Docker |
| 技术栈 | Tauri v2（Rust 壳）+ Bun sidecar + React UI |
| 许可 | Apache-2.0 |
| 当前版本 | v0.3.0（2026-10） |
| 平台 | macOS 14+（Apple Silicon）/ Linux x86_64 & arm64 / Windows x64 |
| Stars | 80 |
⚠️ 版本号浮动说明：本文基于 v0.3.0（2026-10 发布），macOS 为预发布签名状态，安装需手动过 Gatekeeper；Linux arm64 为交叉编译，原生打包尚未完全验证。
§1 是什么 / 解决什么问题
touri 是一个本地优先（local-first）的桌面应用，让你在自己的电脑上运行持久化的 AI teammate——官方称之为 "bot"。
每个 bot 有自己独立的指令、记忆、技能和完整分支聊天历史；所有数据存在本地 SQLite，不经明确授权不离开机器。这解决了两个核心问题：
- 数据主权：不信任云托管 AI teammate 的隐私政策，想让对话、记忆、例程完全留在本地。
- 持久化 agent 桌面化：相比纯终端交互的 Claude Code / OpenCode，touri 提供图形界面、项目管理、定时任务（cron）和内置浏览器自动化。
§2 快速安装
macOS（Apple Silicon）
# 下载 v0.3.0 dmg（预发布，未签名）
# 地址：https://github.com/touri-ai/touri/releases/download/v0.3.0/touri_0.3.0_aarch64.dmg
# 挂载后拖入 /Applications
# 首次启动被 Gatekeeper 拦截后：
# 打开 系统设置 → 隐私与安全性 → 滚动到底部 → 点 "仍然打开"
# 输入密码确认。以后正常启动
# 或终端移除检疫标志：
xattr -dr com.apple.quarantine /Applications/touri.app
Linux（Debian/Ubuntu x86_64）
# AppImage 方式
chmod +x touri_0.3.0_amd64.AppImage
./touri_0.3.0_amd64.AppImage
# 或 Debian 包方式
sudo apt install ./touri_0.3.0_amd64.deb
Linux 依赖（x86_64）
需要 WebKitGTK 4.1、SQLite、xdg-utils、带 libsecret 和 Secret Service 接口的会话 D-Bus（GNOME Keyring 或 KWallet）。在专有显卡检测到的主机上，touri 会设置 WEBKIT_DISABLE_DMABUF_RENDERER=1 避免已知图形兼容问题。
Windows（x64）
下载 .msi 或 -setup.exe 安装包，运行即可。WebView2 必须已安装。⚠️ 均为未签名，SmartScreen 可能警告，选"更多信息 → 仍要运行"。
§3 核心配置：接入 API 模型
方式一：自带 presets（开箱即用）
Settings → API models（葡萄牙语界面为 Configurações → Modelos por API）， 选 provider（OpenRouter、DeepSeek、Z.ai/GLM、Moonshot/Kimi、Groq），粘贴 API key， Save。然后在新建 bot 或 bot 设置里选中。
方式二：自定义兼容 API
需要 base URL（含 API 版本路径），例如 https://api.example.com/v1。
连接测试会发送一条真实消息，可能消耗少量额度。Save 后，同上述方式选中。
⚠️ 注意事项：
- 选 chat model 时必须选支持 tools 的模型。
- API 模型通过 OpenCode 路由，享有与 CLI 版相同的文件夹权限和工具集。
- 密钥存系统密钥链（macOS Keychain / Linux Secret Service / Windows Credential Manager），不出现在数据库或日志中。
- 删除保存的模型会同步删除其密钥；使用该模型的 bot 会在下次启动时提示重新选择。
§4 核心用法
4.1 创建并运行一个 Bot
- 打开 touri → 新建 Bot。
- 设置 Bot 名称、描述、选定运行时（Codex / Claude Code / OpenCode）和 Approval 模式：
-
on-request：每次工具调用前请求批准 -workspace-write：修改工作区文件前批准 -full：无批准，直接执行 - 给 Bot 编写系统指令（system prompt）和技能描述。
- 连接一个本地代码仓库（可选，启用项目预览）。
- 开始对话。
4.2 定时任务（Routines）
Routines 是 cron 式的定时 Bot 触发，支持重叠运行（overlap）和追赶控制（catch-up）。在 Bot 设置里配置触发时间和频率。
4.3 MCP Gateway
Settings → MCP gateway，可为每个 thread 配置独立 token 和批准提示。官方通过此方式让 Bot 访问 MCP 工具。
4.4 浏览器自动化
内置 Agent 浏览器，支持人工接管（human take-over）和可视化的 Computer Use，含可见指示器和终止开关（kill switch）。
⚠️ 平台限制：Linux 隐藏主机控制功能（host computer use）；Browser 自动化需要已安装 Chromium/Chrome 或设置 TOURI_CHROME_BIN 环境变量。
4.5 机器隔离（Bot Machines）
- macOS：Apple Container（沙盒）
- Linux：rootless Podman > Docker > local（无容器引擎时降级）
§5 典型适用场景
| 场景 | 为什么适合 touri |
|---|---|
| 个人代码助手本地化 | Claude Code/OpenCode 持久化 + 图形项目管理 |
| 多 Bot 协作 | 每个 Bot 独立 VM 隔离，指令/记忆互不干扰 |
| 定时自动化任务 | Routines 支持 cron 调度，无需盯守 |
| 企业内网 API 调用 | 完全本地运行，数据不外传，适合安全敏感环境 |
| MCP 工具接入 | 自带 MCP Gateway，无需自建 server |
§6 坑与注意
| 坑 | 说明 | 处理方式 |
|---|---|---|
| macOS Gatekeeper 首次拦截 | v0.3.0 macOS 为未签名预发布，Gatekeeper 必拦截 | 按 §2 步骤手动点"仍然打开"或 xattr 清除检疫标志 |
| Linux arm64 尚未完全验证 | arm64 sidecar 为交叉编译，原生打包/runtime 验证尚待完成 | 如遇异常优先用 x86_64 或上报 issue |
| Windows 无 host 控制 | Windows 版不含 host computer use 功能 | 如需此功能请用 macOS 或 Linux |
| 专有显卡 WebView 兼容 | WebKitGTK 在某些专有驱动上有已知图形问题 | touri 自动设置 WEBKIT_DISABLE_DMABUF_RENDERER=1 规避，或手动加此变量 |
| Linux FUSE 依赖 | AppImage 需要 FUSE 才能运行 | 无 FUSE 时用 APPIMAGE_EXTRACT_AND_RUN=1 绕过 |
| 删除模型 = 删除密钥 | 删除保存的 API 模型会同步擦除密钥 | 如需保留密钥，勿通过 touri UI 删除模型 |
| ENCRYPTION_KEY 丢失 = 连接器重配 | 仅适用于 anythingmcp，touri 无此问题 | — |
§7 与同类对比
| 方案 | 隔离 | MCP | 定时任务 | 平台覆盖 | 数据主权 |
|---|---|---|---|---|---|
| touri | ✅ macOS Container / Linux Podman | ✅ 内置 | ✅ Routines | macOS/Linux/Windows | ✅ SQLite 本地 |
| Claude Code CLI | ❌ 无隔离 | ❌ 需自行桥接 | ❌ 无原生 | 全平台 | ⚠️ 依赖云端 |
| OpenCode | ❌ 无隔离 | ❌ 同上 | ❌ 无 | 全平台 | ⚠️ 同上 |
| AgentForge | ✅ Docker 隔离 | ✅ | ✅ | Linux/macOS | ✅ 本地优先 |
| MCP Hub | ❌ | ✅ MCP Server 即一切 | ❌ | 全平台 | ⚠️ |
touri 的核心差异是桌面 GUI + 隔离 VM + 持久化 Bot，适合不想纯命令行、但又重视本地数据控制的场景。
§8 一句话推荐结论
在本地机器上运行持久化 AI teammate，最干净的数据主权方案；适合愿意折腾预发布软件、对隔离有强需求的高级用户。
⚠️ 本文档不确定之处：
- OpenCode executor 在 Linux 下的具体安装路径与依赖版本，官方文档未完整披露，建议以
opencode --version自行验证。 - Routines 的 catch-up 机制在跨天时区漂移场景下的行为，未在 README 中找到明确说明。
- v0.3.0 的完整更新日志（CHANGELOG.md 仅有标题，未 fetch 全文）。