Claude Code Skill
Delegate coding tasks to the Claude Code CLI via background process with PTY or headless pipe mode.
PTY Mode Required (Interactive)
Claude Code is an interactive terminal application that needs a pseudo-terminal (PTY). Without PTY, output breaks or the agent hangs.
Always use pty:true for interactive mode:
CODEBLOCK0
Two Modes
1. Interactive PTY Mode
For tasks where Claude Code may ask confirmations, need input, or show permission prompts.
CODEBLOCK1
2. Headless Pipe Mode
For automation, scripting, CI-like usage. Uses -p flag for non-interactive.
CODEBLOCK2
Exec & Process Tool Reference
Exec Tool Parameters
| Parameter | Type | Description |
|---|
| INLINECODE2 | string | The shell command to run |
| INLINECODE3 |
boolean |
Required for interactive mode! Allocates a pseudo-terminal |
|
workdir | string | Working directory (agent sees only this folder's context) |
|
background | boolean | Run in background, returns sessionId for monitoring |
|
timeout | number | Timeout in seconds (default: 1800+ for real tasks) |
|
elevated | boolean | Run on host instead of sandbox (if allowed) |
Process Tool Actions (for background sessions)
| Action | Description |
|---|
| INLINECODE8 | List all running/recent sessions |
| INLINECODE9 |
Check if session is still running |
|
log | Get session output (with optional offset/limit) |
|
write | Send raw data to stdin |
|
submit | Send data + newline (like typing and pressing Enter) |
|
send-keys | Send key tokens or hex bytes |
|
paste | Paste text (with optional bracketed mode) |
|
kill | Terminate the session |
Key CLI Flags
| Flag | Purpose |
|---|
| INLINECODE16 | Non-interactive pipe mode (headless) |
| INLINECODE17 |
Structured JSON output (headless only) |
|
--output-format stream-json | Real-time streaming output (headless only) |
|
--resume [SESSION_ID] | Resume by ID, or open interactive picker with optional search term |
|
--continue | Continue the latest session |
|
--fork-session | Create new session ID when resuming (use with
--resume or
--continue) |
|
--from-pr [value] | Resume session linked to a PR by number/URL |
|
--allowedTools 'Bash,Read,Edit,Write,Glob,Grep' | Restrict available tools |
|
--permission-mode acceptEdits | Auto-accept edits, prevents prompt stalls |
|
--permission-mode plan | Read-only exploration mode (no writes) |
|
--dangerously-skip-permissions | Full auto, no guardrails (⚠️ DANGER) |
|
--max-budget-usd N | Spend cap for automation safety |
|
--json-schema '<schema>' | Structured output validation (with
-p) |
|
--append-system-prompt '...' | Add to base prompt (doesn't replace) |
|
--system-prompt '...' | Replace entire system prompt |
|
--agents '<json>' | Inline dynamic subagent definitions |
|
--model <model> | Override model (sonnet, haiku, opus) |
|
--add-dir <path> | Add extra directory to context |
Permission Modes
| Mode | Behavior |
|---|
| INLINECODE37 | Ask per operation |
| INLINECODE38 |
Auto-accept file edits (recommended for background tasks) |
|
plan | Read-only exploration, no writes |
|
dontAsk | Auto-deny unless pre-approved |
|
bypassPermissions | Skip all permission prompts (⚠️ same effect as
--dangerously-skip-permissions) |
System Prompt Modes
| Flag | Behavior |
|---|
| INLINECODE43 | Adds to the default system prompt — Claude Code keeps its built-in instructions |
| INLINECODE44 |
Replaces the entire system prompt — Claude Code loses all default behavior |
Use --append-system-prompt to add context or constraints. Use --system-prompt only when you need full control over the prompt (rare).
Granular Tool Restrictions
Restrict Claude Code's Bash tool to specific subcommands:
CODEBLOCK3
Session Continuity
Track and resume sessions across conversations.
CODEBLOCK4
HANDOFF.md Pattern (Long Sessions)
For tasks that exceed context limits, write progress to a handoff file:
CODEBLOCK5
Patterns
Quick Start: One-Shot Task
CODEBLOCK6
Background Task with Monitoring
CODEBLOCK7
PR Review (Safe — Never in Live Workspace)
⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!
CODEBLOCK8
Parallel Issue Fixing with Git Worktrees
CODEBLOCK9
Fan-Out Pattern (Bulk Operations)
Distribute work across parallel headless invocations:
CODEBLOCK10
Writer/Reviewer Pattern (Dual Sessions)
Two parallel sessions — one implements, one reviews:
CODEBLOCK11
Inline Dynamic Subagents
Define agents without any files on disk:
CODEBLOCK12
Auto-Notify on Completion
For long-running background tasks, append a wake trigger so OpenClaw gets notified immediately:
CODEBLOCK13
Progress Updates
When spawning background agents, keep the user informed:
- - Send 1 short message on start (what's running + where)
- Update only on changes: milestone complete, agent needs input, error, or finish
- If killing a session, say why immediately
- Never let the user see "Agent failed" with zero context
Safety Rules
- 1. Always use
pty:true for interactive mode - Use
--permission-mode acceptEdits for background tasks to prevent prompt stalls - Never run in
~/.openclaw/ workspace - Never checkout branches in live OpenClaw project dir
--dangerously-skip-permissions gets explicit danger warning — prefer INLINECODE51- Respect user's tool choice — don't silently take over if agent fails
- Be patient — don't kill sessions because they're "slow"
- Budget cap automation — use
--max-budget-usd for unattended headless runs - Max 3-4 active sessions — more causes resource contention
- Timeout guidance — use 1800s+ for real tasks, don't let timeouts kill mid-work
Claude Code 技能
通过后台进程使用 PTY 或无头管道模式，将编码任务委托给 Claude Code CLI。
需要 PTY 模式（交互式）
Claude Code 是一个交互式终端应用程序，需要伪终端（PTY）。没有 PTY，输出会中断或代理会挂起。
始终使用 pty:true 进行交互模式：
bash
✅ 正确 - 带 PTY
exec pty:true command:claude 你的提示词
❌ 错误 - 无 PTY，代理可能中断
exec command:claude 你的提示词
两种模式
1. 交互式 PTY 模式
适用于 Claude Code 可能需要确认、需要输入或显示权限提示的任务。
bash
前台（等待完成）
exec pty:true workdir:~/project command:claude 添加深色模式切换
后台（返回 sessionId）
exec pty:true workdir:~/project background:true command:claude 为待办事项构建 REST API
2. 无头管道模式
适用于自动化、脚本编写、类似 CI 的用法。使用 -p 标志实现非交互式。
bash
简单的一次性任务
exec command:claude -p 解释 src/main.ts 的作用 --output-format json
带结构化输出验证
exec command:claude -p 列出 src/ 中所有导出的函数 --output-format json --json-schema {\type\:\object\,\properties\:{\functions\:{\type\:\array\,\items\:{\type\:\string\}}}}
预算上限自动化
exec command:claude -p 重构认证模块 --max-budget-usd 5.00 --output-format json
实时流式输出（JSON 块实时到达）
exec command:claude -p 构建一个辅助函数 --output-format stream-json
Exec 和 Process 工具参考
Exec 工具参数
| 参数 | 类型 | 描述 |
|---|
| command | string | 要运行的 shell 命令 |
| pty |
boolean |
交互模式必需！ 分配伪终端 |
| workdir | string | 工作目录（代理只能看到此文件夹的上下文） |
| background | boolean | 在后台运行，返回 sessionId 用于监控 |
| timeout | number | 超时时间（秒）（实际任务默认 1800+） |
| elevated | boolean | 在主机上运行而非沙箱（如果允许） |
Process 工具操作（用于后台会话）
| 操作 | 描述 |
|---|
| list | 列出所有运行中/最近的会话 |
| poll |
检查会话是否仍在运行 |
| log | 获取会话输出（可选偏移量/限制） |
| write | 发送原始数据到 stdin |
| submit | 发送数据 + 换行（如打字后按回车） |
| send-keys | 发送按键令牌或十六进制字节 |
| paste | 粘贴文本（可选括号模式） |
| kill | 终止会话 |
关键 CLI 标志
| 标志 | 用途 |
|---|
| -p | 非交互式管道模式（无头） |
| --output-format json |
结构化 JSON 输出（仅无头模式） |
| --output-format stream-json | 实时流式输出（仅无头模式） |
| --resume [SESSION_ID] | 按 ID 恢复，或打开交互式选择器（可选搜索词） |
| --continue | 继续最新会话 |
| --fork-session | 恢复时创建新会话 ID（与 --resume 或 --continue 一起使用） |
| --from-pr [value] | 恢复链接到 PR 的会话（按编号/URL） |
| --allowedTools Bash,Read,Edit,Write,Glob,Grep | 限制可用工具 |
| --permission-mode acceptEdits | 自动接受编辑，防止提示卡住 |
| --permission-mode plan | 只读探索模式（不写入） |
| --dangerously-skip-permissions | 完全自动，无防护（⚠️ 危险） |
| --max-budget-usd N | 自动化安全支出上限 |
| --json-schema
| 结构化输出验证（与 -p 一起使用） |
| --append-system-prompt ... | 添加到基础提示词（不替换） |
| --system-prompt ... | 替换整个系统提示词 |
| --agents | 内联动态子代理定义 |
| --model | 覆盖模型（sonnet、haiku、opus） |
| --add-dir | 添加额外目录到上下文 |
权限模式
| 模式 | 行为 |
|---|
| default | 每次操作询问 |
| acceptEdits |
自动接受文件编辑（推荐用于后台任务） |
| plan | 只读探索，不写入 |
| dontAsk | 除非预先批准，否则自动拒绝 |
| bypassPermissions | 跳过所有权限提示（⚠️ 与 --dangerously-skip-permissions 效果相同） |
系统提示词模式
| 标志 | 行为 |
|---|
| --append-system-prompt ... | 添加到默认系统提示词 — Claude Code 保留其内置指令 |
| --system-prompt ... |
替换整个系统提示词 — Claude Code 失去所有默认行为 |
使用 --append-system-prompt 添加上下文或约束。仅在需要完全控制提示词时使用 --system-prompt（很少见）。
细粒度工具限制
将 Claude Code 的 Bash 工具限制为特定子命令：
bash
exec pty:true command:claude --allowedTools Bash(git:,npm:),Read,Edit,Write,Glob,Grep 你的任务
会话连续性
跨对话跟踪和恢复会话。
bash
启动任务
exec pty:true workdir:~/project background:true command:claude --permission-mode acceptEdits 构建功能 X
继续最新会话
exec pty:true workdir:~/project command:claude --continue
按 ID 恢复特定会话
exec pty:true workdir:~/project command:claude --resume abc123
带交互式搜索恢复（查找匹配该词的会话）
exec pty:true workdir:~/project command:claude --resume 认证模块
恢复时分支（创建新会话 ID，保留原始会话）
exec pty:true workdir:~/project command:claude --continue --fork-session
恢复链接到 PR 的会话
exec pty:true workdir:~/project command:claude --from-pr 130
列出最近会话（查找会话 ID）
exec command:claude sessions list
HANDOFF.md 模式（长会话）
对于超出上下文限制的任务，将进度写入交接文件：
bash
在 Claude Code 会话中，要求它写入进度
然后启动新会话，从交接文件继续
exec pty:true workdir:~/project command:claude 读取 HANDOFF.md 并继续其中描述的工作
模式
快速开始：一次性任务
bash
前台带 PTY
exec pty:true workdir:~/project command:claude --permission-mode acceptEdits 为 API 调用添加错误处理
无头一次性任务
exec command:claude -p 总结代码库结构 --output-format json
带监控的后台任务
bash
1. 启动
exec pty:true workdir:~/project background:true timeout:3600 command:claude --permission-mode acceptEdits 构建一个完整的带 JWT 令牌的认证模块
2. 监控
process action:log sessionId:XXX
process action:poll sessionId:XXX
3. 如果需要，发送输入
process action:submit sessionId:XXX data:yes
4. 如果卡住，终止
process action:kill sessionId:XXX
PR 审查（安全 — 绝不在实时工作区中）
⚠️ 关键：绝不在 OpenClaw 自己的项目文件夹
