Imago Local Workspace Agent

本地目录进入 Imago 的信号路径

当前版本采用服务器镜像 + 本地命令桥。agent 主动同步本地目录到服务器镜像；Imago session 选择该 workspace 后，Codex/Claude/shell 由服务器在镜像目录中启动。需要在本机执行的命令通过 mac-run 交给 agent，在本地 workspace 中运行。

NODE 01LOCAL

你的电脑

选择一个本地目录，例如 ~/imago-work 或项目目录。

NODE 02AGENT

Device Agent

每 30 秒扫描一次文件变更，排除 .git、node_modules 等重目录。

NODE 03MIRROR

服务器镜像

服务器保存 workspace 元数据和镜像快照。TUI 输入输出属于服务器上的 PTY 会话，不通过 agent 通道转发。

NODE 04CODEX

TUI 会话

普通用户新建会话时选择该 workspace，Codex/Claude/shell 在服务器镜像目录中工作；本机命令使用 mac-run 执行。

指定目录安装

如果你已经知道要同步哪个目录，可以直接把 workspace 和显示名称写进安装命令。

imago://device-agent/install/custom OPTIONAL

curl -fsSL https://codex.causivo.ai/install-device-agent.sh | bash -s -- --workspace "$HOME/imago-work" --label "我的本地工作目录"

启动、状态和用户边界

已经安装过 agent 的电脑可以只更新脚本并保留本地 config。启动本地后台服务后，Imago 在下一次 sync/poll 成功时会把 workspace 从 agent offline 更新为 agent connected。

更新并重启 agent

只替换 imago-device-agent.js，不改 config.json。这版让 mac-run 后台执行本地命令，避免一个慢命令堵住后续 tunnel poll。

# macOS
curl -fsSL https://codex.causivo.ai/device-agent.js \
  -o ~/.imago/device-agent/imago-device-agent.js
chmod 700 ~/.imago/device-agent/imago-device-agent.js
launchctl kickstart -k gui/$(id -u)/ai.causivo.imago.device-agent
tail -f ~/.imago/device-agent/agent.log

# Linux
curl -fsSL https://codex.causivo.ai/device-agent.js \
  -o ~/.imago/device-agent/imago-device-agent.js
chmod 700 ~/.imago/device-agent/imago-device-agent.js
systemctl --user restart imago-device-agent
systemctl --user status imago-device-agent
tail -f ~/.imago/device-agent/agent.log

`agent offline` 的含义

服务器超过 WEB_TUI_DEVICE_AGENT_STALE_MS 没收到该设备的 sync/poll，默认 90 秒，就会把 workspace 标记为 offline 并禁止新会话使用它。

node ~/.imago/device-agent/imago-device-agent.js \
  --config ~/.imago/device-agent/config.json \
  --once

默认 Persona 和记忆目录

不选择本地 workspace 时，会话进入服务器 scratch workspace，不依赖 agent。普通用户的 Codex home 按用户和 persona 隔离。

/srv/imago/workspace/users/<user-id>/personas/<persona-id>/.codex/
/srv/imago/workspace/users/<user-id>/personas/<persona-id>/.codex/memories/

`Device is not available`

这表示该 device id 已归属其他用户。agent 的 token 必须是 auth DB 里的 active 用户 token；如果 token 正确但仍失败，换一个 --device-id 或让管理员修正设备归属。

curl -fsSL https://codex.causivo.ai/install-device-agent.sh | bash -s -- \
  --device-id "$(hostname)-$(whoami)-imago" \
  --workspace "$HOME/imago-work"

完整卸载

卸载会停止后台服务、从 Imago 后台移除对应 device workspace 记录，并删除 agent 配置、脚本和日志；不会删除你选择的本地 workspace 目录。

imago://device-agent/uninstall REMOVE

curl -fsSL https://codex.causivo.ai/install-device-agent.sh | bash -s -- --uninstall