mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-06 05:51:15 +08:00
feat(workboard): add worker dispatch CLI
* feat(workboard): add worker dispatch CLI * fix(workboard): avoid new unsafe assertions * fix(workboard): keep remote dispatch failures remote
This commit is contained in:
Peter Steinberger
committed by
GitHub
GitHub
parent
1d55caa162
commit
ed46e62bcc
@@ -35,7 +35,7 @@ Use the setup commands by intent:
|
||||
| Pairing and channels | [`pairing`](/cli/pairing) · [`qr`](/cli/qr) · [`channels`](/cli/channels) |
|
||||
| Security and plugins | [`security`](/cli/security) · [`secrets`](/cli/secrets) · [`skills`](/cli/skills) · [`plugins`](/cli/plugins) · [`proxy`](/cli/proxy) |
|
||||
| Legacy aliases | [`daemon`](/cli/daemon) (gateway service) · [`clawbot`](/cli/clawbot) (namespace) |
|
||||
| Plugins (optional) | [`path`](/cli/path) · [`policy`](/cli/policy) · [`voicecall`](/cli/voicecall) (if installed) |
|
||||
| Plugins (optional) | [`path`](/cli/path) · [`policy`](/cli/policy) · [`voicecall`](/cli/voicecall) · [`workboard`](/cli/workboard) (if installed) |
|
||||
|
||||
## Global flags
|
||||
|
||||
@@ -124,6 +124,11 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
disable
|
||||
doctor
|
||||
marketplace list
|
||||
workboard
|
||||
list
|
||||
create
|
||||
show
|
||||
dispatch
|
||||
memory
|
||||
status
|
||||
index
|
||||
@@ -368,7 +373,8 @@ openclaw [--dev] [--profile <name>] <command>
|
||||
terminal (alias: tui --local)
|
||||
```
|
||||
|
||||
Plugins can add additional top-level commands (for example `openclaw voicecall`).
|
||||
Plugins can add additional top-level commands, such as
|
||||
[`openclaw workboard`](/cli/workboard) or `openclaw voicecall`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
221
docs/cli/workboard.md
Normal file
221
docs/cli/workboard.md
Normal file
@@ -0,0 +1,221 @@
|
||||
---
|
||||
summary: "CLI reference for `openclaw workboard` cards, dispatch, and worker runs"
|
||||
read_when:
|
||||
- You want to inspect or create Workboard cards from the terminal
|
||||
- You want to dispatch Workboard worker runs from the CLI
|
||||
- You are debugging Workboard CLI or slash command behavior
|
||||
title: "Workboard CLI"
|
||||
---
|
||||
|
||||
`openclaw workboard` is the terminal surface for the bundled
|
||||
[Workboard plugin](/plugins/workboard). It lets an operator list cards, create a
|
||||
card, inspect one card, and ask the running Gateway to dispatch ready work into
|
||||
subagent worker runs.
|
||||
|
||||
Enable the plugin before using the command:
|
||||
|
||||
```bash
|
||||
openclaw plugins enable workboard
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
openclaw workboard list [--board <id>] [--status <status>] [--json]
|
||||
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
|
||||
openclaw workboard show <id> [--json]
|
||||
openclaw workboard dispatch [--url <url>] [--token <token>] [--timeout <ms>] [--json]
|
||||
```
|
||||
|
||||
The command reads and writes the same plugin-owned SQLite database used by the
|
||||
dashboard and Workboard agent tools. Card ids can be passed by full id or by an
|
||||
unambiguous prefix when a command accepts a card id.
|
||||
|
||||
## `list`
|
||||
|
||||
```bash
|
||||
openclaw workboard list
|
||||
openclaw workboard list --board default --status ready
|
||||
openclaw workboard list --json
|
||||
```
|
||||
|
||||
Text output is compact:
|
||||
|
||||
```text
|
||||
7f4a2c10 ready high default agent-a Fix stale worker heartbeat
|
||||
```
|
||||
|
||||
Columns are id prefix, status, priority, board id, optional agent id, and title.
|
||||
|
||||
Flags:
|
||||
|
||||
| Flag | Purpose |
|
||||
| ------------------- | ---------------------------------------- |
|
||||
| `--board <id>` | Limit results to one board namespace |
|
||||
| `--status <status>` | Limit results to one Workboard status |
|
||||
| `--json` | Print the full card list as machine JSON |
|
||||
|
||||
## `create`
|
||||
|
||||
```bash
|
||||
openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
|
||||
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
| Flag | Purpose |
|
||||
| ----------------------- | --------------------------------------- |
|
||||
| `--notes <text>` | Initial card notes |
|
||||
| `--status <status>` | Initial status, default `todo` |
|
||||
| `--priority <priority>` | Priority, default `normal` |
|
||||
| `--agent <id>` | Assign the card to an agent or owner id |
|
||||
| `--board <id>` | Store the card on a board namespace |
|
||||
| `--labels <items>` | Comma-separated labels |
|
||||
| `--json` | Print the created card as machine JSON |
|
||||
|
||||
`create` writes directly to Workboard SQLite state. The card is immediately
|
||||
visible in the Control UI Workboard tab and to Workboard tools.
|
||||
|
||||
## `show`
|
||||
|
||||
```bash
|
||||
openclaw workboard show 7f4a2c10
|
||||
openclaw workboard show 7f4a2c10 --json
|
||||
```
|
||||
|
||||
Text output prints the compact card line and notes. JSON output returns the full
|
||||
card record, including execution metadata, attempts, comments, links, proof,
|
||||
artifacts, worker logs, protocol state, diagnostics, and automation metadata.
|
||||
|
||||
## `dispatch`
|
||||
|
||||
```bash
|
||||
openclaw workboard dispatch
|
||||
openclaw workboard dispatch --json
|
||||
openclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
|
||||
```
|
||||
|
||||
`dispatch` first calls the running Gateway RPC method
|
||||
`workboard.cards.dispatch`. That path uses the same subagent runtime as the
|
||||
dashboard dispatch action, so ready cards can become real worker sessions.
|
||||
|
||||
The dispatch loop:
|
||||
|
||||
1. Promotes dependency-ready children to `ready`.
|
||||
2. Blocks expired claims or timed-out worker runs.
|
||||
3. Records dispatch metadata on ready cards.
|
||||
4. Selects a small batch of unclaimed ready cards.
|
||||
5. Claims each selected card for the dispatcher or assigned agent.
|
||||
6. Starts a subagent worker run with bounded card context and the card claim
|
||||
token.
|
||||
7. Stores the worker run id, session key, execution status, and worker log on
|
||||
the card.
|
||||
|
||||
Selection is intentionally conservative. One dispatch starts at most three
|
||||
workers by default, skips archived or already-claimed cards, and starts only one
|
||||
card per owner or agent in a single pass. Cards already owned by active running
|
||||
or review work are left for a later dispatch.
|
||||
|
||||
If worker start fails after a card is claimed, Workboard blocks that card,
|
||||
clears the claim, and records the failure in card execution and worker-log
|
||||
metadata. This keeps failed starts visible instead of silently returning the
|
||||
card to the queue.
|
||||
|
||||
If no explicit Gateway target is provided and the local Gateway is unavailable
|
||||
or does not expose the Workboard dispatch method yet, the CLI falls back to
|
||||
data-only dispatch against local Workboard state. Data-only dispatch can still
|
||||
promote dependencies, clean stale claims, and block timed-out runs, but it does
|
||||
not start workers. Auth, permission, validation failures, and failures for an
|
||||
explicit `--url` or `--token` target are reported directly.
|
||||
|
||||
Text output reports worker starts:
|
||||
|
||||
```text
|
||||
dispatch complete: started=2 failures=0
|
||||
```
|
||||
|
||||
Fallback output is explicit:
|
||||
|
||||
```text
|
||||
gateway unavailable; data dispatch only: promoted=1 blocked=0
|
||||
```
|
||||
|
||||
JSON output includes the dispatch result. Gateway-backed dispatch can include
|
||||
`started` and `startFailures`; data-only fallback includes
|
||||
`gatewayUnavailable: true`. Claim tokens are redacted from card JSON output.
|
||||
|
||||
## Slash Command Parity
|
||||
|
||||
Command-capable channels can use the matching slash command:
|
||||
|
||||
```text
|
||||
/workboard list
|
||||
/workboard show 7f4a2c10
|
||||
/workboard create Fix stale worker heartbeat
|
||||
/workboard dispatch
|
||||
```
|
||||
|
||||
Slash command dispatch also uses the Gateway subagent runtime, so it follows the
|
||||
same claim, worker-start, and failure behavior as the dashboard and CLI Gateway
|
||||
path.
|
||||
|
||||
`/workboard list` and `/workboard show` are read commands for authorized command
|
||||
senders. `/workboard create` and `/workboard dispatch` mutate board state and
|
||||
require owner status on chat surfaces or a Gateway client with `operator.write`
|
||||
or `operator.admin`.
|
||||
|
||||
## Permissions
|
||||
|
||||
The CLI dispatch path calls Gateway RPC with `operator.read` and
|
||||
`operator.write` scopes. A read-only Gateway token can inspect Workboard data
|
||||
through read methods, but it cannot create cards or dispatch workers.
|
||||
|
||||
Local `list`, `create`, and `show` commands operate on the local OpenClaw state
|
||||
directory used by the current profile. Use `--dev` or `--profile <name>` on the
|
||||
top-level `openclaw` command when you need a different state root.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No Cards Appear
|
||||
|
||||
Confirm the plugin is enabled for the same profile and state root:
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect workboard --runtime --json
|
||||
```
|
||||
|
||||
If the dashboard shows cards but the CLI does not, check that both commands use
|
||||
the same `--dev` or `--profile` setting.
|
||||
|
||||
### Dispatch Says Data-Only
|
||||
|
||||
Start or restart the Gateway:
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
openclaw gateway status --deep
|
||||
```
|
||||
|
||||
Then retry `openclaw workboard dispatch`. Data-only fallback is useful for local
|
||||
state cleanup, but worker runs need a live Gateway.
|
||||
|
||||
### Dispatch Starts Nothing
|
||||
|
||||
Check for at least one `ready` card without an active claim:
|
||||
|
||||
```bash
|
||||
openclaw workboard list --status ready
|
||||
```
|
||||
|
||||
Cards can also be skipped when the same owner already has running or review
|
||||
work. Move completed work to `done`, release stale claims through the Workboard
|
||||
tools, or run dispatch again after the active worker finishes.
|
||||
|
||||
## Related
|
||||
|
||||
- [Workboard plugin](/plugins/workboard)
|
||||
- [CLI reference](/cli)
|
||||
- [Slash commands](/tools/slash-commands)
|
||||
- [Control UI](/web/control-ui)
|
||||
Reference in New Issue
Block a user