首次交易

本指南帶你從剛克隆的倉庫出發，完成通過 Agent 執行首筆小額交易的全過程。涵蓋動用真實資金前必須瞭解的每一個安全開關，並解釋各自存在的意義。

如需快速瀏覽：安裝 → 登錄 → 設置硬上限 → minara doctor → 對話並交易。頁面其餘內容解釋每一步的重要性。

這是終端演練版本。所有操作均在交互式 minara 對話會話（REPL）中完成。如果更偏好儀表盤，可參考與 Agent 對話，在 Web UI 中運行同樣的首次交易流程。

0. 前提條件

Node.js ≥ 24。
一個 Minara 賬戶（通過設備流程或 API key 登錄）。
已配置一個 LLM 提供商（Anthropic API、Claude OAuth、OpenAI 或 OpenRouter）。
少量願意承受損失的資金。Agent 的設計以安全為先，但任何聯網系統都可能以意外方式出現故障。首次交易應視為演練，而非生產部署。

如果尚未完成克隆和安裝步驟，請參閱安裝。

1. 運行設置嚮導

minara setup

嚮導會檢測可用的提供商，逐一引導完成登錄，探測 ~/.minara/ 目錄中可導入的狀態，搭建工作區（SOUL.md、AGENTS.md、USER.md），運行 doctor 命令，並打印速查表。

嚮導的實際操作：

創建 ~/.minara/（或 $MINARA_DATA_DIR，如已設置），包含 sandbox/files/、workspace/、logs/ 以及空的 minara.db。
將活躍模型寫入 ~/.minara/settings.json 的 model 段，並將消息/提供商憑證存入 ~/.minara/credentials.json。
在 ~/.minara/auth/ 下存儲加密的認證配置。
最後運行完整的 doctor 檢查，確保啟動時的問題立即暴露，而非等到第一次 LLM 調用時才出現。

如果環境變量中已有憑證，嚮導會自動讀取並跳過對應的登錄步驟。

2. 驗證配置

minara doctor

正常輸出中每一項均為綠色：

✓ data dir            /Users/you/.minara
✓ sqlite              minara.db  (WAL)
✓ llm provider        anthropic (api_key)
✓ minara auth         device flow
✓ tool registry       62 tools registered
✓ workspace           SOUL.md, AGENTS.md, USER.md
✓ env                 ANTHROPIC_API_KEY, MINARA_API_KEY set

任何黃色或紅色項都是實質性問題，務必在 doctor 全部通過後再繼續。常見問題：

minara auth (not configured)：運行 minara auth login minara，在瀏覽器中完成設備流程。
llm provider (no credentials)：通過嚮導選擇一個提供商，或直接導出對應的環境變量。
tool registry (0 tools)：通常意味著環境缺少某個工廠函數所依賴的憑證，查看日誌中的缺失環境變量警告。

3. 在首次對話前設置硬約束

這是本頁最重要的步驟。Agent 遵循三條硬編碼上限，由權限等級鉤子鏈強制執行，與 LLM 的行為無關：

# 单笔交易美元上限。Agent 无法执行超过此金额的单笔交易。
minara config set safety.maxTransactionAmount 25

# 每日累计美元上限。原子性扣减，并发交易无法通过竞争超出此限额。
minara config set safety.dailySpendCap 100

# 黑名单。将绝对不希望 Agent 触碰的代币加入其中。
# 规范地址层已拦截已知诈骗代币，此处为用户自控层。
minara config set safety.blockedTokens '["SAFEMARS","SQUID"]'

首次交易時，上限應設置在出錯後仍可接受的範圍內。單筆 $25、每日 $100，意味著最壞情況的損失是 $100，可視為學習成本。

驗證設置是否生效：

minara config list

關於安全層暴露的所有配置項，請參閱資金安全。

4. 啟用緊急關閉開關工作流

在整個會話期間，隨時保持 /kill 觸手可及。它會設置一個標誌，BeforeToolCallHook 鏈在每次工具調用時都會檢查該標誌，激活後立即阻斷所有二級及以上操作。

此步驟無需額外操作，只需記住該命令的存在。在第一輪對話時練習使用：

> /kill
✓ emergency stop ACTIVE — all tier 2+ tools blocked
> /unkill
✓ emergency stop cleared

5. 進入 REPL

minara

會看到身份標識橫幅、速查表和閃爍的提示符。先發起一個只讀問題，確認 Agent 行為正常：

> what's BTC trading at?

Agent 應激活 market.spot 技能，調用 get_price，並返回價格。如需查看完整調用鏈，可用 /logs 20 查看日誌中的工具調用記錄。

再嘗試幾個只讀查詢，建立信心：

> show my portfolio
> trending tokens on solana
> what's my daily spend so far

以上均屬於一級權限，不會發生任何資金移動。

6. 發起一筆小額閃兌

在符合配置上限的前提下，發起金額儘可能小的交易。對於單筆 $25 的上限：

> swap $10 of USDC into ETH on base

預期流程：

Agent 通過 activate_skills 激活 market.spot 技能。
調用 token_safety_check，將 Base 上的 USDC 和 ETH 解析為規範地址。
調用 position_sizer，計算出 $10 的規模，返回 clipped: false（未超出上限）。
針對當前投資組合調用 exposure_limit_check。
對兌換進行模擬，獲取預估輸出和價格影響。
將模擬結果（含價格影響）呈現給用戶並請求確認。
只有在輸入 yes 後，才會調用實際的 swap 工具。

確認步驟是真實存在的。每個帶有 requires_user_confirmation 的三級工具都會在 L3 風險閘門處被阻斷，直到用戶確認。下一輪對話的系統提示詞中應能看到待確認塊：

<pending_confirmation>
  skill: market.spot
  action: swap
  summary: "$10 USDC → ETH on base, est output 0.0028 ETH, price impact 0.3%"
</pending_confirmation>

如果價格影響超過小額交易的滑點閾值（默認 2%），兌換在確認前即會被拒絕。這是滑點保護在發揮作用。

7. 確認並查看審計日誌

輸入 yes 後，Agent 執行兌換並返回 Minara 交易 ID。立即拉取本輪的審計記錄：

sqlite3 ~/.minara/minara.db \
  "SELECT tool_name, blocked, substr(result_json, 1, 80)
     FROM audit
    WHERE session_id = (SELECT session_id FROM sessions ORDER BY created_at DESC LIMIT 1)
    ORDER BY created_at DESC LIMIT 20;"

應看到一條幹淨的工具調用鏈，最後一行是 swap，blocked = 0。每一條前置調用都是兌換前執行的檢查：代幣安全、規模計算、敞口檢查、滑點模擬。

這是排查異常行為時的第一手資料。未來某輪對話出現問題時，首先運行此查詢。

8. 回顧與迭代

首筆兌換完成後，可以嘗試以下操作：

/status：緊急關閉開關狀態、今日消費、已註冊工具數量、活躍技能會話。作為快速概覽的儀表盤。
/budget：今日 LLM 消費，按任務細分。用於瞭解單次會話的實際成本。
/prompt：輸出當前系統提示詞的各個塊。查看可緩存塊與動態塊的邊界，以及活躍技能的提示詞片段，瞭解 LLM 實際接收的內容。
/history 20：最近 20 條歷史記錄，含角色和內容預覽。
/compress：會話較長時運行此命令。它通過 Haiku 對較早的輪次進行摘要，降低提示詞成本。

第一天不該做的事

不要啟動 Autopilot。 Autopilot 會增加一個 LLM 無需人工介入即可做決策的環節。在信任當前配置之前，這不適合用於"驗證 Agent 是否正常工作"。
不要在工作流中禁用緊急關閉開關。 這從來都不是正確答案。
不要將每日上限設置到超出可承受範圍。 上限的意義在於限制出錯時的最大損失。應基於"能接受因 bug 損失多少"來設定，而非"預計今天的交易總額是多少"。
不要公開分享審計日誌。 屏蔽器會遮蔽已知的敏感 key，但交易歷史加時間戳有時足以反推出某些行為模式。將其視為私密的運營數據。
升級後不要跳過 doctor 命令。 Schema 遷移是冪等的，但新版本可能引入新的工具集或環境變量，導致舊配置出現問題。minara doctor 能在幾秒內發現這些問題。

後續步驟

閱讀資金安全，瞭解每筆交易經過的六階段安全路徑。
閱讀沙盒與權限，瞭解鉤子鏈的行為。
閱讀可觀測性，學習關鍵的審計查詢。
準備好自動化後，閱讀工作流和 Autopilot。
更偏好儀表盤？與 Agent 對話在 Web UI 中演示同樣的流程。

首次交易應該感覺平淡無奇，這正是目標所在。如果感覺令人興奮，說明安全層存在 bug，歡迎反饋。

本頁目錄