advisor-claw-skill

Advisor Claw Skill

Status: local validation: passed | smoke test: ok | license: MIT | runtime: Node.js CommonJS | config: OpenClaw JSON5 official | docs: English + 中文

Professional OpenClaw skill scaffold for a budget-aware advisor/executor workflow.

Overview

Mission: create a research report about ai in finance during 2025-2026.

总览

任务：生成一份2025-2026年份有关ai在金融领域的调查报告。

Navigation

English

• Overview
• What Is Actually Implemented
• Key Behaviors
• Architecture
• Runtime Flow
• Directory Layout
• OpenClaw Configuration Sources
• Validation
• Notes And Precautions
• Current Scope
• How to use
• License

中文

• 中文部分
• 概述
• 已真实实现的能力
• 关键行为说明
• 架构图
• 运行流程简图
• 目录结构
• OpenClaw 配置来源
• 验证方式
• 使用注意事项
• 当前范围
• 如何使用
• 许可证

---

English

Overview

Advisor Claw Skill is a production-oriented OpenClaw scaffold that implements a two-role orchestration pattern:

• a lower-cost executor handles the main task loop
• a stronger advisor is invoked only when task complexity, uncertainty, execution pressure, or stagnation justify the extra cost

This repository is not a mock design note anymore. It reflects the result of multiple rounds of review, correction, runtime hardening, and smoke-test validation.

What Is Actually Implemented

The current implementation includes real, validated behavior instead of placeholder documentation:

• strict two-model workflow: the skill requires exactly 2 candidate models
• automatic role assignment: the stronger model becomes advisor, the better price/performance model becomes executor
• OpenClaw config discovery from official config surfaces
• official JSON5 config parsing for ~/.openclaw/openclaw.json
• optional project-level merge with openclaw.config.json
• $include support within the config boundary
• configured-model reuse when a model or provider already exists in OpenClaw config
• external model support when the user explicitly provides an API key
• bounded recovery ladder: executor 3 attempts, advisor 2 attempts, then structured failure
• markdown execution logs written to out/
• end-of-run quality vs resource comparison in the markdown log footer
• executable smoke test covering orchestration, config loading, recovery, and logging

Key Behaviors

Model Selection Rules

• Exactly 2 candidate models must be provided.
• If the candidate already exists in OpenClaw config, the skill reuses it.
• If the candidate is not configured in OpenClaw, an API key is required.
• If neither condition is met, the run fails early with a configuration error.

Execution Rules

• The advisor can be called at initial planning, during execution, and for final quality review.
• Advisor escalation is controlled by a weighted decision engine instead of a single threshold.
• The cost tracker records token and USD usage by role.
• The execution logger persists timeline events and a final summary.

Failure Rules

• Executor retries up to 3 times.
• Advisor repair attempts up to 2 more times.
• If recovery still fails, the orchestrator throws a structured AdvisorRuntimeError with cause and stack trace.

Architecture

flowchart TD
    A[Task Input] --> B[AdvisorOrchestrator]
    B --> C[ModelRegistry]
    C --> C1[Advisor Role]
    C --> C2[Executor Role]
    B --> D[DecisionEngine]
    B --> E[ContextManager]
    B --> F[CostTracker]
    B --> G[ExecutionLogger]
    B --> H[ProviderClient]
    H --> C2
    D --> B
    E --> B
    F --> B
    G --> I[out/*.md]

Runtime Flow

flowchart LR
    A[Load OpenClaw Config] --> B[Validate Exactly 2 Candidate Models]
    B --> C[Auto Assign Advisor / Executor]
    C --> D[Optional Initial Advisor Review]
    D --> E[Executor Pass Loop]
    E --> F{Need Advisor?}
    F -- No --> E
    F -- Yes --> G[Advisor Guidance]
    G --> E
    E --> H[Optional Final QA Review]
    H --> I[Write Markdown Log]
    I --> J[Append Quality vs Token/USD Summary]

Directory Layout

advisor-manager-skill/
├── SKILL.md
├── README.md
├── LICENSE
├── package.json
├── package-lock.json
├── config/
│   ├── default.yaml
│   ├── roles.yaml
│   ├── strategies.yaml
│   └── model_catalog.example.yaml
├── references/
│   ├── conversation-setup.md
│   └── design-review.md
├── scripts/
│   ├── advisor_orchestrator.js
│   ├── context_manager.js
│   ├── cost_tracker.js
│   ├── decision_engine.js
│   ├── execution_logger.js
│   ├── index.js
│   ├── model_configuration_error.js
│   ├── model_registry.js
│   ├── openclaw_config_loader.js
│   ├── provider_client.js
│   ├── runtime_error.js
│   └── smoke_test.js
└── templates/

OpenClaw Configuration Sources

The runtime currently targets the official OpenClaw config layout:

• OPENCLAW_CONFIG_PATH
• ~/.openclaw/openclaw.json
• project-level openclaw.config.json

The loader understands these official structures:

• models.providers
• models.providers.*.models[]
• agents.defaults.models
• agents.defaults.model
• agents.list[].model
• JSON5 comments and trailing commas
• $include expansion inside the config root

Validation

Install dependencies:

npm install

Run the smoke test:

node .\scripts\smoke_test.js

Run syntax checks:

node --check .\scripts\openclaw_config_loader.js
node --check .\scripts\execution_logger.js
node --check .\scripts\cost_tracker.js
node --check .\scripts\advisor_orchestrator.js
node --check .\scripts\smoke_test.js

Notes And Precautions

Please read these before using the skill:

1. This repository is a hardened scaffold, not a full provider-integrated production service.
2. The skill assumes exactly 2 candidate models. Zero, one, or more than two is a hard configuration error.
3. OpenClaw-configured providers are reused only when discovery succeeds from official config structures.
4. Unconfigured external models must provide API-key metadata explicitly.
5. The generated markdown logs may contain task content, warnings, and stack traces. Do not treat out/ as automatically sanitized public output.
6. The quality score in the log footer is an orchestration-side heuristic for runtime assessment, not a universal benchmark.
7. $include resolution is intentionally restricted to the config root boundary.
8. The repository currently keeps package.json as private: true; MIT licensing here expresses source usage terms, not package publication intent.

Current Scope

Included now:

• orchestration logic
• model validation and role assignment
• official-style OpenClaw config loading
• bounded recovery
• markdown execution logging
• cost and token accounting
• bilingual documentation

Intentionally left open:

• real provider SDK integration
• persistent storage backend
• deployment packaging
• live OpenClaw gateway automation hooks

How to use

Basically, just tell your ai platform(openclaw) to use the skill.

License

This project is licensed under the MIT License. See LICENSE for details.

---

中文

概述

Advisor Claw Skill 是一个面向 OpenClaw 的生产导向型技能脚手架，实现了双角色协同模式：

• 低成本执行模型负责主要任务循环
• 只有在复杂度、不确定性、执行压力或停滞程度值得额外成本时，才调用更强的顾问模型

这个仓库现在不再只是设计草案，而是经过多轮复盘、纠偏、运行时加固和 smoke test 验证后的实际结果。

已真实实现的能力

当前实现的是可运行、已验证的功能，而不是占位描述：

• 严格双模型约束：技能要求且只接受 2 个候选模型
• 自动分角：更强的模型担任 advisor，更优性价比模型担任 executor
• 按 OpenClaw 官方配置结构进行模型发现
• 支持解析 ~/.openclaw/openclaw.json 的官方 JSON5 配置
• 支持与项目级 openclaw.config.json 合并
• 支持配置根目录内的 $include
• 当模型或 provider