# kiro-telegram-acp

Adopt this skill: https://proskills.md/skills/other/masami-agent-openclaw-kiro-telegram-acp-skill-skill-src-kiro-telegram-acp

Page: https://proskills.md/skills/other/masami-agent-openclaw-kiro-telegram-acp-skill-skill-src-kiro-telegram-acp
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill-src/kiro-telegram-acp/SKILL.md
size: 8010
upstream: https://github.com/masami-agent/openclaw-kiro-telegram-acp-skill/blob/main/skill-src/kiro-telegram-acp/SKILL.md

```text
---
name: kiro-telegram-acp
description: "Relay Telegram /kiro commands to a downstream Kiro agent via OpenClaw hook. Use when setting up a Telegram-to-Kiro relay, configuring hook-based message routing, or packaging an agent integration as an OpenClaw skill."
homepage: https://github.com/masami-agent/openclaw-kiro-telegram-acp-skill
metadata:
  {
    "openclaw":
      {
        "emoji": "🤖",
        "requires": { "bins": ["openclaw"] },
        "install":
          [
            {
              "id": "npm",
              "kind": "npm",
              "package": "openclaw",
              "bins": ["openclaw"],
              "label": "Install OpenClaw (npm)",
            },
          ],
      },
  }
---

# Kiro Telegram ACP

## Overview

Implement a lightweight relay pattern: capture `/kiro` commands in an OpenClaw hook, cancel the main assistant reply via `message:sending`, forward the stripped prompt to a Kiro agent, then send the response back to Telegram.

Keep the architecture simple. The hook should route, not think. Put durable behavior in the downstream Kiro agent prompt and knowledge files.

## Recommended Architecture

Use this chain:

1. Telegram direct message starts with `/kiro`
2. OpenClaw hook receives `message:received`
3. Hook validates channel, chat type, and command prefix
4. Hook strips `/kiro` and forwards the remaining prompt via `openclaw agent --message --json`
5. The agent processes the prompt and returns a JSON response
6. Hook sends the returned text back to Telegram
7. Hook cancels the main OpenClaw reply via `message:sending` hook with `{ cancel: true }`

**Important:** In OpenClaw 2026.4.2, `message:received` is a void hook — its return value is discarded. `{ suppress: true }` does **not** work. To prevent the main agent from replying, use a `message:sending` hook that returns `{ cancel: true }`. As a belt-and-suspenders measure, also instruct the main agent in `SOUL.md` to ignore `/kiro` messages.

This skill is documented for OpenClaw `2026.4.2`, using `openclaw agent --message --json` for one-shot agent calls.

## Implementation Rules

### 1. Keep the OpenClaw hook narrow

The hook should only do four things:

- detect eligible inbound messages
- normalize the user prompt
- call `openclaw agent --message --json` asynchronously
- send the downstream reply back to Telegram

Do not duplicate business logic, memory, or persona inside the hook unless absolutely necessary.

### 2. Restrict the trigger aggressively

Limit activation to the exact contexts you intend, for example:

- Telegram only
- direct chat only
- message starts with `/kiro`
- optional allowlist of trusted chat IDs

If the command is empty, send a short usage message and still suppress the normal assistant reply.

### 3. Treat Kiro as the reasoning layer

Put these in the Kiro side, not the OpenClaw hook:

- language rules
- domain knowledge
- reusable KB references
- agent persona
- session behavior

For a public skill, keep Kiro resources configurable and avoid hard-coding personal paths when documenting the pattern.

### 4. Prefer async fire-and-forget hook behavior

After dispatching the background handler, return immediately. Use `message:sending` with `{ cancel: true }` to prevent duplicate replies. Never use synchronous blocking calls (`execSync`) inside hook handlers — this freezes the entire gateway.

### 5. Handle failures explicitly

On agent call or Telegram send failure:

- log the error
- send a short failure notice back to the Telegram chat when possible
- avoid crashing the hook process

Document pairing and scope approval requirements.

## Public Skill Deliverables

When packaging this pattern as a public OpenClaw skill, include:

- `SKILL.md` with the integration workflow and constraints
- `references/architecture.md` describing the end-to-end message flow
- `references/hook-template.ts` with a reusable TypeScript hook example
- `references/kiro-agent-template.json` with a sample Kiro agent definition
- optional public README outside the skill folder if publishing a GitHub repo for humans

Do not put README inside the skill folder. Keep the skill itself minimal and agent-focused.

## Workflow

### Step 1: Define the routing contract

Decide all fixed values up front:

- Telegram scope: direct chat only or broader
- command prefix: usually `/kiro`
- target agent name, such as `kiro`
- response timeout
- failure message format

### Step 2: Implement the OpenClaw hook

Create a hook with metadata similar to:

- events: `message:received` and `message:sending`
- always: `true`
- purpose: intercept `/kiro` messages and cancel the main assistant reply

The handler should:

1. **On `message:sending`**: if the session has a pending `/kiro` command, return `{ cancel: true }` to block the main agent reply
2. **On `message:received`**: reject non-message, non-Telegram, non-direct events
3. reject content that does not start with `/kiro`
4. strip the prefix and trim whitespace
5. mark the session as pending (for `message:sending` cancellation)
6. call `openclaw agent --session-id <id> --message <prompt> --json` asynchronously (never use `execSync`)
7. send the result to Telegram with a `🤖 Kiro` prefix

**Critical:** Do not use `execSync` or any synchronous blocking call inside a hook handler. This will freeze the entire gateway event loop.

**Critical:** `message:received` is a void hook in OpenClaw 2026.4.2. Its return value is discarded. Use `message:sending` with `{ cancel: true }` to suppress the main agent reply.

### Step 3: Configure the Kiro agent

Use a Kiro agent definition JSON to set:

- agent name and description
- language preference
- KB or prompt resource files
- optional MCP compatibility flags

Store stable knowledge in separate markdown files so the Kiro agent can load them consistently.

### Step 4: Document operational constraints

State these explicitly in docs:

- this pattern assumes `openclaw` CLI is available locally
- the hook must have permission to talk to Telegram and invoke `openclaw agent`
- device pairing and scope approval may be required
- replies are only as safe as the downstream agent prompt and available tools
- public examples must remove personal bot tokens, user IDs, and private file paths

## Reference Files

Read these files when you need concrete examples:

- `references/architecture.md` for a concise architecture summary
- `references/deployment.md` for deployment steps and troubleshooting
- `references/hook-template.ts` for a reusable OpenClaw hook example
- `references/kiro-agent-template.json` for a sample Kiro agent definition

## Validation Checklist

Before publishing or reusing the pattern, verify:

- `/kiro hello` produces one Telegram reply, not two
- non-`/kiro` messages do not trigger the hook
- empty `/kiro` returns a usage hint
- agent timeout produces a readable error
- pairing failures point users to approval steps
- all personal secrets, IDs, and local paths are replaced with placeholders in public docs

## Alternative Designs

### Option A: OpenClaw hook -> `openclaw agent --message --json`

Use this as the default recommendation for OpenClaw `2026.4.2`.

Pros:

- simple one-shot CLI call
- keeps the hook logic simple
- good separation between routing and agent behavior

Cons:

- depends on local OpenClaw CLI availability
- requires pairing and scope approval in some environments

### Option B: OpenClaw hook -> custom HTTP wrapper -> agent

Use when you intentionally provide your own local HTTP layer.

Pros:

- can simplify integrations that expect HTTP
- may fit other local orchestration systems

Cons:

- adds another component to maintain
- should not be presented as the default OpenClaw behavior

### Option C: OpenClaw hook -> ACP stdio bridge -> agent

Avoid. In OpenClaw 2026.4.2, the ACP bridge routes replies to the chat channel instead of returning them to the stdio client. Not suitable for hook use cases.

Recommendation: prefer Option A for a public starter pattern on current OpenC
```

## File: README.md
upstream: https://github.com/masami-agent/openclaw-kiro-telegram-acp-skill/blob/main/README.md

````text
# openclaw-kiro-telegram-acp

透過 Telegram `/kiro` 指令，將使用者的訊息經由 OpenClaw hook 轉發至 Kiro agent，並將回覆傳回 Telegram。

```text
Telegram → OpenClaw Hook → openclaw agent --message --json → Kiro Agent → Telegram
```

## 功能特色

- 🤖 **Telegram `/kiro` 指令** — 在 Telegram 中直接與 Kiro agent 對話
- 🔀 **雙重回覆抑制** — `message:received` 攔截指令，`message:sending` 以 `{ cancel: true }` 取消主 agent 回覆
- 🧠 **跨訊息記憶** — 同一 chat 的 `/kiro` 對話共享固定 session，Kiro 能記住先前的對話內容
- 🔒 **Chat ID 白名單** — 限制僅允許信任的 Telegram 使用者存取
- 🛡️ **錯誤訊息格式化** — JSON-RPC error、provider error、ACP 權限錯誤皆轉換為使用者友善的訊息
- ⚡ **非同步非阻塞** — 使用 `execFile` 避免凍結 gateway event loop
- 📦 **OpenClaw Skill 封裝** — 可透過 `skill-src/` 或 ClawHub 安裝
- 🔧 **環境變數設定** — agent 名稱、timeout、chat 白名單、回覆前綴皆可透過 `.env` 調整

## 快速開始

完整的安裝步驟請參閱 **[INSTALL.md](INSTALL.md)**。

若偏好自動化流程，可使用內建的互動式安裝腳本：

```bash
npm install
npm run build
npm run install-skill
```

安裝後執行驗證：

```bash
npm run validate
```

若你只是 clone 下來做開發或跑 CI（尚未安裝到 `~/.openclaw/workspace`），可使用 dev 模式，跳過 workspace/安裝檢查：

```bash
npm run validate -- --mode=dev
```

## 相容性說明

本專案針對 OpenClaw `2026.4.2` 開發，使用 `openclaw agent --message --json` 進行 one-shot agent 呼叫。

## 專案結構

```text
.
├── INSTALL.md                      # 統一安裝指南（唯一安裝參考來源）
├── .env.example                    # 環境變數範本
├── src/
│   ├── hook/handler.ts             # OpenClaw Hook handler
│   └── lib/                        # 核心模組（config、error-formatter 等）
├── scripts/                        # 自動化腳本（install、validate、build-skill）
├── templates/                      # Agent config 與 KB 範本
├── skill-src/                      # Skill 原始碼（打包用）
├── docs/                           # 架構、部署文件
└── examples/                       # 範例檔案
```

## 相關文件

| 文件 | 說明 |
|------|------|
| [INSTALL.md](INSTALL.md) | 統一安裝指南 — 前置需求、環境設定、hook 部署、ACP pairing、驗證測試 |
| [docs/architecture.md](docs/architecture.md) | 端對端訊息流程與系統架構 |
| [docs/deployment.md](docs/deployment.md) | 部署步驟與疑難排解 |
| [.env.example](.env.example) | 所有可設定的環境變數與說明 |
| [templates/kiro-agent.json](templates/kiro-agent.json) | Kiro agent JSON 設定範本 |

## License

MIT
````
