feat: config-driven architecture, install wizard, live runtime switching, usage tracking, auto-failover
Major changes: - Config-driven adapters: all channels (Slack, Discord, Telegram, WebChat, Webhooks) controlled via config.json with enabled flags and token auto-detection, no CLI flags required - Runtime engine field: runtime.engine selects opencode/claude from config - Interactive install script: 8-phase setup wizard with AI runtime detection/installation, token setup, identity file personalization (personality presets), aetheel CLI command, background service (launchd/systemd) - Live runtime switching: /engine, /model, /provider commands hot-swap the AI runtime from chat without restart, changes persisted to config.json - Usage tracking: per-request cost extraction from Claude Code JSON output, cumulative stats via /usage command - Auto-failover: rate limit detection on both runtimes, automatic switch to other engine on quota errors with user notification - Chat commands work without / prefix (Slack intercepts / in channels), commands: engine, model, provider, config, usage, reload, cron, subagents, status, help - /config set for editing config.json from chat with dotted key notation - Security audit saved to docs/security-audit.md - Full command reference in docs/commands.md - Future changes doc with NanoClaw agent teams analysis - Logo added to README and WebChat UI - README fully rewritten with all features documented
This commit is contained in:
841
docs/setup.md
Normal file
841
docs/setup.md
Normal file
@@ -0,0 +1,841 @@
|
||||
# Aetheel Server Setup Guide
|
||||
|
||||
Step-by-step guide to deploy Aetheel on a Linux or macOS machine.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (Recommended)
|
||||
|
||||
The interactive installer handles everything automatically:
|
||||
|
||||
```bash
|
||||
# One-line install
|
||||
curl -fsSL http://10.0.0.59:3051/tanmay/Aetheel/raw/branch/main/install.sh | bash
|
||||
```
|
||||
|
||||
Or if you already have the repo cloned:
|
||||
|
||||
```bash
|
||||
./install.sh
|
||||
```
|
||||
|
||||
The installer will:
|
||||
- Check prerequisites (Python 3.12+, uv)
|
||||
- Install dependencies
|
||||
- Detect or install AI runtimes (OpenCode / Claude Code)
|
||||
- Walk you through token configuration
|
||||
- Install the `aetheel` command
|
||||
- Optionally set up a background service (launchd/systemd)
|
||||
|
||||
After install, use the `aetheel` command:
|
||||
|
||||
```bash
|
||||
aetheel start # Start the bot
|
||||
aetheel stop # Stop the background service
|
||||
aetheel restart # Restart the service
|
||||
aetheel status # Check status
|
||||
aetheel logs # Tail live logs
|
||||
aetheel setup # Re-run setup wizard
|
||||
aetheel update # Pull latest + update deps
|
||||
aetheel doctor # Run diagnostics
|
||||
aetheel config # Edit config.json
|
||||
```
|
||||
|
||||
For flags and options: `aetheel help`
|
||||
|
||||
---
|
||||
|
||||
## Manual Setup
|
||||
|
||||
If you prefer to set things up manually, follow the steps below.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#1-prerequisites)
|
||||
2. [Install System Dependencies](#2-install-system-dependencies)
|
||||
3. [Install uv (Python Package Manager)](#3-install-uv)
|
||||
4. [Install an AI Runtime](#4-install-an-ai-runtime)
|
||||
5. [Clone the Repository](#5-clone-the-repository)
|
||||
6. [Install Python Dependencies](#6-install-python-dependencies)
|
||||
7. [Configure Secrets (.env)](#7-configure-secrets)
|
||||
8. [Configure Settings (config.json)](#8-configure-settings)
|
||||
9. [Set Up Messaging Channels](#9-set-up-messaging-channels)
|
||||
10. [Run the Test Suite](#10-run-the-test-suite)
|
||||
11. [Start Aetheel](#11-start-aetheel)
|
||||
12. [Run as a systemd Service](#12-run-as-a-systemd-service)
|
||||
13. [Verify Everything Works](#13-verify-everything-works)
|
||||
14. [Optional: Enable WebChat](#14-optional-enable-webchat)
|
||||
15. [Optional: Enable Webhooks](#15-optional-enable-webhooks)
|
||||
16. [Optional: Configure Hooks](#16-optional-configure-hooks)
|
||||
17. [Optional: Configure Heartbeat](#17-optional-configure-heartbeat)
|
||||
18. [Optional: Add MCP Servers](#18-optional-add-mcp-servers)
|
||||
19. [Optional: Create Skills](#19-optional-create-skills)
|
||||
20. [Updating](#20-updating)
|
||||
21. [Troubleshooting](#21-troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
| Requirement | Minimum | Recommended |
|
||||
|---|---|---|
|
||||
| OS | Ubuntu 20.04 / Debian 11 | Ubuntu 22.04+ / Debian 12+ |
|
||||
| Python | 3.12 | 3.13 |
|
||||
| RAM | 512 MB | 1 GB+ (fastembed uses ~300 MB for embeddings) |
|
||||
| Disk | 500 MB | 1 GB+ |
|
||||
| Network | Outbound HTTPS | Outbound HTTPS |
|
||||
|
||||
You also need at least one of:
|
||||
- Slack workspace with admin access (for Slack adapter)
|
||||
- Telegram bot token (for Telegram adapter)
|
||||
- Discord bot token (for Discord adapter)
|
||||
- Nothing (for WebChat-only mode)
|
||||
|
||||
And at least one AI runtime:
|
||||
- [OpenCode](https://opencode.ai) CLI
|
||||
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
|
||||
- An API key for the LLM provider (Anthropic, OpenAI, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 2. Install System Dependencies
|
||||
|
||||
```bash
|
||||
# Update packages
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Install essentials
|
||||
sudo apt install -y git curl build-essential
|
||||
|
||||
# Verify
|
||||
git --version
|
||||
curl --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Install uv
|
||||
|
||||
[uv](https://docs.astral.sh/uv/) is the recommended Python package manager. It handles Python versions, virtual environments, and dependencies.
|
||||
|
||||
```bash
|
||||
# Install uv
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
|
||||
# Add to PATH (restart shell or source profile)
|
||||
source ~/.bashrc # or ~/.zshrc
|
||||
|
||||
# Verify
|
||||
uv --version
|
||||
```
|
||||
|
||||
uv will automatically install the correct Python version (3.13) when you run `uv sync`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Install an AI Runtime
|
||||
|
||||
You need at least one AI runtime. Pick one (or both):
|
||||
|
||||
### Option A: OpenCode (recommended)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
|
||||
# Verify
|
||||
opencode --version
|
||||
|
||||
# Configure a provider
|
||||
opencode auth login
|
||||
```
|
||||
|
||||
### Option B: Claude Code
|
||||
|
||||
```bash
|
||||
# Requires Node.js
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
|
||||
# Install Claude Code
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# Verify
|
||||
claude --version
|
||||
```
|
||||
|
||||
### Set your API key
|
||||
|
||||
Whichever runtime you use, you need an API key for the LLM provider:
|
||||
|
||||
```bash
|
||||
# For Anthropic (used by both OpenCode and Claude Code)
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
|
||||
# For OpenAI
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
```
|
||||
|
||||
Add these to your `.env` file later (step 7).
|
||||
|
||||
---
|
||||
|
||||
## 5. Clone the Repository
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
cd ~
|
||||
git clone http://10.0.0.59:3051/tanmay/Aetheel.git
|
||||
cd Aetheel
|
||||
|
||||
# Verify
|
||||
ls pyproject.toml # Should exist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Install Python Dependencies
|
||||
|
||||
```bash
|
||||
# Install project + test dependencies
|
||||
uv sync --extra test
|
||||
|
||||
# Verify Python version
|
||||
uv run python --version # Should be 3.13.x
|
||||
|
||||
# Verify key packages
|
||||
uv run python -c "import click; import aiohttp; import apscheduler; print('All packages OK')"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Configure Secrets
|
||||
|
||||
Secrets (tokens, API keys) go in the `.env` file. This file is gitignored.
|
||||
|
||||
```bash
|
||||
# Create from template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit with your tokens
|
||||
nano .env
|
||||
```
|
||||
|
||||
Fill in the tokens you need:
|
||||
|
||||
```bash
|
||||
# Required for Slack
|
||||
SLACK_BOT_TOKEN=xoxb-your-bot-token
|
||||
SLACK_APP_TOKEN=xapp-your-app-token
|
||||
|
||||
# Required for Telegram (if using --telegram)
|
||||
TELEGRAM_BOT_TOKEN=your-telegram-token
|
||||
|
||||
# Required for Discord (if using --discord)
|
||||
DISCORD_BOT_TOKEN=your-discord-token
|
||||
|
||||
# AI provider API key
|
||||
ANTHROPIC_API_KEY=sk-ant-your-key
|
||||
|
||||
# Optional overrides
|
||||
# OPENCODE_MODEL=anthropic/claude-sonnet-4-20250514
|
||||
# LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
See [docs/slack-setup.md](slack-setup.md) and [docs/discord-setup.md](discord-setup.md) for how to get these tokens.
|
||||
|
||||
---
|
||||
|
||||
## 8. Configure Settings
|
||||
|
||||
Non-secret settings go in `~/.aetheel/config.json`. A default is created on first run, but you can create it now:
|
||||
|
||||
```bash
|
||||
# Create the config directory
|
||||
mkdir -p ~/.aetheel/workspace
|
||||
|
||||
# Generate default config
|
||||
uv run python -c "from config import save_default_config; save_default_config()"
|
||||
|
||||
# View it
|
||||
cat ~/.aetheel/config.json
|
||||
```
|
||||
|
||||
Edit if needed:
|
||||
|
||||
```bash
|
||||
nano ~/.aetheel/config.json
|
||||
```
|
||||
|
||||
Key settings to review:
|
||||
|
||||
```json
|
||||
{
|
||||
"runtime": {
|
||||
"mode": "cli",
|
||||
"model": null
|
||||
},
|
||||
"claude": {
|
||||
"no_tools": false,
|
||||
"allowed_tools": ["Bash", "Read", "Write", "..."]
|
||||
},
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"default_channel": "slack",
|
||||
"default_channel_id": ""
|
||||
},
|
||||
"webchat": {
|
||||
"enabled": false,
|
||||
"port": 8080
|
||||
},
|
||||
"webhooks": {
|
||||
"enabled": false,
|
||||
"port": 8090,
|
||||
"token": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Set Up Messaging Channels
|
||||
|
||||
### Slack (see [docs/slack-setup.md](slack-setup.md))
|
||||
|
||||
1. Create a Slack app at https://api.slack.com/apps
|
||||
2. Add bot scopes: `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `channels:history`, `users:read`
|
||||
3. Enable Socket Mode, generate an app-level token (`xapp-...`)
|
||||
4. Install to workspace, copy bot token (`xoxb-...`)
|
||||
5. Invite bot to channels: `/invite @Aetheel`
|
||||
|
||||
### Discord (see [docs/discord-setup.md](discord-setup.md))
|
||||
|
||||
1. Create app at https://discord.com/developers/applications
|
||||
2. Create bot, copy token
|
||||
3. Enable Message Content Intent
|
||||
4. Invite with `bot` scope + Send Messages + Read Message History
|
||||
|
||||
### Telegram
|
||||
|
||||
1. Message @BotFather on Telegram
|
||||
2. `/newbot` → follow prompts → copy token
|
||||
3. Set `TELEGRAM_BOT_TOKEN` in `.env`
|
||||
|
||||
---
|
||||
|
||||
## 10. Run the Test Suite
|
||||
|
||||
Before starting, verify everything works:
|
||||
|
||||
```bash
|
||||
cd ~/Aetheel
|
||||
|
||||
# Run the full test + smoke check script
|
||||
uv run python test_all.py
|
||||
```
|
||||
|
||||
You should see all checks pass:
|
||||
|
||||
```
|
||||
━━━ RESULTS ━━━
|
||||
Total: 45 checks
|
||||
Passed: 45
|
||||
Failed: 0
|
||||
Skipped: 0
|
||||
All checks passed! 🎉
|
||||
```
|
||||
|
||||
If anything fails, fix it before proceeding. Common issues:
|
||||
- Missing packages → `uv sync --extra test`
|
||||
- Wrong directory → `cd ~/Aetheel`
|
||||
|
||||
You can also run just the pytest suite:
|
||||
|
||||
```bash
|
||||
uv run python -m pytest tests/ -v --ignore=tests/test_scheduler.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Start Aetheel
|
||||
|
||||
### Basic start (Slack only)
|
||||
|
||||
```bash
|
||||
uv run python main.py
|
||||
```
|
||||
|
||||
### With additional adapters
|
||||
|
||||
```bash
|
||||
# Slack + Discord
|
||||
uv run python main.py --discord
|
||||
|
||||
# Slack + Telegram
|
||||
uv run python main.py --telegram
|
||||
|
||||
# Slack + Discord + WebChat
|
||||
uv run python main.py --discord --webchat
|
||||
|
||||
# All adapters
|
||||
uv run python main.py --discord --telegram --webchat
|
||||
```
|
||||
|
||||
### With Claude Code runtime
|
||||
|
||||
```bash
|
||||
uv run python main.py --claude
|
||||
```
|
||||
|
||||
### Test mode (no AI, echo handler)
|
||||
|
||||
```bash
|
||||
uv run python main.py --test
|
||||
```
|
||||
|
||||
### Using the CLI
|
||||
|
||||
```bash
|
||||
# Same as above but via the click CLI
|
||||
uv run python cli.py start --discord --webchat
|
||||
|
||||
# One-shot chat (no adapters needed)
|
||||
uv run python cli.py chat "What is Python?"
|
||||
|
||||
# Diagnostics
|
||||
uv run python cli.py doctor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Run as a systemd Service
|
||||
|
||||
To keep Aetheel running after you disconnect from SSH:
|
||||
|
||||
### Create the service file
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/aetheel.service
|
||||
```
|
||||
|
||||
Paste (adjust paths to match your setup):
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Aetheel AI Assistant
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=your-username
|
||||
WorkingDirectory=/home/your-username/Aetheel
|
||||
ExecStart=/home/your-username/.local/bin/uv run python main.py
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
Environment=PATH=/home/your-username/.local/bin:/usr/local/bin:/usr/bin:/bin
|
||||
|
||||
# Load .env file
|
||||
EnvironmentFile=/home/your-username/Aetheel/.env
|
||||
|
||||
# Optional: add more adapters
|
||||
# ExecStart=/home/your-username/.local/bin/uv run python main.py --discord --webchat
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Enable and start
|
||||
|
||||
```bash
|
||||
# Reload systemd
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Enable on boot
|
||||
sudo systemctl enable aetheel
|
||||
|
||||
# Start now
|
||||
sudo systemctl start aetheel
|
||||
|
||||
# Check status
|
||||
sudo systemctl status aetheel
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u aetheel -f
|
||||
```
|
||||
|
||||
### Manage the service
|
||||
|
||||
```bash
|
||||
sudo systemctl stop aetheel # Stop
|
||||
sudo systemctl restart aetheel # Restart
|
||||
sudo systemctl disable aetheel # Disable on boot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. Verify Everything Works
|
||||
|
||||
### Check the startup log
|
||||
|
||||
```bash
|
||||
sudo journalctl -u aetheel --no-pager | tail -20
|
||||
```
|
||||
|
||||
You should see:
|
||||
|
||||
```
|
||||
============================================================
|
||||
Aetheel Starting
|
||||
============================================================
|
||||
Config: /home/user/.aetheel/config.json
|
||||
Runtime: opencode/cli, model=default
|
||||
Channels: slack
|
||||
Skills: 0
|
||||
Scheduler: ✅
|
||||
Heartbeat: ✅ 3 tasks
|
||||
Subagents: ✅
|
||||
Hooks: ✅ 0 hooks
|
||||
Webhooks: ❌
|
||||
============================================================
|
||||
```
|
||||
|
||||
### Test from Slack/Discord/Telegram
|
||||
|
||||
1. Send `status` → should show runtime info
|
||||
2. Send `help` → should show command list
|
||||
3. Send any question → should get an AI response
|
||||
4. Send `/reload` → should confirm reload
|
||||
|
||||
### Test from CLI
|
||||
|
||||
```bash
|
||||
uv run python cli.py doctor
|
||||
uv run python cli.py status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Optional: Enable WebChat
|
||||
|
||||
Browser-based chat at `http://your-server:8080`.
|
||||
|
||||
### Via config
|
||||
|
||||
Edit `~/.aetheel/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"webchat": {
|
||||
"enabled": true,
|
||||
"port": 8080,
|
||||
"host": "0.0.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Set `host` to `0.0.0.0` to accept connections from other machines (not just localhost).
|
||||
|
||||
### Via CLI flag
|
||||
|
||||
```bash
|
||||
uv run python main.py --webchat
|
||||
```
|
||||
|
||||
### Firewall
|
||||
|
||||
If using `ufw`:
|
||||
|
||||
```bash
|
||||
sudo ufw allow 8080/tcp
|
||||
```
|
||||
|
||||
Then open `http://your-server-ip:8080` in a browser.
|
||||
|
||||
---
|
||||
|
||||
## 15. Optional: Enable Webhooks
|
||||
|
||||
HTTP endpoints for external systems to trigger the agent.
|
||||
|
||||
### Configure
|
||||
|
||||
Edit `~/.aetheel/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"webhooks": {
|
||||
"enabled": true,
|
||||
"port": 8090,
|
||||
"host": "0.0.0.0",
|
||||
"token": "your-secret-webhook-token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Generate a random token:
|
||||
|
||||
```bash
|
||||
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
|
||||
```
|
||||
|
||||
### Firewall
|
||||
|
||||
```bash
|
||||
sudo ufw allow 8090/tcp
|
||||
```
|
||||
|
||||
### Test
|
||||
|
||||
```bash
|
||||
# Health check (no auth)
|
||||
curl http://localhost:8090/hooks/health
|
||||
|
||||
# Wake the agent
|
||||
curl -X POST http://localhost:8090/hooks/wake \
|
||||
-H "Authorization: Bearer your-secret-webhook-token" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text": "What time is it?"}'
|
||||
|
||||
# Send to a specific channel
|
||||
curl -X POST http://localhost:8090/hooks/agent \
|
||||
-H "Authorization: Bearer your-secret-webhook-token" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "New alert from monitoring",
|
||||
"channel": "slack",
|
||||
"channel_id": "C123456"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 16. Optional: Configure Hooks
|
||||
|
||||
Lifecycle hooks run custom code on gateway events.
|
||||
|
||||
### Create a hook
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.aetheel/workspace/hooks/startup-logger
|
||||
```
|
||||
|
||||
Create `~/.aetheel/workspace/hooks/startup-logger/HOOK.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: startup-logger
|
||||
description: Log when the gateway starts
|
||||
events: [gateway:startup]
|
||||
enabled: true
|
||||
---
|
||||
# Startup Logger
|
||||
Logs a message when Aetheel starts.
|
||||
```
|
||||
|
||||
Create `~/.aetheel/workspace/hooks/startup-logger/handler.py`:
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger("aetheel.hooks.startup-logger")
|
||||
|
||||
def handle(event):
|
||||
logger.info("Gateway started — startup hook fired!")
|
||||
```
|
||||
|
||||
Hooks are discovered automatically on startup.
|
||||
|
||||
---
|
||||
|
||||
## 17. Optional: Configure Heartbeat
|
||||
|
||||
The heartbeat system runs periodic tasks automatically.
|
||||
|
||||
### Edit HEARTBEAT.md
|
||||
|
||||
```bash
|
||||
nano ~/.aetheel/workspace/HEARTBEAT.md
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```markdown
|
||||
# Heartbeat Tasks
|
||||
|
||||
## Every 30 minutes
|
||||
- Check if any scheduled reminders need attention
|
||||
|
||||
## Every morning (9:00 AM)
|
||||
- Summarize yesterday's conversations
|
||||
- Check for any pending follow-ups
|
||||
|
||||
## Every evening (6:00 PM)
|
||||
- Update MEMORY.md with today's key learnings
|
||||
```
|
||||
|
||||
### Configure where heartbeat responses go
|
||||
|
||||
Edit `~/.aetheel/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"heartbeat": {
|
||||
"enabled": true,
|
||||
"default_channel": "slack",
|
||||
"default_channel_id": "C123456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Set `default_channel_id` to the Slack channel ID where heartbeat responses should be sent.
|
||||
|
||||
---
|
||||
|
||||
## 18. Optional: Add MCP Servers
|
||||
|
||||
External tool servers that extend the agent's capabilities.
|
||||
|
||||
Edit `~/.aetheel/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"brave-search": {
|
||||
"command": "uvx",
|
||||
"args": ["brave-search-mcp@latest"],
|
||||
"env": {
|
||||
"BRAVE_API_KEY": "your-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Aetheel writes the appropriate config file (`.mcp.json` or `opencode.json`) to the workspace before launching the runtime.
|
||||
|
||||
---
|
||||
|
||||
## 19. Optional: Create Skills
|
||||
|
||||
Skills teach the agent how to handle specific types of requests.
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.aetheel/workspace/skills/weather
|
||||
```
|
||||
|
||||
Create `~/.aetheel/workspace/skills/weather/SKILL.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: weather
|
||||
description: Check weather for any city
|
||||
triggers: [weather, forecast, temperature, rain]
|
||||
---
|
||||
|
||||
# Weather Skill
|
||||
|
||||
When the user asks about weather:
|
||||
1. Use web search to find current conditions
|
||||
2. Include temperature, conditions, and forecast
|
||||
3. Format the response with emoji
|
||||
```
|
||||
|
||||
Skills are loaded at startup and can be reloaded with `/reload`.
|
||||
|
||||
---
|
||||
|
||||
## 20. Updating
|
||||
|
||||
```bash
|
||||
cd ~/Aetheel
|
||||
|
||||
# Pull latest
|
||||
git pull
|
||||
|
||||
# Update dependencies
|
||||
uv sync --extra test
|
||||
|
||||
# Run tests
|
||||
uv run python test_all.py
|
||||
|
||||
# Restart service
|
||||
sudo systemctl restart aetheel
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 21. Troubleshooting
|
||||
|
||||
### "No channel adapters initialized!"
|
||||
|
||||
No messaging tokens are set. Check your `.env` file has at least one of:
|
||||
- `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`
|
||||
- `TELEGRAM_BOT_TOKEN` (with `--telegram` flag)
|
||||
- `DISCORD_BOT_TOKEN` (with `--discord` flag)
|
||||
- `--webchat` flag (no tokens needed)
|
||||
|
||||
### "AI runtime not initialized"
|
||||
|
||||
The AI CLI (opencode or claude) isn't installed or isn't in PATH.
|
||||
|
||||
```bash
|
||||
# Check
|
||||
which opencode
|
||||
which claude
|
||||
|
||||
# Install OpenCode
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
```
|
||||
|
||||
### "Request timed out"
|
||||
|
||||
The AI took too long. Increase timeout in config:
|
||||
|
||||
```json
|
||||
{
|
||||
"runtime": { "timeout_seconds": 300 },
|
||||
"claude": { "timeout_seconds": 300 }
|
||||
}
|
||||
```
|
||||
|
||||
### Memory system init failed
|
||||
|
||||
Usually means fastembed can't download the embedding model on first run. Check internet access and disk space.
|
||||
|
||||
```bash
|
||||
# Test manually
|
||||
uv run python -c "from fastembed import TextEmbedding; e = TextEmbedding(); print('OK')"
|
||||
```
|
||||
|
||||
### Port already in use (WebChat/Webhooks)
|
||||
|
||||
Another process is using the port. Change it in config or find the process:
|
||||
|
||||
```bash
|
||||
sudo lsof -i :8080 # Find what's using port 8080
|
||||
```
|
||||
|
||||
### systemd service won't start
|
||||
|
||||
Check logs:
|
||||
|
||||
```bash
|
||||
sudo journalctl -u aetheel -n 50 --no-pager
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- Wrong `WorkingDirectory` path
|
||||
- Wrong `User`
|
||||
- `.env` file not found (check `EnvironmentFile` path)
|
||||
- uv not in PATH (check `Environment=PATH=...`)
|
||||
|
||||
### Run diagnostics
|
||||
|
||||
```bash
|
||||
uv run python cli.py doctor
|
||||
```
|
||||
|
||||
This checks config validity, workspace, runtime CLIs, tokens, and memory DB.
|
||||
Reference in New Issue
Block a user