Add Windows launcher script and Telegram setup guide
Claude-Session: https://claude.ai/code/session_01JtuZTCMW9TyogEmBgGf8JT
This commit is contained in:
EugeneTes
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.
|
||||
Reference in New Issue
Block a user