Clawby Q 是一个面向美股和加密市场的量化研究客户端。它把因子研究、策略组合、历史回测、实时监测、纸盘交易、前向证据收集和可视化看板放在同一个本地优先的平台中。
它的用途不是提供一个“神奇买卖信号”，而是帮助用户把一个量化想法变成可检查、可回测、可监测和可复盘的研究流程：
- 从本地因子库和机构公式因子中选择研究因子；
- 将因子组合成量化机器人和策略；
- 使用历史数据进行回测，观察收益、回撤、胜率和风险调整表现；
- 使用纸盘和前向证据记录新市场环境下的表现；
- 通过看板查看机器人、因子、事件、持仓、证据和风险状态；
- 在证据充分前保持研究模式，不把历史结果当作未来收益承诺。
Clawby Q 默认是本地运行的纸盘和研究系统。当前公开发布版不会向交易所提交真实订单，也不是投资建议。
G1-G6 是 Clawby Q 内部六组量化机器人的名称，不是股票代码，也不是六个软件版本。每组包含多个独立机器人，并由共享的数据、组合、风控、验证和治理模块提供支持。
| 机器人组 | 中文定位 | English name | 主要职责 |
|---|---|---|---|
| G1 | 流动性与短线反转 | Liquidity & Short-Term Reversal | 研究流动性变化、成交量冲击和短线均值回归机会 |
| G2 | 趋势与突破延续 | Trend & Breakout Continuation | 研究趋势、突破、动量和突破后的延续行为 |
| G3 | 事件与信息确认 | Event & Information Confirmation | 研究财报、宏观事件、新闻和信息确认对价格的影响 |
| G4 | 横截面与残差相对价值 | Cross-Sectional & Residual Relative Value | 研究横截面排名、相对价值、残差和配对关系 |
| G5 | 波动环境与防御风控 | Volatility Regimes & Defensive Risk Control | 研究波动率状态、压力环境、仓位约束和防御性退出 |
| G6 | 机构公式独立挑战组 | Institutional Formula Challenge Group | 只使用机构量化资料中登记的公式和因子，作为独立研究与挑战组 |
G1-G5 的标准组结构为 8 个美股机器人、2 个加密机器人和 1 个审查机器人。审查机器人负责汇总评分、数据质量、组合风险和证据边界，不直接产生交易信号。G6 是独立的机构公式研究组，主要研究美股，不与 G1-G5 的因子选择混为一谈。
Clawby Q is a local-first quantitative research and paper-trading platform for US equities and crypto markets. It combines factor research, strategy composition, historical backtesting, real-time monitoring, paper trading, forward-evidence collection, and interactive dashboards in one reproducible workflow.
The project is designed to make quantitative research inspectable rather than to provide a magical trading signal. Users can:
- select research factors from local libraries and institutional-formula registries;
- combine factors into strategies and independent research robots;
- run historical backtests and review return, drawdown, win rate, and risk-adjusted metrics;
- collect paper-trading and forward evidence under new market conditions;
- inspect robot, factor, event, portfolio, evidence, and risk status through the dashboard;
- keep the system in research mode until sufficient evidence has been collected.
The public release runs locally and is paper-trading/research only by default. It does not submit live orders to an exchange and is not investment advice.
G1-G6 are the names of the six quantitative robot groups inside Clawby Q. They are not ticker symbols and they are not six separate software versions. The groups share data, portfolio, risk, validation, and governance services while keeping their research logic separate.
- G1 — Liquidity & Short-Term Reversal: studies liquidity changes, volume shocks, and short-horizon mean reversion.
- G2 — Trend & Breakout Continuation: studies trend, breakout, momentum, and post-breakout continuation.
- G3 — Event & Information Confirmation: studies earnings, macro events, news, and information confirmation.
- G4 — Cross-Sectional & Residual Relative Value: studies cross-sectional ranking, relative value, residual behavior, and pairs relationships.
- G5 — Volatility Regimes & Defensive Risk Control: studies volatility regimes, stress conditions, position limits, and defensive exits.
- G6 — Institutional Formula Challenge Group: uses only registered formulas and factors from the institutional quantitative research materials as an independent challenge group, focused mainly on US equities.
The standard structure for G1-G5 is eight US-equity robots, two crypto robots, and one review robot. The review robot summarizes scores, data quality, portfolio risk, and evidence boundaries; it does not create trade signals. G6 is a separate institutional-formula research group and must not be confused with the factor selection of G1-G5.
- The public release supports
PAPER,MONITOR, andOFFmodes only. - It does not include live order endpoints and does not submit real exchange orders.
- Clawby is an optional supporting data router and confirmation layer; local templates and cached logic can still run without a key.
- Public seed directories are reproducible starting points, not guarantees of current exchange permissions or real-time tradable universes.
- The release includes 491 mature-event replays for G1, G2, and G5, plus 321 six-month trade replays for G6. These are for research charts and historical comparison only; they are not official forward evidence, live returns, or a deployable capital curve.
- G3 and G4 do not currently ship with real historical replay snapshots. Their charts remain empty instead of fabricating data. New local results take precedence after a local run.
- Before running, refresh market data and public exchange instruments locally. Formal forward evidence must start from complete trading days observed by the new machine.
- Historical performance does not guarantee future results. This project is not financial advice.
cp .env.example .env
# Edit .env with your own Clawby key; never commit .env.
./mac_setup_v3_product.sh
./mac_install_v3_product_services.shDouble-click 安装V3产品.bat, then double-click 启动V3产品.bat. Full instructions are in README_WINDOWS_V3.md.
Open http://127.0.0.1:8765/, then run:
python3 verify_public_release.pyThe first run creates local state only. It does not inherit the publisher's Run ID, account, positions, evidence, or performance results. Formal forward evidence must be collected from complete trading days observed on the new machine.
Clawby Q 支持用户使用自己的 Clawby Key 进行普通授权，授权只用于只读数据访问：
- 打开看板，进入“配置”。
- 在“Clawby 数据”中填写用户自己的
CLAWBY_API_KEY并保存。 - 点击“测试授权”。客户端只调用 Clawby 官方账户接口，验证 Key 并读取账户限额。
- 看板只显示授权状态、脱敏后的 Key 信息和限额信息。Key 会保存在 macOS 钥匙串或 Windows DPAPI 本机安全存储中。
授权测试是只读的，绝不提交订单。没有 Key 时系统仍可使用缓存、历史回测、纸盘和本地研究功能。公开版保持 PAPER 模式，不启用实盘执行。
这是普通授权，不是 DRM 或下载锁。用户需要使用自己的有效 Clawby Key，发布者的 Key 不会包含在项目中。
Clawby Q supports ordinary, user-owned Clawby authorization for read-only data access:
- Open the dashboard and go to Settings / 配置.
- In Clawby Data / Clawby 数据, enter your own
CLAWBY_API_KEYand save it. - Click Test authorization / 测试授权. The client calls Clawby's documented account endpoint to verify the key and read the account rate limit.
- The dashboard shows only the authorization state, masked key metadata, and rate-limit metadata. The key remains in macOS Keychain or Windows DPAPI-protected local storage.
The authorization check is read-only and never submits an order. A missing key leaves Clawby in cache-only mode; historical backtests, paper trading, and local research still work. The public release remains PAPER and does not enable live execution.
Clawby Q is an open-source client, so ordinary authorization is not a DRM or a download lock. Users need their own valid Clawby key for live Clawby data access; the publisher's key is never included.
factor_library/: candidate US short- and medium-term factors and institutional-formula factors.data/public_seed/: sanitized public seed universe, exchange directory, and historical replay chart snapshots.config/: paper-trading, data-contract, scoring, risk, credential-isolation, and research-governance configuration.docs/: product architecture, forward-evidence, and macOS/Windows operating guidance.results/: generated locally after the first run; it is not part of the public seed package. The dashboard prefers local results and falls back to sanitized public replay snapshots when local results are absent.
On the dashboard home page, open the group performance section, select Historical Replay, and switch between G1, G2, G5, or G6. The curve is an equal-weighted compounded research curve based on event or trade exit times. The side panel shows replay return, maximum drawdown, event/trade count, and win rate.
These charts are for comparison and research only. Historical replay data is not written into the formal forward ledger and does not trigger automatic promotion.
Only publish code, factor formulas, and data that you own or are legally allowed to redistribute. Do not commit third-party API responses, account state, private research reports, credentials, or local machine paths. Review .gitignore, .env.example, and PUBLIC_RELEASE_POLICY.md before creating a public release.