Telegram

The Telegram connection lets you write to apfelclaw remotely through a private Telegram bot while the backend continues running locally on your Mac.

What it supports

  • Private bot chats only
  • One approved Telegram account
  • One linked private Telegram chat
  • Tool execution follows the normal approval policy unless Telegram tool auto-approve is enabled
  • Shared slash commands such as /new, /help, /version, /apfel ..., /config, and /config set ...

After setup, Telegram can keep talking to apfelclaw even when the TUI is closed.

Prerequisites

  • The backend is running locally with apfelclaw serve or through the first-run onboarding flow
  • You have created a Telegram bot with BotFather and have a bot token

Setup

You can do this during first-run onboarding in apfelclaw, or later from the chat app.

Run this inside the TUI:

/remotecontrol setup telegram <botToken>

apfelclaw verifies the bot token and starts Telegram linking mode. The provider does not auto-approve tools by default. Write tools such as creating a note or a calendar event stay denied until you enable tool auto-approve from the TUI.

Next:

  1. Send a private message to your Telegram bot
  2. Return to the TUI
  3. Run:
/remotecontrol status telegram

The status output should show:

  • enabled: true
  • pollingEnabled: true
  • approvedChatID: ...
  • approvedUserID: ...

That means the provider is linked to one private chat and one Telegram user account.

Useful chat commands

/remotecontrol
/remotecontrol status telegram
/remotecontrol disable telegram
/remotecontrol enable-tools telegram
/remotecontrol disable-tools telegram
/remotecontrol reset telegram

Telegram commands

Once linked, the Telegram chat can use the shared command layer:

  • /new starts a fresh session for the linked Telegram chat
  • /help shows supported commands
  • /version shows the backend version and current apfel status
  • /apfel status shows apfel version, update, and maintenance state
  • /apfel restart asks for confirmation, and /apfel restart confirm performs the restart when supported
  • /apfel upgrade asks for confirmation, and /apfel upgrade confirm upgrades Homebrew-managed apfel and restarts it when supported
  • /config shows the current config
  • /config set ... updates the editable config fields (assistantName, userName, approvalMode, debug, apfelHost, apfelPort)

Example:

/config set assistantName Orbit
/config set apfelPort 11436

apfelHost and apfelPort need a backend restart before they take effect.

Tool auto-approve and notes

Telegram can create Apple Notes on the Mac that hosts the backend. The note is written locally in Notes.app; Telegram only sends the request and the confirmation reply.

Write tools stay denied until you opt in from the local TUI:

/remotecontrol enable-tools telegram

That sets autoApproveTools for the Telegram provider. After it is on, a message such as “Write a note that I need milk” can create the note. This flag is all-or-nothing: it also allows other write tools such as add_calendar_event.

Turn it back off with:

/remotecontrol disable-tools telegram

The first note may prompt macOS Automation permission for Notes.app on that Mac. Notes created this way appear in the default Notes folder, including iCloud Notes when that account is enabled.

Runtime behavior

The backend owns the Telegram poller. That means:

  • setup can happen during apfelclaw onboarding or from the chat app
  • message handling happens in the backend
  • Telegram shows a typing indicator while the backend is working on a normal chat request
  • Telegram continues to work after the chat app is closed

Update and maintenance notes

  • apfelclaw checks in the background whether your installed apfel version is current
  • /apfel status also reports live runtime health (prewarmed, contextWindow) and whether the install meets the recommended 1.8.4 minimum
  • Homebrew installs are compared against the Homebrew formula version, not just the GitHub release feed
  • Upgrade and restart actions are explicit and require a second confirmation command in Telegram
  • Restarting or upgrading apfel briefly interrupts model requests while the backend waits for apfel to become healthy again

Storage

Telegram remote control state is persisted locally:

  • Global app config: ~/.apfelclaw/config.json
  • Remote control config: ~/.apfelclaw/remote-control.json
  • Session memory and remote chat mappings: ~/.apfelclaw/memory.sqlite

Security notes

The current Telegram integration is intentionally narrow:

  • only private chats are accepted
  • only the approved chat ID is accepted
  • only the approved Telegram user ID is accepted
  • write tools stay denied until /remotecontrol enable-tools telegram is run in the local TUI

If you reset Telegram remote control, the stored approval and local session mapping are cleared.