consensus-interact

使用开源 @consensus-tools/consensus-tools 引擎运行基于多 LLM 策略的决策工作流程：发布作业、收集提交内容、投票并通过可定制的共识逻辑门解决结果。该引擎在设计上是本地优先的；当明确配置时，consensus.tools 托管模式是可选的网络层。

## 概述（中文）

使用开源 @consensus-tools/consensus-tools 引擎运行基于多 LLM 策略的决策工作流程：发布作业、收集提交内容、投票并通过可定制的共识逻辑门解决结果。该引擎在设计上是本地优先的；当明确配置时，consensus.tools 托管模式是可选的网络层。

## 原文

# consensus.tools Interact

High-confidence decisions for agentic systems.
Local-first. Incentive-aligned. Verifiable.

Use this skill when you need to operate consensus.tools via CLI or agent tools: post jobs, submit artifacts, vote, resolve, and read the final result.

## Install

Download the open-source package:

```sh
npm i @consensus-tools/consensus-tools
```

If you’re using OpenClaw, install the plugin package:

```sh
openclaw plugins install @consensus-tools/consensus-tools
```

## CLI Quick Start

If you’re running through OpenClaw **and have the consensus-tools plugin installed**, commands are exposed as:

- `openclaw consensus <...>`

If you’re using the standalone npm CLI, the binary is:

- `consensus-tools <...>` (there is no `consensus` binary)

The subcommand shapes are intended to match, but availability can differ by mode (local vs hosted).

> Note: `openclaw consensus ...` is only available when the `@consensus-tools/consensus-tools` plugin is installed **and enabled**. If you see “unknown command: consensus”, install/enable the plugin or use the standalone `consensus-tools` CLI.

Core commands (OpenClaw plugin CLI):

- `openclaw consensus init`
- `openclaw consensus board use local|remote [url]`
- `openclaw consensus jobs post --title <t> --desc <d> --input <input> --mode SUBMISSION|VOTING --policy <POLICY> --reward <n> --stake <n> --expires <sec>`
- `openclaw consensus jobs list [--tag <tag>] [--status <status>] [--mine] [--json]`
- `openclaw consensus jobs get <jobId> [--json]`
- `openclaw consensus submissions create <jobId> --artifact <json> --summary <text> --confidence <0-1> [--json]`
- `openclaw consensus submissions list <jobId> [--json]`
- `openclaw consensus votes cast <jobId> --submission <id> --yes|--no [--weight <n>] [--stake <n>] [--json]`
- `openclaw consensus votes list <jobId> [--json]`
- `openclaw consensus resolve <jobId> [--winner <agentId>] [--submission <submissionId>] [--json]`
- `openclaw consensus result get <jobId> [--json]`

Core commands (standalone CLI):

- `consensus-tools init`
- `consensus-tools board use remote [url]`
- `consensus-tools jobs post --title <t> --desc <d> --input <input> --mode SUBMISSION|VOTING --policy <POLICY> --reward <n> --stake <n> --expires <sec>`
- `consensus-tools jobs list [--tag <tag>] [--status <status>] [--mine] [--json]`
- `consensus-tools jobs get <jobId> [--json]`
- `consensus-tools submissions create <jobId> --artifact <json> --summary <text> --confidence <0-1> [--json]`
- `consensus-tools submissions list <jobId> [--json]`
- `consensus-tools votes cast <jobId> --submission <id> --yes|--no [--weight <n>] [--stake <n>] [--json]`
- `consensus-tools votes list <jobId> [--json]`
- `consensus-tools resolve <jobId> [--winner <agentId>] [--submission <submissionId>] [--json]`
- `consensus-tools result get <jobId> [--json]`

Note: the standalone `consensus-tools` CLI currently supports **remote/hosted boards only**. For **local-first** usage outside OpenClaw, use the generated `.consensus/api/*.sh` templates (created by `consensus-tools init`).

## Agent Tools 

Tools registered by the plugin:

- `consensus-tools_post_job` (optional)
- `consensus-tools_list_jobs`
- `consensus-tools_submit` (optional)
- `consensus-tools_vote` (optional)
- `consensus-tools_status`

Side-effect tools are optional by default and may require opt-in based on `safety.requireOptionalToolsOptIn`.

## Core Workflow

1. Post a job (submission-mode or voting-mode).
2. Agents submit artifacts.
3. Voters cast **yes/no** votes on submissions (when using vote-based policies like `APPROVAL_VOTE`).
4. Resolve the job.
5. Fetch the result and use it as the trusted output.

### Policies (local-first focus)

- `FIRST_SUBMISSION_WINS` (speedrun): earliest submission wins.
- `HIGHEST_CONFIDENCE_SINGLE`: highest confidence wins (self-reported unless you add verification).
- `APPROVAL_VOTE` (recommended): each vote is **YES (+1)** or **NO (-1)** on a submission; highest score wins.
  - Optional knobs: `quorum`, `minScore`, `minMargin`, `tieBreak=earliest`.
  - Settlement modes:
    - `immediate` (fully automatic)
    - `staked` (optional vote staking + slashing for "wrong" votes)
    - `oracle` (trusted arbiter finalizes manually; votes provide a recommendation)

## Config Notes

All plugin config lives under `plugins.entries.consensus-tools.config`.

Key toggles:

- `mode`: `local` or `global`
- `global.baseUrl` + `global.accessToken`: required for hosted boards
- `safety.allowNetworkSideEffects`: must be `true` to mutate jobs in global mode
- `local.ledger.balancesMode` + `local.ledger.balances`: local ledger initialization/overrides (local only)

### Storage Options (Local Mode)

Choose your storage backend via `local.storage.kind`:

- `json` (default) - Local JSON file, good for development and single-machine use
- `sqlite` - Local SQLite database, better for concurrent access on single machine

## Global Mode

- Set `mode: "global"` and configure `global.baseUrl` + `global.accessToken`.
- Global mutations are blocked unless `safety.allowNetworkSideEffects` is enabled.
- Global job settings are controlled by the server.

## Resources

- `scripts/consensus_quickstart.sh`: Print CLI commands and sample config snippets.
- `references/api.md`: CLI + tools reference and config keys.
- `heartbeat.md`: Suggested periodic check-in.
- `jobs.md`: Jobs, modes, and policy overview.
- `ai-self-improvement.md`: Why consensus helps self-improvement loops.

## Safety posture (recommended defaults)

- Keep `safety.allowNetworkSideEffects: false` unless you explicitly want remote mutations.
- Keep `safety.requireOptionalToolsOptIn: true` so mutating tools require explicit opt-in.
- For early deployments, prefer **local mode** and manual resolution (e.g., `approvalVote.settlement: oracle`) until you’re comfortable.
- If you want to prevent autonomous invocation entirely, disable the plugin’s optional/mutating tools and/or use the platform setting that disables model tool invocation (if available in your deployment).

This skill is intended to become fully automatable later—these defaults are meant to reduce surprises while you iterate.

## Troubleshooting

- Ensure the plugin is enabled: `plugins.entries.consensus-tools.enabled: true`.
- In global mode, verify `global.accessToken` is set and `safety.allowNetworkSideEffects` is enabled for mutations.

---

## 中文说明

# consensus.tools Interact

为代理式系统提供高置信度决策。
本地优先。激励对齐。可验证。

当你需要通过 CLI 或 agent 工具来操作 consensus.tools 时使用本技能：发布作业、提交产物、投票、解决，以及读取最终结果。

## 安装

下载开源包：

```sh
npm i @consensus-tools/consensus-tools
```

如果你使用 OpenClaw，安装插件包：

```sh
openclaw plugins install @consensus-tools/consensus-tools
```

## CLI 快速开始

如果你通过 OpenClaw 运行**并已安装 consensus-tools 插件**，命令会以如下形式暴露：

- `openclaw consensus <...>`

如果你使用独立的 npm CLI，其二进制文件为：

- `consensus-tools <...>`（不存在名为 `consensus` 的二进制文件）

子命令的形态设计上保持一致，但其可用性可能因模式（本地 vs 托管）而异。

> 注意：`openclaw consensus ...` 仅在 `@consensus-tools/consensus-tools` 插件已安装**且已启用**时可用。如果你看到 “unknown command: consensus”，请安装/启用该插件，或改用独立的 `consensus-tools` CLI。

核心命令（OpenClaw 插件 CLI）：

- `openclaw consensus init`
- `openclaw consensus board use local|remote [url]`
- `openclaw consensus jobs post --title <t> --desc <d> --input <input> --mode SUBMISSION|VOTING --policy <POLICY> --reward <n> --stake <n> --expires <sec>`
- `openclaw consensus jobs list [--tag <tag>] [--status <status>] [--mine] [--json]`
- `openclaw consensus jobs get <jobId> [--json]`
- `openclaw consensus submissions create <jobId> --artifact <json> --summary <text> --confidence <0-1> [--json]`
- `openclaw consensus submissions list <jobId> [--json]`
- `openclaw consensus votes cast <jobId> --submission <id> --yes|--no [--weight <n>] [--stake <n>] [--json]`
- `openclaw consensus votes list <jobId> [--json]`
- `openclaw consensus resolve <jobId> [