Persistent Code Terminal

persistent-code-terminal

OpenClaw 的持久化编码终端。它为每个项目创建一个独立的 tmux 会话：

-code-session

该设计使以终端为中心的 AI 编程（如 Codex CLI / Claude Code / 任意 CLI 工具）更加可靠，并具备移动端/SSH 友好性：

• 可随时 detach/reattach，不丢失输出
• 跨轮次保持 Shell 状态
• 持续运行长期任务（例如开发服务器、watch 模式等）

OpenClaw 自然语言路由

当用户意图是“在此仓库中使用自然语言驱动 Codex CLI”时，应优先通过本技能进行路由。

智能自动触发机制：

• 路由开关：openclaw.config.dev.autoCodeRouting（默认值为 false）

• 若启用，则将编码工作流消息交由以下脚本处理：

  • {baseDir}/bin/persistent-code-terminal-route.sh ""

• 该路由脚本执行如下逻辑：

  • 意图识别：检测是否属于代码变更 / 修复 / 测试 / 构建 / 提交 / 推送 / Codex 相关表述
  • 安全过滤：仅允许在 Git 仓库中执行含明确动作动词的指令；若用户输入包含 不要执行，只分析，则跳过执行

  • 执行链路：

    • persistent-code-terminal-auto.sh --max-retries 3 --instruction ""
    • persistent-code-terminal-summary.sh --lines 120
  • 依赖缺失兜底：若缺少 tmux 或 codex 等依赖，自动调用 doctor 提供诊断与引导建议

多项目路由支持：

• 单条消息可包含多个项目任务，任务之间可用换行符 / ； / ; 分隔

• 支持的任务格式包括：

  • 给项目
  • 给项目：
  • 为修复/增加/修改 ...
  • 项目 ...；项目 ...

• 各项目任务按顺序串行执行：

  • start.sh --project
  • auto.sh --max-retries 3 --instruction ""
  • summary.sh --lines 120 --json
• 对于无效或未知项目的任务，仅标记为失败，不影响其余任务执行

快捷触发方式（推荐）：

• 若用户消息以 codex 开头，则将剩余文本作为指令处理

• 执行：

  • {baseDir}/bin/persistent-code-terminal-codex-exec.sh ""

• 并随后报告状态：

  • {baseDir}/bin/persistent-code-terminal-status.sh
  • {baseDir}/bin/persistent-code-terminal-summary.sh --lines 120

聊天驱动场景下的推荐执行模式：

• start.sh（或由 send.sh 隐式自动创建会话）
• 使用 codex-exec.sh "" 进行 Codex 驱动的工作
• 使用 status.sh / summary.sh 进行简洁的状态汇报

若用户说“检查项目/继续会话/跑测试并总结”，请直接调用本技能对应脚本，无需让用户手动输入冗长的 Shell 命令。

核心模型（必须遵循）

start → send → read → decide

1) 启动/确保会话存在：

• {baseDir}/bin/persistent-code-terminal-start.sh

2) 发送单条命令：

• {baseDir}/bin/persistent-code-terminal-send.sh ""

  • 命令执行完成后会在 pane 中追加哨兵标记：__PCT_EXIT_CODE__N
  • 支持参数：--timeout、--dry-run、--phase

3) 读取输出：

• {baseDir}/bin/persistent-code-terminal-read.sh

  • 解析最新哨兵标记，并更新 .pct-state.json

4) 快速检查状态（可选）：

• {baseDir}/bin/persistent-code-terminal-status.sh
• {baseDir}/bin/persistent-code-terminal-summary.sh --lines 120
• {baseDir}/bin/persistent-code-terminal-doctor.sh
• {baseDir}/bin/persistent-code-terminal-list.sh（列出所有 *-code-session 会话）
• {baseDir}/bin/persistent-code-terminal-switch.sh --project

状态文件：

• .pct-state.json（位于当前项目目录下）
• 字段包括：projectDir、session、lastCommand、lastExitCode、phase、updatedAt

结构化输出支持：

• {baseDir}/bin/persistent-code-terminal-read.sh --json
• {baseDir}/bin/persistent-code-terminal-summary.sh --json
• {baseDir}/bin/persistent-code-terminal-auto.sh --json

Codex 优先工作流（单次执行）

若系统已安装 codex CLI，推荐使用：

• {baseDir}/bin/persistent-code-terminal-codex-exec.sh ""

• 默认行为等价于：

  • codex exec --full-auto --sandbox workspace-write --cd""

• 可在指令前传入额外参数：

  • {baseDir}/bin/persistent-code-terminal-codex-exec.sh --json -o /tmp/codex.json ""
• 设置环境变量 PCT_CODEX_NO_DEFAULT_FLAGS=1 可禁用默认参数

示例：

• {baseDir}/bin/persistent-code-terminal-codex-exec.sh "Implement feature X. Ensure build and tests pass. Commit and push to current branch. Do NOT force push."

安全规范

• 除非用户明确要求，否则禁止执行 git push --force
• 禁止将密钥等敏感信息暴露在终端输出中
• 优先使用特性分支（feature branch）；除非用户明确指定，否则禁止直接向 main / master 分支推送
• 对涉及网络或特权操作（例如 git push），须严格遵守当前生效的 Codex 审批策略与 sandbox 策略