XMethues/clawchat-plugin-connect

ClawChat Connect
从 ClawChat 运行本地编码代理 Runtime，并在你选择时使用独立管理的 Web App。

ClawChat Connect 是一个本地 Core 服务和 Plugin 宿主。Core 负责 Agent Binding、ClawChat 传输、Workspace 和 Connect Session 记录、Runtime 调度、Plugin 生命周期以及命令行管理。Runtime Plugin 负责其原生运行时协议。Managed Web App Plugin 负责完整的 Web 产品。可选的 Liveware Plugin 将选定的 App 暴露给其 Binding；Core 不会附带或提供无条件的浏览器应用程序。

产品模型

| 产品 | 所有者 | 边界 |
| --- | --- | --- |
| Connect Core | clawchat-connect | Agent Binding、ClawChat 传输、Workspace/Session 记录、Plugin 权限、CLI 恢复。 |
| Runtime Plugin | 确切安装的 Plugin 能力 | Runtime 进程/协议、原生登录、模型、工具、审批以及原生 Thread 存储。 |
| Managed Web App | 其 Provider Plugin | Web 服务器、浏览器资源/协议、身份验证、Web Session、Interaction、重连行为以及呈现。 |
| Web App Exposure | 官方 clawling.exposure.liveware Plugin | 对不透明租用环回 App 上游的一次私有 Binding 发布。 |

这些是相互独立的产品。Runtime 可以在其选定的 App 不可用时保持健康，而 App 也可以在 Binding Runtime 停止时保持健康。Connect 绝不会将这些健康域表示为单一状态。

不存在跨产品的 Session 连续性承诺。一个 ClawChat Connect Session、dsh web Session、opencode web Session 以及可选的 Connect Client Session 可能引用同一个仓库，但仍具有独立的身份验证、历史记录、Interaction 状态和重连行为。Connect 不会在它们之间复制对话或工具上下文。

Managed Web App 选择

选择是确定且精确的：

1. 如果 Binding 的确切 Runtime 能力声明了原生 Managed Web App，则选择它。
2. 否则，选择一个已安装的兼容 Managed Web App，该 App 明确指定了确切的 pluginId 和 capabilityId。
3. 否则，该 Binding 没有 App。

临时不可用绝不会改变选择，也绝不会触发兼容性代理、回退页面或隐藏的 Client 端点。

官方映射：

| Runtime 能力 | 选定的 App |
| --- | --- |
| clawling.runtime.deepseek-harness/deepseek-harness | 原生 DSH Web（dsh web）。 |
| clawling.runtime.opencode/opencode | 原生 OpenCode Web（opencode web）。 |
| Codex 以及两个 WorkBuddy 能力 | 可选的 clawling.web.connect-client/connect-client，仅当该完整 Plugin 被明确安装时。 |
仅 CLI 安装是有效的。运行时设置和 Agent Binding 激活绝不会隐式安装可选的 Connect Client Plugin。对于未选择任何 App 的 Binding，Liveware 不会发布任何内容。

要求

当前 beta 归档支持 Apple 芯片上的 macOS。你需要一个 ClawChat 账户、一个 Agent 邀请码，以及至少一个可用且已认证的受支持运行时。DeepSeek Harness 不需要全局安装 DSH：其官方 Web Provider 和 Binding Runtime 在可用时会使用显式配置或安装的 dsh，否则会通过第一个可用的受支持包启动器（先是 bunx，然后是 npx，再是 pnpm dlx）启动 @deepseek-ai/dsh。所选的启动器可能会填充其用户缓存。Connect 不会对 DSH 进行认证或重新配置，也不会安装、升级、认证或重新配置 Codex、OpenCode 或 WorkBuddy。

快速开始

安装 Core

curl -fsSL https://raw.githubusercontent.com/XMethues/clawchat-plugin-connect/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

安装程序会根据 checksums.txt 验证发布归档，安装 Core、官方 Plugin Bundles、skills 和 notices，并移除过时的根级 liveware 和 clawchat-connect-client 载荷。归档可以包含或省略可选的 Connect Client Plugin，并且仍然有效。浏览器资源（如果存在）仅存在于该受完整性保护的 Plugin Bundle 内。

当前 beta 指针为 release-channel/latest-beta.txt。固定某个发布版本：

curl -fsSL https://raw.githubusercontent.com/XMethues/clawchat-plugin-connect/main/install.sh | sh -s -- v0.1.0-beta.9

初始化并安装 Runtime Plugin

clawchat-connect init

choose one or more exact Runtime Plugins
clawchat-connect plugin setup --non-interactive --select clawling.runtime.codex
clawchat-connect agent add work --plugin clawling.runtime.codex --capability codex
clawchat-connect activate work YOUR_INVITE_CODE

clawchat-connect service install
clawchat-connect service status
clawchat-connect doctor

等效的 Runtime 选择包括 clawling.runtime.opencode/opencode、clawling.runtime.deepseek-harness/deepseek-harness，以及受支持的 WorkBuddy 能力。Runtime 配置属于确切能力的 schema：

clawchat-connect agent add work \
--plugin clawling.runtime.opencode \
--capability opencode \
--runtime-config-json '{"serverUrl":"http://127.0.0.1:4096"}'

plugin setup 在可用时通过正在运行的 Plugin Manager 工作。在服务停止的情况下，CLI 可以直接安装所选发布版本捆绑的 Plugin。此无头路径是恢复和管理边界；不需要 Web App。

可选兼容的 Connect Client

仅当需要 Codex 或 WorkBuddy 浏览器管理时，才在单独的显式操作中安装它：

clawchat-connect plugin setup --non-interactive --select clawling.web.connect-client
Connect 客户端 Bundle 包含其完整的服务器入口、完整的浏览器图，以及覆盖每个辅助浏览器资产的规范完整性清单。它可独立于 Core 和 Runtime Plugins 移除。Client Extensions 以精确的 Managed Web App 为目标，通过 managedWebApp.pluginId 加上 managedWebApp.capabilityId 指定；它们的作用域为 App，从不是安装全局的。

可选的私有 Liveware 暴露

clawchat-connect plugin setup --non-interactive --select clawling.exposure.liveware

Liveware 是 Web App Exposure，不是 Client，也不是 Runtime。对于每个符合条件的已激活 Binding，它发布已选定的 Managed Web App。每个 Binding 拥有独立的私有 ClawChat App、隧道、注册和退役状态。

Provider 仅返回精确的环回 HTTP 上游。Core 对其进行验证，将其与已提交的 Plugin Activation Generation 关联，并向 Liveware 授予租约。Provider 拥有的原生作用域决定 Managed Web App Instance 键，因此多个 Binding 可以租用一个 Instance。释放最后一个租约会停止它。过期的 generation 无法获取、续订或发布 Instance。选定的 Provider 永远不会收到 ClawChat 凭据或转发的 Liveware 主体。

工作区和会话

clawchat-connect workspace add work /absolute/path/to/project
clawchat-connect workspace list work

Core Sessions 保持固定于一个 Agent Binding、精确的 Runtime capability 和 Workspace。Runtime 原生 Thread ID 保持对 Runtime Adapter 私有。在 ClawChat 中，根据精确 Runtime 的支持情况，使用 /new、/workspace、/sessions、/switch、/model、/mode、/cancel 和 /status。

打开原生或兼容的 Web App 不会恢复 ClawChat Connect Session。请根据该产品自身的 Session 和身份验证模型在该产品中继续工作。

操作和恢复

clawchat-connect service status
clawchat-connect doctor
clawchat-connect plugin list
clawchat-connect agent list
clawchat-connect workspace list work

按以下顺序操作：

1. 检查 Core 服务和 ClawChat Binding 健康状况。
2. 检查精确的 Runtime capability 及其原生依赖。
3. 检查 Managed Web App 选择和 Instance 健康状况。
4. 单独检查 Binding 的 Liveware Publication。

App 故障不会停止 Runtime 轮次。Runtime 故障不会授权重新选择 App。Publication 故障不会改变上述任何一项。如果 Web App 不可用，请使用 CLI 检查、安装、启用、禁用或替换 Plugins，并修复 Bindings；Core 不暴露任何秘密回退 Web 管理端点。

安全边界

- Plugin 安装是受信任的进程内代码执行。仅安装经过审查的 Bundles 并验证来源。
- 官方发布归档在解压前进行 SHA-256 校验。官方 Plugin 入口产物和辅助资产通过 SHA-256 SRI 固定到发布版本。
- 受管理的 Web App 上游必须是精确的环回 HTTP 源。用户提供的端点以及 LAN/原生上游均会被拒绝。
- Liveware 仅接收不透明的上游租约。Core 保留 Plugin 权限、Activation Generation 隔离、Binding 凭据以及受管理资源的退役。
- 受管理的 Web App 拥有自己的身份验证。Core 不会向其中注入 ClawChat 身份、Cookie、凭据或 Session 状态。
- 私有 Liveware 发布仍仅限所有者，但所暴露的 App 保留其自身的安全模型。
- 即使未安装任何 App，CLI 管理仍然可用，并且是修复损坏 Web 产品的恢复途径。

参见安装指南、架构、运行时适配器契约和插件编写。

插件作者契约

一个完整的受管理 Web App 能力声明：

- 类型 managed-web-app 以及当前能力接口版本；
- 要么为同一 Plugin 原生所有权提供 nativeRuntimeCapabilityIds，要么提供精确的 compatibleRuntimes 引用；
- 一个由 App 拥有的 Provider，用于生成稳定的原生作用域 Instance 键；
- 一个精确的环回上游，以及就绪、健康、释放和最终租约关闭行为；
- 其 Bundle 内完整的服务器和浏览器资产，且所有辅助资产均受完整性覆盖；
- 若支持，App 作用域的 Client Extensions，由所选 App 图和 Activation Generation 隔离。

不要代理另一个产品，不要仅为减少进程数量而重用 Binding Runtime，不要声称 Session 连续性，不要接受未受管理的端点，也不要暴露不完整的浏览器负载。

开发与发布

bun install
bun run dev
bun run check
bun run build

bun run build 会在 dist/src 下生成 Core，并在 dist/official-plugins 下生成官方 Bundle；它不会将 dist/client 作为根包负载发布。官方 DSH 和 OpenCode Bundle 包含其原生受管理 Web App 贡献。可选的 Connect Client Bundle 包含其完整的浏览器图。发布归档按原样复制 Bundle 目录，因此无论是否包含可选 Client，合格归档均有效。

匹配 v-beta. 的版本标签会运行测试版发布工作流。该工作流会发布归档、安装程序支持文件、校验和、发布说明以及 release-channel/latest-beta.txt 指针。本地已安装产品的资格验证是可选的，不会阻止打标签。

许可证

MIT