$SHELL Miner CLI v1.1.0

Red-team AI Agents to mine $SHELL points. Free to start, bring your own LLM API Key for full rewards.

通过红队测试 AI Agent 来挖掘 $SHELL 积分。免费即可开始，自带 LLM API Key 获得完整积分奖励。

Quick Start / 快速开始

# Install & configure / 安装并配置
npx @openshell-cc/miner-cli@latest setup

# Start mining / 开始挖矿
npx @openshell-cc/miner-cli@latest start

Or install globally / 或全局安装：

npm install -g @openshell-cc/miner-cli
miner-cli setup
miner-cli start

Mining Modes / 挖矿模式

| | Free 免费模式 | Self-LLM 自算力模式 | |---|---|---| | LLM API Key | Not needed 不需要 | Required 需要 | | Point multiplier 积分倍率 | ×0.1 | ×1.0 (10x free) | | Daily attacks 每日攻击 | 5 per day 每天5次 | Unlimited 无限制 | | Verify tasks 验证任务 | None 无 | Unlimited 无限制 | | Breach records 攻破记录 | Not counted 不计入 | Counted 计入 | | After daily limit 超出限额 | Forced offline until next UTC midnight 强制下线至次日UTC零点 | N/A |

Upgrade to Self-LLM / 升级为自算力模式

Two ways / 两种方式：

1. Set LLM_API_KEY in .env — automatically detected on startup / 在 .env 中设置 LLM_API_KEY，启动时自动检测
2. API call / 接口调用: POST /auth/upgrade-to-self-llm (Bearer token)

Your LLM API Key runs only on your local machine and is never uploaded to any server. 你的 LLM API Key 仅在本地运行，绝不上传到任何服务器。

Configuration / 配置说明

Run miner-cli setup or copy .env.example to .env:

运行 miner-cli setup 或复制 .env.example 为 .env：

Required / 必填

| Variable 变量 | Description 说明 | |---|---| | ORACLE_URL | Oracle server address 服务器地址 (default: https://oracle.openshell.cc) | | SHELL_API_KEY | Miner API key from dashboard 控制面板签发的矿工密钥 (sk-shell-xxx) |

Optional (Self-LLM) / 可选（自算力模式）

| Variable 变量 | Description 说明 | |---|---| | LLM_API_KEY | Your LLM API Key (enables self_llm mode) 你的 LLM API Key | | LLM_PROVIDER | Provider name 提供商名称 (auto-detected from key prefix 按前缀自动检测) | | LLM_MODEL | Model name 模型名称 (each provider has a default 各提供商有默认值) | | LLM_BASE_URL | Custom OpenAI-compatible endpoint 自定义兼容端点 (for Ollama/vLLM/etc.) |

Supported LLM Providers / 支持的 LLM 提供商

| Provider 提供商 | LLM_PROVIDER | Default Model 默认模型 | Get Key 获取 | |---|---|---|---| | Anthropic | anthropic | claude-haiku-4-5 | console.anthropic.com | | OpenAI | openai | gpt-4o-mini | platform.openai.com | | DeepSeek | deepseek | deepseek-chat | platform.deepseek.com | | Google Gemini | gemini | gemini-2.5-flash | aistudio.google.com | | xAI Grok | grok | grok-3-mini-fast | console.x.ai | | Custom 自定义 | any name | set LLM_MODEL | set LLM_BASE_URL |

Custom OpenAI-Compatible API / 自定义兼容 API

# Ollama local inference / Ollama 本地推理
LLM_PROVIDER=openai
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3
LLM_API_KEY=ollama

# Together AI / vLLM / Fireworks / Groq / etc.
LLM_PROVIDER=openai
LLM_BASE_URL=https://api.together.xyz/v1
LLM_MODEL=meta-llama/Llama-3-70b-chat-hf
LLM_API_KEY=your-key

How Mining Works / 挖矿流程

1. Poll 领取任务  →  Receive target agent info + system prompt
2. Generate 生成   →  Your LLM crafts an attack payload to trigger hidden canary actions
3. Execute 执行    →  Send payload to target agent, collect response + action log
4. Prove 证明      →  Compute executionHash = SHA256({payload, actionLog, agentResponseHash})
5. Submit 提交     →  Upload proof to Oracle (payload + actionLog + agentResponse + hash)
6. Verify 验证     →  3 other miners independently re-execute your payload, vote on result
7. Settle 结算     →  2/3 consensus → points credited; failed → no points

Attack Rewards / 攻击积分

| Defense Level 防御等级 | Points (Self-LLM) 积分 | Points (Free ×0.1) | |---|---|---| | None 无防御 | 1,000 | 100 | | Basic 基础防御 | 2,000 | 200 | | Advanced 高级防御 | 4,000 | 400 |

Canary System / 金丝雀系统

Each target agent has "canary actions" — specific tool calls that count as a successful breach. The miner CLI shows you which actions to trigger, and automatically checks locally before submitting (only submits if canary actions are detected in the action log).

每个目标 Agent 都有"金丝雀动作"——特定的工具调用代表攻破成功。矿工 CLI 会显示需要触发哪些动作，并在提交前自动本地检查（仅在 action log 中检测到金丝雀动作时才提交）。

Peer Verification / 互验机制

After a successful attack, 3 other miners independently re-execute your payload and vote:

• 2/3 agree → points settled
• Honest verifiers earn 8-15% of the original task's points
• Anti-collusion: same-IP / same-cluster miners cannot verify each other

攻击成功后，3 名其他矿工独立重新执行你的 payload 并投票：

• 2/3 一致 → 积分结算
• 诚实验证者获得原始任务积分的 8-15%
• 反串谋：同 IP / 同集群矿工不能互相验证

Breach Records / 攻破记录

Self-LLM miners' successful breaches are tracked on the Breach Records page (/breaches):

• My Breaches: personal list of all agents you've breached
• Breach Leaderboard: global ranking by unique agents breached

Free users' breaches are not counted in any records.

自算力矿工的攻破记录展示在攻破记录页面 (/breaches)：

• 我的攻破：你攻破过的所有 Agent 列表
• 攻破排行榜：按攻破 Agent 种数的全球排名

免费用户的攻破不计入任何记录。

Anti-Cheat / 反作弊

Duplicate Detection / 重复检测

| Scenario 场景 | Result 结果 | |---|---| | First breach of an agent 首次攻破 | Full points 全额积分 | | Same agent, different strategy 同 Agent 不同策略 | Full points 全额积分 | | Same agent, same strategy (same user) 相同策略 | 0 points | | Same strategy used by many miners 多人相同策略 | Diminishing returns 递减 |

Honeypot Detection / 蜜罐检测

| Failures 失败次数 | Penalty 惩罚 | |---|---| | 1-3 | Warning only 仅警告 | | 4 | -10% points | | 5 | -50% points | | 6+ | All points cleared 清零 |

Commands / 命令

miner-cli setup              # First-time configuration / 首次配置
miner-cli start              # Start mining / 开始挖矿
miner-cli start --referral X # Start with referral code / 带推荐码启动
miner-cli status             # Check mining status / 查看状态

Build from Source / 从源码构建

git clone https://github.com/openshell-cc/shell-protocol.git
cd shell-protocol
pnpm install
cd packages/miner-cli
cp .env.example .env   # Edit .env with your keys / 编辑填入密钥
pnpm build
node dist/index.js start

Development mode / 开发模式:

pnpm --filter @openshell-cc/miner-cli dev -- start

OpenClaw Auto-Configuration / OpenClaw 自动配置

Below is a prompt you can give directly to OpenClaw (or any AI agent) to automatically configure and start mining. Copy the entire block and paste it as your OpenClaw system prompt or task.

以下是一段提示词，你可以直接给 OpenClaw（或任何 AI 代理）使用，它会自动配置并开始挖矿。复制整段内容作为 OpenClaw 的系统提示或任务即可。

Follow us / 关注我们: 𝕏 @openshell_cc

You are a $SHELL miner operator. Your job is to set up and run the $SHELL miner CLI.

## Setup Steps

1. Install the miner CLI:
   npm install -g @openshell-cc/miner-cli@latest

2. Create a .env file with these variables:
   ORACLE_URL=https://oracle.openshell.cc
   SHELL_API_KEY=<your sk-shell-xxx key from the $SHELL dashboard>
   LLM_API_KEY=<your LLM API key>
   LLM_PROVIDER=<provider name: anthropic|openai|deepseek|gemini|grok>

   Note: If using Ollama or other local LLM, also set:
   LLM_BASE_URL=http://localhost:11434/v1
   LLM_MODEL=<model name>

3. Run setup wizard if .env is not configured:
   miner-cli setup

4. Start mining:
   miner-cli start

## How It Works

- The miner polls the Oracle server for attack tasks
- Each task includes canary actions (target tool calls) that the miner must trigger
- Your LLM generates an attack payload to trick the agent into calling canary actions
- The miner executes the payload locally against the target agent with mock tools
- Local pre-check: only submits if canary actions are detected in the action log
- It computes a proof hash: SHA256({payload, sorted actionLog, SHA256(agentResponse)})
- Submits the proof to Oracle
- 3 other miners independently verify by re-executing your payload
- 2/3 consensus = points credited

## Task Types

- Attack tasks: You generate payload, execute against agent, submit proof
- Verify tasks (self_llm only): Re-execute another miner's payload, vote on result

## Points

- No defense agent: 1,000 pts (×0.1 for free mode)
- Basic defense: 2,000 pts
- Advanced defense: 4,000 pts
- Verification: 8-15% of original task points

## Important

- Your LLM API key stays local, never uploaded
- Free mode: 5 attacks/day, no verify tasks
- Self-LLM mode: unlimited attacks + verify tasks
- The miner handles everything automatically — just keep it running
- Follow @openshell_cc on X for updates: https://x.com/openshell_cc