Julien Cabillot
147 lines
4.6 KiB
Markdown
147 lines
4.6 KiB
Markdown
> **Fork** of [alexanxin/opencode-dispatch](https://github.com/alexanxin/opencode-dispatch) — security hardening and Python-only rewrite.
|
|
|
|
# Beyond the Terminal: The Road to a Truly Autonomous AI Agent
|
|
|
|
**opencode-dispatch** is a secure Telegram bridge for the [opencode CLI](https://opencode.ai). It brings the power of a 120K-star, self-hosted AI agent to your pocket—giving you "Dispatch-style" remote access without the corporate subscription or vendor lock-in.
|
|
|
|
<p align="center">
|
|
<img src="https://pbs.twimg.com/media/HEREOD6WcAAaG7_?format=jpg&name=4096x4096" alt="opencode-dispatch Cover" width="700">
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/alexanxin/opencode-dispatch"><img src="https://img.shields.io/github/stars/alexanxin/opencode-dispatch?style=for-the-badge" alt="GitHub Stars"></a>
|
|
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
|
|
<a href="https://opencode.ai"><img src="https://img.shields.io/badge/opencode-CLI-orange?style=for-the-badge" alt="opencode"></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## Why opencode-dispatch?
|
|
|
|
While the industry moves toward closed, subscription-based mobile interfaces, **opencode-dispatch** stays true to the open-source ethos: **Your models, your hardware, your data.**
|
|
|
|
- **📱 Remote Autonomy:** Manage codebases, run tests, and refactor files from a Telegram chat.
|
|
- **🤖 Model Agnostic:** Connect to 75+ providers via Models.dev or run entirely local via Ollama.
|
|
- **🔒 Security First:** Built-in Telegram Chat ID locking and context isolation.
|
|
- **⚡ Lightweight:** Runs on a $5 VPS or your local machine with minimal overhead.
|
|
|
|
## The Vision: Building "OpenClaw"
|
|
|
|
This repository is more than a bridge; it's a foundational layer for a persistent, autonomous agent ecosystem. We are moving beyond stateless terminal commands toward an agent that:
|
|
|
|
1. **Remembers:** Persistent cross-session context.
|
|
2. **Acts:** Scheduled task execution and background monitoring.
|
|
3. **Learns:** A plug-and-play skills and personality registry.
|
|
|
|
---
|
|
|
|
## What You Need
|
|
|
|
- **[opencode CLI](https://opencode.ai)** installed — verify with `opencode --version`
|
|
- A Telegram account
|
|
- Python 3.10+
|
|
- A Telegram bot token (free from [@BotFather](https://t.me/BotFather))
|
|
|
|
## Quick Setup
|
|
|
|
### Step 1: Create a Telegram Bot
|
|
|
|
1. Open Telegram and search for **@BotFather**
|
|
2. Send `/newbot` and follow the prompts to get your **token**.
|
|
|
|
### Step 2: Install Dependencies
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Step 3: Configure
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and set your Telegram bot token and chat ID:
|
|
|
|
```env
|
|
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
|
TELEGRAM_ALLOWED_CHAT_ID=your_chat_id_here
|
|
OPENCODE_API_URL=http://127.0.0.1:5050
|
|
```
|
|
|
|
> Get your chat ID by messaging [@userinfobot](https://t.me/userinfobot) on Telegram.
|
|
|
|
### Step 4: Start opencode
|
|
|
|
```bash
|
|
cd ~/your-project
|
|
opencode serve --port 5050
|
|
```
|
|
|
|
> **Important:** Always `cd` into a specific project folder first. This limits opencode's access to that folder and its subfolders.
|
|
|
|
### Step 5: Run the Bot
|
|
|
|
```bash
|
|
python bot.py
|
|
```
|
|
|
|
### Bot Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/start` | Welcome message and server info |
|
|
| `/status` | Server health, session ID, queue size |
|
|
| `/working` | Check what task is currently being processed |
|
|
| `/clear` | Clear pending messages from queue |
|
|
|
|
## Security
|
|
|
|
### 1. Chat ID locking (Required)
|
|
|
|
The bot **requires** `TELEGRAM_ALLOWED_CHAT_ID` to be set and will refuse to start without it. This ensures only your Telegram account can interact with the bot.
|
|
|
|
### 2. Limit workspace access
|
|
|
|
Never run from your home directory (`~`) or root (`/`). opencode can access all files in the directory it's started from.
|
|
|
|
### 3. Password protect (Recommended)
|
|
|
|
Set a password to prevent unauthorized local access:
|
|
|
|
```bash
|
|
OPENCODE_SERVER_PASSWORD=your-secret opencode serve --port 5050
|
|
```
|
|
|
|
Then add to `.env`:
|
|
|
|
```env
|
|
OPENCODE_SERVER_PASSWORD=your-secret
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**"Can't connect to opencode"**
|
|
- Make sure `opencode serve --port 5050` is running in a terminal
|
|
- Verify with: `curl http://127.0.0.1:5050/global/health`
|
|
|
|
**"Bot isn't responding"**
|
|
- Check your Telegram bot token in `.env`
|
|
- Make sure the bot is running (`python bot.py`)
|
|
|
|
**"Port already in use"**
|
|
- Pick a different port: `opencode serve --port 5051`
|
|
- Update `OPENCODE_API_URL` in `.env` to match
|
|
|
|
**"opencode command not found"**
|
|
- Install: `curl -fsSL https://opencode.ai/install | bash`
|
|
- Then run: `source ~/.zshrc`
|
|
|
|
## Contributing
|
|
|
|
Found a bug? Have an improvement? Open an issue or submit a pull request!
|
|
|
|
## License
|
|
|
|
MIT
|