Troubleshooting

Common issues and solutions for OpenClaw with ArmorIQ.

Quick Diagnostics

Run these commands to quickly identify issues:

# Check gateway is running
ps aux | grep gateway

# Check recent errors
grep -i "error\|fail\|denied" /tmp/openclaw/openclaw-*.log | tail -20

# Check ArmorIQ initialization
grep "ArmorIQ SDK initialized" /tmp/openclaw/openclaw-*.log

# Check policy status
grep "policy" /tmp/openclaw/openclaw-*.log | tail -10

Gateway Issues

Gateway won't start

Symptoms:

No output when running node scripts/run-node.mjs --dev gateway
Error: Cannot find module

Solutions:

# Rebuild the project
rm -rf dist/
pnpm build

# Check Node version
node --version  # Needs >=22.22.3 <23, >=24.15.0 <25, or >=25.9.0

# Install dependencies
pnpm install

# Check for TypeScript errors
pnpm tsc --noEmit

Gateway crashes immediately

Check logs:

tail -100 /tmp/openclaw/openclaw-*.log | grep -i error

Common causes:

Invalid openclaw.json syntax
Missing API keys
Port already in use

Fix port conflict:

# Find process on port 19001
lsof -i :19001

# Kill it
kill -9 <PID>

Gateway not connecting to Telegram

Check:

Bot token in config:
```
grep botToken ~/.openclaw/openclaw.json
```

Telegram channel enabled:

"channels": {
  "telegram": {
    "enabled": true
  }
}

Look for Telegram errors:

grep telegram /tmp/openclaw/openclaw-*.log | tail -20

ArmorIQ Plugin Issues

Plugin not loading

Symptoms:

No ArmorIQ SDK initialized in logs
Policy commands don't work

Check plugin config:

cat ~/.openclaw/openclaw.json | jq '.plugins'

Required structure:

{
  "plugins": {
    "enabled": true,
    "entries": {
      "armoriq": {
        "enabled": true
      }
    }
  }
}

Both plugins.enabled AND armoriq.enabled must be true.

"Plan captured with 0 steps"

Symptoms:

Tools don't execute
Agent gives text-only responses

Causes:

LLM didn't recognize tool usage was needed
Tool definitions not loaded
Model doesn't support function calling

Solutions:

Rephrase prompt to explicitly request tools:

Use the web_search tool to find Boston attractions, 
then use write_file to save results to /tmp/results.md

Check model supports tools:

"model": {
  "primary": "openai/gpt-4-turbo"  // Good
  // NOT: "openai/gpt-3.5-turbo" (may not work)
}

Verify build includes tools:
```
pnpm build
```

Policy commands fail

Symptoms:

"Policy update denied" message
"Unauthorized" errors

Check allowlist:

cat ~/.openclaw/openclaw.json | jq '.plugins.entries.armoriq.policyUpdateAllowList'

Your Telegram user ID must be in the list.

Get your ID:

Message @userinfobot
Copy the numeric ID
Add to config in multiple formats:

"policyUpdateAllowList": [
  "6193457473",
  "@your_username",
  "your_username",
  "telegram:6193457473"
]

Restart gateway after changes:

pkill -f "node.*gateway"
node scripts/run-node.mjs --dev gateway &

API key errors

Symptoms:

"API key invalid" errors
"Unauthorized" from ArmorIQ services

Check the signed-in key:

cat ~/.armoriq/credentials.json   # "apiKey" should start with ak_live_

The key normally lives here, not in openclaw.json. A key in the config or in ARMORIQ_API_KEY overrides it, so check those too if the account looks wrong.

Test API key:

armoriq whoami

Shows the account and key the plugin will use. If it reports no credentials, run armoriq login. A key that is present but rejected shows up as a 401 on the first intent token request in the gateway logs.

Connection Issues

Cannot reach ArmorIQ services

Symptoms:

Timeout errors
"Connection refused"

Check connectivity:

# Backend reachable (expect 200)
curl -s -o /dev/null -w '%{http_code}\n' https://api.armoriq.ai/

# IAP/CSRG reachable (expect 405 or 422 — the route exists and is rejecting
# an empty GET, which is what you want to see here)
curl -s -o /dev/null -w '%{http_code}\n' https://iap.armoriq.ai/intent

Neither service exposes /health. A 404 from https://api.armoriq.ai/health means the route does not exist, not that the service is down.

Check firewall:

# Ensure HTTPS (443) is allowed
sudo ufw status

Check DNS:

nslookup iap.armoriq.ai

Token verification fails

Symptoms:

"Token invalid" errors
"Proof verification failed"

Causes:

Token expired (default: 60s)
Tool arguments changed after planning
Network latency caused timeout

Solutions:

Retry the request
Check for clock skew: date should match UTC
Ensure stable network connection

Configuration Issues

Invalid JSON syntax

Check syntax:

cat ~/.openclaw/openclaw.json | jq .

Common errors:

Missing commas between fields
Trailing commas (not allowed in JSON)
Unquoted strings
Missing closing brackets

Use a JSON validator:

python3 -m json.tool ~/.openclaw/openclaw.json

Wrong config location

OpenClaw looks for config at:

~/.openclaw/openclaw.json

Verify:

ls -la ~/.openclaw/openclaw.json
cat ~/.openclaw/openclaw.json | head -20

Environment variables not loaded

Check variables:

echo $OPENAI_API_KEY
echo $ARMORIQ_API_KEY

If empty, source your profile:

source ~/.bashrc

source ~/.config/fish/config.fish

Log Analysis

Find all errors

grep -i "error\|exception\|fail" /tmp/openclaw/openclaw-*.log | tail -50

Check verification flow

grep -E "Capturing plan|Plan captured|verify-step|allowed" /tmp/openclaw/openclaw-*.log | tail -30

Check policy actions

grep -i "policy" /tmp/openclaw/openclaw-*.log | tail -20

Watch logs live

tail -f /tmp/openclaw/openclaw-*.log | grep --line-buffered -E "error|warn|ArmorIQ|policy"

Common Error Messages

"ArmorIQ SDK not initialized"

Cause: Plugin config missing or invalid

Fix:

{
  "plugins": {
    "enabled": true,
    "entries": {
      "armoriq": {
        "enabled": true,
        "apiKey": "ak_live_..."
      }
    }
  }
}

"Policy update denied: user not in allowlist"

Cause: Your Telegram ID not in policyUpdateAllowList

Fix: Add your ID to the allowlist and restart gateway.

"Intent token request failed"

Cause: Cannot reach IAP service or invalid API key

Fix:

Check internet connection
Verify API key is valid
Test: curl https://iap.armoriq.ai/health

"Step verification failed: proof mismatch"

Cause: Tool arguments changed after plan was created

Fix: Retry the request - this is usually transient.

"Token expired"

Cause: More than 60 seconds between plan creation and execution

Fix:

Ensure fast network connection
Check for slow LLM responses
Retry the request

Reset Everything

If all else fails, reset to a clean state:

# Stop gateway
pkill -f "node.*gateway"

# Clean build
cd /path/to/aiq-openclaw
rm -rf dist/ node_modules/

# Reinstall
pnpm install
npm install @armoriq/sdk

# Rebuild
pnpm build

# Reset policies (via Telegram after restart)
# Send: Policy reset

# Restart
node scripts/run-node.mjs --dev gateway &

Get Help

Collect debug info

Before asking for help, collect:

# System info
node --version
pnpm --version

# Config (redact API keys!)
cat ~/.openclaw/openclaw.json | sed 's/ak_live_[^"]*/***/g'

# Recent logs
tail -100 /tmp/openclaw/openclaw-*.log > debug.log

Support channels

GitHub Issues: https://github.com/armoriq/armorclaw/issues
Documentation: https://docs.armoriq.ai
Email: license@armoriq.io

Troubleshooting Checklist

Gateway running? (ps aux | grep gateway)
ArmorIQ initialized? (check logs for ArmorIQ SDK initialized)
API keys valid? (test with curl)
Telegram bot token correct?
User ID in allowlist?
JSON config valid? (jq .)
Build up to date? (pnpm build)
Node in a supported range? (node --version; needs >=22.22.3 <23, >=24.15.0 <25, or >=25.9.0)
Network connectivity? (test ArmorIQ endpoints)

Troubleshooting

On this page