Add Windows launcher script and Telegram setup guide
Claude-Session: https://claude.ai/code/session_01JtuZTCMW9TyogEmBgGf8JT
This commit is contained in:
EugeneTes
@@ -4,6 +4,8 @@ A personal assistant you talk to over Telegram. The agent engine is [Pi](https:/
|
||||
|
||||
## Setup (Windows or any host with Node 24)
|
||||
|
||||
On Windows the quickest path is `run.bat`, which creates `.env` on the first run, then installs, builds, and starts the bot on every later run. The step by step guide, including how to get the bot token and your user id, is in [SETUP-WINDOWS.md](SETUP-WINDOWS.md).
|
||||
|
||||
1. Create a bot with @BotFather and copy the token.
|
||||
2. Find your numeric Telegram user id (send `/start` to @userinfobot).
|
||||
3. Log in to a model provider once with `pi` so `~/.pi/agent/auth.json` exists, or plan to set `PI_MODEL` plus a provider API key.
|
||||
|
||||
124
SETUP-WINDOWS.md
Normal file
124
SETUP-WINDOWS.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Setting up Volcanic Secretary on Windows
|
||||
|
||||
This guide takes you from a fresh checkout to a Telegram bot that answers you. No Docker involved. Budget about ten minutes.
|
||||
|
||||
## What you need
|
||||
|
||||
- Windows 10 or 11.
|
||||
- Node.js 24 or newer, from https://nodejs.org. Check with `node -v` in a terminal.
|
||||
- Git for Windows at its default location, which gives the assistant a `bash` for running scripts.
|
||||
- Pi installed and able to reach a model. If typing `pi` in a terminal and sending `hi` gets an answer, you are set; the bot reuses the same credentials from `~/.pi/agent`.
|
||||
- A Telegram account on your phone or desktop.
|
||||
|
||||
## Step 1: Create the bot and get its token
|
||||
|
||||
1. In Telegram, open a chat with **@BotFather**.
|
||||
2. Send `/newbot`.
|
||||
3. Give it a display name (for example `Volcanic Secretary`) and then a username that ends in `bot` (for example `volcanic_secretary_bot`). Usernames must be unique across Telegram, so add digits if the first try is taken.
|
||||
4. BotFather replies with a token that looks like `123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. Copy the whole thing.
|
||||
|
||||
Treat the token like a password. Anyone who has it can send messages as your bot.
|
||||
|
||||
## Step 2: Find your own Telegram user id
|
||||
|
||||
The bot only talks to one person, identified by a number, not a username.
|
||||
|
||||
1. Open a chat with **@userinfobot** and send `/start`.
|
||||
2. It replies with a line such as `Id: 987654321`. That number is your user id.
|
||||
|
||||
Any other user who messages the bot is ignored. Their id is written to the bot's log once, which is also how you can double check your own id later.
|
||||
|
||||
## Step 3: Create and fill in `.env`
|
||||
|
||||
1. Double-click `run.bat` in the project folder. On the first run it copies `.env.example` to `.env`, opens it in Notepad, and stops.
|
||||
2. Edit the two required lines:
|
||||
|
||||
```
|
||||
TELEGRAM_BOT_TOKEN=123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
TELEGRAM_OWNER_ID=987654321
|
||||
```
|
||||
|
||||
No quotes, no spaces around `=`.
|
||||
|
||||
3. Optional lines, leave them as they are unless you want the feature:
|
||||
|
||||
| Line | What it does |
|
||||
| --- | --- |
|
||||
| `OPENAI_API_KEY=` | Enables voice notes. Paste an OpenAI API key and voice messages get transcribed before the assistant sees them. Without it, voice notes get a polite "not configured" reply. |
|
||||
| `STT_MODEL=gpt-4o-transcribe` | The OpenAI transcription model. Fine as is. |
|
||||
| `PI_MODEL=` | Forces a model, for example `anthropic/claude-opus-4-8`. Empty means Pi's own default from `~/.pi/agent/settings.json`. |
|
||||
| `SECRETARY_TIMEZONE=` | IANA zone for reminders and cron jobs, for example `Europe/Berlin`. Empty means the Windows system zone. |
|
||||
| `SECRETARY_SHELL=` | Full path to `bash.exe` if Git is not installed at `C:\Program Files\Git`. |
|
||||
| `WORKSPACE_DIR=./workspace` | Where the assistant keeps its memory file, scripts, and files you send. |
|
||||
| `LOG_LEVEL=info` | Set to `debug` to see more in the console. |
|
||||
|
||||
4. Save the file and close Notepad.
|
||||
|
||||
## Step 4: Start the bot
|
||||
|
||||
Double-click `run.bat` again. It installs dependencies the first time, builds, and starts. The console should show lines like these:
|
||||
|
||||
```
|
||||
workspace D:\...\VolcanicSecretary\workspace
|
||||
telegram bot @volcanic_secretary_bot
|
||||
agent ready: anthropic/claude-opus-4-8
|
||||
scheduler ready with 0 job(s)
|
||||
polling started
|
||||
```
|
||||
|
||||
Within a second or two your Telegram chat with the bot receives `🟢 Online.` followed by a short status block.
|
||||
|
||||
Send `hi`. You will see a `⚙️ Working…` message that updates while the assistant works, then the reply.
|
||||
|
||||
Useful commands in the chat:
|
||||
|
||||
| Command | Effect |
|
||||
| --- | --- |
|
||||
| `/status` | Busy or idle, model, context usage, number of scheduled jobs |
|
||||
| `/new` | Start a fresh conversation, the old one stays on disk |
|
||||
| `/stop` | Abort what the assistant is doing right now |
|
||||
| `/jobs` | List scheduled jobs |
|
||||
| `/cancel <id>` | Delete a scheduled job by its id from `/jobs` |
|
||||
| `/compact` | Shrink the conversation context |
|
||||
|
||||
## Step 5: Stop the bot
|
||||
|
||||
Press Ctrl+C in the console window. The bot shuts down cleanly. Windows then asks `Terminate batch job (Y/N)?`, answer `Y`. Closing the window also works.
|
||||
|
||||
## Everyday use
|
||||
|
||||
- Photos are shown to the model. Files you send land in `workspace\inbox\` and the assistant is told the path.
|
||||
- The assistant writes durable facts to `workspace\MEMORY.md`. You can edit that file yourself; the bot reads it fresh every turn.
|
||||
- `workspace\AGENTS.md` holds standing instructions and the persona. Edit it to change how the assistant behaves; changes apply after `/new` or a restart.
|
||||
- Scheduled jobs are stored in `workspace\.secretary\jobs.json` and survive restarts.
|
||||
- After pulling code updates, delete the `node_modules` folder or run `npm install` once so the launcher picks up new dependencies.
|
||||
|
||||
## Keeping it running in the background
|
||||
|
||||
`run.bat` is meant for a visible console window. To run the bot unattended, install pm2 once and register it:
|
||||
|
||||
```powershell
|
||||
npm install -g pm2
|
||||
npm run build
|
||||
pm2 start "node --env-file-if-exists=.env dist/main.js" --name secretary --cwd "D:\Projects\Names\VolcanicSecretary"
|
||||
pm2 save
|
||||
```
|
||||
|
||||
Alternatively, Windows Task Scheduler can start `run.bat` at logon, but any startup error then waits on the `pause` prompt inside a window you may not see.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| What you see | Cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| `Config error: TELEGRAM_BOT_TOKEN is required` | `.env` is missing or the line is empty | Run `run.bat`, fill in the token, save |
|
||||
| `.env still contains the placeholder bot token` | The example value was never replaced | Paste the real token from BotFather |
|
||||
| `Startup failed: GrammyError: Call to 'getMe' failed! (401: Unauthorized)` | The token is wrong or was revoked | Copy it again from BotFather, or send `/revoke` there and use the new one |
|
||||
| `Startup failed: Error: No model available` or `No credentials for provider` | Pi has no working model credentials | Run `pi` in a terminal and log in, or set `PI_MODEL` plus the provider's API key in `.env` |
|
||||
| Bot says `🟢 Online.` but never answers your messages | `TELEGRAM_OWNER_ID` is not your id | Look in the console for `ignoring update from user 987654321`, put that number in `.env`, restart |
|
||||
| `409: Conflict` in the console | A second copy of the bot is running with the same token | Stop the other one (another window, pm2, or Docker) |
|
||||
| Voice notes reply "Voice transcription is not configured" | No OpenAI key | Add `OPENAI_API_KEY` to `.env` and restart |
|
||||
| A scheduled script fails with `failed to start bash` | Git for Windows is not at the default path | Set `SECRETARY_SHELL` to the full path of `bash.exe` |
|
||||
| Replies arrive as raw text with `<b>` tags | Telegram rejected the formatting, the bot fell back to plain text | Harmless; report the message content if it repeats |
|
||||
| The window closes before you can read anything | An error happened before the launcher's pause | Open a terminal in the folder and run `.\run.bat` from there |
|
||||
|
||||
If the console shows a message not in this table, start the bot with `LOG_LEVEL=debug` in `.env` and read the last few lines before the exit.
|
||||
85
run.bat
Normal file
85
run.bat
Normal file
@@ -0,0 +1,85 @@
|
||||
@echo off
|
||||
setlocal
|
||||
title Volcanic Secretary
|
||||
cd /d "%~dp0"
|
||||
|
||||
rem ---------------------------------------------------------------
|
||||
rem Volcanic Secretary launcher for Windows (no Docker).
|
||||
rem First run: creates .env from .env.example and opens it for editing.
|
||||
rem Later runs: installs dependencies if missing, builds, starts the bot.
|
||||
rem See SETUP-WINDOWS.md for the Telegram setup steps.
|
||||
rem ---------------------------------------------------------------
|
||||
|
||||
where node >nul 2>nul
|
||||
if errorlevel 1 (
|
||||
echo Node.js 24 or newer is required but was not found on PATH.
|
||||
echo Install it from https://nodejs.org and run this file again.
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
for /f "tokens=1 delims=v." %%a in ('node -v') do set NODE_MAJOR=%%a
|
||||
if %NODE_MAJOR% LSS 24 (
|
||||
echo Node.js 24 or newer is required. Found version:
|
||||
node -v
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if not exist ".env" (
|
||||
copy ".env.example" ".env" >nul
|
||||
echo.
|
||||
echo First run: created .env from .env.example.
|
||||
echo Fill in TELEGRAM_BOT_TOKEN and TELEGRAM_OWNER_ID, save the file,
|
||||
echo then run this file again. SETUP-WINDOWS.md explains where to get them.
|
||||
echo.
|
||||
if not defined SECRETARY_NO_EDITOR start "" notepad ".env"
|
||||
pause
|
||||
exit /b 0
|
||||
)
|
||||
|
||||
findstr /b /c:"TELEGRAM_BOT_TOKEN=123456:ABC" ".env" >nul
|
||||
if not errorlevel 1 (
|
||||
echo.
|
||||
echo .env still contains the placeholder bot token.
|
||||
echo Put your real token from @BotFather after TELEGRAM_BOT_TOKEN= and save.
|
||||
echo See SETUP-WINDOWS.md, step 1.
|
||||
echo.
|
||||
if not defined SECRETARY_NO_EDITOR start "" notepad ".env"
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if not exist "node_modules" (
|
||||
echo Installing dependencies, this takes a minute the first time...
|
||||
call npm install
|
||||
if errorlevel 1 (
|
||||
echo npm install failed. Check your internet connection and try again.
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
)
|
||||
|
||||
echo Building...
|
||||
call npm run build
|
||||
if errorlevel 1 (
|
||||
echo Build failed. See the errors above.
|
||||
pause
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
echo.
|
||||
echo Starting Volcanic Secretary. Press Ctrl+C in this window to stop it.
|
||||
echo.
|
||||
rem DEP0040 is a punycode deprecation inside a dependency, not something the user can act on.
|
||||
node --disable-warning=DEP0040 --env-file-if-exists=.env dist\main.js
|
||||
set EXIT_CODE=%errorlevel%
|
||||
|
||||
if not "%EXIT_CODE%"=="0" (
|
||||
echo.
|
||||
echo The bot stopped with exit code %EXIT_CODE%.
|
||||
echo Compare the last lines above with the Troubleshooting table in SETUP-WINDOWS.md.
|
||||
pause
|
||||
)
|
||||
endlocal
|
||||
exit /b %EXIT_CODE%
|
||||
Reference in New Issue
Block a user