Optio Local 完全指南：从浏览器远程管理自己机器上的终端与 Agent 会话-平芜编程栈

【免费下载链接】optio

Workflow orchestration for AI agent swarms.

项目地址：https://gitcode.com/gh_mirrors/opt/optio

Optio Local是 Optio（一个面向 AI Agent 集群的自托管工作流编排平台）的本地运行能力：在你自己的电脑上运行一个轻量 daemon（optio local up），就能从浏览器远程管理本机终端与 Agent 会话——开 shell、执行命令、启动claude/codex/cursor等 Agent CLI，甚至让 GitHub、Slack、定时任务自动在你机器上"开工"。本指南带你从零完成配对，并掌握会话管理、自动化和"需要你"提醒机制。

一、什么是 Optio Local？

在 Optio 里，每份工作（Work）都回答五个问题：When（何时触发）、Where（在哪运行）、Who（谁执行）、What（做什么）、Then（完成后如何）。其中 "Where" 有两个选项：

运行位置	说明
Optio pod（集群）	在你的 Kubernetes 集群里起容器运行
My machine（本机）	通过 Optio Local 跑在你已配对电脑的某个目录里

Optio Local 就是 "Where = 你的机器" 的答案。它的核心特点：

🔒仅出站连接：daemon 主动连到 Optio API 的一个 WebSocket，你的电脑无需开放任何入站端口，浏览器永远不会直连你的机器；
📂目录白名单：你显式添加哪些目录，Agent 才能在哪些目录里工作；
🔑用本机登录态：本地运行直接使用你机器上已装好的 Agent CLI 及其本地登录/凭证，服务器不向你的电脑下发任何密钥；
🔔"需要你"队列：Agent 跑完一轮、敲了终端铃、或命令执行结束后，会话会进入 Needs you（需要你）队列，favicon 变黄、标签页标题出现(N)计数。

架构上只有一条数据通路（详见 docs/optio-local.md 的 Architecture 一节）：

浏览器 ── REST /api/local/* ──┐ 浏览器 ── WS 终端流 ──────────┤ ├── Optio API（中继 + 数据库） ⇐ 出站 WebSocket ⇐ daemon（optio local up） Webhook / 定时 / 工单触发 ─────┘ 在本机白名单目录内运行 PTY 终端

daemon 的核心实现位于 apps/cli/src/local/（终端管理、屏幕模型、注意力检测、会话转录等），服务端中继在 local-relay.ts。

二、如何配对一台机器：三步上手

第 1 步：启动 Optio（若尚未部署）

安装 Docker Desktop 并启用 Kubernetes，然后：

git clone https://gitcode.com/gh_mirrors/opt/optio cd optio ./scripts/setup-local.sh

打开 http://localhost:30310 完成初始化（API 在 http://localhost:30400）。

第 2 步：在电脑上运行 daemon

安装 Optio CLI 后，执行配对命令（命令会显示当前服务器的地址，按提示带上--server与 PAT）：

optio local up

daemon 启动后会以出站 WebSocket 连到 API 并注册主机（POST /api/local/hosts/register），在网页的Machines页（/machines）即可看到你的机器。主机身份会持久化在~/.config/optio/local.json——请勿把这个文件拷到别的电脑。

第 3 步：添加目录白名单

optio local add ~/workspace/myrepo # 添加一个目录 optio local dirs # 查看当前白名单 optio local remove ~/workspace/myrepo optio local status # 查看主机与终端状态

也可以在网页上直接增删目录：Machines 页或 New work 表单里点 "+ Add a directory…"（组件 host-dirs.tsx）。路径必须是绝对路径或位于~之下，daemon 会自动检测每个目录的 git remote——这正是后续"事件触发跑在对应仓库"的匹配依据。

💡 小贴士：配对页面（/machines的 "Add machine"）会实时等待你的机器连上，连接成功即显示在线状态，无需手动刷新。

三、在浏览器里打开、切换和管理本地终端

配好机器后，新建会话时Where选My machine，再选主机与目录，就能得到三种终端（见 local.ts 的POST /api/local/terminals）：

spec 类型	用途
`shell`	一个裸 shell，适合手动敲命令
`command`	直接执行一条原始命令（退出码决定结果）
`agent`	启动 Agent CLI（`claude`、`codex`、`cursor`、`gemini`、`opencode`），可附 prompt

打开某个本地终端后（/local/[id]焦点页），你会获得：

🖥️完整 xterm.js 终端：完整回滚、真彩色（TERM=xterm-256color+truecolor），即使你是中途接入，也会先重放"屏幕快照"再直播后续输出；
💬Chat / Terminal 切换：Agent 会话的对话会被提炼成可读的 Chat 视图（你的提问、Agent 回复、工具调用、思考过程），手机上也能正常换行阅读——会话结束后默认落在 Chat 视图；
⧉分屏：最多同时看 3 个终端（/local/<id>?split=<id2>,<id3>），侧边栏支持会话 rail，按 Needs you / Working / Idle / Finished 分组，可搜索、可置顶；
⌨️快捷键：Ctrl/⌘+Shift+↑/↓切换会话，Ctrl/⌘+Shift+↵跳到等待最久的 Needs you 会话，Ctrl/⌘+Shift+B显示/隐藏侧栏。

多设备协作也有细节：笔记本标签页和手机同时打开同一终端时，系统会仲裁 PTY 尺寸归属（services/local-grid.ts），被"借用"尺寸的屏幕会显示 "Sized for another device · Use this screen" 提示，点一下即可接管。

四、在本机运行 Task 和 Job：零密钥下发

除了手动开会话，Optio 的Task（如"给 issue 提 PR"）和Job（定时/触发式任务）也支持把run location设为local：

在 New Task 表单、Job 编辑器或定时 Task 编辑器中，Where选My machine→ 选主机与目录（只列出 git checkout，自动识别 remote）；
Then选headless（默认：claude -p等，Agent 退出即结束）或interactive（Agent 停在提示符等你继续，你关闭会话才算结束）；
机器离线时任务会停在queued/host_offline，daemon 一上线自动补发，不会丢；
运行状态、token 用量、开出的 PR 链接都会同步回 Run 页面，Job/Task 详情页直接嵌入该会话（embedded-session.tsx）。

调度与同步逻辑见 local-run-service.ts。整个过程中，本地运行只用你机器上的 Agent CLI 和本机登录，服务器不向你的电脑传输任何密钥——这也是很多团队把敏感仓库的工作放在本地的原因。

五、Local Blueprints：用事件触发本机自动化

Automation（蓝图）回答的是"当 X 发生，就在我的机器上跑 Y"。一个蓝图包含：

Who：Agent（Claude Code / Codex / Cursor / Gemini / OpenCode）或一条纯 shell 命令；
What：命令模板commandTemplate（支持{{param}}参数替换）或引用 Prompt 库里的模板；
Where：指定主机 / 目录 / 仓库——也可以写成"事件所属的仓库"，这样一条 PR 审查蓝图就能覆盖你本机 checkout 的所有仓库，没 checkout 的自动跳过；
When：触发器，与 Job 共享同一套 14 种触发器，本地蓝图常用的是github/gitlab/slack/linear/jira/pagerduty/sentry/schedule/webhook等；
Then：interactive（跑完一轮就停下等你，默认）或headless（一次性执行完即退出）。

几个官方菜谱（docs/optio-local.md 的 Recipes 一节，/machines页面的 Automations 区也提供一键预设）：

场景	配置思路
我被 @ 到 PR 时，自动审查	Agent = Claude Code，Where = 事件仓库，触发器 =`github`+`events: [review_requested, mentioned]`+ 你的 login；prompt 用`{{url}}`、`{{headBranch}}`等参数
Slack 频道来消息就处理	触发器 =`slack`+ 频道`channelId`（可加关键词），Then = 保持会话打开等你
告警机器人发帖后自动排障	触发器 =`slack`+`postedBy: "bots"`并指定 bot 名，prompt 用`{{botName}}`、`{{text}}`组装
Linear 工单派给我就分诊并开 PR	触发器 =`linear`+`events: [assigned]`+ 你的 user

安全上，事件 payload 永远不会变成"可执行命令"：参数会被封装成带单引号的 shell 变量，{{title}}只引用变量而不直接拼入命令（renderCommandTemplate），Agent prompt 则以单个引号 argv 传入——恶意事件内容无法注入 shell 语法。触发匹配逻辑在 event-trigger-service.ts。

六、"需要你"提醒机制：知道何时该看回终端

Optio Local 最贴心的设计是注意力检测（daemon 侧实现于 attention.ts），三层信号、最强者生效：

Agent Hooks（精确）：Claude Code 的Stop/Notification/UserPromptSubmit钩子直接告知状态——停下等你 → needs you，提交新消息 → working；Codex 则通过转录轮次标记达到同等精度；
终端铃 BEL（通用）：任何程序输出响铃符 → needs you；
静默兜底：Agent 输出后静默 ≥12 秒判定为在等你；shell 命令跑完静默同理。

needs you 状态会随操作自动清除，2 小时无响应则衰减为 idle，不会一直"喊你"。浏览器侧的联动（attention-watcher.tsx）：

🟡 favicon 出现黄点 = 有会话需要你（绿 = Agent 工作中，灰 = 平静），标签页标题显示(N)计数；
会话头部的bell 按钮可为该会话开启浏览器通知，会话转为 needs you 的瞬间即推送，点击直达该会话；
会话结束后还可用Resume chat按钮通过claude --resume <id>（或codex resume）原样续聊，继承工单/自动化徽章。

七、常见问题 FAQ

Q1：我的机器必须开放端口吗？内网/家庭网络能用吗？不用。daemon 走出站WebSocket，只依赖你能访问 Optio API 的 URL。这正是它优于传统"远程桌面/RDP 式"方案的地方。

Q2：机器断线了，排队的任务会丢吗？不会。主机离线时终端停在pending / host_offline，daemon 重新连接（hello帧）后自动 flush 补发。

Q3：Agent 会话能恢复吗？能。daemon 会捕获 Agent 自己的 session id（local_terminals.agent_session_id），即使 headless 一次性运行，也能之后 "Resume chat" 继续对话；Claude Code 转录缺失时还支持按需回捞（transcript backfill）补全历史对话。

Q4：本地运行的成本怎么看？会话头部有用量 chip：daemon 增量解析 Claude Code 转录文件（usage-tracker.ts），按公开牌价折算本次会话的 token 与估算花费；Codex 的 rate limit 快照也会上报到 Overview 的 Usage limits 面板。

Q5：白名单是安全边界吗？它划定的是"工作在哪里跑"，而不是把机器与主人隔离——白名单目录里的 shell 本来就能访问整台机器。所以 Optio Local 的定位是在自己可信的电脑上做受控编排，而非多租户隔离。