Telegram File Browser

⚠️ 🚨 CRITICAL BUTTON STRUCTURE WARNING 🚨

The buttons array from the script is a 2D array where each inner array = one row. ALWAYS pass it directly to the message tool without modification.

• In OpenClaw context: use response['buttons'] directly
• In Python scripts: use payload['buttons'] from build_message_payload()

❌ NEVER flatten, restructure, re-group, or stringify rows.

Zero-Footgun Protocol

When sending any browser menu, follow the correct workflow for your context:

If in OpenClaw (using exec + message tools):

1. Run browser_dispatcher.py via exec tool
2. Use response['messageToolCall'] as the complete payload for the message tool
3. Don't touch the buttons — use them exactly as returned inside that payload
4. If send succeeds and the response includes postSend, then update liveMessageId and optionally delete the previous menu

If in standalone Python script:

1. Generate plan via run_browser_action.py or import functions
2. Run build_message_payload(plan) and require ok: true
3. Use payload['message'] and payload['buttons'] from the validated result

Common mistakes to avoid:

• ❌ Don't rewrite buttons manually
• ❌ Don't flatten buttons into one row
• ❌ Don't pass buttons as a JSON string

Telegram File Browser

Build Telegram file-browsing flows around a single live menu plus optional side messages for previews, paths, and downloads.

Invocation

When the user explicitly invokes telegram-file-browser or asks to use this skill:

1. Open an interactive browser immediately in the same turn.
2. Default the root to ~/.openclaw/workspace unless the user gave a path.
3. Do not reply with a conversational clarification like “你想让我做什么？” when the user already asked to browse.
4. Ask a follow-up only when the target path or safety boundary is genuinely ambiguous.
5. If the input is config, open the configuration flow instead of the browser tree.

Do not stop at describing the skill when you already have enough information to launch the UI.

Runtime Contexts

This skill can be used in two different contexts. Choose the one that matches your environment.

Context 1: OpenClaw Tool Calls (Most Common)

When you're running inside OpenClaw and using exec + message tools (like right now), use browser_dispatcher.py via exec, then call the message tool with the exact JSON from the script.

⚠️ The script already validates and returns the correct payload — use it directly, don't rewrite anything.

Step 1: Run the script via exec tool

# Run the dispatcher to get the final message-tool payload
result = exec(command="python3 ~/.openclaw/workspace/skills/telegram-file-browser/scripts/browser_dispatcher.py open-root")
response = json.loads(result)  # response contains messageToolCall, postSend, and compatibility fields

Step 2: Call message tool with the script's output

# ✅ CORRECT: pass the dispatcher payload through directly
message(**response['messageToolCall'])

# ❌ WRONG: don't rewrite buttons yourself
message(
    action='send',
    message=response['message'],
    buttons=[[{...}, {...}]]
)

# ❌ WRONG: don't stringify the payload either
message(action='send', message=response['message'], buttons=json.dumps(response['buttons']))

Complete example:

# 1. Get the complete message-tool payload
result = exec(command="python3 ~/.openclaw/workspace/skills/telegram-file-browser/scripts/browser_dispatcher.py open-root")
response = json.loads(result.stdout)

if response['ok'] and response.get('messageToolCall'):
    # 2. Send exactly what the dispatcher returned
    msg_result = message(**response['messageToolCall'])

    # 3. Update liveMessageId if requested
    post_send = response.get('postSend') or {}
    if msg_result.get('messageId') and post_send.get('updateLiveMessageId'):
        exec(command="python3 ~/.openclaw/workspace/skills/telegram-file-browser/scripts/browser_dispatcher.py update-message-id " + str(msg_result['messageId']))

    # 4. Delete the previous live menu only after the new one succeeds
    previous_id = post_send.get('previousMessageId')
    if previous_id and post_send.get('cleanupPreviousMessage'):
        message(action='delete', messageId=previous_id)

Callback handling:

# 1. Handle callback
result = exec(command="python3 ~/.openclaw/workspace/skills/telegram-file-browser/scripts/browser_dispatcher.py handle-callback " + callback_data)
response = json.loads(result.stdout)

# 2. Execute the exact tool payload returned by the script
if response.get('messageToolCall'):
    msg_result = message(**response['messageToolCall'])

    post_send = response.get('postSend') or {}
    if msg_result.get('messageId') and post_send.get('updateLiveMessageId'):
        exec(command="python3 ~/.openclaw/workspace/skills/telegram-file-browser/scripts/browser_dispatcher.py update-message-id " + str(msg_result['messageId']))

    previous_id = post_send.get('previousMessageId')
    if previous_id and post_send.get('cleanupPreviousMessage'):
        message(action='delete', messageId=previous_id)

Important for current Telegram/OpenClaw routing:

If a button click arrives as a plain inbound text message like tfb_root_v12_w8 instead of a native callback event, treat that text as the callback_data and run the exact same callback flow above. Do not ignore it just because it came in as a message.

Recommended detection rule:

• if inbound text matches ^tfb_(root|dir|preview|path|download|back|close)_
• treat it as a telegram-file-browser callback
• run browser_dispatcher.py handle-callback <that_text> immediately
• do not ask the user what they mean

Context 2: Standalone Python Script

When you're writing a standalone Python script (not inside OpenClaw), use the import-based approach with build_message_payload.

import sys
sys.path.insert(0, '~/.openclaw/workspace/skills/telegram-file-browser/scripts')
from run_browser_action import open_root, handle_callback
from send_plan import build_message_payload

STATE = '~/.openclaw/workspace/.openclaw/telegram-file-browser/state.json'
ROOT = '~/.openclaw/workspace'


def send_browser_plan(plan):
    """Send message using OpenClaw's message tool or Telegram API."""
    if plan['toolAction'] == 'noop':
        return None
    if plan['toolAction'] == 'delete':
        return {"action": "delete", "messageId": plan['messageId']}
    if plan['toolAction'] == 'send-file':
        return {"action": "send", "path": plan['path'], "caption": plan.get('caption')}

    # MUST validate through build_message_payload
    wrapped = build_message_payload(plan)
    if not wrapped['ok']:
        raise RuntimeError(wrapped['error'])
    
    payload = wrapped['payload']
    return {
        "action": payload['action'],
        "message": payload['message'],
        "buttons": payload['buttons'],
        "replyTo": payload.get('replyTo')
    }


# First open
send_browser_plan(open_root(STATE, ROOT))

# Handle callback
send_browser_plan(handle_callback(STATE, callback_data))

Why build_message_payload is required in Python scripts:

• Validates button structure (2D array, one row per item)
• Returns the exact payload to send
• Prevents common mistakes like flattening buttons

Why it's NOT needed in OpenClaw context:

• browser_dispatcher.py already returns a validated payload
• Just use the JSON values directly

⚠️ For OpenClaw tool calls: Just use browser_dispatcher.py — see Context 1 above.

The examples below are for standalone Python scripts only.

Tool Plan Contract

In OpenClaw context (most common): Use browser_dispatcher.py — it already validates and returns the correct payload. Just use the JSON values directly.

In standalone Python scripts: Use run_browser_action.py + build_message_payload(plan) as the guardrail.

Supported toolAction values:

Plans that send buttons should also include viewType (for example directory or file-actions) so the validator can enforce row-shape rules.

• send
• delete
• send-file
• noop

Map them to OpenClaw message actions like this:

• send
  • In OpenClaw context: Use browser_dispatcher.py — the response already contains validated message and buttons. Just pass them to the message tool:

    message(action='send', message=response['message'], buttons=response['buttons'])

  • In Python scripts: Run build_message_payload(plan) first, then use:

    payload = wrapped["payload"]
    message(action=payload["action"], message=payload["message"], buttons=payload["buttons"])

  • Pass buttons as a real 2D array (each inner array = one row)
  • Do not stringify or flatten buttons

⚠️ Common mistakes to avoid:

# ❌ WRONG — flatten all buttons into one row
buttons = [[{...item1...}, {...item2...}, {...item3...}]]

# ❌ WRONG — stringify buttons  
buttons = json.dumps(response['buttons'])

# ✅ CORRECT — use script output directly
buttons = response['buttons']

• delete

  • use message action=delete
  • pass messageId

• send-file

  • use message action=send
  • pass path or filePath
  • pass caption
  • if replyTo is present, pass it as replyTo

• noop

  • do not send any user-visible message unless debugging is explicitly needed

Important runtime note:

• With the current OpenClaw message tool, Telegram inline buttons are reliably attached on send, not on edit.
• Therefore navigation should be implemented as send a fresh menu, then optionally delete the previous one.
• Treat edit-message mode as replace the prior menu with minimal chat noise, not as a literal button-preserving in-place edit.

Display Modes

Persist display mode in config.json.

edit-message

• keep one logical live browser menu
• because current OpenClaw tooling does not reliably preserve Telegram buttons on edit, implement this as:
  1. send a fresh menu
  2. update liveMessageId
  3. delete the previous menu after send succeeds
• best for low-noise chat history

new-message

• navigation sends a fresh browser menu
• old menus remain in history unless you intentionally delete them
• update liveMessageId to the newly sent menu after success
• previews, path replies, and downloads still reply to the current live menu

Core Interaction Rules

Keep callback payloads short

Never place full file paths in callback_data.

Use opaque ids and store the real mapping in state.

Split navigation from content

Use the menu for navigation only.

Use separate messages for:

• file previews
• copyable path output
• file downloads
• error notices that should not replace the current menu

File click behavior

When a user clicks a file from a directory listing:

1. Open a file action menu.
2. Do not immediately dump file contents.
3. Offer at least 👁 预览, 📋 路径, ⬇️ 下载, ⬅️ 返回, ❌ 关闭.
4. Prefer one button per row here as well unless a later UX change explicitly says otherwise.