安装教程

本教程按平台分章节，请跳到对应章节。全程本地运行，不需要账号，也不上云。

通用前置：

• Agent 环境：已安装 Claude Code / Codex / OpenCode / OpenClaw 中的至少一个
• 装好引擎即最小可用：安装脚本自动跑 runex init（建库 + 加载引擎系统 ontology），并部署引擎级 runex skill 到各 Agent 平台（三平台一致）。业务类型 / 连接 / Obsidian vault 不预设，按需配置

macOS arm64

开始之前

• 系统：macOS 13 及以上，Apple Silicon（arm64）
• 权限：安装 .app 需要写入 /Applications 或 ~/Applications；默认会优先尝试 /Applications，权限不足时自动回退到用户目录

第 1 步：解压并运行 install.sh

unzip runex-macos-arm64.zip
cd runex-macos-arm64/
./install.sh

install.sh 会帮你完成四件事：

1. 把 runex 终端命令放到 ~/.local/bin/runex（实际是 Runex.app 内部 Mach-O 的符号链接，避免动态库路径断裂）
2. 把 Runex.app 安装到 /Applications/（或 ~/Applications/，如果前者不可写）
3. 移除 com.apple.quarantine 属性，避免第一次双击被 Gatekeeper 拦截
4. 把引擎级 runex skill（通用图搜/检/改接口）部署到各 Agent 平台的 skills 目录：
   • ~/.claude/skills/
   • ~/.codex/skills/
   • ~/.agents/skills/
   • ~/.config/opencode/skills/

然后自动跑 runex init 建库并加载引擎 system ontology。

装完即最小可用（ADR-0018：引擎保持最小基座，不预设任何场景）。引擎只装载系统类型，业务类型 / 连接 / Obsidian vault 不预设——需要时按需配置。

重复运行 ./install.sh 是安全的，会覆盖旧版本 skill 和二进制文件，但不会删除 ~/.runex/ 里的数据。

第 2 步：启动菜单栏托盘

在 Finder 中双击 Runex.app，或者在终端运行：

open /Applications/Runex.app
# 如果安装到了用户目录：
# open ~/Applications/Runex.app

屏幕右上角菜单栏会出现 Runex 图标。点击图标可以看到：

验证安装

runex --version
runex doctor

runex doctor 会检查二进制、skill、数据库、连接状态，全部绿色即表示安装成功。

如果 runex 命令找不到，说明 ~/.local/bin 不在你的 PATH 里。把下面这行加进 ~/.zshrc 或 ~/.bashrc：

export PATH="$HOME/.local/bin:$PATH"

第一次使用

install.sh 已自动跑过 runex init（建库 + 加载引擎系统 ontology）。确认一下：

runex doctor

然后：

1. 想用 Obsidian 管理知识库？先 runex vault bind default ~/.runex/runex-vault，再同步模板，最后用 Obsidian 打开该目录（详见 runex skill 的 vault-bind 工作流）

2. 需要业务类型（Task / Person / CRM 等）？从源码仓库 src/runex/bundled/optional/ 取 .scm，runex ontology load <file>

3. 在 Claude Code / Codex / OpenCode / OpenClaw 里直接对 AI 说话：

   记一下，下周三给王老师发课程大纲。

   AI 会通过 runex skill 在本地图里创建实体和任务。换会话、关窗口、甚至换 Agent，这个状态都不会丢。

卸载

保留数据（只删除程序）：

./install.sh --uninstall

彻底删除，包括 ~/.runex/ 里的所有数据：

./install.sh --uninstall --purge-data

谨慎：--purge-data 会删除你的本地图数据库，不可恢复。

常见问题

双击 Runex.app 提示”无法打开”

Runex.app 是 ad-hoc 签名，没有 Apple Developer ID。install.sh 已经移除了 quarantine 属性，正常情况下不会弹窗。如果仍然弹窗：

1. 打开 系统设置 → 隐私与安全性
2. 滚动到最下方，点击 仍要打开

托盘意外退出

直接在终端重新启动：

open /Applications/Runex.app

不想同步了

在托盘菜单选择 暂停，或者终端执行：

runex connection pause --all

恢复同步：

runex connection resume --all

Linux x86_64

开始之前

• 系统：Linux x86_64（glibc），或 aarch64（arm 变体包 runex-linux-aarch64.zip）
• Agent 环境：已安装 Claude Code / Codex / OpenCode / OpenClaw 中的至少一个

第 1 步：解压并运行 install.sh

unzip runex-linux-x86_64.zip
cd runex-linux-x86_64/
./install.sh

install.sh 会帮你完成三件事：

1. 把 runex 终端命令放到 ~/.local/bin/runex
2. 把引擎级 runex skill（通用图搜/检/改接口）部署到各 Agent 平台的 skills 目录：
   • ~/.claude/skills/
   • ~/.codex/skills/
   • ~/.agents/skills/
   • ~/.config/opencode/skills/
3. 自动跑 runex init 建库并加载引擎系统 ontology

装完即最小可用（ADR-0018）。Linux 没有 macOS 的 .app / 菜单栏托盘；runex 是纯终端 CLI。业务类型 / 连接 / vault 不预设，按需配置。

重复运行 ./install.sh 是安全的，会覆盖旧版本 skill 和二进制文件，但不会删除 ~/.runex/ 里的数据。

验证安装

runex --version
runex doctor

runex doctor 会检查二进制、skill、数据库、连接状态，全部绿色即表示安装成功。

如果 runex 命令找不到，说明 ~/.local/bin 不在你的 PATH 里。把下面这行加进 ~/.bashrc 或 ~/.zshrc：

export PATH="$HOME/.local/bin:$PATH"

第一次使用

1. 想用 Obsidian 管理知识库？先 runex vault bind default ~/.runex/runex-vault，再同步模板，最后用 Obsidian 打开该目录（详见 runex skill 的 vault-bind 工作流）

2. 需要业务类型（Task / Person / CRM 等）？从源码仓库 src/runex/bundled/optional/ 取 .scm，runex ontology load <file>

3. 在 Claude Code / Codex / OpenCode / OpenClaw 里直接对 AI 说话：

   记一下，下周三给王老师发课程大纲。

   AI 会通过 runex skill 在本地图里创建实体和任务。换会话、关窗口、甚至换 Agent，这个状态都不会丢。

卸载

保留数据（只删除程序）：

./install.sh --uninstall

彻底删除，包括 ~/.runex/ 里的所有数据：

./install.sh --uninstall --purge-data

谨慎：--purge-data 会删除你的本地图数据库，不可恢复。

Windows amd64

开始之前

• 系统：Windows 10 及以上，x64（amd64）
• 运行时：PowerShell 7（pwsh），系统自带 Windows PowerShell 5.1 也兼容但建议装 pwsh
• 权限：默认装到 %LOCALAPPDATA%\Programs\runex，全程用户级 PATH（HKCU\Environment），不需要管理员 / UAC

第 1 步：解压并运行 install.ps1

用资源管理器右键 zip → 全部解压，或者在 PowerShell 里：

Expand-Archive runex-windows-amd64.zip
cd runex-windows-amd64
pwsh install.ps1

install.ps1 会帮你完成六件事：

1. 部署 standalone 构建到 %LOCALAPPDATA%\Programs\runex\：
   • runex.dist\runex.exe（Nuitka standalone 主二进制）
   • runex.cmd（PATH 上的转发脚本，调用上面的 exe）
2. 把 %LOCALAPPDATA%\Programs\runex 加入用户级 PATH（写 HKCU\Environment，新 shell 自动生效）
3. 在 %USERPROFILE%\.runex\ 跑 runex init 建库并加载引擎系统 ontology
4. 把引擎级 runex skill 部署到各 Agent 平台的 skills 目录：
   • %USERPROFILE%\.claude\skills\
   • %USERPROFILE%\.codex\skills\
   • %USERPROFILE%\.agents\skills\
   • %USERPROFILE%\.config\opencode\skills\
   • （Windows 用拷贝而非符号链接——软链需要管理员 / 开发者模式；macOS / Linux 用 ln -s）
5. 在 开始菜单 创建两个快捷方式：
   • Runex Tray —— 通过 VBS 静默启动托盘（不会弹黑色控制台窗口）
   • Runex CLI —— 打开终端并显示 runex --help
6. 跑 runex doctor 验证

重复运行 install.ps1 是幂等的：覆盖二进制、刷新 PATH、覆盖 skill、追加快捷方式，但不会清掉 %USERPROFILE%\.runex\ 里的数据。业务类型 / 连接 / vault 不预设，按需配置。

自定义路径

默认值可通过参数 / 环境变量覆盖：

pwsh install.ps1 -BinDir C:\Tools\runex          # 自定义安装目录
pwsh install.ps1 -RunexHome D:\Data\runex        # 自定义 RUNEX_HOME
$env:RUNEX_BIN_DIR = "D:\Tools\runex"            # 或者用环境变量
$env:RUNEX_HOME = "D:\Data\runex"

第 2 步：启动系统托盘

install.ps1 已经创建好 Runex Tray 快捷方式，最方便的是按 Win 键 → 搜 Runex → 回车即可。也可以：

• 开始菜单 → 找到 Runex Tray，点击启动（VBS 静默启动，不弹控制台窗口）
• 或者在 PowerShell 里直接跑：runex tray

屏幕右下角系统托盘会出现 Runex 图标。右键点击可以看到：

验证安装

关键：PATH 变更只对新的 PowerShell 窗口生效，所以请开一个新 shell 跑：

runex --version
runex doctor           # 应输出 all green

runex doctor 会检查二进制、PATH、数据库、连接状态，全部绿色即表示安装成功。

如果 runex 在新 shell 里仍找不到，确认 PATH：

$env:Path -split ';' | Select-String 'Programs\\runex'

或手动刷新当前 shell：

$env:Path = [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' + $env:Path

第 3 步：确认引擎就绪

install.ps1 已经自动跑过 runex init（建库 + 引擎系统 ontology）。确认一下：

runex doctor

想用 Obsidian 管理知识库？先 runex vault bind default %USERPROFILE%\.runex\runex-vault，再同步模板，最后用 Obsidian 打开该目录（详见 runex skill 的 vault-bind 工作流）。需要业务类型？从源码仓库 src/runex/bundled/optional/ 取 .scm 后 runex ontology load <file>。

第一次使用

初始化完成后，直接对 Agent 说话：

记一下，下周三给王老师发课程大纲。

Agent 会在本地图里创建「王老师」实体和一个待办任务。换会话、关窗口、甚至换 Agent，这个状态都不会丢。

卸载

保留数据（只删除程序）：

pwsh scripts/runex/install.ps1 -Uninstall

彻底删除，包括 %USERPROFILE%\.runex\ 里的所有数据：

pwsh scripts/runex/install.ps1 -Uninstall -PurgeData

谨慎：-PurgeData 会删除你的本地图数据库，不可恢复。

常见问题

runex 命令在新 shell 里找不到

PATH 改的是 HKCU\Environment，只有新启动的 shell 会读到。当前已经打开的 PowerShell / Windows Terminal 标签页需要关掉重开，或者手动 refreshenv / 重新登录桌面。

如果你用了 gsudo / runas 提升到管理员 shell，用户级 PATH 在那个上下文里是看不到的——直接用管理员 PATH 或者退回当前用户 shell。

托盘意外退出

直接在 PowerShell 里重新启动：

runex tray

或者从开始菜单再点一次 Runex Tray。

托盘启动了但每次都弹黑窗口

确认你用的是 Runex Tray 快捷方式（VBS 静默启动），而不是直接双击 runex.exe。直接双击 exe 会因为 Nuitka 编译时选了 console subsystem 而弹控制台窗口。

不想同步了

在托盘菜单选择 Pause，或者 PowerShell 里：

runex connection pause --all

恢复同步：

runex connection resume --all

扩展点位置与优先级

装好引擎后，你的扩展代码（kernels / sources / sinks / recipes / connectors / providers / agents 七个 bucket）放在 runex 主目录下的 extensions/ 子目录：

$RUNEX_HOME/extensions/        # 默认是 ~/.runex/extensions
├── kernels/*.py       # 算子实现（Effect / 守卫 / 副作用）
├── sources/*.py       # 入站通道（DataSourceSpec）
├── sinks/*.py         # 出站通道（SinkSpec）
├── connectors/*.py    # 通用连接器（ConnectorSpec）
├── recipes/*.py       # 记录→节点 映射（RecipeSpec）
├── providers/*.py     # Tier-2 agent provider（ADR-0012）
└── agents/*.py        # Tier-2 worker handler

macOS / Linux 默认是 ~/.runex/extensions。 Windows 默认是 %USERPROFILE%\.runex\extensions。

优先级

引擎按以下顺序选一个作为扩展根：

1. RUNEX_EXTENSIONS_DIR —— 显式覆盖，用于服务账号 / Docker / 自定义层级
2. $RUNEX_HOME/extensions —— 跟数据库、blob 同一棵树
3. ~/.runex/extensions —— 单用户本地默认

# 示例：服务账号下指定扩展路径（macOS / Linux）
export RUNEX_EXTENSIONS_DIR=/srv/runex/extensions
runex

# 示例：Windows 下指定扩展路径
$env:RUNEX_EXTENSIONS_DIR = "D:\runex\extensions"
runex

如何写一个扩展（TL;DR）

每个 bucket 一个文件，模块顶层声明 KERNELS / SPEC / HANDLERS，重启 runex 即可生效。详见 docs/extension-authoring.md。

下一步

• 小行星矿场数字孪生 —— 主线教程：从”一张档案卡”到”AI 总裁拍板关停”
• 让它自动跑（无人值守） —— 定时戳它，收尾交给机器
• 写扩展 —— 七个 bucket 的完整参考