⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
kiro-telegram-acp
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
openclaw-kiro-telegram-acp
透過 Telegram /kiro 指令,將使用者的訊息經由 OpenClaw hook 轉發至 Kiro agent,並將回覆傳回 Telegram。
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。
若偏好自動化流程,可使用內建的互動式安裝腳本:
npm install
npm run build
npm run install-skill
安裝後執行驗證:
npm run validate
若你只是 clone 下來做開發或跑 CI(尚未安裝到 ~/.openclaw/workspace),可使用 dev 模式,跳過 workspace/安裝檢查:
npm run validate -- --mode=dev
相容性說明
本專案針對 OpenClaw 2026.4.2 開發,使用 openclaw agent --message --json 進行 one-shot agent 呼叫。
專案結構
.
├── 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 | 統一安裝指南 — 前置需求、環境設定、hook 部署、ACP pairing、驗證測試 |
| docs/architecture.md | 端對端訊息流程與系統架構 |
| docs/deployment.md | 部署步驟與疑難排解 |
| .env.example | 所有可設定的環境變數與說明 |
| templates/kiro-agent.json | Kiro agent JSON 設定範本 |
License
MIT
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skill-src/kiro-telegram-acp/SKILL.md7.8 KBupstream ↗
--- 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 OpenCREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/masami-agent-openclaw-kiro-telegram-acp-skill-skill-src-kiro-telegram-acp.md