claude-task-runner（Claude task runner 开发）

Claude Task Runner

Use the local runner script instead of raw claude -p when the task needs any of these:

• model switching via cc-switch
• durable task state under ~/.openclaw/state/cc-tasks/
• notification on completion/failure
• structured-output enforcement via JSON Schema
• multi-file artifact validation (--expect-file, --expect-contains, --expect-glob)

Primary script:

• /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh

Quick decision

Use this skill when:

• the user asks to run Claude Code non-interactively / in batch / in background
• you need a coding or analysis task to survive beyond a single shell command
• you want the result judged by actual outputs, not just model text
• tmux interaction is unnecessary or risky

Do not use this skill when:

• a direct read / edit is simpler
• the user explicitly wants a live interactive tmux session
• the task needs persistent interactive back-and-forth inside Claude Code

Default workflow

1. Pick the model alias.

- GLM-5.1 for architecture / long-context reasoning - minimax-m2.7 for deeper problem solving and robust headless runs

1. Decide whether the task needs validation.
2. If validation is needed, prefer both:

- structured result validation with --json-schema-file - artifact validation with --expect-file, --expect-contains, --expect-glob

1. Run the task with cc-task-runner.sh run or run-file.
2. Inspect with status, then log if anything looks off.
3. Treat missing artifact or structured_output.status=failure as a real failure.

Command patterns

Minimal run

bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh run \
  "task-name" \
  "GLM-5.1" \
  "/abs/workdir" \
  -- "Your task prompt here"

Write task with permission mode

bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh run \
  "task-name" \
  "GLM-5.1" \
  "/abs/workdir" \
  --permission-mode bypassPermissions \
  -- "Create /abs/workdir/output.txt with content: hello world"

Multi-file validation

All --expect-file, --expect-contains, --expect-glob support repeat usage. --expect-contains binds to the most recent --expect-file before it.

bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh run \
  "multi-check" \
  "GLM-5.1" \
  "/abs/workdir" \
  --permission-mode bypassPermissions \
  --expect-file "/abs/workdir/a.txt" \
  --expect-contains "alpha" \
  --expect-file "/abs/workdir/b.txt" \
  --expect-glob "out/*.log" \
  -- "Create a.txt with 'alpha ok', b.txt with 'bravo ok', and out/run.log"

Meaning:

• a.txt must exist AND contain "alpha"
• b.txt must exist (no content check)
• out/*.log glob must match at least one file

Full combo: schema + multi-file + glob

bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh run \
  "full-check" \
  "GLM-5.1" \
  "/abs/workdir" \
  --permission-mode bypassPermissions \
  --json-schema-file "/abs/schema.json" \
  --expect-file "/abs/workdir/output.txt" \
  --expect-contains "expected text" \
  --expect-glob "logs/*.log" \
  -- "Your task prompt"

Prompt from file

bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh run-file \
  "task-name" \
  "minimax-m2.7" \
  "/abs/workdir" \
  "/abs/prompt.txt" \
  --json-schema-file "/abs/schema.json"

Inspect state

bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh status "task-name"
bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh log "task-name"
bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh list
bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh kill "task-name"
bash /Users/zhengweidong/.openclaw/workspace/scripts/cc-task-runner.sh clean

Validation parameters

Binding order example

--expect-file a.txt \
--expect-contains "hello" \
--expect-contains "world" \   # both "hello" AND "world" checked in a.txt
--expect-file b.txt \          # b.txt just needs to exist
--expect-glob "out/*.csv"      # independent glob check

Validation rules

For tasks that must produce files, always provide at least one artifact check.

Preferred combinations:

• file creation only → --expect-file
• exact or critical content → --expect-file + --expect-contains
• one-or-more generated files → --expect-glob
• non-file report / analysis → --json-schema-file
• implementation task → schema + artifact checks together

Permission mode: Prefer --permission-mode bypassPermissions in trusted local environments when the task must write files or run Bash. Without it, Claude may ask for manual approval and the task will hang.

Do not trust plain language like "已完成" or "done" without validation.

Exit codes

JSON schema guidance

Keep schemas small. Use them to force a machine-checkable result contract.

Good default schema for most tasks:

• status: success|failure
• summary: short text
• files_changed: optional array
• error_category: optional
• suggestion: optional

Model notes

Current local environment supports GLM-5.1 headless via:

• base URL: https://open.bigmodel.cn/api/anthropic
• model id: glm-5.1

The local cc-switch wrapper already special-cases this. Use the alias GLM-5.1, not a raw model id, when calling the runner.

Failure handling

If a task fails:

1. run status
2. run log
3. identify which layer failed:

- model/runtime error (exit 1) - artifact validation failure (exit 2) - structured schema failure (exit 3)

1. either rerun with a stricter prompt or fix the prompt/schema/expectations

If the model says success but artifact validation fails, trust the validator, not the prose.

Files to read when needed

Read these only when you need deeper details:

• references/runner-usage.md for usage notes and patterns
• references/task-schema-example.json for a reusable schema template
• scripts/run-task-example.sh for a concrete invocation pattern