OpenShrimp 发布：在 Telegram 里远程驱动 Claude 处理本地项目

Your personal Claude, on Telegram.

Chat with Claude from Telegram while it works on real projects on your own computer. It runs on your machine, asks before it changes anything, and goes wherever your phone does. It's the shrimp 🦐 to OpenClaw's lobster.

Small, personal, gets the job done.

Quick Start · Commands · Code Review · Scheduled Tasks · Voice Notes · macOS App · Deployment

OpenShrimp vs OpenClaw

Both are self-hosted and open source. They solve different problems.

TL;DR: OpenClaw is a Swiss Army knife for daily life. OpenShrimp is your personal Claude at work on your own computer, asking before every change.

OpenShrimp vs Claude Code Remote Control

Both let you use Claude Code from your phone. They take very different approaches.

TL;DR: Remote Control mirrors a terminal session to your phone. OpenShrimp is the session — always on, in Telegram, with a proper code review flow. No extra app required.

Why OpenShrimp?

You're away from your desk but want Claude to fix a bug, review a diff, dig through a website, or set something running for the morning. OpenShrimp gives you a full agent session from any Telegram chat — on your phone, your tablet, wherever.

• Real work on real files. Claude reads, edits, and writes files in your actual project directories, runs commands, and uses tools — no copy-pasting between a chat window and your computer.
• Pluggable backends. Run on the Claude Agent SDK (default), or point a context at OpenCode to use GPT, Gemini, or any OpenCode-supported provider.
• You stay in control. Every file mutation needs your explicit approval — one tap to approve or deny. See How Tool Approval Works. When you're ready to commit, /review opens a swipe-based staging UI.
• Talk to it. Send a voice note and it gets transcribed automatically as a prompt — no typing needed. Great for quick instructions when you're on the go.
• Multiple projects, one bot. Switch between project contexts on the fly with /context. Each context has its own working directory, CLAUDE.md, model, and tool permissions.
• Persistent sessions. Pick up where you left off. Sessions survive restarts, and you can /resume any previous conversation.
• Forum topic support. Use Telegram forum channels to organize conversations — each topic thread gets its own independent agent session. Run parallel tasks in the same chat without them stepping on each other. The agent auto-titles each topic for easy navigation.
• Sandbox isolation. Run each context inside its own virtual machine, with only the project directory exposed.
• Computer use. Enable a headless desktop inside the sandbox — the agent can launch Chromium, click around, take screenshots, and interact with GUIs. Watch live via VNC.
• Group chat ready. Add the bot to a team chat. It responds to @mentions and replies, so it stays out of the way until you need it.
• Schedule recurring tasks. Tell the agent to check your repo every morning, monitor a CI pipeline, or run a one-shot task later — all via natural language. Tasks run in isolated sessions automatically.
• Watch background tasks. When the agent runs a long command in the background, tap "View output" to open a live terminal viewer right in Telegram.
• Locked down by default. User allowlist, path-scoped file access, and granular tool approval. The agent can't silently read your ~/.ssh or write outside your project.

Code Review

OpenShrimp includes a mobile-first code review UI built as a Telegram Mini App. Send /review to open it.

It works like Tinder for diffs — each hunk is a card. Swipe right to stage, left to skip, down to undo. You review at the hunk level, not the file level, so you can cherry-pick exactly the changes you want — like git add -p, but designed for your phone.

Voice Notes

Send a voice message instead of typing. OpenShrimp automatically transcribes it using Moonshine — a fast, lightweight speech-to-text model that runs locally. The transcribed text is sent to the agent as a prompt, prefixed with [Transcribed from voice note] so it knows the input came from speech.

The moonshine-stt binary is auto-downloaded on first use. No setup required.

Scheduled Tasks

Set up recurring or one-shot tasks that the agent runs automatically. Just describe what you want in natural language — "check for broken tests every morning at 9am", "summarize the git log every Friday", or "run this migration in 30 minutes".

The agent manages schedules via built-in tools. Use /schedule to see what's active or remove tasks. Scheduled tasks run in isolated sessions with read-only access, so they can report but not modify your code without a follow-up conversation.

Sandbox Isolation

You can run each context inside an isolated sandbox by adding a sandbox: block to your context config. The agent runs inside the guest with only the project directory shared in — so it can't touch anything else on the host.

contexts:
  my-project:
    directory: /home/you/projects/my-project
    sandbox:
      backend: libvirt   # libvirt (Linux), lima (macOS), hcs (Windows)

Session state is stored separately per context under ~/.config/openshrimp/containers/, so sandboxed contexts don't interfere with each other or your host agent state (e.g. ~/.claude).

There is one backend per platform. On Linux, backend: libvirt runs a QEMU/KVM guest. On macOS, backend: lima gives full VM isolation via Apple's Virtualization.framework. On Windows, backend: hcs runs a Linux guest on the Host Compute Service — guest images download automatically on first boot, but the host has its own prerequisites, so read the HCS sandbox guide before enabling it.

macOS App

On macOS, OpenShrimp is also available as a menu bar app. Download the .dmg from Releases, drag to Applications, and launch — no terminal needed.

• Lives in the menu bar (shrimp icon) with no Dock icon
• First-run setup wizard walks you through your bot token, user ID, first project folder, and whether to keep OpenShrimp running after you sign in
• Start/stop the bot, open config, view logs — all from the menu bar
• "Start at Login" registers a system login item, so it appears under Login Items in System Settings
• The bot runs as its own process, so /restart from Telegram works and the menu keeps reporting what it is actually doing
• The bot updates itself in place when a new release is out

Windows App

On Windows, OpenShrimp is also available as a notification-area app. Download the .msi from Releases and run it — no terminal needed.

• Lives in the notification area with no taskbar window
• First-run setup wizard walks you through configuration with native dialogs, and offers to keep OpenShrimp running after you sign in
• Start/stop the bot, open config, view logs — all from the tray menu
• "Start at Login" toggle, backed by a logon scheduled task

The installer is per-user (into %LOCALAPPDATA%\Programs\OpenShrimp) and needs no administrator rights. It bundles everything: the bot, the .NET runtime, and the Windows App SDK.

Note: The Windows app is currently unsigned, so SmartScreen will warn on first run — choose "More info" then "Run anyway".

Quick Start

Prerequisites

• Either the Claude Code CLI installed and authenticated (via claude login or an Anthropic API key) for the default claude_sdk backend, or opencode auth login if you choose the opencode backend — the OpenCode CLI itself is downloaded for you (see Agent Backends)
• A Telegram bot token from @BotFather — we strongly recommend enabling Threaded Mode (Settings → Bot Settings → Threads Settings → Threaded Mode). This lets each conversation run in its own forum topic with an independent agent session.

Option 1: Download Binary (recommended)

Grab the latest binary from Releases. No Python or package manager required — just download, configure, and run.

Note: The Linux binaries require glibc ≥ 2.39 (Ubuntu 24.04+, Debian 13+, Fedora 40+). On older distros, use the from-source install instead.

# Linux x86_64
curl -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-linux-x86_64 -o openshrimp
# Linux ARM64
curl -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-linux-aarch64 -o openshrimp
# macOS Apple Silicon
curl -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-macos-aarch64 -o openshrimp

chmod +x openshrimp

# Windows x86_64 (PowerShell) — includes the HCS sandbox backend
curl.exe -fsSL https://github.com/yjwong/open-shrimp/releases/latest/download/openshrimp-windows-x86_64.exe -o openshrimp.exe

Note: The Windows binary bundles the HCS sandbox backend. Guest images download on first boot, but a sandboxed context still needs Hyper-V rights and WSL's kernel — see the HCS sandbox guide.

On first run, the binary will automatically set up an isolated Python environment and install dependencies. If no config file exists, an interactive setup wizard walks you through creating one. Subsequent runs start instantly.

Option 2: From Source

Requires Python 3.12+ and uv.

git clone https://github.com/yjwong/open-shrimp.git
cd open-shrimp

# Build the web apps (requires Node.js 18+)
for app in review-app terminal-app markdown-app vnc-app; do
  (cd "web/$app" && npm install && npm run build)
done

# If you don't need the web features, create empty placeholders instead:
# for app in review-app terminal-app markdown-app vnc-app; do mkdir -p "web/$app/dist"; done

uv sync

Just like the binary, running uv run openshrimp without a config file will launch the interactive setup wizard. Or configure manually:

Manual config setup

cp config.example.yaml ~/.config/openshrimp/config.yaml

Edit ~/.config/openshrimp/config.yaml with your bot token, Telegram user IDs, and project directories:

telegram:
  token: "YOUR_BOT_TOKEN"

allowed_users:
  - 123456789  # Your Telegram user ID

contexts:
  my-project:
    directory: /home/you/projects/my-project
    description: "My awesome project"
    model: claude-sonnet-4-6   # claude_sdk backend; OpenCode needs provider/model — see Agent Backends

default_context: my-project

Run

# Binary
./openshrimp

# From source
uv run openshrimp

# If using an API key instead of Claude Code login
ANTHROPIC_API_KEY=sk-ant-... ./openshrimp

Or deploy as a systemd service for always-on access — see Deployment.

Commands

How Tool Approval Works

OpenShrimp enforces a layered permission model:

• Read-only tools (Read, Glob, Grep) — auto-approved within the context directory
• Write tools (Edit, Write) — always require manual approval via Telegram inline buttons
• Bash and other tools — configurable per-context via allowed_tools patterns (e.g., Bash(git *))
• Paths outside the context directory — always require manual approval, regardless of tool type

When a tool needs approval, you get three options: Allow (once), Accept all [tool] (auto-approve that tool for the session), or Deny. Edit/Write get the familiar "Accept all edits" button instead. All session-level approvals reset on /clear or context switch.

Agent Backends

The top-level backend: key picks the agent runtime that drives OpenShrimp. Two ship: claude_sdk (the default — the Claude Agent SDK) and opencode (sst/opencode over its HTTP serve API, supporting OpenAI, Anthropic, and Google models). Any context can override the global choice with its own backend: key. Note this agent backend: is a different setting from the sandbox backend: (libvirt/lima/hcs) described under Sandbox Isolation.

Two preconditions on the host:

• Provider-qualified models. Every OpenCode context's model: must be provider/model (e.g. openai/gpt-5.5, anthropic/claude-opus-4-7, google/gemini-2.5-pro). An unqualified model fails fast at startup.
• Pre-authenticate. Run opencode auth login on the host; OpenShrimp reuses the credentials.

The CLI is not something you install: the first turn on an OpenCode context downloads a pinned build (about 60 MB) and reports the transfer in the chat. Only that copy is run — an opencode on your PATH or at ~/.opencode/bin/opencode is ignored, since the pin is what keeps host and guest on one build. Set $OPENCODE_BIN to run your own instead.

backend: opencode
contexts:
  my-project:
    directory: /home/you/projects/my-project
    model: openai/gpt-5.5   # provider/model REQUIRED

Deployment

The easiest way to deploy is with the built-in install command:

# Install as a systemd user service (Linux), a launchd agent (macOS),
# or a logon task (Windows)
openshrimp install

# Remove it
openshrimp uninstall

This auto-detects your platform, finds the executable path, and sets everything up — including enabling lingering on Linux so the service runs without an active login session. It refuses to install unless it finds a config the bot can load, so complete the setup wizard first — which offers to do this for you at the end anyway.

Manual setup

If you prefer to set up the service manually:

# ~/.config/systemd/user/open-shrimp.service
[Unit]
Description=OpenShrimp Telegram Bot

[Service]
ExecStart=/path/to/uv run openshrimp
# Only needed if not using Claude Code login:
# Environment=ANTHROPIC_API_KEY=sk-ant-...
Restart=always

[Install]
WantedBy=default.target

systemctl --user enable --now open-shrimp

License

MIT