scotthuang/agent-knock-knock

Agent Knock Knock (AKK)

npm
Node.js
License: MIT

Agent Knock Knock 让 OpenClaw、Pi 或 DeepSeek Harness 控制已在 tmux 或 Herdr 中运行的 Codex 和 Claude Code。无需盯着远程终端即可观察工作进展，从聊天中发送下一条指令，并在编码代理完成或需要关注时获得回调。

AKK 从不启动隐藏的替代代理。控制器 Host、人类和 AKK 都使用同一个可见终端和原生编码代理会话。

留在终端中。保持掌控。无需 hooks。无需代理端插件。无需 YOLO。

为 OpenClaw 安装

你需要 OpenClaw 2026.6.5+、Node.js 22.19.0+，以及以同一操作系统用户身份运行且已认证的 codex 或 claude CLI。

openclaw plugins install clawhub:@scotthuang/agent-knock-knock
openclaw gateway restart

在你的项目中启动一个共享的编码代理终端：

cd /absolute/path/to/project
tmux new-session -s akk-work -c "$(pwd -P)" codex

如果偏好使用 claude，可以用它替代 codex。Herdr 用户可参阅 Herdr 快速入门。

在 OpenClaw 中，首先发送：

/akk doctor

在出现 AKK doctor: ready 后，发送一条单独的消息：

/akk inspect this repository and summarize it

这就是完整的首个任务流程。有关终端设置和多窗格，请参阅 tmux 快速入门。直接使用 /akk ... 命令无需更改 OpenClaw 工具策略。

为 Pi 安装

Pi 可以无需 OpenClaw 而作为控制器 Host。当前连接器面向 Pi 0.84.4：

npm install -g @earendil-works/pi-coding-agent@0.84.4
pi install npm:@scotthuang/agent-knock-knock-pi@next
pi

Pi 应显示 AKK ready。在 Codex 或 Claude Code 已在 tmux 或 Herdr 中运行的情况下，输入 /akk list。该连接器提供 /akk、完整的经过能力握手验证的语义工具目录、捆绑的 agent-knock-knock 技能、对发起工作的 Pi 会话的回调，以及原生审批对话框。请参阅 Pi 连接器指南。

为 DeepSeek Harness 安装

该连接器支持 DeepSeek Harness Web 0.1.1-rc.2、0.1.2-alpha.1 和
0.1.5-rc.2：

dsh plugin --profile web add @scotthuang/agent-knock-knock-deepseek-harness@next
dsh web

打开一个 Web 对话并输入 /akk list。该连接器为每个对话提供 /akk、相同的经过能力握手验证的语义工具目录、捆绑的 agent-knock-knock 技能，以及对发起工作的确切 Harness Agent 的回调。请参阅 DeepSeek Harness 连接器指南。

实际效果
AKK 通过 tmux 编排 Claude Code 到 Codex 的交接

OpenClaw 要求 Claude Code 写入一个文件，等待 AKK 报告完成，然后将结果交给 Codex。两个终端都保持可用，供人类直接控制。点击预览查看完整质量的视频。

AKK 为你提供什么

假设已有多个 Codex 或 Claude Code 任务在 tmux 或 Herdr 中运行：

- 无需照看即可监视。 /akk watch  观察已在进行的任务，并在任务完成、需要批准或受阻时发送回调。你可以离开终端，从手机或其他聊天客户端继续。
- 无需在狭小的远程控制台中输入即可发送。 /akk :  将你的自然语言指令发送到选定的实时编码代理终端。用户显式发送优先于过期的 AKK 管理状态。
- 显式识别模糊的 Codex 前台。 当多个 rollout 文件或最近的 /clear 阻止持久归属时，一个已通告的前台识别操作可以检查一个确切的空闲窗格，而无需猜测哪个 rollout 是当前的。
- 通过原生目录切换模型。 /akk models  列出一个确切的物理 Codex 或 Claude Code 窗格当前提供的选项；不需要 Codex rollout/原生线程归属，因此这也可以在第一个 rollout 出现之前工作。/akk set-model ... 消费一个确切通告的模型/推理努力元组，而不接受原始斜杠命令、按键或菜单索引。Codex 将模型和普通努力（直至 max）同步到当前和未来会话的默认值；其 ultra 努力仅限当前会话，而原生 UI 不暴露为未来会话选择的确切非 Ultra 努力，因此 AKK 省略该不可观察字段。Claude Code 仅更改当前会话。
- 仅继续或清除已证实的模型控制残留。 如果一次失败的带配置 Codex 0.154.0/0.155.1 模型控制尝试留下一个确切的 /model 补全面或裸 /model Composer，新的 List 可能同时通告 /akk models  和 /akk repair-model-control 。Models 使用单独的残留绑定权限，将该确切的原生斜杠命令继续到只读目录发现中，而无需重新输入。如果确切的原生选择器已经打开，List 会将窗格标记为非空闲，并仅通告 repair。Repair 仍然是仅用于清理的逃生舱口，从不按 Enter，并且必须证明 Composer 为空。
- 检查和恢复。 /akk status  在回调延迟时显示当前状态。持久回调记录和 Watches 在瞬时 Host 故障后提供恢复路径。
- 刻意批准。 AKK 可以呈现 Codex 或 Claude Code 的权限请求，并提交明确的人工决定。它会保留编码代理现有的权限模式。
- 来回交接控制权。 你可以随时附加到同一个 tmux 或 Herdr 窗格。AKK 不会创建并行的隐藏对话。

常见工作流程是：

/akk list
/akk watch
/akk models
/akk set-model
/akk codex: run the tests and explain any failures
/akk status

如果 List 通告了 repair-model-control，它是一种替代清理流程：

/akk repair-model-control
/akk list
/akk models
/akk set-model

使用来自最新 /akk list 的标识符和操作；不要猜测或缓存终端 ID。模型切换是故障关闭的：同一个确切的物理窗格/进程必须仍然没有活动 Turn 或任何拥有输入的批准、问卷/编辑器或只读查看器，并且必须显示确切的空闲空 Composer 或一个稳定的已配置 Codex 0.154.0/0.155.1 /model 残留。已配置的 Codex 0.154.0/0.155.1 零 rollout 窗格不需要 identify_foreground 或已解析的原生 rollout 身份；Claude Code 仍然需要其确切的当前原生 Session。当 List 为 Composer 残留同时通告这两个操作时，model_options 可以将其继续到目录中，而 repair_model_control 只会清除它。打开的确切选择器是非空闲的，并且只暴露修复。如果继续、修复或模型切换报告 uncertain，请检查窗格，而不是自动重试。

工作原理

OpenClaw / Pi / DeepSeek Harness
│
AKK Host adapter
│
Session · Turn · Watch · Callback
│
tmux / Herdr
│
Codex / Claude Code

对于受管理的 Send，AKK 会验证选定的终端和编码代理进程，写入一个用户请求，监控该确切 Turn，并将完成或关注回调返回给发起 Host 会话。如果陈旧的 AKK 记账在终端输入之前阻止了显式 Codex Send，AKK 可以回退到经过验证的一次性物理 Send，并附加一个只读 Watch 以进行回调和 Status 恢复。

原生 Pi 和 DeepSeek Harness 连接器通过版本化、无密钥的 Host Adapter 能力握手接受共享目录。启动时会根据目录和 Skill 的 SHA-256 摘要验证有序的语义工具注册和捆绑的 Skill；较旧、缺失或漂移的握手会故障关闭，而不是挂载部分工具表面。连接器包版本彼此保持独立。
在当前的 OpenClaw 插件和核心 Host Adapter 中，一个空闲的 Codex 窗格如果前台 rollout 身份不明确，可能会宣告 identify_foreground。该操作会向确切的窗格发出一次封闭的 /status 命令。它不会改变 AKK Store，但会向可见终端输入内容。其 30 秒的结果仅用于诊断，不会授予后续权限。单独的 identify_and_send 操作在探测和一个请求任务期间保持一个终端锁，然后依赖确切的请求接受——而非状态卡片——来确定持久的 Session 和 Turn 身份。普通的 Send、List 和 Status 从不运行此探测。

AKK 是本地优先的：没有托管控制平面或遥测。它只存储路由、生命周期恢复、回调投递和幂等性所需的本地状态。

兼容性

| 组件 | 支持的边界 |
| --- | --- |
| 终端宿主 | tmux；本地 Herdr 0.8.0 协议 19 |
| 编码代理 | Codex 和 Claude Code；允许未知的完整版本，但会给出兼容性警告，如果行为发生变化则会自然失败 |
| OpenClaw | 2026.6.5+；插件 API 和 Gateway 2026.5.12+ |
| Pi 连接器 | Pi 0.84.4 |
| DeepSeek Harness 连接器 | 0.1.1-rc.2、0.1.2-alpha.1 和 0.1.5-rc.2 |
| 运行时 | macOS 或 Linux 上的 Node.js 22.19.0+ |

相邻的 OpenClaw 边界 2026.5.10-beta.2 有意不受支持。Herdr 支持是精确版本，因为其本地控制协议尚未成为稳定的公共 API。有关各连接器经过测试的发布状态和限制，请参阅各自的连接器指南。

文档

选择与您要执行的操作相匹配的指南：

| 指南 | 用途 |
| --- | --- |
| tmux 快速开始 | 首个 OpenClaw 任务、多个窗格和选择器 |
| Herdr 快速开始 | 本地 Herdr 发现和精确版本检查 |
| Pi 连接器 | Pi 安装、语义工具目录、捆绑技能、原生审批、回调、升级和卸载 |
| DeepSeek Harness 连接器 | Harness 安装、审批契约、回调、升级和故障排除 |
| 操作员指南 | 完整命令参考、可靠的 Send、Watch、Status、审批、恢复、Sessions 和原生线程 |
| OpenClaw 操作 | npm 替代方案、配置、自动审批策略、监督器行为和故障排除 |
| Host Bridge 和 Profiles | 通过 MCP/stdio 和声明式 Profile 连接另一个控制器 Host |
| 终端交接协议 | 身份、Turn 生命周期、回调保证、安全围栏和交接语义 |
| 存储和日志记录 | 状态目录、权限、协议迁移、日志和隐私 |
| 测试 | 测试层级、架构检查和证据工作流 |
| 贡献指南 | 本地开发与贡献工作流 |

安装替代方案

偏好使用 npm 的 OpenClaw 用户可以直接安装同一个核心包：

npm install -g @scotthuang/agent-knock-knock
agent-knock-knock install-openclaw --verify

ClawHub 仍是推荐的 OpenClaw 安装途径。请勿将两种变体安装到同一个 OpenClaw 配置文件中。

要在本地构建仓库：

npm install
npm run build
npm run test:fast

连接器开发需在仓库根目录运行 npm run pi:build，或执行 cd connectors/pi && npm run build；DeepSeek Harness 有对应的 npm run deepseek:build 脚本。

安全与隐私

AKK 会控制终端，因此请将安装视为特权本地自动化操作。请使用非特权操作系统账户，限制 tmux 和 Herdr 套接字，保持状态目录私有，并在允许输入前审查审批提示。AKK 不会削弱 Codex 或 Claude Code 的权限，面向模型的工具永远不会收到终端控制令牌、回调凭据、Composer 文本或审批指纹。

请通过 GitHub 安全公告 私下报告漏洞。请勿在公开 issue 中包含机密信息、私有终端输出或凭据。

许可证

MIT