實戰手冊 · Field Manual 2026-05-30
TraderAlice/OpenAlice · 4.6k ★
A
開源交易代理 / Local AI Trading

本機優先的開源
AI 交易代理。

OpenAlice 是本機優先的開源 AI 交易代理。它把研究、下單計畫、風控檢查與人工批准放在同一個工作區,讓每一步都能檢查、回放、停止。

4.6k
GitHub Stars
938
Commits
22+
Node.js 版本
AGPL
開源授權
01
定位與核心概念

覆蓋研究、下單、風控與人工批准的交易工作台。

OpenAlice 的 README 用一句話定位自己:Your one-person Wall Street。它要做的是一個覆蓋 research、position entry、ongoing management、risk management、exit decision 的 AI 交易代理,並且支援 equities、crypto、commodities、forex、macro 多資產類別。

它刻意跑在你自己的機器上。交易牽涉 broker credentials、private keys 與真金白銀,OpenAlice 的架構把「做決定」與「真的送單」拆開:Alice process 負責 agent runtime、研究工具、Web UI、Telegram、MCP 與 workspace;UTA service 才持有 broker 連線、git-like order state、guard、FX 與 snapshots。

最值得理解的是 Trading-as-Git:先 stage order,用 message commit,最後 push 才執行。Push 前會跑 guard pipeline,執行後會留下 history 與 snapshot。這讓 AI 交易從「黑箱建議」變成「每一步都能 review 的變更紀錄」。

OpenAlice Flow · 交易生命週期
Research→ Stage→ Commit→ Guard→ Approve→ Push→ Snapshot
Trading-as-Git 與 Guard pipeline 的設計目標：每筆交易都能看 diff、擋下、追溯。
— 依 OpenAlice README 的 Trading-as-Git 與 Guard pipeline 架構整理
02
從原始碼啟動

目前以 source 安裝為主，
使用 pnpm dev 啟動。

OpenAlice 目前是 contributor / early-adopter 路徑。你需要 Node.js 22+、pnpm 10+、git、Claude Code CLI。Claude Code CLI 要先跑一次登入;預設 provider 會走你的本機 Claude Code session,不需要先填 API key。

git clone https://github.com/TraderAlice/OpenAlice.git cd OpenAlice pnpm install pnpm dev

啟動後看哪個 URL?

pnpm dev 會印出 backend、MCP、UI 三個 URL。README 的預設範例是 backend http://localhost:47331、MCP http://localhost:47332/mcp、UI http://localhost:5173。開發模式請打開 UI URL,不要直接開 backend port。

[dev] backend → http://localhost:47331 [dev] MCP → http://localhost:47332/mcp [dev] UI → http://localhost:5173 engine: started web plugin listening on http://localhost:47331
Server / Docker 路徑。如果你要放到 VPS 或 always-on box,README 給的路徑是 docker compose up -d --build,再進 container 跑 claude 與 codex login 完成 OAuth。Docker 只 expose Web UI port 47331;MCP port 刻意不對外開。
03
能力總覽

功能分為研究、風控、執行三個層級。

OpenAlice 不是單一聊天機器人,而是一個 TypeScript / pnpm monorepo。README 把能力分成 Trading、Research & Analysis、Automation、Interface 與 AI provider。下面用實務視角重新分組:哪些能力負責看市場,哪些能力負責限制風險,哪些能力負責讓 agent 可以在工作區長時間做事。

Trading · 01
UTA
Unified Trading Account
多個 broker 被包成獨立 UTA。AI 與前端只碰 UTA,不直接碰 broker implementation。
Trading · 02
Trading-as-Git
Stage / Commit / Push
先 stage order,commit message 留下意圖,最後 push 執行。交易歷史像 git log 一樣可 review。
Trading · 03
Guard Pipeline
下單前安全檢查
每個 account 可配置 max position size、cooldown、symbol whitelist 等 guard,在送到 broker 前先擋。
Trading · 04
Snapshots
帳戶狀態紀錄
週期性與事件驅動 snapshot,支援 equity curve 這類 dashboard 視角。
Research · 05
OpenTypeBB
TypeScript-native OpenBB
股票、加密貨幣、大宗商品、貨幣、總經資料走 TypeScript-native OpenBB / OpenTypeBB engine。
Research · 06
Fundamentals
公司基本面研究
README 列出 company profiles、financial statements、ratios、analyst estimates、earnings calendar、insider trading、market movers。
Research · 07
News Archive
背景 RSS 收集
News collector 背景收 RSS,保留 archive search,讓 agent 查市場脈絡不是只看當下 prompt。
Automation · 08
Cron / Heartbeat
排程事件
Scheduling 層負責「什麼時候觸發」:cron、interval、one-shot timestamp、heartbeat active-hours 與 dedup window。
Runtime · 09
Workspace
Agent 的本機工作區
每個任務一個 directory + git repo + persistent terminal session,可跑 claude / codex / shell,並透過 MCP 接 OpenAlice 工具。
Runtime · 10
Inbox
Workspace-to-user Push
agent 在 workspace 裡呼叫 inbox_push,把文件與 markdown comment 推到 UI 的 Inbox tab,使用者再回到 session 繼續。
Interface · 11
Web / Telegram / MCP
多個入口
Web UI 提供 chat、Inbox、portfolio、config;Telegram 有 mobile access;MCP server 對外部 agent 開工具面。
Provider · 12
Claude / Vercel AI SDK
可切換模型後端
預設可用 Claude Agent SDK;也可切 Vercel AI SDK 連 Anthropic、OpenAI、Google 等 provider。

四層架構說明

層級 負責什麼 為什麼重要
Alice process agent runtime、research domain、workspace launcher、Web / Telegram / MCP 負責研究、決策、溝通,不直接持有 broker credentials。
UTA service broker adapters、Trading-as-Git、guards、FX、snapshots 真正送單與持有 credentials 的 carrier,目前同 host 但可朝獨立裝置演進。
Guardian 啟動與監督 UTA / Alice / Vite 負責順序啟動、health gate、config 變更後重啟 UTA。
Workspace 本機 agent CLI session + MCP tools 長工作流用原生 Claude Code / Codex CLI,保留 prompt cache 與 terminal UX。
04
Power Tips · README / Docs

從 README 與 docs 確認的使用注意事項。

這一段不編社群傳聞,只整理 repo 內 README、Dockerfile、docker-compose、project docs 與 changelog 能確認的使用線索。OpenAlice 還在快速變動,所以最重要的技巧不是找隱藏 flag,而是先選對入口、隔離憑證、用 paper/demo account 驗證流程。

TIP 01

優先用 Workspace chat

README 明確說 workspace chat 是互動 UI chat 的推薦路徑。它跑原生 claude / codex / shell CLI,有 vendor prompt cache、terminal rendering 與完整工具面。

來源 · README Two kinds of chat
TIP 02

不要開錯 port

開發模式 UI 通常在 5173,backend 通常在 47331。新 checkout 沒有 pre-built UI bundle,直接開 backend port 會讓你誤判服務壞掉。

來源 · README Quick Start
TIP 03

看到 serveStatic warning 先不要慌

README 說 dev mode 裡 ui/dist 不存在是正常的,因為 UI 由 Vite 提供。等 production build 後,這個 warning 才會消失。

來源 · README Start it
TIP 04

Docker 不會把 MCP port 對外開

docker-compose.yml 只 expose 47331。MCP server port 47332 是給 container 裡的 CLI 用,刻意不暴露到公網。

來源 · docker-compose.yml
TIP 05

第一次 Docker 要進 container 登入 agent CLI

README 與 Docker 註解都要求 first run 後執行 docker exec -it openalice claude 與 docker exec -it openalice codex login,讓 OAuth credentials 留在 volume。

來源 · README Run on a server
TIP 06

所有設定都在 data/config

AI provider、accounts、connectors、telegram、tools、market-data、news、snapshot、heartbeat 等設定都以 JSON 存在 data/config/,並由 Zod 驗證。

來源 · README Configuration
TIP 07

Windows 要有 POSIX shell

Workspace bootstrap 會依賴 bash、sed、cp、mkdir、basename、printf 等 POSIX utilities。README 建議 Git for Windows 或 WSL2;純 cmd / PowerShell 不支援。

來源 · README Windows
TIP 08

看懂 AGPL 再拿去改服務

repo 的 package 與 GitHub license 都是 AGPL-3.0-only。如果你改成網路服務,授權義務和 MIT / Apache 類工具完全不同。

來源 · package.json + LICENSE
TIP 09

Contributor 路徑不是產品安裝器

README 說 macOS DMG 與 Windows installer 還在路上。現在要試用就是 clone source、pnpm install、pnpm dev。

來源 · README Quick Start
TIP 10

把 UTA service 當 credential carrier

README 的架構描述很清楚:Alice 做研究與決策,UTA service 才是 broker credentials、orders、guards、snapshots 的 carrier。這是理解風控邊界的核心。

來源 · README Architecture
05
Worked Example

本機啟動到生成待批准交易計畫的完整流程。

下面是照 README 能確認的路徑寫成的實戰腳本:先跑本機開發環境,打開 UI,用 Workspace chat 要 Alice 做研究與交易計畫。重點不是讓 AI 自動 push order,而是讓它把研究、假設、order plan 與 guard 結果放到你面前,你再決定要不要批准。

~/OpenAlice · local dev · workspace chat
Shell › git clone https://github.com/TraderAlice/OpenAlice.git cd OpenAlice pnpm install pnpm dev
[dev] backend → http://localhost:47331 [dev] MCP → http://localhost:47332/mcp [dev] UI → http://localhost:5173 engine: started web plugin listening on http://localhost:47331
Browser › open http://localhost:5173 → Sidebar → Workspaces → Chat
You › 請幫我研究 NVDA 今天是否適合建立小部位。 限制:只允許 paper / demo account,單筆風險不要超過帳戶 1%, 先給研究摘要、order plan、guard 檢查結果,不要直接執行。
Alice › 我會先查 symbol / quote / fundamentals / recent news, 再把交易假設與風險界線整理成一個 staged plan。 執行前需要你的明確批准。
[workspace created under ~/.openalice/workspaces/<wsId>] [MCP tools available through global + workspace-scoped servers] [research: market data → fundamentals → news archive]
Alice › 研究摘要 · 這不是財務建議;以下只是一個 paper-trading plan。 · 核心假設、失效條件、position sizing 與退出條件列在下方。
Staged Order Plan · account: paper / demo UTA · action: staged only · commit message: research-backed small test position · push: waiting for explicit user approval
Guard Pipeline ✓ max position size ✓ cooldown window ✓ symbol policy ✓ account mode: paper/demo
You › 先不要 push。把研究假設跟風險條件推到 Inbox,我晚點再回來看。
[agent calls inbox_push from workspace] Inbox entry created: NVDA paper-trade research plan
UTA、Trading-as-Git 與 Inbox 的設計前提：每筆訂單在推送前先 stage、解釋、過 guard，由使用者決定是否執行。
— 依 README 的 UTA、Trading-as-Git、Inbox 與 Workspace 流程整理

這段流程驗證的三件事

此流程測試的是系統能否把交易意圖轉為可檢查的 artifact。關鍵確認點有三：研究來源是否足夠、order plan 是否有明確失效條件、guard 是否能攔截超出設定規則的操作。

OpenAlice 的定位是 local-first trading desk，研究、風控、審批、執行在同一條流程上，每個環節都留下紀錄。它不適合作為單純的「AI 選股建議」工具。

06
先看清楚這些

使用前需確認的風險邊界與限制事項。

  • README 明確警告:不要把它當可保證獲利的 live trading 系統。OpenAlice 是 active development 的 experimental software;作者不保證 correctness、reliability 或 profitability,也不承擔 financial losses。
  • 目前沒有原生 installer。DMG 與 Windows installer 還在路上。現在的路徑是 clone source + pnpm dev,適合 contributor / early adopter,不適合期待一鍵安裝的一般用戶。
  • 本機開發模式跳過 localhost auth gate。README 說 local dev 對 127.0.0.1 / ::1 會 zero friction。不要把這種模式直接暴露到 LAN 或 public internet。
  • OPENALICE_DISABLE_AUTH=1 是逃生門,不是部署建議。只有在 Tailscale ACL、VPN、reverse-proxy auth 之類外部邊界已經保護好時才該考慮。
  • Traditional chat token 成本較高。README 說傳統 /chat 缺少 CLI vendor 的 prompt cache 與原生 rendering,長 session 建議用 Workspace chat。
  • Windows 不是純 PowerShell 可跑。Workspace bootstrap 需要 POSIX shell 與 utilities;建議 Git for Windows 或 WSL2。README 也說團隊目前不常 dogfood Windows。
  • Docker volume 是狀態核心。config、workspaces、claude/codex credentials、logs 都在 openalice-data volume。docker compose down -v 會 factory reset。
  • AGPL-3.0-only 會影響商業部署。如果你修改後提供網路服務,需要理解 AGPL 的 source-sharing 義務。這不是 permissive license。
07
下一步路徑

建議先以 paper / demo 帳戶完整驗證流程。

對 OpenAlice 最務實的採用路徑不是「今天接 live broker」。先把它當研究與 paper-trading workflow 跑通:確認資料源、確認 workspace chat、確認 guard pipeline、確認 Inbox 與 approval path,最後再評估是否把真實 broker credentials 放進 UTA service。

建議學習路線

1. 跑完本機 Quick Start。確認 node --version 是 22+、pnpm --version 是 10+、claude --version 可執行,再跑 pnpm dev。

2. 只開 UI port。開 http://localhost:5173 或 Vite 印出的實際 port。不要把 backend / MCP port 當主要入口。

3. 讀 project-structure 與 safe docs。docs/project-structure.md 幫你找 code; safe/README.md、safe/THREAT_MODEL.md、safe/AGENT_BRIEF.md 才是把交易代理放進安全邊界的起點。

4. 用 paper / demo account 練 Trading-as-Git。先練 stage、commit、guard、approve、push 的 mental model,不要在第一天接 live funds。

5. 如果要 self-host,先讀 Authentication。server / Docker / LAN-exposed 模式會產生 admin token;token 只印一次,session cookie 7 天。這不是可以忽略的部署細節。

最該讀的五份延伸閱讀

① README.md，產品定位、Quick Start、架構、Key Concepts、Docker 與 auth。
② docs/project-structure.md，monorepo 結構與主要模組位置。
③ docs/event-system.md，事件與 scheduling 相關背景。
④ safe/，安全範圍、威脅模型與 agent brief。
⑤ CHANGELOG.md，UTA split、UI polish、OpenBB / OpenTypeBB、provider 與 connector 變更脈絡。

優先熟悉 approval path：確認使用者能在 push 前攔截不符預期的訂單，是部署安全邊界的起點。
— 依 OpenAlice README 採用路徑整理