clawed-tty-agent

将 Claude Code CLI 封装为 A2A 协议的 agent 服务。其他 agent 或调用方通过标准 A2A JSON-RPC 协议提交编码任务，本 agent 调用 Claude Code 执行并返回结果。

安装

# 从私有 registry 安装
knpm install -g clawed-tty-agent

# 或从公开 npm 安装（发布后可用）
npm install -g clawed-tty-agent

双模式架构

通过环境变量 REGISTRY_URL 切换运行模式：

| | Standalone 模式 | Proxy 模式 | |---|---|---| | 触发条件 | 无 REGISTRY_URL | 设置 REGISTRY_URL | | 接收任务 | 自建 Express，接收 HTTP POST | 连接 Registry WebSocket，接收推送 | | 适用场景 | 本地开发、直连测试 | 容器部署、NAT 环境 | | 协议格式 | 标准 A2A JSON-RPC | 标准 A2A JSON-RPC |

两种模式的请求体格式完全一致，调用方无需感知 agent 的运行模式。

Standalone: 调用方 → HTTP POST → Agent Express → ClaudeCodeExecutor
Proxy:      调用方 → Registry REST → Registry WS → Agent → ClaudeCodeExecutor

Agent ID 格式

Proxy 模式下，agent 使用稳定的 ID，重启后复用：

tty-{workspaceId}-{workDirHash}

• Docker 容器: workspaceId = docker-{WORKSPACE_ID}
• 物理机: workspaceId = {os}-{ipHash}

示例：

• Docker 容器: tty-docker-task123-a1b2c3d4
• 本地 Linux: tty-linux-e5f6g7h8i9j1-a1b2c3d4
• 本地 Windows: tty-windows_nt-9i0j1k2l-a1b2c3d4

快速开始

Standalone 模式

cd /path/to/project
clawed-tty-agent

# 或指定端口
PORT=4001 clawed-tty-agent

启动后输出：

🤖  Claude Code A2A Agent (standalone mode)
    URL:         http://localhost:4000/
    Agent Card:  http://localhost:4000/.well-known/agent-card.json

Proxy 模式

cd /path/to/project
REGISTRY_URL=http://localhost:5001 clawed-tty-agent

启动后输出：

🤖  Claude Code A2A Agent (proxy mode)
    Agent ID:    tty-linux-e5f6g7h8i9j1-a1b2c3d4
    Registry:    http://localhost:5001
    WebSocket:   ws://localhost:5001/ws
    Connecting...

    Registered:  agentId=tty-linux-e5f6g7h8i9j1-a1b2c3d4

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | REGISTRY_URL | - | Registry URL，设置后进入 Proxy 模式 | | WORK_DIR | 当前目录 | Claude Code 工作目录 | | AGENT_ID | 自动生成 | 手动指定 Agent ID | | AGENT_NAME | 目录名 | Agent 显示名称 | | WORKSPACE_ID | - | Docker workspace ID（由 workspace skill 设置） | | PORT | 4000 | Standalone 模式监听端口 | | HOST | localhost | Standalone 模式监听地址 | | CLAUDE_BIN | claude | Claude Code CLI 路径 | | ALLOWED_TOOLS | 全部 | 逗号分隔的允许工具列表 | | PERMISSION_MODE | acceptEdits | 权限模式：default/acceptEdits/auto |

Docker 部署

通过 workspace skill 在容器内部署：

1. workspace skill 创建容器，设置 WORKSPACE_ID 环境变量
2. 安装 agent: npm install -g clawed-tty-agent
3. 运行 agent: REGISTRY_URL=http://registry:5001 clawed-tty-agent

A2A 协议

支持以下 A2A JSON-RPC 方法：

message/send

提交编码任务。

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "msg-001",
      "role": "user",
      "parts": [{"kind": "text", "text": "Add error handling to src/api.ts"}]
    }
  }
}

tasks/get

查询任务状态。

tasks/cancel

取消正在执行的任务。

源码结构

src/
├── index.ts            # 入口：模式选择、Express 服务、WS 客户端
├── executor.ts         # ClaudeCodeExecutor：A2A AgentExecutor 实现
├── claude-runner.ts    # ClaudeCodeRunner：node-pty 封装 Claude Code CLI
├── claude-types.ts     # Claude Code stream-json 事件类型定义
└── simple-event-bus.ts # 轻量 ExecutionEventBus

License

MIT