企业官网建设流程全解析

Agentero 是一款为人与 Agent 协作而生的一站式科研工作台。它的远程 Vault功能允许你通过SSH在本地打开服务器上的科研资料库：论文、PDF、Markdown 笔记全部保留在服务器，你却在本地界面流畅地阅读、标注、导入论文，并调用运行在服务器上的 Agent 做总结与整理。数据权威永远在服务器，界面体验却和本地几乎一样。

为什么需要远程 Vault？

科研场景里，数据往往"住"在别处：

• 论文和 PDF 在实验室服务器 / 集群 / 云服务器上，本地只是临时工作机；
• 你希望 Agent（Claude、Codex、OpenCode 等）直接在数据所在的服务器上运行，而不是把大文件拷来拷去；
• 多台设备需要访问同一份资料库，但又不想依赖额外的同步工具。

Agentero 的远程 Vault 正是为此设计：本地 UI + SFTP 文件通道 + 远端 Agent，一条 SSH 通道全部打通。

使用前提：3 个检查项 + 1 条平台限制

开始之前，对照 docs/usage/remote-vault.md 检查清单：

💡 服务器上的 ACP Agent 属于可选项：只想读论文、写笔记可以先不装；想让 Agent 帮你总结整理时再按下一节配置。

连接远程 Vault：5 步完成 SSH 连接

连接逻辑实现在 remote-vault-dialog.tsx，欢迎页与 Vault 切换菜单共用同一个对话框：

1. 打开入口：欢迎页选择Open Remote Vault，或当前窗口的 Vault 切换菜单中选择同名入口；
2. 填写 Host：输入 SSH 主机别名或user@host。对话框会自动解析~/.ssh/config中的 Host 条目提供联想，直接回车选中即可；
3. 填写远程路径：填入服务器上 Vault 的绝对路径（例如/home/you/vault）；
4. 点击 Connect：等待文件树加载完成；
5. 确认就绪：看到 Library 论文列表和papers/目录出现，即连接成功。

一条 SSH，三条通道在工作

连接成功后，Agentero 同时使用（设计详见 docs/backend/remote.md）：

• SFTP：读写文件树、Markdown 和 PDF；
• SSH：在服务器上执行远程 Agent；
• 会话内 Catalog 工作副本：论文列表查询读本机镜像、元数据修改后自动写回远端，保证 Library 操作快速又不丢数据。

大文件树为什么也能秒开？

大型远程库的文件树采用"产品目录全量加载 + 其他目录按需展开"的策略：papers/、notes/、plans/、.agents/等目录打开时完整加载，代码仓、实验目录等其他根目录只先列一层，展开时才请求下一层，同时跳过node_modules、.venv、.git等无关目录。同一混合型远程库的打开耗时相比旧方案可减少约 35 倍（见 docs/bug_fix/remote-vault-tree-lazy.md），所以论文多、目录深的库也不必担心打开太慢。

远程 Agent：必须安装在服务器上，而不是本机

这是新手最容易踩的坑：

⚠️ 远程 Agent 必须安装在服务器上。Agentero 会在远程 Vault 根目录启动它，使 Agent 看到的工作目录与 SFTP 文件树完全一致。

在服务器上先确认命令存在（至少准备一个你实际要用的）：

command -v claude-agent-acp command -v codex-acp command -v opencode

然后在 Agentero 的 Agent 设置中选择远程可用的 Agent，界面会显示每个 Agent 的安装与 ACP 就绪状态：

一个容易忽略的细节：非交互 SSH 的 PATH

Agentero 通过非交互 SSH（BatchMode）探测和启动远端 Agent，它的PATH往往比你的交互终端更"瘦"——brew、nvm等目录可能不在其中。可以先用这条命令按 Agentero 同样的方式自检：

ssh -T -o BatchMode=yes <host> 'bash -lc "command -v claude-agent-acp; echo PATH=$PATH"'

如果交互终端里能找到命令、但这里找不到，两个办法任选其一：

• 在 Agent 设置中使用绝对路径；
• 把命令所在目录加入服务器非交互 shell 也会执行的配置（如~/.profile）。

另外注意：Claude Code（claude）≠ ACP 入口（claude-agent-acp），只装了前者还需要安装 ACP 适配器，设置页会给出明确的安装提示（详见 docs/bug_fix/remote-acp-path-ssh.md）。

在远程 Vault 里怎么工作？

连接成功后，日常操作与本地 Vault 基本一致：

• 📚 浏览 Library 和文件树；
• 📄 打开远程 PDF 阅读（PDF 会暂存本机缓存，仅用于预览）；
• ✍️ 编辑并保存NOTES.md；
• 📥 导入论文（远端写路径 + 回收站桥接，与本地共用同一套校验）；
• 🤖 使用 Agent 总结、问答、整理笔记；
• 🔗 查看双链反链，在 References 里看引用近邻图。

断开连接后，远程目录仍是唯一事实来源——随时可以用scp、git等常规工具从服务器取回全部数据。

常见问题排查清单

按 docs/usage/remote-vault.md 的排障顺序，连接失败时依次确认：

其他两条使用注意：

• 不要并发写同一个 Vault：按单写者设计，避免多个客户端、Agent 和外部同步程序同时修改；
• 远程文件变化不会即时推送：远端没有本地 inotify 等价物，Agent 结束、用户保存或重新展开目录时会按需检查；需要时手动刷新文件树即可——刷新会重新加载远程 Catalog，无需清理 PDF 缓存或重新导入论文。

写在最后

Agentero 远程 Vault 让"数据在服务器、体验在本地"成为现实：SFTP 管文件、SSH 管 Agent、Catalog 工作副本管元数据，一次连接全部就位。论文库可以放心放在服务器集群上，换台 Mac 或 Linux 机器、用 SSH 连上，就能立刻继续阅读和写作。更多细节请查阅官方教程 docs/usage/remote-vault.md 与后端设计文档 docs/backend/remote.md。