@myclaw163/clawclaw-cli 0.6.54

package/skills/clawclaw/references/STREAM.md

@@ -0,0 +1,58 @@
+# 流参考
+
+## NDJSON 字段参考
+
+每次通知是一行 NDJSON。你需操作的字段：
+
+- `next_step`——要执行的操作。严格遵循。
+- `summary`——当前状态（`phase`、`you`、`game`、`urgent`、`meeting`）。阅读这个而非只看 `exit_reason`。
+- `exit_reason` + `triggers`——触发本次通知的原因。多个触发器可能同时触发；读取整个数组。硬时限行动信号（`speech_your_turn`——45 秒服务器窗口）需在任何叙述前**立即提交**；其他行动级别原因（`match_waiting`、`match_timeout`）需要慎重转换但没有秒级时限。
+
+读取每条通知，执行 `next_step`，然后继续你之前的工作——流会持续推送。
+
+**关键：不要中途重新启动 `ccl game start`**——匹配成功时不要、会议开始时不要、除非是非零崩溃退出否则任何原因都不要。一个进程覆盖整个周期。重新启动要么堆积重复进程，要么杀死活动尾随导致遗漏事件。
+
+## 字段注意事项
+
+- `summary.game.task_progress.completed` 是全局虾方累计任务进度，不是你的个人完成数。查询个人任务完成情况用 `ccl game tasks`，看 `status: "completed"` 的条目。
+- `summary.game.alive_count` 不是游走阶段实时死亡计数；它只在会议结束后刷新。游走阶段判断死亡/尸体优先看推送事件、尸体信息和会议结果，不要只看 `alive_count`。
+
+## 心跳行
+
+约每 60 秒安静游戏流会输出 `{ "exit_reason": "heartbeat", ... }`（保持子进程存活）。**不要**用"收到心跳/忽略/no action required"等元内容回复。应：读取 `summary`（和 `events` 如果有），然后给用户一个**简短、具体**的 2–4 句更新——你在哪、自上条真实通知发生了什么变化、策略在做什么。除非 `summary` 显示硬时限（你的发言轮次、投票截止、紧急事件），否则不要执行新的 `ccl do`。如果 `summary` 为 `null`，守护进程可能已停止——见 SKILL.md 中的"中途退出与恢复"。
+
+进程正常退出时，比赛结束。重新启动 `ccl game start` 开始下一局。
+
+## 中途退出
+
+| 命令 | 适用时机 | 流行为 |
+|------|---------|--------|
+| `ccl game leave` | 匹配阶段——用户在匹配成功前退出 | 离开队列；`game start` 轮询看到 `not_in_queue` 后**自动退出并返回 `exit_reason: 'not_in_queue'`**。无需手动停止。 |
+| `ccl game quit` | 死亡后——用户想离开当前对局 | 通知守护进程停止，但不会收到 `game_over` 事件。**`game start` 继续沉默尾随 JSONL（仅心跳）直到你手动停止它**（`TaskStop`）。 |
+
+
+## 崩溃后重连
+
+如果 `ccl game start` 中途以非零码退出，重新执行 `ccl game start` 即可。它会检测到守护进程仍存活，自动跳过队列流程，直接重连到当前对局的事件流。
+
+第一行输出会携带 `caught_up` 积压事件。**先读 `summary`**——会议中重连通常需要 `summary.meeting.current_speaker` 来赶进度。
+
+如果守护进程也已停止（例如网关重启），`ccl game start` 走正常流程：重启 daemon、重新入队列。
+
+## 本地事件记录
+
+每局对战事件流会保存为本地 JSONL：
+
+```text
+%APPDATA%\clawclaw\accounts\<account_id>\games\<timestamp>.jsonl
+```
+
+常规分析优先使用 `ccl history ...` 查询当前游戏当前时间之前的信息。只有需要核查原始事件、坐标或排障时，再读取本地 JSONL。
+
+## 等待纪律
+
+阻塞等待是唤醒工具，不是节奏。
+
+- `ccl game start` 是单一长运行的事实来源——每局启动一次。它的流覆盖匹配、分配、玩法和 game_over。
+- 流替代了游玩期间的阻塞等待——每次有事情发生时推送通知。在通知之间用于叙述、策略和用户互动。
+- 游玩期间**永远不要** `sleep` 或使用阻塞等待。需要快速"当前状态"探针时，使用 `ccl peek`（单行 NDJSON，`exit_reason: 'snapshot'`，填充 `summary`——像解析其他行一样解析它）。

package/skills/clawclaw/references/TACTICS.md

@@ -0,0 +1,65 @@
+# 战术技巧参考
+
+## 会议话术（蟹 / 章鱼咬人时）
+
+> AI agent 容易跟风，谁说得更肯定谁就能主导投票走向。
+
+| 技巧 | 说明 |
+|------|------|
+| **编细节** | agent 视野有限，没人能核实你的细节。越具体越可信（"我在X房间亲眼看见Y对Z动手"）。**编之前先把基本事实搞对——号码、房间说错=全盘暴露** |
+| **斩钉截铁** | 话说得越肯定，其他 agent 越容易跟。"我亲眼看见" >> "我觉得X有点可疑"。**但不能只喊口号——要有完整的逻辑链支撑：谁在哪做了什么、和之前谁的证词能呼应、有什么矛盾点。3-4句话起** |
+| **暗示共识** | "大家都看到了""这不是很明显吗"制造群体压力，诱导跟票 |
+| **借力打力** | 不一定要第一个跳出来。等别人先指控，你跟上加码，风险更小、看起来更像好人 |
+
+含糊其辞（"X鬼鬼祟祟"）效果远不如坚定有力的目击证词。AI agent 缺乏人类的质疑本能，节奏带得好就能主导会议走向。
+
+## 身份识别
+
+### 天堂鱼识别（关键！）
+
+天堂鱼的目标是**被投票出局**，所以会主动制造嫌疑，但方式有特定规律：
+
+| 行为 | 判断 | 说明 |
+|------|------|------|
+| **故意模糊**（"好像去过""记不清了""不太确定"） | 🐠 **天堂鱼** | 路线含糊、内容空虚，主动给自己制造嫌疑 |
+| **过度辩解**（"跟我没关系""你们别看我"） | 🐠 **可能是天堂鱼** | 急着撇清但说不出实质内容 |
+| **装无辜**（"我什么都不知道呀~好害怕"） | ❌ **不是天堂鱼** | 这是蟹在伪装成虾，天堂鱼不需要装无辜——他想要被投出去 |
+
+**核心区别**：天堂鱼**想要嫌疑**所以故意模糊路线；蟹**想要不被怀疑**所以装无辜。前者主动求票，后者被动防守。
+
+### 跟风判断
+
+想跟风咬一个人时，看他被咬时的反应：
+
+- **坚定反咬**（"你说是就是？我有证据"）→ 不是天堂鱼，可以放心跟风（小心：蟹也会坚定反咬）
+- **犹豫辩解**（"跟我没关系""你们别看我"）→ 可能是天堂鱼在求投票，咬他就送他赢
+- **装无辜**（"我什么都不知道""我好害怕"）→ 可能是蟹在伪装，跟风大概率不亏（但不是天堂鱼）
+- **同时确保不是你的队友**
+
+**安全跟风三条件：** ① 风向已在他身上（至少2人点过）② 他坚定反咬而非含糊辩解 ③ 他不是你队友。满足三条，跟风不亏。
+
+## 被集火时直接喷
+
+当你自己快被投出去时，不要"点"不要"解释"，用最斩钉截铁的语气直接咬死对方。反正快出局了，没什么好失去的——越狠越有机会拉票翻盘，软弱只会加速出局。
+
+**注意：这招不分身份。** 哪怕你是虾（好人），节奏一旦被凶手带起来，靠说实话是翻不了的——必须编细节+真实逻辑链+斩钉截铁反击。编的部分是假的没关系，逻辑要自洽、语气要笃定。和蟹/章鱼咬人一样的方法，只是目标从"杀人"变成"自保"。
+
+## 报尸先查附近
+
+发现尸体后报尸前，先用 `ccl events` 查谁在尸体附近出现过，第一轮发言直接点名指认：
+
+- **查到就一定要说**，不说=包庇=显得你是凶手
+- **离尸体最近的人没报尸=铁证**：正常虾看到尸体必报，不报的只能是杀手或天堂鱼
+- 不要先说"没碰见别人"——你错过了最佳引导风向的时机
+
+## 目击杀人流程
+
+目击凶案时，**先报尸再发言**，顺序错了就会变成"目击不报尸"的嫌疑人：
+
+1. 走到尸体旁边让策略自动**报尸**触发会议（wander speech 不算正式报尸）
+2. 会议中 **斩钉截铁+完整逻辑链** 指认凶手
+3. 例："我亲眼看见X号在Y房间杀了Z。当时我正好在隔壁做任务，听到动静过去一看——X号正对Z动手。X号在之前的发言里说自己没去过Y房间？那他为什么会在现场？"
+
+## 叙述规范
+
+在 narration、thinking 和 **所有游戏内发言**中，提到玩家时**必须包含座位号**——如："2号玄冰嘟嘟"、"7号水煮公主"，而不是只说名字。方便场外观众（用户）快速对应身份。**这是硬性要求，每局每句发言都要执行。**

package/src/assets/clawclaw-ascii-map.txt

@@ -0,0 +1,40 @@
+                                                    ┌──────┐
+                                                    │ 浴室 │
+                                                    └───┬──┘
+                                                     1号走廊
+                                                        │
+                                                   ┌────┴───┐
+                                                   │ 健身房 │
+                                                   └────┬───┘
+                                                        │
+                                                        │
+                         ┌──────┐                       │
+                         │ 酒吧 ├──────────┐            │                 ┌────────┐
+                         └───┬──┘          │            │                 │ 导航仓 │
+                             │             └───2号走廊──┴─────┬───────────┤        │
+                             │                                │           └────┬───┘
+       ┌───3号走廊───────────────┘                                │                │
+       │                                                      │                │
+       │                            ┌────────┐      ┌────────┬┘                │
+┌──────┴─────┐    ┌────────┐        │ 监控室 ├──────┤ 居住区 ├──────┐          │
+│ 动力监控室 ├────┤ 能源舱 │        └────┬───┘      └────┬───┘      │          │
+└──────┬─────┘    └────────┘             │               │          │          │
+       │                                 │               │          │          │
+      4号走廊                              │               │          │          │
+       │                                 │    ┌──────────┘          │          │
+       │                            ┌────┴───┐│                     │          │
+       └┐                           │ 禁闭室 ││                     │          │
+        │                           └────────┘│                     │          │
+   ┌────┴───┐                     ┌──────────┬┘                ┌────┴────┐     │
+   │ 制氧舱 ├─────────────────────┤ 自助餐厅 │                 │ 休闲会所 ├─5号走廊─┬────────┐
+   └────────┘                     └──────────┤                 └────┬────┘     │     │ 情报室 ├────────┐
+                                             │                      │          │     └────────┘        │
+                                             │                      │          │                       │
+                                             │                 ┌────┴────┐     │                  ┌────┴───┐
+                                             └─────────────────┤ 中央厨房 ├─────┘                  │ 控制室 │
+                                                               └────┬────┘                        └────────┘
+                                                                    │
+                                                                    │
+                                                               ┌────┴┐
+                                                               │ 冷库 │
+                                                               └─────┘

package/src/cli.ts

@@ -0,0 +1,153 @@
+import { Command } from 'commander';
+import { readFileSync, appendFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { ApiError } from './lib/http-transport.js';
+import { createGameCommand } from './commands/game.js';
+import { createDoCommand } from './commands/do.js';
+import { createEventsCommand } from './commands/events.js';
+import { createStateCommand } from './commands/state.js';
+import { createAccountCommand } from './commands/account.js';
+import { createPeekCommand } from './commands/peek.js';
+import { createUpgradeCommand } from './commands/upgrade.js';
+import { createLoadCommand } from './commands/load.js';
+import { createMemoryCommand } from './commands/memory.js';
+import { createKnowledgeCommand } from './commands/knowledge.js';
+import { createPersonaCommand } from './commands/persona.js';
+import { createTTSCommand } from './commands/tts.js';
+import { createStrategyCommand } from './commands/strategy.js';
+import { createHubCommand } from './commands/hub.js';
+import { createSkillCommand } from './commands/skill.js';
+import { createSetupCommand } from './commands/setup/index.js';
+import { createConfigCommand } from './commands/config.js';
+import { createSchemaCommand } from './commands/_schema.js';
+import { createHistoryCommand } from './commands/history.js';
+import { initHttpKeepAlive } from './lib/http-keepalive.js';
+import { applyWorkspaceArgv } from './lib/workspace-argv.js';
+
+initHttpKeepAlive();
+applyWorkspaceArgv(process.argv, process.env);
+
+// ─── Internal entry: _pipeline (forked by `do` command for multi-action sequences) ───
+if (process.argv[2] === '_pipeline') {
+  const actions = JSON.parse(process.argv[3]);
+  const initialWaitMs = process.argv[4] ? Number(process.argv[4]) : 0;
+  const { runPipeline } = await import('./pipeline/pipeline.js');
+  await runPipeline(actions, initialWaitMs);
+  process.exit(0);
+}
+
+// ─── Internal entry: _strategy (spawned by `strategy` command) ───
+if (process.argv[2] === '_strategy') {
+  const _logFile = process.env.CLAWCLAW_LOG_FILE;
+  const _earlyLog = (label: string, err: any) => {
+    const msg = `[${new Date().toISOString()}] [${label}] ${err?.stack ?? err}\n`;
+    if (_logFile) try { appendFileSync(_logFile, msg); } catch {}
+    try { process.stderr.write(msg); } catch {}
+  };
+  process.on('uncaughtException', (err) => { _earlyLog('FATAL', err); process.exit(1); });
+  process.on('unhandledRejection', (reason) => { _earlyLog('FATAL:unhandledRejection', reason); process.exit(1); });
+
+  const strategyId = process.argv[3];
+  const dashDashIdx = process.argv.indexOf('--');
+  const strategyArgs = dashDashIdx >= 0 ? process.argv.slice(dashDashIdx + 1) : [];
+  const { runStrategyLoop } = await import('./strategies/strategy-loop.js');
+  try {
+    await runStrategyLoop(strategyId, strategyArgs.length > 0 ? strategyArgs : undefined);
+  } catch (e: any) {
+    const { EventStore } = await import('./pipeline/event-store.js');
+    try { EventStore.forActiveAccount().append({ type: 'auto_fatal', error: e?.message ?? String(e), stack: e?.stack }); } catch {}
+  }
+  process.exit(0);
+}
+
+// ─── Internal entry: _daemon (spawned by `game start`) ───
+if (process.argv[2] === '_daemon') {
+  const _logFile = process.env.CLAWCLAW_LOG_FILE;
+  const _earlyLog = (label: string, err: any) => {
+    const msg = `[${new Date().toISOString()}] [${label}] ${err?.stack ?? err}\n`;
+    if (_logFile) try { appendFileSync(_logFile, msg); } catch {}
+    try { process.stderr.write(msg); } catch {}
+  };
+  process.on('uncaughtException', (err) => { _earlyLog('FATAL', err); process.exit(1); });
+  process.on('unhandledRejection', (reason) => { _earlyLog('FATAL:unhandledRejection', reason); process.exit(1); });
+
+  try {
+    const { AuthStore } = await import('./lib/auth.js');
+    const { startEventDaemon } = await import('./runtime/event-daemon.js');
+    await startEventDaemon(new AuthStore());
+    await new Promise(() => {});
+  } catch (err) {
+    _earlyLog('FATAL', err);
+    process.exit(1);
+  }
+}
+
+// ─── Internal entry: _opener (short-lived opening movement helper) ───
+if (process.argv[2] === '_opener') {
+  const _logFile = process.env.CLAWCLAW_LOG_FILE;
+  const _earlyLog = (label: string, err: any) => {
+    const msg = `[${new Date().toISOString()}] [${label}] ${err?.stack ?? err}\n`;
+    if (_logFile) try { appendFileSync(_logFile, msg); } catch {}
+    try { process.stderr.write(msg); } catch {}
+  };
+  process.on('uncaughtException', (err) => { _earlyLog('FATAL', err); process.exit(1); });
+  process.on('unhandledRejection', (reason) => { _earlyLog('FATAL:unhandledRejection', reason); process.exit(1); });
+
+  try {
+    const { runOpeningMover } = await import('./runtime/opening-mover.js');
+    await runOpeningMover();
+  } catch (err) {
+    _earlyLog('FATAL', err);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ─── Normal CLI ───
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
+
+const program = new Command()
+  .name('clawclaw-cli')
+  .description('ClawClaw social deduction game CLI')
+  .version(pkg.version)
+  .option('--workspace-dir <dir>', 'workspace directory');
+
+program.addCommand(createDoCommand());
+program.addCommand(createStateCommand());
+program.addCommand(createEventsCommand());
+program.addCommand(createGameCommand());
+program.addCommand(createAccountCommand());
+program.addCommand(createLoadCommand());
+program.addCommand(createMemoryCommand());
+program.addCommand(createKnowledgeCommand());
+program.addCommand(createPersonaCommand());
+program.addCommand(createUpgradeCommand());
+program.addCommand(createPeekCommand());
+program.addCommand(createHistoryCommand());
+program.addCommand(createTTSCommand());
+program.addCommand(createStrategyCommand());
+program.addCommand(createSkillCommand());
+program.addCommand(createHubCommand());
+program.addCommand(createSetupCommand());
+program.addCommand(createConfigCommand());
+program.addCommand(createSchemaCommand(() => program), { hidden: true });
+
+try {
+  await program.parseAsync();
+} catch (err) {
+  if (err instanceof ApiError) {
+    if (err.status === 422) {
+      console.info(`API key is missing or malformed. Run: clawclaw-cli account register`);
+    } else if (err.status === 401) {
+      console.info(`Account not found or API key expired. Run: clawclaw-cli account register`);
+    } else {
+      console.info(`Request failed (${err.status}): ${err.body}`);
+    }
+  } else {
+    console.error(err instanceof Error ? err.message : String(err));
+  }
+  process.exit(1);
+}

package/src/commands/_schema.ts

@@ -0,0 +1,109 @@
+/**
+ * `_schema` — internal hidden command exposing the entire commander tree as JSON.
+ *
+ * Adapter consumers (e.g. `openclaw-clawclaw`) call this to auto-generate one tool
+ * per leaf subcommand without having to hand-translate each `ccl` command.
+ *
+ * Hidden by convention: name starts with `_` so the walker excludes it from output,
+ * and `--help` listings of regular tooling generally skip underscore-prefixed entries.
+ */
+
+import { Command, Option, Argument } from 'commander';
+import { getMeta, type CommandMeta } from '../lib/command-meta.js';
+
+interface OptionSchema {
+  flags: string;
+  long?: string | null;
+  short?: string | null;
+  attributeName: string;
+  description?: string;
+  defaultValue?: unknown;
+  /** option marked with `<value>` — value required */
+  required: boolean;
+  /** option marked with `[value]` — value optional */
+  optional: boolean;
+  /** option marked with `.makeOptionMandatory()` — option itself required */
+  mandatory: boolean;
+  negate: boolean;
+  takesValue: boolean;
+}
+
+interface ArgumentSchema {
+  name: string;
+  description?: string;
+  required: boolean;
+  variadic: boolean;
+  defaultValue?: unknown;
+}
+
+interface CommandSchema {
+  name: string;
+  description?: string;
+  aliases: string[];
+  options: OptionSchema[];
+  arguments: ArgumentSchema[];
+  subcommands: CommandSchema[];
+  /** path from root, joined by space, e.g. "account leaderboard" */
+  path: string;
+  /** true when the command has no subcommands and is therefore directly invocable */
+  leaf: boolean;
+  /** Adapter-facing metadata (omitted if no metadata is set on this command). */
+  meta?: CommandMeta;
+}
+
+function dumpOption(o: Option): OptionSchema {
+  const flags = o.flags;
+  const takesValue = flags.includes('<') || flags.includes('[');
+  return {
+    flags,
+    long: o.long ?? null,
+    short: o.short ?? null,
+    attributeName: o.attributeName(),
+    description: o.description || undefined,
+    defaultValue: o.defaultValue,
+    required: o.required,
+    optional: o.optional,
+    mandatory: o.mandatory,
+    negate: o.negate,
+    takesValue,
+  };
+}
+
+function dumpArgument(a: Argument): ArgumentSchema {
+  return {
+    name: a.name(),
+    description: a.description || undefined,
+    required: a.required,
+    variadic: a.variadic,
+    defaultValue: a.defaultValue,
+  };
+}
+
+function walkCommand(cmd: Command, parentPath: string[] = []): CommandSchema {
+  const path = [...parentPath, cmd.name()];
+  const visibleSubs = (cmd.commands || []).filter((c) => !c.name().startsWith('_'));
+  const meta = getMeta(cmd);
+  return {
+    name: cmd.name(),
+    description: cmd.description() || undefined,
+    aliases: cmd.aliases() ?? [],
+    options: (cmd.options || []).map(dumpOption),
+    arguments: (cmd.registeredArguments || []).map(dumpArgument),
+    subcommands: visibleSubs.map((c) => walkCommand(c, path)),
+    path: path.slice(1).join(' '), // exclude root program name from path
+    leaf: visibleSubs.length === 0,
+    ...(meta && Object.keys(meta).length > 0 ? { meta } : {}),
+  };
+}
+
+export function createSchemaCommand(getProgram: () => Command): Command {
+  return new Command('_schema')
+    .description('[internal] dump full command tree as JSON for adapter auto-generation')
+    .option('--pretty', 'Indent JSON output')
+    .action((opts: { pretty?: boolean }) => {
+      const tree = walkCommand(getProgram());
+      console.log(JSON.stringify(tree, null, opts.pretty ? 2 : 0));
+    });
+  // Note: to hide from `ccl --help`, the parent passes { hidden: true } to addCommand().
+  // See cli.ts registration site.
+}

package/src/commands/account.ts

@@ -0,0 +1,209 @@
+import { Command } from 'commander';
+import { AuthStore } from '../lib/auth.js';
+import type { AuthProfile } from '../lib/auth.js';
+import { GameClient, ApiError } from '../lib/game-client.js';
+import { createProfileDirs, cmdInit } from '../lib/init-command.js';
+import { setMeta } from '../lib/command-meta.js';
+import { hubReminder, readCachedGamesPlayed, writeGamesPlayedCache } from '../lib/hub-reminder.js';
+
+const DEFAULT_SERVER_URL = 'https://myclaw.163.com/claw';
+const SERVER_URL_ENV = 'CLAWCLAW_SERVER_URL';
+
+function createClientForProfile(profile: AuthProfile): GameClient {
+  return new GameClient({
+    lobbyUrl: profile.serverUrl,
+    gameServerUrl: profile.gameServerUrl,
+    apiKey: profile.apiKey,
+    agentName: profile.agentName,
+  });
+}
+
+function extractServerAccountName(payload: any): string | undefined {
+  const data = payload?.data ?? payload;
+  return data?.agent_name ?? data?.agentName ?? data?.name;
+}
+
+function getRegisterServerUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env[SERVER_URL_ENV]?.trim();
+  return configured || DEFAULT_SERVER_URL;
+}
+
+export function createAccountCommand(): Command {
+  const account = new Command('account');
+  account.description('Account management & game data');
+
+  // ─── Auth ───
+
+  account
+    .command('register')
+    .description('Register new agent')
+    .option('-n, --name <name>', 'Agent name (max 16 chars); omit to let the server choose randomly')
+    .option('-d, --desc <text>', 'Agent description (max 500 chars)')
+    .option('--invite-code <code>', 'Invite code (required during beta)')
+    .option('--avatar-url <url>', 'Avatar image URL')
+    .option('--avatar-file <path>', 'Avatar image file (jpeg/png/gif/webp, max 1MB)')
+    .action(async (opts: { name?: string; desc?: string; inviteCode?: string; avatarUrl?: string; avatarFile?: string }) => {
+      const authStore = new AuthStore();
+      const { created, path: wsPath } = cmdInit();
+      if (created) console.log(`[ClawClaw] Workspace initialized at ${wsPath}`);
+      const serverUrl = getRegisterServerUrl();
+
+      const tmpClient = new GameClient({ lobbyUrl: serverUrl, apiKey: '' });
+      const result = await tmpClient.registerAgent({
+        name: opts.name,
+        description: opts.desc,
+        inviteCode: opts.inviteCode,
+        avatarUrl: opts.avatarUrl,
+        avatarFile: opts.avatarFile,
+      });
+      const d = result.data ?? result;
+      const apiKey = d.api_key ?? d.apiKey ?? '';
+      if (!apiKey) throw new Error('Registration failed: server did not return an API key.');
+      const agentName = d.agent_name ?? '';
+      if (!agentName) throw new Error('Registration failed: server did not return an agent name.');
+
+      const profile: AuthProfile = {
+        agentName,
+        apiKey,
+        serverUrl,
+      };
+      authStore.addProfile(profile);
+      try { createProfileDirs(profile); } catch {}
+      console.log(JSON.stringify({ ...result, message: `Registered and saved as profile "${agentName}"` }, null, 2));
+    });
+
+  account
+    .command('rename <name>')
+    .description('Rename agent (max once/month, max 2/year, not during a game)')
+    .action(async (newName: string) => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const client = GameClient.fromAuth();
+      const result = await client.renameAgent(newName);
+      const oldName = profile.agentName;
+      profile.agentName = newName;
+      authStore.removeProfile(oldName);
+      authStore.addProfile(profile);
+      authStore.switchProfile(newName);
+      console.log(JSON.stringify({ ...result, message: `Renamed "${oldName}" → "${newName}"` }, null, 2));
+    });
+
+  account
+    .command('switch <apiKey>')
+    .description('Switch active profile by API key')
+    .action(async (apiKey: string) => {
+      const authStore = new AuthStore();
+      const data = authStore.load();
+      const profileKey = Object.keys(data.profiles).find(key => data.profiles[key]?.apiKey === apiKey);
+      if (!profileKey) {
+        throw new Error(`Profile with apiKey "${apiKey}" not found. Use \`clawclaw-cli account list\` to inspect saved accounts.`);
+      }
+      authStore.switchProfile(profileKey);
+      console.log(JSON.stringify({ message: 'Switched active profile', apiKey }, null, 2));
+    });
+
+  account
+    .command('list')
+    .description('List all saved profiles with current server names')
+    .action(async () => {
+      const authStore = new AuthStore();
+      const active = authStore.getActive();
+      const data = authStore.load();
+      const result = await Promise.all(Object.values(data.profiles).map(async (profile) => {
+        try {
+          const me = await createClientForProfile(profile).getMe();
+          return {
+            name: extractServerAccountName(me) ?? profile.agentName,
+            apiKey: profile.apiKey,
+            active: profile.apiKey === active?.apiKey,
+          };
+        } catch {
+          return {
+            name: profile.agentName,
+            apiKey: profile.apiKey,
+            active: profile.apiKey === active?.apiKey,
+          };
+        }
+      }));
+      console.log(JSON.stringify(result, null, 2));
+    });
+
+  // ─── Game Data ───
+
+  account
+    .command('leaderboard')
+    .description('Show leaderboard')
+    .option('-p, --page <number>', 'Page number')
+    .option('-l, --limit <number>', 'Items per page (max 100)', '20')
+    .action(async (opts: { page?: string; limit: string }) => {
+      const client = GameClient.fromAuth();
+      const page = opts.page ? Number(opts.page) : undefined;
+      const result = await client.getLeaderboard(page, Number(opts.limit));
+      console.log(JSON.stringify(result, null, 2));
+    });
+
+  account
+    .command('settlement')
+    .description('Show settlement data from last game')
+    .action(async () => {
+      const client = GameClient.fromAuth();
+      try {
+        const result = await client.getSettlement();
+        // `ccl account settlement` is the last command the agent runs before
+        // writing the debrief close, and its `data` block is long enough to bury
+        // the reminder that rode in on the `game_over` push. Re-attach it here as
+        // the final fields (after `data`) so the nudge is the freshest thing in
+        // context the moment the agent writes the close.
+        const reminder = hubReminder(readCachedGamesPlayed());
+        const out: Record<string, any> = (result && typeof result === 'object' && !Array.isArray(result))
+          ? { ...result }
+          : { result };
+        if (reminder) {
+          out.hub_reminder = reminder;
+          out.next_step = `Write the post-game debrief with your user from this settlement, then close out. ${reminder}`;
+        }
+        console.log(JSON.stringify(out, null, 2));
+      } catch (err: any) {
+        if (err instanceof ApiError && err.body?.includes('NO_SETTLEMENT')) {
+          console.info('No settlement data yet. The game may still be in progress, or you quit early after dying; you can still give a brief recap from known events so far.');
+          return;
+        }
+        throw err;
+      }
+    });
+
+  account
+    .command('history')
+    .description('Show game history')
+    .option('-p, --page <number>', 'Page number', '1')
+    .option('-l, --limit <number>', 'Items per page (max 100)', '20')
+    .action(async (opts: { page: string; limit: string }) => {
+      const client = GameClient.fromAuth();
+      const result = await client.getGameHistory(Number(opts.page), Number(opts.limit));
+      console.log(JSON.stringify(result, null, 2));
+    });
+
+  account
+    .command('info')
+    .description('Print account name, Claw Key, and spectate URL')
+    .action(async () => {
+      const authStore = new AuthStore();
+      const profile = authStore.getActive();
+      if (!profile) throw new Error('Not logged in.');
+      const client = GameClient.fromAuth();
+      const result = await client.getMe();
+      if (result?.data) delete result.data.tutorial;
+      const gp = result?.data?.games_played;
+      if (typeof gp === 'number') writeGamesPlayedCache(gp);
+      const origin = new URL(profile.serverUrl).origin.replace(/^http:\/\//, 'https://');
+      const url = `${origin}/lobby?token=${encodeURIComponent(profile.apiKey)}`;
+      console.log(JSON.stringify({ ...result, clawKey: profile.apiKey, spectateUrl: url }, null, 2));
+    });
+
+  // ── Adapter metadata (consumed by ccl _schema, applied by openclaw-clawclaw L2 generator) ──
+  setMeta(account.commands.find((c) => c.name() === 'register')!, { requiresConfirm: true });
+  setMeta(account.commands.find((c) => c.name() === 'rename')!, { requiresConfirm: true });
+
+  return account;
+}

package/src/commands/config.ts

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { getWorkspaceDir } from '../lib/init-command.js';
+import { AuthStore } from '../lib/auth.js';
+
+export function createWorkspaceSubcommand(): Command {
+  return new Command('workspace')
+    .description('Print the workspace directory path')
+    .action(() => {
+      console.log(getWorkspaceDir());
+    });
+}
+
+export function createApikeySubcommand(): Command {
+  return new Command('apikey')
+    .description('Print the active account API key')
+    .action(() => {
+      const store = new AuthStore();
+      const profile = store.getActive();
+      if (!profile) throw new Error('Not logged in. Run: clawclaw-cli account register');
+      console.log(profile.apiKey);
+    });
+}
+
+export function createConfigCommand(): Command {
+  const config = new Command('config');
+  config.description('Query ClawClaw CLI configuration.');
+  config.addCommand(createWorkspaceSubcommand());
+  config.addCommand(createApikeySubcommand());
+  return config;
+}