remote-codex 協作機制

為什麼需要 remote-codex？

我目前的工作環境不是單一電腦，而是一組分散式研究工作站：

MacBook：主要互動介面與控制端
Mac mini：常駐服務、FuBoard、輕量自動化
- FuBoard：跨主機、跨 Codex thread 的持久化狀態板
workstation / studio / NAS 等：GPU、資料庫、長時間任務、模型服務

傳統上，Codex 在本機 thread 裡很強，但如果任務牽涉到遠端資料、GPU、LM Studio、PostgreSQL、tmux session，單一 Codex 就會卡在「我看不到那台機器目前發生什麼事」。

remote-codex 的目的就是：

讓一個 Codex 可以透過 SSH 呼叫另一台主機上的 Codex，並把任務狀態、handoff、blocker、結果摘要寫進 FuBoard，形成多主機 Codex 之間的共享留言板。

這不是單純的 SSH wrapper，而是一個「Codex 指揮 Codex」的協作模式。

核心設計

remote-codex 目前有三個核心元件：

~/.codex/skills/remote-codex/
├── SKILL.md
├── agents/openai.yaml
└── scripts/
    ├── remote_codex_exec.sh
    ├── remote_codex_board.py
    └── remote_codex_task.sh

1. `remote_codex_exec.sh`

負責把 prompt 丟給遠端主機上的 Codex CLI：

printf '%s\n' 'Reply with exactly: REMOTE_OK' \
  | ~/.codex/skills/remote-codex/scripts/remote_codex_exec.sh workstation

它會：

透過 SSH 連到 host alias
bootstrap 遠端 PATH
找到 codex
執行 codex exec
從 stdin 傳入完整 prompt

2. `remote_codex_board.py`

負責把 FuBoard 當作跨主機 Codex 留言板：

~/.codex/skills/remote-codex/scripts/remote_codex_board.py post \
  --to workstation \
  --topic 'RIVET validation' \
  --status question \
  --message 'Please confirm whether the watchdog is still attached.'

讀取最近留言：

~/.codex/skills/remote-codex/scripts/remote_codex_board.py read --tail 80

3. `remote_codex_task.sh`

負責「帶 FuBoard 狀態紀錄」地呼叫遠端 Codex：

cat prompt.txt \
  | ~/.codex/skills/remote-codex/scripts/remote_codex_task.sh studio \
      --cd /Users/<user>/Desktop/2026\ RIVET \
      --topic 'RIVET quick validation'

它會自動：

在 FuBoard 寫入 queued
呼叫遠端 Codex
streaming output 回本機
成功時寫 done
失敗時寫 error

預設只寫 metadata，不會把完整 prompt 或 output 貼到 FuBoard。

SKILL 片段

remote-codex 的 frontmatter 明確說明用途：

---
name: remote-codex
description: Run Codex on remote machines over SSH using host aliases from `~/.ssh/config`, delegate one-off or long-running tasks to another host's Codex CLI, repair remote Codex PATH/auth issues, and coordinate persistent cross-host handoffs through a FuBoard message board.
---

快速使用流程：

## Quick start

1. Read `~/.ssh/config` first and use aliases instead of raw IPs.
2. If the task might have cross-host handoffs, first read the current board tail:

```bash
~/.codex/skills/remote-codex/scripts/remote_codex_board.py read --tail 80

For routine one-off remote runs:

printf '%s\n' 'Reply with exactly: REMOTE_OK' \
  | ~/.codex/skills/remote-codex/scripts/remote_codex_exec.sh workstation

FuBoard 整合片段：

```markdown
## FuBoard message board

Use FuBoard as a persistent, low-volume mailbox for Codex agents on different hosts.

Defaults:

- Credentials: `~/.config/fuboard/credentials.json`
- Page slug: `remote-codex`
- Section: `Codex message board`
- Sender id: hostname or `$REMOTE_CODEX_HOST_ID`

權限控制機制

這個架構故意分成多層權限，而不是讓所有 Codex 都拿到所有能力。

Layer 1：SSH 權限

所有遠端主機必須先存在於：

~/.ssh/config

remote-codex 永遠優先使用 SSH alias，不直接硬寫 IP。

好處：

host identity 集中管理
可搭配 Tailscale / LAN / ProxyJump
可限制 key、user、port
可撤銷單一 host 存取權

Layer 2：Codex CLI 權限

遠端 Codex 執行時可選擇：

--yolo

或安全一點：

--no-yolo

建議規則：

任務類型	建議模式
查詢系統狀態	可用 `--yolo`
讀取研究 artifact	可用 `--yolo`，但不可外洩 PHI
修改 repo	視情況使用 `--no-yolo`
刪除資料、搬移大型資料	不自動授權
sudo / 系統設定	需要額外明確授權
PHI / 報告原文	不寫入 FuBoard

Layer 3：FuBoard reader / writer 分權

FuBoard credentials 存在：

~/.config/fuboard/credentials.json

格式概念如下：

{
  "board_url": "http://100.x.x.x:8765",
  "default_project": "remote-codex",
  "reader": {
    "username": "reader",
    "password": "..."
  },
  "writer_token": "..."
}

設計原則：

reader 用 basic auth
writer 用 bearer token
Codex 不應在回答中印出 token/password
遠端 host 不一定需要 writer token
如果遠端 host 沒有 FuBoard credential，由控制端代為寫入 --from HOST

Layer 4：FuBoard 資料安全規則

FuBoard 是持久化共享筆記，不是 raw log dump。

允許寫入：

host
cwd
run id
thread id
task topic
blocker
artifact path
sanitized summary
next action

禁止寫入：

PHI
病歷號以外的敏感識別資訊
accession number
radiology report 原文
token / password / API key
private URL
大量 raw logs
模型完整輸出中含敏感內容的片段

資料交換格式

目前 FuBoard message board 使用 Markdown append 格式，方便人類閱讀，也容易用 script parse。

Message schema v1

概念欄位：

timestamp: ISO-8601 local time
status: note | queued | running | question | blocked | done | error | heartbeat
from: sender host or agent id
to: target host or agent id
topic: short task label
run_id: optional external run/session id
thread_id: optional Codex thread id
cwd: optional working directory
message: short sanitized text

實際 Markdown 格式：

- **2026-06-19T04:13:56+08:00** `done` | from `macbook` | to `all-hosts` | topic **remote-codex FuBoard integration**
  - message:
    > remote-codex now includes FuBoard message-board helpers.

更完整例子：

- **2026-06-19T05:22:10+08:00** `blocked` | from `studio` | to `macbook` | topic **RIVET Lingshu monitor** | cwd `/Users/<user>/Desktop/2026 RIVET`
  - message:
    > LM Studio is reachable, but no model is currently loaded.
    > Need controller decision: load model or postpone run.

狀態碼約定

Status	用途
`note`	一般留言
`queued`	任務已派發
`running`	任務進行中
`question`	需要控制端或使用者回答
`blocked`	遠端 Codex 卡住，需要外部處理
`done`	任務完成
`error`	任務失敗
`heartbeat`	長任務存活訊號

典型工作流

情境：MacBook 要 studio 跑 RIVET 檢查

控制端先讀留言板：

remote_codex_board.py read --tail 80

接著派任務：

cat <<'EOF' \
  | ~/.codex/skills/remote-codex/scripts/remote_codex_task.sh studio \
      --cd /Users/<user>/Desktop/2026\ RIVET \
      --topic 'RIVET validation'
Please inspect the current RIVET validation status.
Return:
- active tmux sessions
- latest log path
- whether Answer Cube validation is OK
- next blocker if any
Do not print PHI or raw reports.
EOF

FuBoard 會留下：

`queued` from `macbook` to `studio`

完成後留下：

`done` from `macbook` to `studio`

如果遠端 Codex 卡住，則留下：

`error` or `blocked`

為什麼不是只用 SSH？

因為 SSH 只能解決「執行命令」，不能解決「多個 Codex 之間如何保留上下文」。

remote-codex + FuBoard 補上了幾個關鍵能力：

持久化 handoff：thread 關掉也知道誰做過什麼。
多主機共享狀態：MacBook、studio、workstation 都可以讀同一塊板。
低風險資訊交換：預設只傳 metadata，不傳完整敏感 output。
人類也能讀FuBoard 是 Markdown，不是藏在某個 agent memory 裡。
Codex 可機器讀取：格式固定，可 parse status/topic/from/to。

未來可以再加強的地方

1. ACK / resolved 機制

目前 message board 是 append-only。未來可加入：

msg_id: rcx-20260619-0001
reply_to: rcx-20260619-0001
ack_by: studio
resolved: true

2. JSONL sidecar

FuBoard 保留 Markdown，人類閱讀；另外可在 artifact 目錄保存：

{"ts":"2026-06-19T05:00:00+08:00","status":"queued","from":"macbook","to":"studio","topic":"RIVET validation"}

3. per-host capability registry

每台 host 可在 FuBoard 登記：

host: studio
roles:
  - lm-studio
  - gpu-runner
  - postgresql-replica
codex: installed
fuboard_writer: yes

這樣控制端 Codex 可以自動選擇最適合的 host。

結語

remote-codex 的核心不是「遠端執行指令」，而是把多台主機上的 Codex 變成一個可協作的研究工作網路。

SSH 提供 transport
Codex CLI 提供遠端 reasoning/action
FuBoard 提供持久化共享狀態
permission layers 控制風險
message schema 讓人類與 agent 都能讀

這樣一來，MacBook 不只是呼叫遠端機器，而是成為一個 Codex controller；studio、workstation、mac mini、NAS 則可以各自成為有能力、有記憶、有交接紀錄的 remote Codex worker。