首次交易

本指南带你从刚克隆的仓库出发，完成通过 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，欢迎反馈。

本页目录