OpenAlice 完整教學

本文目的：把 OpenAlice 的「為什麼這樣設計」、「該怎麼跑起來」、「能怎麼接進你既有的 AI 工作流」一次講清楚。不是逐行 source walkthrough，重點放在架構、運維、資安、整合面。

1. 專案定位

1.1 一句話總結

OpenAlice 是一個 本地執行的 AI Trading Agent framework，跑在你自己的機器上，把 「決策」（Alice） 與 「執行 / 持有 broker 憑證」（UTA service） 拆成兩支可獨立部署的程序，並用 Git-like 工作流 把每筆下單都變成可審計、可回滾、必須使用者明示批准的 commit。

1.2 為什麼不是「再一個交易 bot」

1.3 適合什麼情境

• 想把 LLM 串進自己的交易但 不願意把 broker 憑證上雲 → 本地跑、可拆 UTA
• 已經是 Claude Code 或 Codex 重度使用者，想讓那條 CLI 也能下單 → MCP 工具直接掛
• 要做 multi-asset、multi-broker 統一帳本 → UTA + Trading-as-Git
• 想 fork 出自己領域的 satellite repo（例如台股、Crypto、Pre-IPO research）→ template + satellite repo 是官方建議路徑

1.4 警語

README 寫得很清楚，這裡照樣強調 —— v0.30 仍在 beta，禁止用於真錢實單交易，無正確性、可靠性、獲利擔保。

2. 安裝指南

2.1 三種跑法總覽

2.2 環境需求

Workspace bootstrap 用 bash + POSIX utils，純 cmd.exe / PowerShell 不支援。

2.3 本機開發三步

1git clone https://github.com/TraderAlice/OpenAlice.git
2cd OpenAlice
3pnpm install      # 大約 1 分鐘，含 node-pty 等 native dep
4pnpm dev

開機後 terminal 印三條 URL：

1[dev] backend  →  http://localhost:47331
2[dev] MCP      →  http://localhost:47332/mcp
3[dev] UI       →  http://localhost:5173

重要：dev 模式直接開 UI 那條（5173）；backend port（47331）在 dev 模式只 serve 預編 UI bundle，會 404。

2.4 Docker 部署（VPS / 自建主機）

1git clone https://github.com/TraderAlice/OpenAlice.git
2cd OpenAlice
3docker compose up -d --build
4docker exec -it openalice claude       # OAuth：把 URL 貼到瀏覽器
5docker exec -it openalice codex login  # 同上（如有用 codex）

之後開 http://<server>:47331，第一次會看到 admin-token 登入頁；token 從 log 抓：

1docker logs openalice 2>&1 | grep -A1 'admin token'

關鍵設計：

• MCP server 的 47332 故意不對外曝光，只給容器內 CLI 用
• 所有狀態（config、workspaces、CLI 憑證、log）都在 openalice-data named volume；docker compose down -v = factory reset
• Base image 是 node:22-trixie-slim（Debian 13），因為 Longbridge 等 native dep 要 glibc 2.39；Alpine 不行（musl + 沒 bash）

2.5 第一次跑常見錯誤

3. 核心架構解析

3.1 雙程序 + Guardian

OpenAlice 把過去常見的 monolithic trading bot 故意拆成兩支 process：

• Alice：決策腦 —— Agent runtime、research domain、Workspace、Web UI、MCP server。不持有 broker 憑證。
• UTA service：執行手 —— broker 連線、Trading-as-Git 狀態機、Guards、FX、snapshot。bind 127.0.0.1，只接 Alice loopback。
• Guardian（scripts/guardian/）：thin supervisor，照順序帶起來 UTA → 等 /__uta/health → 起 Alice → 起 Vite（dev only）；broker config 改變時自動 respawn UTA。

下圖是整體互動（README 內附；這裡簡化）：

graph TB
  subgraph Surfaces["Surfaces"]
    WEB[Web UI]
    INB[Inbox tab]
    MCPS[MCP Server]
  end

  subgraph Workspace["Workspace
dir + git + native CLI"]
    WCLI[claude / codex / shell]
  end

  subgraph Alice["Alice — 決策腦"]
    GR[GenerateRouter]
    TC[ToolCenter]
    IS[InboxStore]
    AW[AgentWork
cron / heartbeat]
    MD[MarketData]
    AN[Analysis]
    NC[News]
    SDK[UTA SDK
loopback HTTP]
  end

  subgraph UTA["UTA service — 執行手"]
    TG[Trading-as-Git]
    GD[Guards]
    BK[Brokers
CCXT/Alpaca/IBKR/Longbridge]
    FX[FX + Snapshots]
  end

  subgraph Sched["Scheduling"]
    CRON[Cron / Heartbeat / Webhook]
  end

  CRON --> AW --> GR
  AW -.->|deliver| IS
  WEB --> Workspace
  WEB --> INB
  SDK -.->|HTTP| UTA
  Workspace -->|mcp.json| MCPS
  MCPS --> TC
  TC --> MD
  TC --> AN
  TC --> NC
  TC --> SDK
  Workspace -.->|inbox_push| IS
  IS --> INB

3.2 為什麼要拆 Alice / UTA

設計動機在 README 寫得最清楚 —— 「像 hardware wallet」：

v0.30 仍 co-located，但設計上 protocol 已備好 detach。

3.3 monorepo 佈局

 1OpenAlice/
 2├── src/                        # Alice 主程序
 3│   ├── core/                   # GenerateRouter / ToolCenter / InboxStore / AgentWork / config / event-log
 4│   ├── ai-providers/           # agent-sdk (Claude) / vercel-ai-sdk (OpenAI/Anthropic/Google) / codex / mock
 5│   ├── domain/                 # market-data / analysis / news / thinking
 6│   ├── task/                   # cron / heartbeat / metrics
 7│   ├── tool/                   # AI tool 定義
 8│   ├── workspaces/             # workspace launcher / template / adapter / git-service
 9│   ├── webui/                  # BFF / WebSocket / auth gate
10│   ├── server/                 # MCP server
11│   ├── migrations/             # config schema migration（0001 → 0007）
12│   └── main.ts                 # composition root
13├── services/uta/               # UTA service（broker carrier）
14│   ├── domain/trading/brokers/ # alpaca / ccxt / ibkr / longbridge / leverup / mock
15│   └── http/                   # loopback HTTP API
16├── packages/
17│   ├── ibkr/                   # @traderalice/ibkr — IBKR TWS API TS port
18│   ├── opentypebb/             # @traderalice/opentypebb — OpenBB platform TS port
19│   └── uta-protocol/           # UTA wire protocol（Alice ↔ UTA 共用 types）
20├── apps/desktop/               # Electron wrapper（macOS DMG / Windows installer 規劃中）
21├── ui/                         # React + Vite 前端
22├── scripts/guardian/           # L2 supervisor（dev.ts / prod.mjs / shared.ts）
23├── default/                    # persona.default.md / heartbeat.default.md（git-tracked 預設）
24├── safe/                       # red team toolkit（playbooks / harness / findings）
25└── docs/                       # 設計文件

3.4 Scheduling 與 Execution 雙層解耦

OpenAlice 把 automation 切成兩層 —— scheduling（什麼時候 fire）與 execution（fire 進到哪）。

這就是為什麼 README 反覆強調 “the last mile is being rebuilt” —— scheduling 是穩的，但 trigger 怎麼落到 workspace 還在迭代。

3.5 安全邊界

• Web 邊界一個 admin-token gate（256-bit，首次開機 print 一次到 stdout）
• 三模式 fallback：localhost → 完全 passthrough；server → 強制 token；OPENALICE_DISABLE_AUTH=1 → 顯式 opt-out（給已有 Tailscale / VPN / reverse-proxy 的人）
• cookie Secure + HttpOnly + SameSite=Lax
• Origin allowlist 擋 CSRF
• Webhook ingest（POST /api/events/ingest）走 Bearer token + timing-safe comparison（node:crypto.timingSafeEqual），未設 token 時直接回 503（default-deny）

4. Helper Scripts 詳細用法

scripts/ 內的東西不是「給 user 跑」的 helper，更像 build / supervisor 工具。逐個列：

4.1 開發常用 npm script

1pnpm dev              # Guardian dev 模式（UTA + Alice + Vite）
2pnpm build            # turbo build + tsup main.ts
3pnpm test             # vitest run
4pnpm test:watch       # vitest 監看模式
5pnpm test:e2e         # vitest 跑 vitest.e2e.config.ts
6pnpm test:bbProvider  # vitest 跑 vitest.bbProvider.config.ts（OpenTypeBB provider 整合測）
7pnpm electron:dev     # build + 啟動 Electron 桌面
8pnpm electron:pack    # 打包桌面 app

4.2 Vitest 三套 config

• vitest.config.ts — 預設 unit test
• vitest.e2e.config.ts — end-to-end，會碰真的 broker / data API，要 credential
• vitest.bbProvider.config.ts — OpenTypeBB provider 整合測

CI 跑前兩套，第三套通常只在 provider 改動時手動跑。

5. 應用場景

5.1 個人量化研究 + 半自動下單

• 設一個 Mock UTA 跑回測
• 接 Alpaca paper trading 或 Binance testnet 跑模擬
• Heartbeat 每天盤前 fire 一次研究 prompt → Inbox 推報告 → 你看了之後在 Workspace 按 commit & push 才真的下單

5.2 Cross-asset 統一帳本

把 Alpaca（美股）+ Binance（crypto）+ IBKR（亞洲股、選擇權）+ Longbridge（港股）統一塞進不同 UTA。AI 看 portfolio 時看到一張統一帳本，不需要切後台。

5.3 把交易能力掛進你既有的 Claude Code workflow

OpenAlice 的 MCP server（dev 模式在 localhost:47332/mcp）可以掛進任何外部 Claude Code / Cursor / Codex session。Workspace 內甚至自帶 .mcp.json，agent 自然就看到 trading tool。

5.4 Pre-IND / 內部研究 satellite

OpenAlice 主 repo 故意不收 ecosystem PR，所有領域延伸（你公司的私有 research stack）走 satellite repo + template 機制。這對我們 Apotek 這種要做內部研究 pipeline 的場景特別合：satellite repo 可 private、可 chmod 700、可不上 Discord，主 repo 只負責 launcher。

5.5 紅隊演練 lab

safe/ 是 ready-to-use 的 red team toolkit。對想學 “2026 攻擊者是 agent” 的工程師，這個 repo 本身就是教材 —— spawn 一個 fresh Claude，給它讀 safe/AGENT_BRIEF.md，請它對你的 dev 實例攻一輪。

6. 資安掃描報告

範圍：src/ + scripts/ + packages/ + services/ + ui/src/，排除 *.spec.ts / *.test.ts / *.d.ts。

6.1 高風險（🔴 高）

無。沒掃到硬編碼憑證、shell injection、SQL injection、SSRF 等高風險樣本。

6.2 中風險（🟡 中）

6.3 低風險（🟢 低）

• Regex .exec() 出現多處（rss-parser、cron/engine、heartbeat、workspace-creator），都是合法的字串 parsing，不是 child_process.exec
• 沒看到 pickle / __import__ / os.system（也不該有，是 TS repo）
• 沒看到 hard-coded API key / secret / token（grep 過 (api_key|password|secret|token)\s*=\s*['"]...['"]，0 hit）
• env var 使用集中在 process.env.COMPACT_PCT_OVERRIDE、process.env.OPENALICE_*，沒有把 user input 直接拼進 shell 的反模式

6.4 整體結論

🟢 低風險。專案明顯有 資安自覺：

• 自帶 safe/ red team toolkit + THREAT_MODEL.md
• 雙程序架構刻意把 broker 憑證隔離到 UTA service，bind 127.0.0.1
• Auth gate 走 timing-safe 比較、default-deny webhook、HttpOnly + SameSite cookie
• Origin allowlist 擋 CSRF

要 self-host 的人應該額外注意：

1. 務必把 admin token 從 docker log 撈出來保管（首次開機後就不會再印）
2. 不要在 bind=0.0.0.0 同時設 OPENALICE_DISABLE_AUTH=1（README 預設 refuse to start）
3. TLS 一定要在前面（Caddy / nginx / Cloudflare Tunnel），不要直接把 47331 暴露在公網
4. broker 帳號優先用 testnet / paper trading；README 自己也強調 beta 階段不要真錢

7. FAQ

Q1：必須用 Claude 嗎？可不可以接 OpenAI / Gemini？ 可以。ai-provider.json 切到 vercel-ai-sdk，填 OpenAI / Anthropic / Google API key 即可，runtime 可切。但 README 強調 Claude 是 reference implementation，因為原生 prompt cache 在長對話可便宜 10×。

Q2：必須裝 Claude Code CLI 嗎？ 若用預設 Workspace 跑 claude adapter，是。要省略可改用 codex adapter 或 shell adapter（不跑 LLM、純 PTY）。

Q3：能不能不裝 broker，就用 research / news 功能？ 可以。research / market data / news / analysis 都在 Alice 側，跟 UTA broker 解耦。

Q4：可以接到我自己公司的 MCP server 嗎？ 可以。OpenAlice 的 MCP server 本身就是 tool exposure 接口；外部 MCP server 則透過 Workspace 的 .mcp.json 加進去就好。

Q5：UTA 真的可以拆到另一台機器嗎？ v0.30 仍 co-located；wire protocol 在 packages/uta-protocol 已備好，但官方目前還沒 ship 跨主機部署的 SOP。如果要嘗試，自己 fork 並加 TLS / mutual auth。

Q6：可以做高頻交易嗎？ 不適合。Trading-as-Git + 使用者明示批准的設計擺明就是「人類週期」工具，不是 µs-level。

Q7：AGPL-3.0 對商用有影響嗎？ 有。AGPL 的「網路使用 = distribution」條款代表把它包進 SaaS 對外提供服務時，必須把你的修改也以 AGPL 釋出。內部自用、fork 後不對外提供服務則不受限制。

Q8：擴充新 broker 該怎麼動？ 看 services/uta/src/domain/trading/brokers/registry.ts，每個 broker 自己宣告 configSchema + configFields + fromConfig，照 ccxt/ 或 alpaca/ 樣子加新 dir 即可。packages/ibkr 是更深度自家 port，當 reference。

Q9：怎麼貢獻？ README 明示 主 repo 不收 ecosystem PR（不是不要 PR，是不要「我想加 X broker」這種擴充）。實際上社群活躍在 satellite repo + template。修 bug、改 trading domain、改 workspace launcher → 主 repo 歡迎；加 X data provider → 自己開 satellite。

8. 進階技巧

8.1 Evolution mode

1// data/config/agent.json
2{
3  "evolutionMode": true,
4  "claudeCodePermissions": { ... }   // 完整 Bash + 檔案系統
5}

打開後 Alice 可以對自己 source code 動手腳（self-modification）。建議只在 disposable VM 內開，並把 git 提交保護打開（main branch protection）。

8.2 自定 persona / heartbeat prompt

預設在 default/persona.default.md 與 default/heartbeat.default.md（git-tracked）。覆寫請寫在 data/brain/persona.md 與 data/brain/heartbeat.md（gitignored）。第一次跑會自動 copy default → 覆寫路徑。

8.3 設定 webhook ingest

1// data/config/webhook.json
2{
3  "tokens": [
4    { "id": "tradingview", "value": "<random-256-bit-hex>" }
5  ]
6}

外部呼叫：

1curl -X POST http://localhost:47331/api/events/ingest \
2  -H "Authorization: Bearer <token>" \
3  -H "Content-Type: application/json" \
4  -d '{"type":"signal","payload":{"symbol":"AAPL","action":"buy"}}'

未設 token 直接 503，不要把這個 endpoint 開在公網但留空 token。

8.4 自定 workspace template

把你的 bootstrap script + 初始檔放成獨立 satellite repo（例如 my-team/openalice-template-foo），在 OpenAlice template registry 註冊一條指向該 repo。新 workspace 一開出來就是你那套形狀。

8.5 跑紅隊演練

1pnpm dev                                  # terminal 1
2# terminal 2：
3claude                                    # 開新對話
4> 讀 safe/AGENT_BRIEF.md 並對這個 dev 實例做紅隊

agent 會自己讀 safe/knowledge/、跑 safe/playbooks/ 的 curl 模板、把 finding 寫到 safe/findings/。

8.6 跨多個 UTA 統一查 portfolio

UTA 是獨立帳本但有共同 SDK；可在 Alice 的 ctx.utaManager 上呼叫 portfolio 聚合 API（v0.30 已提供），AI tool 也直接拿得到。

9. 整合進其他工作流

把 OpenAlice 視為「給 AI agent 用的交易與 research 後端」，幾種具體串法：

10. 重點摘要 Checklist

看完後該記住的幾條（自己跑前可逐項對表）：

• OpenAlice = 本地 AI Trading Agent，跨 5 大資產類別，AGPL-3.0
• 雙程序架構：Alice（決策，不持憑證）+ UTA（broker carrier，bind 127.0.0.1）
• Trading-as-Git：stage → commit → push，使用者每筆都要批准
• Guard pipeline 是 trading 版 ESLint，order 進 broker 前攔截
• Workspace 是「dir + git + 持久 PTY 跑 native CLI」，推薦 substrate
• Inbox 是 workspace → user 的唯一 push 通道（含自動化 run）
• MCP server 在 dev 模式 localhost:47332/mcp，不對外曝光
• Auth：localhost passthrough / server 強制 admin token / OPENALICE_DISABLE_AUTH=1 顯式 opt-out
• Heartbeat / Cron / Webhook 是 scheduling 層，execution 層 last mile 仍在重構
• Satellite repo + Template 是 ecosystem 擴充正解；主 repo 不收領域擴充 PR
• Broker 支援：CCXT / Alpaca / IBKR / Longbridge / Leverup / Mock
• AI provider：Claude Agent SDK（推薦）/ Vercel AI SDK（Anthropic / OpenAI / Google）
• 資安等級：🟢 低；eval 已被嚴格 allowlist 緩解；自帶 safe/ red team toolkit
• 目前 v0.30.0-beta.1，禁止真錢實單，beta 階段
• Windows 必須走 Git for Windows 或 WSL2，純 cmd / PowerShell 不行

11. 進一步閱讀

• 官方網站：https://openalice.ai
• 官方文件：https://openalice.ai/docs
• DeepWiki Q&A（自然語言問整份 codebase）：https://deepwiki.com/TraderAlice/OpenAlice
• 倉庫內 spec：
  • README.md — 入口（最權威，本文很多段直譯自此）
  • CLAUDE.md — 給 AI agent 讀的 architecture brief
  • CHANGELOG.md — 細節變更紀錄
  • docs/project-structure.md — 完整 file tree 註解
  • docs/agent-sdk-notes.md — Claude Agent SDK 串接注意事項
  • docs/opentypebb-tutorial.md — 自家 OpenBB TS port 教學
  • docs/mcp-ask-connector.md — MCP connector ask 模式
  • docs/event-system.md — append-only event log 設計
  • safe/README.md + safe/AGENT_BRIEF.md + safe/THREAT_MODEL.md — red team toolkit 完整文件
  • packages/ibkr/DESIGN.md — IBKR TWS API TS port 設計細節
• 社群：
  • Discord：https://discord.gg/zf4STmrQd8（英文為主）
  • QQ 群：https://qm.qq.com/q/iSg6O4FmrC（中文開發者）
  • X：https://x.com/OpenAliceAI

下一步建議：先 pnpm dev 跑起來，用 mock broker 走一次「研究 → stage → commit → push」流程體會 Trading-as-Git 的節奏，再決定要不要接真 broker（請從 paper trading / testnet 開始）。