使用教程

openInvest 是给 AI agent 用的投资 runtime（issue #133）：你的 agent 负责对话和记忆，openInvest 负责投资决策。下面按最常见路径展开。

1. 安装（以 Claude Code 为例；其他 agent 见第 5 节）

/plugin marketplace add longsizhuo/openInvest
/plugin install invest@openinvest

装完得到三样东西，全部零配置：

组件	作用
MCP server（自动注册）	agent 能调什么：status / live_prices / decisions / explain_decision / record_execution / buy / sell / run_committee …
invest skill	agent 怎么编排委员会（Coordinator 协议、决策纪律）
invest-setup skill	首次 3 问 onboarding

后端从 PyPI 分发（openinvest）：首次调用时 uvx 自动拉包（只需要 uv），数据放 ~/openInvest（memory/ db/ .env）。后端版本固定在 run.sh 里、随插件发版更新，更新插件即更新后端。 首次 MCP 连接可能超时（在等 PyPI 下载）——重试一次即可，之后 uvx 走缓存秒连。

不用 plugin 也可以只挂 MCP：

bash

claude mcp add openinvest -e INVEST_HOME=~/openInvest -- uvx openinvest-mcp

2. 初始化

对 Claude 说 "set up invest" / 帮我初始化 invest —— 3 个问题（称呼、风险偏好、当前持仓）写入配置；API key 不在对话里给，用户自己写进 ~/openInvest/.env。持仓多的话直接甩券商截图， agent 自己 OCR 后走 import。

没配 key（持仓只录了现金）或解析失败时，用系统前就持有的仓位逐只补录： buy --existing-position（MCP：独立工具 record_existing_position）——不扣现金， history 记 funding_source: external_funding、source: skill_cli:existing_position （MCP 是 mcp:existing_position）。普通 buy 是新买入，会从现金里扣。先跑 status，它已列出的 symbol 不要再补（会重复计数）。老版本 MCP server 没有这个工具，会回 Unknown tool: record_existing_position——别退回用 buy（会扣现金），改用 CLI 或升级。

3. 日常使用（自然语言即可，agent 自己选工具）

你说	agent 调
"看看我的持仓 / 涨了多少"	`status`
"我的收益率 / 回撤 / 跑赢大盘没"	`performance`（TWR 30d/YTD/成立以来 + XIRR + 最大回撤 + vs 基准；`status.performance` 同一块）
"黄金现在什么价"	`live_prices`
"纳指跌 10% 我亏多少"	`what_if`
"要不要再平衡 / 回到目标配置该买卖多少"	`rebalance_plan`（按 strategy.md 的 `target_pct` 对照现状，出 BUY/SELL 清单，按整手取整；只出清单，不下单）。目标权重让 agent 写：`track_asset --target-pct` / `set_allocations --target-pct SYMBOL=0.3`，不用手改文件
"该不该买 AAPL / 跑个委员会"	Coordinator（Claude Code，免 API key）或 `run_committee`（Direct，需 DEEPSEEK_API_KEY）
"为什么今天是 HOLD"	`explain_decision`（完整 4 角色辩论 transcript + CIO memo）
"委员会都拦了我什么"	`discipline`
"刚买了 500 股"	`buy` / `record_trade`
"这 3000 股我早就有了"	`status` 里没有才补：`buy --existing-position`（MCP `record_existing_position`，不扣现金）

4. 决策闭环（Decision Accounting）

委员会给了建议之后，告诉 agent 你做没做——这是闭环的入口：

委员会：ACCUMULATE AAPL ¥2000
你：这次我不买了。
agent：好的，方便说下原因吗？（估值 / 资金 / 不同意？）
你：现金留着交房租。
agent → record_execution("2026-07-02/AAPL", rejected, reason="现金留给房租")

之后随时问：

"我听了几次建议？" → decisions 返回采纳率 + 每条决议的决议↔干预↔执行↔结果全链（默认只列最近 20 条，可按标的 / 裁决过滤，采纳率按全部匹配算）
"哪些建议我没执行、后来怎么样？" → 同上，outcome 字段有事后 1d/7d/30d 收益
"防御规则在省钱还是费钱？" → discipline 反事实账本

不声明也有兜底：7 天内同标的同向成交会被自动匹配为"已执行"。

5. 其他 agent（Codex / Hermes / OpenClaw / 任意 MCP client）

接入原则见 #133：openInvest 是 agent 的投资 runtime，MCP 是第一接口；对话/记忆/通知渠道由宿主 agent 自己负责。

Codex：codex plugin marketplace add longsizhuo/openInvest 后 codex plugin add invest@openinvest（同一套 skill；MCP 工具再跑 codex mcp add openinvest --env INVEST_HOME=$HOME/openInvest -- uvx openinvest-mcp，见 plugin/README）
Gemini / Cursor / 任意脚本：CLI Direct 路径——run.sh run_committee SYM 一键拿 verdict（需 DEEPSEEK_API_KEY）；全部子命令见 SKILL.md
任意 MCP client：stdio server 是标准 MCP，不挑 client

Hermes Agent（Nous Research）

MCP 声明式接入（~/.hermes/config.yaml）。指向插件自带的 run.sh：它把后端钉在这次插件发版对应的版本，插件更新后跟着更新；trust: untrusted 让 Hermes 在写账本的工具前先问用户。Hermes 不经 shell 启动进程，路径里的 ~ 不会展开，要写绝对路径（插件装在 $HERMES_HOME/plugins/openinvest）：

yaml

mcp_servers:
  openinvest:
    command: bash
    args: ["/home/YOU/.hermes/plugins/openinvest/skills/invest/scripts/run.sh", "mcp"]
    trust: untrusted

Hermes 自动发现全部 MCP 工具并与内置工具并列注册。skills 一条命令装（Hermes 官方插件目录， 2026-10-14 收录）：

bash

hermes plugins install openinvest --enable

官方目录装的是 Nous 审核过、固定到某个提交的版本，不弹安全扫描确认；run.sh 固定的后端版本也跟着这个提交走，所以 skills 和 MCP 工具都可能比 main 旧。版本随我们提交的目录更新 PR 前进，可能比 main 晚。要 main 上的最新提交就按仓库路径装： hermes plugins install longsizhuo/openInvest/plugin --enable。

装完以 openinvest:invest / openinvest:invest-setup 命名空间加载（Hermes plugin skill 是显式加载制，不进自动索引）。注意 hermes skills install 路线会被其社区源安全扫描拦截（金融写操作 skill 必触发 dangerous verdict）——走 plugin 路线。 plugin 路线要装 plugin/ 子目录：Hermes 0.21 起安装也会扫描整棵目录，从仓库根装会扫到 docs/tests 并判 dangerous 直接拦下（2026-10-13 在 0.21.7 实测），plugin/ 子目录扫描结果为 safe。以前从仓库根装过的：0.21 起 hermes plugins update 不再接管旧安装（报 no owned Git checkout），重装一次即可，二选一：hermes plugins install openinvest --enable --force 换成官方目录版（2026-10-15 实测，原来的启用状态保留）；想继续跟 main 就用 hermes plugins install longsizhuo/openInvest/plugin --enable --force。

信息联动：若装有 Longbridge 等行情/新闻 skill，看到与持仓相关的新闻时用 ingest_event 喂进事件账本——券商级信息源接入决策管道，零额外集成。

聊天里临时问"该不该买 X"，不想配 key？走 Coordinator：Hermes 有 delegate_task（隔离子任务委派），跟 Claude Code 的 Agent({...}) 一样能扮演委员会 4 个角色——不需要任何第三方 API key，用你自己订阅的模型。协议见 references/committee-protocol-hermes.md。

⚠️ 但这只适用于你在场的交互场景——Coordinator 协议依赖 Hermes 临场决定 "调哪个工具、prompt 怎么拼"，2026-07-14 实测过一次让它无人值守跑这套协议：没有老实调用 delegate_task，自己选了别的路子，还撞上安全拦截卡住不动。 每日 cron 这类无人值守场景，不管什么 agent，一律走 Direct（下一节），配置一个 LLM_API_KEY 即可——不一定要付费，千问/智谱/MiMo 等目前都有免费额度可用，即使付费 DeepSeek 日报量级也就 ¥0.01-0.03 一次。

OpenClaw

一键装（已发布 ClawHub bundle-plugin，2026-07-16 在 openclaw 2026.6.11 实测 skills + MCP 双注册、plugins doctor 零问题）：

bash

openclaw plugins install clawhub:openinvest

MCP 后端也可以声明式手动接（bundle 未生效或想显式控制 uvx 参数时， ~/.openclaw/openclaw.json，JSON5）：

json5

{
  mcp: {
    servers: {
      openinvest: {
        command: "uvx",
        args: ["openinvest", "mcp"],
        env: { INVEST_HOME: "~/openInvest" },
      },
    },
  },
}

别混淆两个 OpenClaw：上面说的是 npm 的 OpenClaw（docs.openclaw.ai，ClawHub 生态）。另一个 openclaw-python（openxjarvis，Python 重实现）截至 0.8.x 它的 plugins install 是未实现 stub（返回假 success 什么都不装）——openclaw-python 用户走 workspace skills/ 拷贝：

bash

git clone https://github.com/longsizhuo/openInvest ~/openInvest
cp -r ~/openInvest/plugin/skills/* ~/.openclaw/workspace/skills/   # workspace 路径以你的配置为准

每日日报 cron（宿主 agent 侧）

服务器内置的 daily_report cron 已于 2026-07-12 默认停用（jobs/daily_report.ymlenabled: false）——按 #133 的分工，定时触发和通知渠道归宿主 agent，openInvest 只提供能力面：

bash

uvx openinvest daily_report   # 完整日报管道，stdout = 邮件正文同源 markdown，不发邮件

报告格式由后端统一保证（同一条 assemble_full_report 管道：多资产委员会 + Gemini 第二意见 + 翻译官人话解读 + 纪律台账；单股资产的裁决旁另列"近 7 天已入库、 severity≥mid 的资产专属事件"，最多 5 条、相似转述合并——只展示，不额外喂给委员会）——所有用户、所有 agent 的 cron 拿到的日报一模一样，不需要在 prompt 里教 agent 怎么写报告。

以 Hermes 为例（--no-agent = 脚本 stdout 原样投递，Hermes 侧零 LLM token）：

bash

mkdir -p ~/.hermes/scripts
cat > ~/.hermes/scripts/daily_invest.sh <<'EOF'
#!/usr/bin/env bash
INVEST_HOME=~/openInvest exec uvx openinvest daily_report
EOF
hermes cron create "0 2 * * 1-5" --name daily-invest-report \
  --no-agent --script daily_invest.sh --deliver <渠道>

注意：

cron 按服务器本地时区解析（UTC 机器上北京 10:00 = 0 2 * * 1-5）；--deliver 换成你配好的渠道（telegram / discord / signal / platform:chat_id）
后端跑委员会走 Direct 路径，INVEST_HOME/.env 里要有 LLM_API_KEY（任意 OpenAI 兼容端点，DEEPSEEK_API_KEY 仍兼容；免费额度供应商也行，见上方 "不想配 key？"一节）
重跑会重新跑整个委员会（消耗 token）——语义与原 cron / GH Actions workflow_dispatch 一致
熔断（数据全废）或未配置 target_assets 时 stdout 是结构化 JSON——收到 JSON = 该排查了
想要 LLM 二次加工（翻译 / 只推增量），改 --skill openinvest:invest + 一句话 prompt（"跑 daily_report 子命令，把输出按 X 加工后投递"），报告主体仍由后端生成
OpenClaw 等其他带 cron 的 agent 同理——能定时跑 shell 就能用

筛选 / 期权链 / 财报电话会 / SEC 文件：openInvest 不自建，请 host agent 并用托管 MCP

这四类数据 openInvest 不自建、不代理、不加依赖。用户问"帮我筛一下 XX 条件的股票""看下 NVDA 的期权链" "这次财报电话会说了什么""查下 10-K 原文"时，由 host agent 在 openInvest 旁边再注册一个托管 MCP 自己调。三个可选（来源核对于 2026-10）：

MCP	接入	覆盖面	成本
Alpha Vantage（官方托管）	远程端点 `https://mcp.alphavantage.co/mcp`（官方文档页以"our official MCP server"链到它）；免费 key 在 alphavantage.co/support 领取。key 怎么带（URL 查询参数还是请求头）以官方 MCP 页为准，这里没有核实，不抄	官方 API 目录含期权数据、财报电话会逐字稿、基本面；具体暴露哪些工具以服务端 `tools/list` 为准	免费 key 每日 25 次
Financial Datasets（托管）	`https://mcp.financialdatasets.ai`（无凭证时返回 401）；key 在 financialdatasets.ai 申请。开源仓库 financial-datasets/mcp-server 也可本地 stdio 跑，环境变量 `FINANCIAL_DATASETS_API_KEY`。托管端点的鉴权头名称这里没有核实	三大报表（利润表 / 资产负债表 / 现金流）、股价、公司新闻、加密货币；官网另列内部人交易（Form 4）和 10-K 检索	付费 API
OpenBB MCP server（自托管，PyPI `openbb-mcp-server`）	`pip install openbb-mcp-server openbb` 后 `openbb-mcp`，默认 `http://127.0.0.1:8001/mcp`（streamable-http，`--transport sse` 可选）；只放本机，别暴露公网。`--allowed-categories equity,news` 限定暴露范围，`--tool-discovery` 把全量工具藏到搜索工具后面	已装 OpenBB 扩展的路由，按类别分组：equity / economy / news / fixedincome / derivatives / etf / currency / commodity / index / regulators / crypto	免费（底层数据源可能要各自的 key）

注册用你的 agent 自己的 MCP 命令（Claude Code：claude mcp add --transport http <名字> <url>；Codex / Hermes / Cursor 走各自的 MCP 配置）。 key 不要贴进对话、笔记或账本。

边界：只作委员会之外的背景，不进裁决输入。 这些 MCP 返回的东西用来回答用户在委员会之外的问题；不要塞进 ingest_event、委员会 prompt / brief 或 record_execution 的理由。原因：委员会的输入是确定性、可回放（as-of 安全）的，实时拉的筛选结果 / 期权链 / 逐字稿 / 文件原文不是。裁决仍只来自 run_committee。对用户说清哪些数字来自委员会、哪些来自托管 MCP。

来源（2026-10 核对）：Alpha Vantage 文档、 mcp.alphavantage.co、Financial Datasets、 financial-datasets/mcp-server、 openbb-mcp-server (PyPI)。

6. Web GUI（已退役 2026-07-05）

GUI 壳层已退役：run.sh gui 已删除，后端不再 serve 网页面板。看持仓 / 录入 / 跑委员会全部走上面的 CLI / MCP / skill 路径。前端重做时会以独立仓库直连 MCP。

下一步

→ 04-execution-paths.md — Coordinator vs Direct 双路径原理

→ 06-api.md — REST / MCP 全部端点

→ 05-data-model.md — 账本都存在哪

使用教程 ​

1. 安装（以 Claude Code 为例；其他 agent 见第 5 节） ​

2. 初始化 ​

3. 日常使用（自然语言即可，agent 自己选工具） ​

4. 决策闭环（Decision Accounting） ​

5. 其他 agent（Codex / Hermes / OpenClaw / 任意 MCP client） ​

Hermes Agent（Nous Research） ​

OpenClaw ​

每日日报 cron（宿主 agent 侧） ​

筛选 / 期权链 / 财报电话会 / SEC 文件：openInvest 不自建，请 host agent 并用托管 MCP ​

6. Web GUI（已退役 2026-07-05） ​

下一步 ​

使用教程

1. 安装（以 Claude Code 为例；其他 agent 见第 5 节）

2. 初始化

3. 日常使用（自然语言即可，agent 自己选工具）

4. 决策闭环（Decision Accounting）

5. 其他 agent（Codex / Hermes / OpenClaw / 任意 MCP client）

Hermes Agent（Nous Research）

OpenClaw

每日日报 cron（宿主 agent 侧）

筛选 / 期权链 / 财报电话会 / SEC 文件：openInvest 不自建，请 host agent 并用托管 MCP

6. Web GUI（已退役 2026-07-05）

下一步