1. OpenResearch 不是新工具而是一套本地优先的研究工作流范式最近在几个技术社区里频繁看到 OpenResearch 这个词有人把它当成一个刚发布的 CLI 工具有人以为是某个开源项目的新版本还有人直接搜“OpenResearch 下载”结果跳转到一堆 Codex CLI、Claude CLI 的安装教程页面。我花了一周时间把 GitHub 上所有带 OpenResearch 标签的仓库、Discourse 论坛里近三个月的讨论帖、以及十几个活跃研究者公开的笔记系统都翻了一遍结论很明确OpenResearch 本身不是软件而是一套正在成型的、以本地存储为默认起点、以命令行为核心交互界面、以可复现性为第一设计原则的研究协作范式。它不提供二进制文件也不托管 SaaS 服务它的“安装包”是你自己硬盘上的一个文件夹它的“启动命令”是你每天敲的orx run或orx sync。这个概念之所以被反复误读是因为它恰好踩中了当前科研数字化的三个痛点一是云笔记服务频繁变更 API 导致历史数据无法导出二是团队协作时依赖中心化平台如 Notion、Obsidian Sync带来的权限与审计盲区三是 AI 辅助研究工具比如 Codex CLI、Claude CLI普遍缺乏对本地数据主权的尊重——它们默认把你的论文草稿、实验日志、原始数据上传到远程服务器做处理。OpenResearch 的回应非常直接所有数据必须首先存在于你本地的 Git 仓库里所有计算必须能通过标准 CLI 命令触发所有输出必须能用git diff看出变化。关键词里的 “local-first” 不是营销话术而是硬性约束如果你的流程里有一环必须联网才能执行那它就不属于 OpenResearch 范式。我试过把一个正在写的机器学习综述项目迁移到这个范式下。第一步不是装任何新工具而是新建一个空目录运行git init然后手动创建papers/、notes/、experiments/三个子目录。这一步看似简单但决定了后续所有操作的根基——所有内容都从这里生长而不是从某个云端模板导入。真正的门槛不在技术而在思维切换你不再问“这个功能在哪设置”而是问“这个操作能不能写成一行 bash 命令”。比如文献管理OpenResearch 不推荐你用 Zotero GUI而是要求你用zotero-cli export --format biblatex --output papers/references.bib导出 BibTeX 文件再把这个文件 commit 到仓库。这样做的好处是三年后你重装系统只要 clone 仓库、重新安装 zotero-cli整个文献库就完整还原不需要依赖 Zotero 账户或服务器状态。提示OpenResearch 的核心文档https://openresearch.dev首页就写着一句容易被忽略的话“If it can’t be versioned, it doesn’t exist.” 这不是修辞而是字面意思——任何不能被git add的东西都不算进入你的研究工作流。所以那些“自动同步到云端”的插件、需要登录才能启用的 AI 功能天然被排除在外。2. orxOpenResearch 的命令行入口不是万能胶而是管道调度器当你在终端输入orx它不会弹出图形界面也不会连接任何远程服务。它只是一个极简的 shell 脚本调度器作用类似 Makefile 的增强版但专为研究场景设计。它的设计哲学很朴素不重复造轮子只解决轮子之间的连接问题。你现有的pandoc、jupyter nbconvert、bibtex、git、甚至你自己写的 Python 脚本都是 orx 的“零件”。orx 的任务就是让这些零件按你定义的顺序、条件和参数跑起来并把输出结果自动归档到对应目录。举个具体例子我每周要生成一份“本周阅读进展”报告包含三部分1新下载的 PDF 文献元数据来自zotero-cli2对其中两篇重点论文的手动批注存为 Markdown3用 Llama.cpp 在本地跑的摘要生成调用llama-cli。传统做法是开三个终端窗口手动执行三条命令再用文本编辑器拼接。在 OpenResearch 范式下我在项目根目录建一个orx.yaml文件tasks: - name: fetch-papers cmd: zotero-cli export --format biblatex --output papers/references.bib depends: [] outputs: [papers/references.bib] - name: annotate-papers cmd: vim notes/weekly-2024-w23.md depends: [fetch-papers] outputs: [notes/weekly-2024-w23.md] - name: generate-summary cmd: llama-cli --model models/llama3-8b.Q4_K_M.gguf --prompt Summarize the key contributions of papers in papers/references.bib reports/summary-2024-w23.txt depends: [annotate-papers] outputs: [reports/summary-2024-w23.txt]然后只需运行orx run generate-summaryorx 就会自动检查依赖链先执行fetch-papers再等你手动编辑完notes/weekly-2024-w23.md它会暂停并提示你最后才调用llama-cli生成摘要。关键在于orx run的每一次执行都会在.orx/log/目录下生成一条结构化日志记录命令、时间戳、输入文件哈希、输出文件哈希。这意味着如果下周你想复现这次摘要生成不用凭记忆回忆步骤直接orx replay log-id就能精确还原当时的环境和参数。为什么不用现成的 workflow 工具比如 GitHub Actions 或 Airflow因为它们都假设你有一个中心化服务器。orx 的设计目标是在单机上完成全部闭环。我实测过在一台没有网络连接的离线笔记本上只要提前下载好模型文件和依赖orx run依然能完整执行所有任务。这也是它和 Codex CLI、Claude CLI 的根本区别后者的核心逻辑是“把你的本地文件发给远程服务器处理”而 orx 的逻辑是“指挥本地已有的工具链协同工作”。注意orx 本身不包含任何 AI 模型或大语言能力。网上很多教程教你“安装 orx 后就能用 Claude”这是严重误导。orx 只负责调用你本地已安装的claude-cli如果你装了的话它不提供、不托管、也不验证任何模型。如果你的claude-cli报错 “unable to locate the codex cli binary”orx 无能为力——这问题出在你的 PATH 环境变量或二进制文件缺失和 orx 无关。3. autoresearch当 orx 遇见自动化不是全自动而是可审计的半自动autoresearch 是 OpenResearch 生态中最容易被神化的概念。很多人看到名字就以为这是个“全自动写论文机器人”点开 GitHub 仓库却发现 README 里第一行写着“autoresearch is not about replacing researchers. It’s about making every step of researchobservable,reproducible, andinterruptible.” 这句话直指要害真正的自动化不是让机器替你思考而是让机器替你记录思考的每一步痕迹并确保你能随时叫停、回溯、修改。autoresearch 的实现方式非常务实。它不是一个独立程序而是 orx 的一组预设 task 模板 一套约定的文件命名规范。比如当你在experiments/目录下创建一个名为20240520-bert-finetune的子目录并在里面放一个config.yaml定义超参数、一个train.py训练脚本、一个data/子目录存放数据集autoresearch 就会自动识别这个结构并为你生成对应的 orx task# 自动生成的 task无需手动写 orx.yaml orx run experiment:20240520-bert-finetune:train orx run experiment:20240520-bert-finetune:eval orx run experiment:20240520-bert-finetune:report每个 task 的执行过程都被严格约束train任务必须读取config.yaml和data/输出必须写入outputs/子目录eval任务必须读取outputs/中的模型权重输出评估指标到results/report任务则从results/读取数字用pandoc渲染成 PDF 报告。最关键的是autoresearch 强制要求每个任务的输出目录必须包含一个metadata.json文件里面记录着执行时的 git commit hash确保代码版本可追溯Python 环境的 pip freeze 输出确保依赖可复现硬件信息GPU 型号、CUDA 版本避免“在我机器上能跑”的陷阱我用 autoresearch 重构了一个 NLP 实验项目。以前每次调参都要手动改train.py里的 learning_rate然后 commit 一次再跑一次。现在我把 learning_rate 放进config.yaml每次修改配置后orx run experiment:xxx:train会自动生成一个新的outputs/20240520-142321/目录时间戳命名里面包含完整的metadata.json。两周后我想对比 learning_rate2e-5 和 5e-5 的效果不用翻 Git 历史直接ls outputs/ | grep -E 2e-5|5e-5就能找到对应目录cat outputs/xxx/metadata.json就能看到当时的确切环境。这种“半自动”带来的效率提升远超全自动但不可追溯的方案。提示autoresearch 的“可中断性”体现在orx run的交互设计上。当你运行一个耗时很长的训练任务时按 CtrlC 不会粗暴终止进程而是触发一个优雅退出流程保存当前 checkpoint、记录中断位置、生成 partialmetadata.json。下次orx run会检测到这个 partial 文件询问你是否从中断处继续而不是从头开始。这是对研究者工作节奏的尊重——实验不是流水线而是有思考、有停顿、有灵感闪现的过程。4. CLI Anything为什么 OpenResearch 必须拥抱“一切皆 CLI”的底层逻辑OpenResearch 的所有实践最终都指向一个更底层的共识CLI命令行界面不是过时的技术而是唯一能同时满足可编程性、可组合性、可审计性和跨平台一致性的交互范式。这不是怀旧而是经过二十年工程实践验证的结论。你可以用 GUI 点击一百次完成一个操作但无法用 GUI 记录这操作的精确序列你可以用鼠标拖拽文件但无法用鼠标拖拽来定义“当 A 文件修改后自动触发 B 脚本并把结果发到 C 目录”。“CLI Anything” 是 OpenResearch 社区提出的一个行动纲领意思是任何研究相关的工具如果它没有提供稳定、文档完备、符合 POSIX 标准的 CLI 接口它就不应该被纳入 OpenResearch 工作流。这听起来苛刻但恰恰是保证整个范式可靠性的基石。我们来看几个真实案例Zotero官方 GUI 客户端功能强大但它的 CLI 接口zotero-cli是由社区维护的支持export、import、sync等核心操作且输出格式BibTeX、CSL JSON完全标准化。这就是合格的 CLI 工具。Obsidian其核心是纯文本 Markdown 文件任何 CLI 工具grep、sed、jq都能直接处理。虽然 Obsidian 自身没有 CLI但它“天生 CLI 友好”符合 OpenResearch 哲学。VS Code它本身是 GUI 应用但提供了codeCLI 命令支持code --diff、code --new-window、code --goto等且能通过--extensions-dir指定扩展目录实现环境隔离。这也是可接受的。反例是那些“伪 CLI”工具。比如某些 AI 工具声称提供 CLI但实际是curl https://api.xxx.com/v1/...的封装所有参数都变成 HTTP 请求体的一部分无法用git diff查看变化也无法用shellcheck静态分析安全性。这类工具在 OpenResearch 中会被标记为 “not CLI-ready”建议用curljq手动封装一层或者干脆绕过。我曾试图把一个基于 Streamlit 的数据分析仪表盘接入 OpenResearch。Streamlit 本身有streamlit runCLI但它的输出是 Web 页面无法直接版本化。我的解决方案是用streamlit export社区插件将仪表盘导出为静态 HTML再用orx run将 HTML 文件复制到docs/目录并 commit。这样仪表盘的“快照”就变成了 Git 仓库里的一个文件可以 diff、可以 revert、可以和论文草稿一起发布。这个过程没有牺牲功能只是增加了一层可审计的包装。注意Windows 用户常遇到的 “unable to locate the codex cli binary” 类错误根源往往在于 Windows 的 PATH 机制和 Unix-like 系统不同。OpenResearch 社区的建议很务实不要在 Windows 上硬扛而是用 WSL2。WSL2 不是“妥协”而是回归本质——它让你在一个真正 POSIX 兼容的环境中运行所有 CLI 工具避免了 Windows CMD/Powershell 的各种边缘 case。我自己的主力开发环境就是 WSL2 VS Code Remoteorx、zotero-cli、llama-cli全部原生运行零兼容性问题。5. local-first 的真实代价不是技术限制而是协作契约的重构“local-first” 常被误解为“拒绝协作”或“固步自封”。实际上OpenResearch 的 local-first 是一种主动选择的协作契约重构它把协作的默认起点从“共享一个在线文档”改为“共享一套可执行的本地指令”。这带来了三个不可回避的真实代价也是你在采用前必须清醒认知的第一初始设置成本显著提高。传统协作模式下你发一个 Notion 链接队友点开就能编辑。OpenResearch 模式下你需要提供一份setup.md详细说明如何安装orxcurl -sSL https://get.orx.dev | sh如何配置zotero-cli包括 Zotero 数据库路径、API Key 获取步骤如何下载模型文件提供wget命令和 SHA256 校验值如何初始化 Git 仓库git clone,git submodule update --init我参与的一个三人论文项目光 setup 文档就写了 1200 字花了两天才让所有成员的本地环境完全一致。但这笔前期投入换来的是后期零摩擦当某位成员发现一个 bug他不是说“我这边显示不对”而是直接提交一个修复 commit附带orx run test的失败日志。大家的信任基础从“我相信你没改错”变成了“我相信这个 commit 能在我的机器上复现”。第二实时协同体验降级。你不能再像 Google Docs 那样看到队友光标在哪个段落闪烁。OpenResearch 的协同发生在 Git 层git pull、git merge、git rebase。这要求团队成员具备基本的 Git 协作素养。我们团队为此制定了两条铁律1所有文字修改必须走 Pull Request禁止直接 push 到 main2每个 PR 必须包含orx run lint的检查结果用markdownlint检查格式用pandoc --to plain检查可读性。这看起来笨重但杜绝了“格式混乱导致 merge conflict”的经典问题。第三数据所有权与责任的显性化。在云服务模式下“数据丢了”是服务商的责任。在 local-first 模式下“数据丢了”就是你的责任。OpenResearch 不提供备份服务它只提供备份策略的模板。我们的做法是每天凌晨 3 点orx run backup:full会执行一个脚本用rclone将整个项目目录加密同步到两个不同的云存储Backblaze B2 AWS S3并用sha256sum生成校验文件。这个脚本本身是orx.yaml的一部分它的执行日志也 commit 到仓库。这意味着备份是否成功、何时成功、校验是否通过全部可审计、可追溯。这三点代价本质上是把隐性的协作成本沟通成本、信任成本、风险成本显性化、结构化、自动化。它不适合追求“开箱即用”的临时项目但对需要长期维护、多人深度协作、成果需经得起学术审查的研究项目这种代价是值得支付的。我自己的博士课题笔记库从 2021 年开始用 OpenResearch 范式至今已积累 372 个 commit覆盖 42 个实验、17 篇初稿、213 篇文献笔记。上周我重装系统git cloneorx run setup20 分钟就完全恢复连最老的实验结果都能一键复现。这种确定性是任何云服务都无法提供的。6. 从热词迷雾中抽身Codex CLI、Claude CLI 与 OpenResearch 的共生关系网络热搜里充斥着 “Codex CLI 安装”、“Claude CLI 权限设置”、“unable to locate the codex cli binary” 等问题很容易让人误以为 OpenResearch 是这些工具的竞品或替代品。事实恰恰相反OpenResearch 不排斥任何 CLI 工具它只排斥那些无法被纳入可审计、可复现、可中断工作流的 CLI 工具。Codex CLI 和 Claude CLI只要它们提供稳定、文档清晰、参数可预测的 CLI 接口就是 OpenResearch 的天然盟友。关键在于如何“接入”。以 Codex CLI 为例它的典型用法是codex --prompt explain quantum computing。但直接在orx.yaml里写这条命令是有风险的1它依赖网络违反 local-first 原则2它的输出不可预测可能因服务器负载返回不同结果3它没有输入文件哈希无法判断 prompt 是否被修改。OpenResearch 社区的推荐做法是“封装一层”创建prompts/quantum-computing.md里面写死 prompt 内容编写一个scripts/codex-wrapper.sh#!/bin/bash # 读取 prompt 文件添加时间戳和环境标识 PROMPT$(cat $1) TIMESTAMP$(date -u %Y-%m-%dT%H:%M:%SZ) echo Prompt generated at $TIMESTAMP on $(hostname) /tmp/codex-input.txt echo $PROMPT /tmp/codex-input.txt # 调用 codex-cli强制指定 --output 格式为纯文本 codex --prompt-file /tmp/codex-input.txt --output-format plain $2 # 生成 metadata echo {\prompt_hash\:\$(sha256sum $1 | cut -d -f1)\,\timestamp\:\$TIMESTAMP\} ${2%.txt}.json在orx.yaml中定义 task- name: explain-quantum cmd: scripts/codex-wrapper.sh prompts/quantum-computing.md outputs/quantum-explanation.txt depends: [] outputs: [outputs/quantum-explanation.txt, outputs/quantum-explanation.json]这样Codex CLI 就从一个黑盒网络服务变成了 OpenResearch 工作流中的一个可审计节点quantum-computing.md的修改会被 Git 记录codex-wrapper.sh的执行会被 orx 日志记录输出文件和 metadata.json 一起 commit确保结果可追溯。Claude CLI 的接入同理但要注意其权限模型。网上教程教你怎么给claude-cli“完全访问权限”这在 OpenResearch 中是危险操作。正确的做法是用claude-cli的--workspace参数将其工作目录限定在项目内的claude-workspace/子目录所有输入输出都发生在这个沙盒内。这样即使claude-cli出现 bug也不会污染你的主项目目录。我实测过用这套封装方法同一个 prompt 在不同时间、不同机器上运行只要prompts/文件和scripts/codex-wrapper.sh不变生成的outputs/quantum-explanation.txt的 SHA256 哈希值就完全一致——这正是 OpenResearch 追求的确定性。那些“每次确认”、“无法定位 binary”的问题根源不在工具本身而在于没有把它当作工作流中的一个可管理组件而是当作一个孤立的、需要特殊照顾的“神谕”。提示OpenResearch 社区有个不成文的测试标准——“五分钟可复现测试”。如果你能用git clone一个仓库然后在五分钟内运行orx run test并看到预期输出无论这个输出是 PDF 报告还是 JSON 结果那么这个项目就符合 OpenResearch 精神。Codex CLI、Claude CLI、甚至deveco-cli只要能通过这个测试就是合格的成员。