Bot shows offline

Symptoms: agent installed cleanly, but the bot icon shows offline in Discord / Telegram doesn't respond / Slack user shows as inactive.

Fix:

sento restart

Wait 30 seconds for the channel handshake. If still offline, sento logs -n 50 and look for auth errors.

Common root causes:

  • Bot token expired or revoked (Discord token resets every 90 days of inactivity)
  • Required intents / scopes removed after install (see the channel-specific docs for required perms)
  • Network blip — Guardian usually catches this within a minute

"Node 20+ required"

Symptoms: npx sentoagent init fails with a Node version error.

Fix (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
node -v

On macOS: brew install node@20 then brew link --force node@20.

Permission errors during install

Symptoms: EACCES writing to /usr/lib/node_modules or similar.

Fix: you're running as root or without a user-level npm prefix. Create a regular user, run install as that user:

adduser sento
su - sento
npx sentoagent init

Sentō's installer sets NPM_CONFIG_PREFIX=~/.npm-global so user-level installs work; it will not run as root on Docker or Linux.

Playwright crashes / agent OOMs

Symptoms: agent freezes or crashes when asked to browse the web.

Fix: your host has less than 2 GB of RAM. Resize the VPS to at least 2 GB. Chromium needs room to breathe.

"Message Content Intent" error (Discord)

Symptoms: agent logs show Used disallowed intents or the agent silently ignores messages.

Fix: open Discord Developer Portal → your app → Bot → Privileged Gateway Intents → enable Message Content Intent and Server Members Intent. Restart the agent.

Agent doesn't respond to messages

Symptoms: bot is online, but doesn't respond.

Checks in order:

  1. Channel permissions — the bot role needs View Channel + Send Messages in that specific channel.
  2. Mention gating — in groups, requireMention: true in access.json means the bot only responds when @mentioned.
  3. DM policy — if dmPolicy: "disabled" or "allowlist" with empty allowFrom, nothing gets through. Check ~/.claude/channels/<channel>/access.json.
  4. Rate limits — if you've been spamming the bot, the rate limiter may be dropping messages temporarily.

Guardian doesn't restart a stuck agent

Symptoms: agent is stuck, Guardian isn't reacting.

Checks:

  • Is Guardian running? pgrep -fa guardian.js should return at least one match.
  • Is the restart count at max? Check /tmp/sento-guardian-<agent>.json. If restarts.length >= 3, Guardian gave up until the 30-minute window rolls.

Fix: delete the state file and restart both:

rm /tmp/sento-guardian-<agent>.json
sento restart

Agent's memory isn't persisting

Symptoms: you tell the agent to remember something, but next session it doesn't know.

Checks:

  • Is ClawMem installed? ls ~/workspace/memory/ should show at least MEMORY.md.
  • Did the agent actually write it? Look at the most recent file in ~/workspace/memory/ and cat it.
  • Are you relying on Gemini embeddings without an API key? If so, semantic search doesn't work but keyword search still does.

iMessage: SQLITE_CANTOPEN

Symptoms: iMessage agent can't read messages, logs show SQLITE_CANTOPEN.

Fix: the terminal you launched Sentō from doesn't have Full Disk Access. Grant it:

System Settings → Privacy & Security → Full Disk Access → add Terminal (or iTerm / Warp / Ghostty). Restart the terminal.

Still stuck?

Open an issue on GitHub with:

  • Your OS / hostname type (VPS provider, macOS version, Docker image)
  • Output of sento doctor
  • Last 40 lines of sento logs

Real humans read every one.