Skip to main content

​
Installation Issues

Problem: curl: Permission denied or similar error.Solution: Use sudo or install to a user directory:
# Option 1: Use sudo
sudo curl -fsSL https://klaw.sh/install.sh | sudo sh

# Option 2: Install to user directory
mkdir -p ~/bin
curl -fsSL https://klaw.sh/install.sh | sh -s -- --prefix ~/bin
export PATH="$HOME/bin:$PATH"
Problem: klaw: command not foundSolution: Ensure /usr/local/bin is in your PATH:
echo $PATH
# If /usr/local/bin is missing:
export PATH="/usr/local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for permanence
Problem: “klaw cannot be opened because it is from an unidentified developer”Solution:
xattr -d com.apple.quarantine /usr/local/bin/klaw
Or go to System Preferences → Security & Privacy → Allow.

​
Provider Issues

Problem: ANTHROPIC_API_KEY not set or authentication errors.Solutions:
  1. Check the key is set correctly: 
    echo $ANTHROPIC_API_KEY
  2. Ensure no extra whitespace: 
    export ANTHROPIC_API_KEY="sk-ant-..."  # No spaces
  3. Verify the key is valid at the provider’s dashboard.
Problem: connection refused or timeout errors.Solutions:
  1. Check internet connectivity
  2. Verify no firewall blocking outbound HTTPS
  3. Check provider status page
  4. Try a different provider: 
    klaw chat --provider openrouter
Problem: 429 Too Many Requests or quota errors.Solutions:
  1. Wait and retry
  2. Check your usage at the provider dashboard
  3. Upgrade your plan
  4. Use a different model with lower cost

​
Slack Integration Issues

Problem: Messages to the bot get no response.Checklist:
  1. Is the bot invited to the channel? (/invite @klaw)
  2. Is Socket Mode enabled in Slack app settings?
  3. Are both tokens set? 
    echo $SLACK_BOT_TOKEN
echo $SLACK_APP_TOKEN
  4. Check klaw start output for errors
  5. Verify the bot has required OAuth scopes
Problem: Bot takes too long to respond.Solutions:
  1. Check API provider latency
  2. Use a faster model (claude-haiku-3)
  3. Reduce agent skills/tools
  4. Check system resources on the klaw host
Problem: Bot doesn’t see all messages.Solutions:
  1. Ensure channels:history OAuth scope is granted
  2. For private channels, add groups:history
  3. Check Event Subscriptions are enabled
  4. Verify message.channels event is subscribed

​
Distributed Mode Issues

Problem: connection refused when joining controller.Solutions:
  1. Verify controller is running: 
    klaw controller status
  2. Check network connectivity: 
    nc -zv controller-host 9090
  3. Verify token matches
  4. Check firewall rules (port 9090)
  5. Ensure controller is listening on correct interface: 
    klaw controller start --host 0.0.0.0
Problem: klaw dispatch hangs or fails.Solutions:
  1. Check if nodes are connected: 
    klaw get nodes
  2. Verify agent exists on a node: 
    klaw get agents
  3. Check controller logs for errors
Problem: Nodes show as disconnected intermittently.Solutions:
  1. Check network stability
  2. Increase heartbeat timeout
  3. Check node resource usage (CPU, memory)
  4. Review controller logs for disconnect reasons

​
Container Issues

Problem: klaw build fails.Solutions:
  1. Ensure Podman is installed: 
    podman --version
  2. Run from klaw source directory
  3. Check Containerfile exists
  4. Verify disk space
Problem: klaw run fails immediately.Solutions:
  1. Build the image first: 
    klaw build
  2. Check if image exists: 
    podman images | grep klaw
  3. Check container logs: 
    klaw logs <container-name>

​
General Issues

Problem: Settings in config.toml are ignored.Solutions:
  1. Check config file location: 
    cat ~/.klaw/config.toml
  2. Validate TOML syntax (no errors)
  3. Environment variables override config
  4. Run klaw config view to see effective config
Problem: klaw using excessive memory.Solutions:
  1. Reduce conversation history length
  2. Clear old sessions: 
    rm -rf ~/.klaw/sessions/*
  3. Use a smaller model
  4. Restart klaw to clear memory
Problem: Cryptic error messages.Solutions:
  1. Enable debug logging: 
    klaw chat --log-level debug
  2. Check logs: 
    cat ~/.klaw/logs/klaw.log
  3. Report issue on GitHub with logs

​
Getting Help

If you can’t resolve your issue:
  1. Check GitHub Issues for similar problems
  2. Join the Discord community
  3. File a new issue with:
    • klaw version (klaw version)
    • OS and architecture
    • Steps to reproduce
    • Relevant logs