MonoClaw

FAQ & Troubleshooting

Installation

Q: monoclaw: command not found

A: Reload your shell:

source ~/.bashrc   # or ~/.zshrc

If still not found, check that ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Q: Installation fails on "building wheel for ..."

A: Ensure you have build tools installed:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3-dev

# Then retry
curl -fsSL https://raw.githubusercontent.com/monoclaw/monoclaw-runtime/main/scripts/install.sh | bash

Q: Can I install without admin rights?

A: Yes. The default per-user install does not require admin rights. It installs to ~/.monoclaw/ and ~/.local/bin/.

Configuration

Q: Where is my config stored?

A:

  • Config: ~/.monoclaw/config.yaml
  • Secrets: ~/.monoclaw/.env

Q: How do I reset to default config?

A:

mv ~/.monoclaw/config.yaml ~/.monoclaw/config.yaml.backup
monoclaw setup

Q: Can I use multiple API keys?

A: Yes, via credential pools:

model:
  provider: openrouter
  credential_pool:
    - key: "${OPENROUTER_KEY_1}"
    - key: "${OPENROUTER_KEY_2}"

Models

Q: Which model should I use?

A: For most users, Claude Sonnet or GPT-5.5 offers the best balance. For cost-sensitive tasks, DeepSeek Flash is excellent. For Chinese, GLM-4.5 Air or Qwen3 work well.

Q: Why do I need 64K context?

A: Mona uses tools and maintains conversation history. Smaller context windows cause her to forget earlier parts of the conversation, leading to broken workflows.

Q: Can I use a local model?

A: Yes. See the Local LLMs on Mac guide.

Gateway

Q: Bot doesn't respond to messages

A:

  1. Check monoclaw gateway status
  2. Verify the bot token is correct
  3. Check the allowlist
  4. Look at gateway logs: monoclaw gateway logs

Q: How do I find my Telegram user ID?

A: Message @userinfobot on Telegram.

Q: Can I run multiple gateways?

A: Yes, using profiles. Each profile can have its own gateway with different bots.

Tools

Q: Why can't Mona access the internet?

A: Enable web tools:

monoclaw tools enable web

Q: Docker backend says "permission denied"

A: Add your user to the docker group:

sudo usermod -aG docker $USER
# Log out and back in

Security

Q: Where are my API keys stored?

A: In ~/.monoclaw/.env, AES-256 encrypted with your master key.

Q: How do I rotate my master key?

A:

monoclaw secrets rotate-master-key

Q: Can Mona send emails without approval?

A: No. All email sends require explicit user approval.

Performance

Q: Why is Mona slow?

A: Common causes:

  1. Slow LLM provider — try a faster model
  2. Large context — clear old sessions
  3. Many tools enabled — disable unused tools
  4. Local model too large — use quantization

Q: How do I reduce API costs?

A:

  • Use cheaper models for simple tasks
  • Use local models where possible
  • Reduce context by clearing old sessions
  • Use [SILENT] in cron jobs to avoid unnecessary processing

Updates

Q: How do I update MonoClaw?

A:

monoclaw update

Q: Update broke something. How do I rollback?

A:

cd ~/.monoclaw/monoclaw-runtime
git log --oneline -10
git checkout <previous-commit>
uv pip install -e ".[all]"

Getting help