使用手冊

開源交易代理 / Local AI Trading

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

TraderAlice/OpenAlice 實戰手冊：安裝、架構、UTA / Trading-as-Git / Guard pipeline 能力、桌面與 Docker 路徑，以及 live trading 前的風險邊界說明。

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

TraderAlice/OpenAlice
星標
4.6K
分支
706
授權
—
資料截至
閱讀時間
11 分
更新日期
開啟原始報告
GitHub Stars
4.6k
Commits
938
Node.js 版本
22+
開源授權
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 的變更紀錄」。

  1. Research

  2. Stage

  3. Commit

  4. Guard

  5. Approve

  6. Push

  7. 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。

bash
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。

bash
[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

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 processagent runtime、research domain、workspace launcher、Web / Telegram / MCP負責研究、決策、溝通,不直接持有 broker credentials。
UTA servicebroker 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。

04Power Tips · README / Docs

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

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

優先用 Workspace chat

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

來源 · README Two kinds of chat

不要開錯 port

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

來源 · README Quick Start

看到 serveStatic warning 先不要慌

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

來源 · README Start it

Docker 不會把 MCP port 對外開

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

來源 · docker-compose.yml

第一次 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

所有設定都在 data/config

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

來源 · README Configuration

Windows 要有 POSIX shell

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

來源 · README Windows

看懂 AGPL 再拿去改服務

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

來源 · package.json + LICENSE

Contributor 路徑不是產品安裝器

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

來源 · README Quick Start

把 UTA service 當 credential carrier

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

來源 · README Architecture

05Worked 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
ok: engine: started
ok: web plugin listening on http://localhost:47331


$ Browser ›
  open http://localhost:5173 → Sidebar → Workspaces → Chat


$ You ›
  請幫我研究 NVDA 今天是否適合建立小部位。
  限制:只允許 paper / demo account,單筆風險不要超過帳戶 1%,
  先給研究摘要、order plan、guard 檢查結果,不要直接執行。


claude: 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]


claude: Alice ›
  hl: 研究摘要
    · 這不是財務建議;以下只是一個 paper-trading plan。
    · 核心假設、失效條件、position sizing 與退出條件列在下方。


  hl: Staged Order Plan
    · account: paper / demo UTA
    · action: staged only
    · commit message: research-backed small test position
    · push: waiting for explicit user approval


  ok: Guard Pipeline
    ok: ✓ max position size
    ok: ✓ cooldown window
    ok: ✓ symbol policy
    ok: ✓ account mode: paper/demo


$ You ›
  先不要 push。把研究假設跟風險條件推到 Inbox,我晚點再回來看。


# [agent calls inbox_push from workspace]
ok: 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先看清楚這些

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

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 採用路徑整理