OpenClaw - Personal AI Assistant
=================================

OpenClaw is an open-source AI assistant that runs on your own server and
communicates via messaging platforms you already use. It connects to LLM
providers (Claude, GPT, etc.) and can interact via Telegram, email, WhatsApp,
Signal, Discord, and many more channels.

Website: https://openclaw.ai/
GitHub:  https://github.com/openclaw/openclaw

Prerequisites
-------------

1. An Anthropic API key (https://console.anthropic.com/settings/keys)
   and/or an OpenRouter API key (https://openrouter.ai/settings/keys)

2. For Telegram: a bot token from @BotFather on Telegram

3. For Gmail: a Gmail App Password (NOT your real password)
   - Enable 2FA on your Google account
   - Go to: https://myaccount.google.com/apppasswords
   - Create an app password for "Mail"

Configuration
-------------

Required settings in service.env:

  ANTHROPIC_API_KEY   - Anthropic API key (primary LLM provider)
  OPENROUTER_API_KEY  - OpenRouter API key (fallback provider)
                        At least one of these must be set.

Optional channel settings:

  TELEGRAM_BOT_TOKEN  - Telegram bot token from @BotFather
  GMAIL_ADDRESS       - Gmail address for email integration
  GMAIL_APP_PASSWORD  - Gmail App Password (16-character code)

Security settings:

  DM_POLICY           - "pairing" (default), "allowlist", or "open"

Ports
-----

  GATEWAY_PORT (default: 18789) - Web dashboard, WebChat, and API

Setup
-----

1. Configure your service.env with API keys and channel credentials

2. Install the service:
   ds install <server> openclaw

3. Note the gateway token printed during installation - you need it
   to access the web dashboard

4. Open the web dashboard:
   http://<server-ip>:18789

5. Paste the gateway token in Settings to authenticate

Channel Setup
-------------

TELEGRAM (automated):
  Set TELEGRAM_BOT_TOKEN in service.env before install.
  After install, send a message to your bot on Telegram.

WEBCHAT (always available):
  Access via the web dashboard at http://<server-ip>:18789

EMAIL / GMAIL (post-install):
  After install, set up the email skill:
  1. docker exec <container> openclaw skills install imap-smtp-email
  2. Configure in the Control UI with:
     IMAP: imap.gmail.com:993 (TLS)
     SMTP: smtp.gmail.com:587 (STARTTLS)
     Username: your Gmail address
     Password: your Gmail App Password

WHATSAPP (interactive, post-install):
  Requires scanning a QR code with your phone:
  docker exec -it <container> openclaw channels login

SIGNAL (interactive, post-install):
  Requires phone number verification:
  docker exec -it <container> openclaw channels add --channel signal

Security Notes
--------------

- API keys are stored in openclaw.json inside the data directory
- Gmail App Passwords are scoped credentials, not your real password
- Telegram bot tokens only control the bot, not your Telegram account
- WhatsApp/Signal use session-based auth, no passwords stored
- Set DM_POLICY="pairing" (default) to require a pairing code
  before the bot responds to new contacts
- The gateway token controls dashboard access - keep it secret

Data Storage
------------

All data is stored in: ${DATA_PATH}
  config/    - OpenClaw configuration (openclaw.json)
  workspace/ - Agent workspace and session data

The gateway token is saved in: ${DATA_PATH}/gateway.token

Retrieving Your Gateway Token
------------------------------

If you lose your gateway token:
  cat ${DATA_PATH}/gateway.token

Or check the config file:
  cat ${DATA_PATH}/config/openclaw.json | grep token

More Information
----------------

Documentation: https://docs.openclaw.ai/
Channel Guide:  https://docs.openclaw.ai/gateway/configuration
Docker Guide:   https://docs.openclaw.ai/install/docker