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
2. Decide whether the task needs validation.
3. If validation is needed, prefer both:
   • structured result validation with --json-schema-file
   • artifact validation with --expect-file, --expect-contains, --expect-glob
4. Run the task with cc-task-runner.sh run or run-file.
5. Inspect with status, then log if anything looks off.
6. Treat missing artifact or structured_output.status=failure as a real failure.

Command patterns#

Minimal run#

bash

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

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

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

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

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

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#

ParameterRepeatableBinds toDescription--expect-file <path>✅ yesselfFile must exist after task--expect-contains <text>✅ yesprevious --expect-fileThat file must contain text--expect-glob <pattern>✅ yesselfGlob must match ≥1 file--json-schema-file <file>❌ noselfEnforces structured output--permission-mode <mode>❌ noselfbypassPermissions or acceptEdits``--fallback-model <alias>❌ noselfRetry with this model on failure--max-retries <n>❌ noselfMax retry attempts (default: 1)

Binding order example#

bash

--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#

CodeMeaning0Task completed, all validations passed1Model/runtime error2Artifact validation failed3Structured output reported failure

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)
4. 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