⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.1.0

kiro-telegram-acp

masami-agent@masami-agent⭐ 0 stars· last commit 7mo ago· 0 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐ 0 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

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.jsonKiro 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 OpenC
  • README.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

// REPO STATS

0 stars
0 open issues
Last commit: 7mo ago