Dépannage

AI provider tokens must be set in scorpiox-env.txt. Tokens can expire or be revoked.

# Check current token configuration
grep -E "(TOKEN|KEY|AUTH)" ~/.scorpiox/scorpiox-env.txt

# Update token
echo "CLAUDE_CODE_TOKEN=sk-ant-..." >> ~/.scorpiox/scorpiox-env.txt

# Verify provider connectivity
sx providers --test

Scorpiox code requires the HOME environment variable to locate its configuration directory at ~/.scorpiox/.

# Set HOME explicitly (Linux/Mac)
export HOME=/home/youruser

# For containers / CI:
docker run -e HOME=/root scorpiox/code

# Verify:
echo $HOME && sx --version

The ROUTER_URL must be set in scorpiox-env.txt for the provider routing layer to function.

# Add to configuration
echo "ROUTER_URL=https://api.scorpiox.net/router" >> ~/.scorpiox/scorpiox-env.txt

# Verify connectivity
curl -sI https://api.scorpiox.net/router

Bridge or binary download failed integrity check. This can occur with unstable network connections or CDN issues.

# Clear download cache and retry
rm -rf ~/.scorpiox/cache/downloads/
sx bridge --update

# Manual verification
sha256sum ~/.scorpiox/bin/sx

# Check dist server
curl -sI https://dist.scorpiox.net

Rootless containers require user namespace support in the kernel.

# Check kernel support
cat /proc/sys/kernel/unprivileged_userns_clone

# Enable if disabled (requires root)
echo 1 | sudo tee /proc/sys/kernel/unprivileged_userns_clone

# Alternatively, run with podman
podman run --rm -it scorpiox/code sx --version

FRP authentication requires valid credentials and network access to the tunnel server at frp.scorpiox.net.

# Check FRP config
grep FRP_ ~/.scorpiox/scorpiox-env.txt

# Test connectivity
curl -sI https://frp.scorpiox.net

# Re-authenticate
sx frp --login
sx frp --status

The agent attempted to execute a tool binary (execvp) that is not installed or not in PATH.

# Check which tool failed in the logs
LOG_LEVEL=DEBUG sx agent 2>&1 | grep "exec failed"

# Verify common tools are installed
which bash curl git podman

# Check PATH
echo $PATH

Ctrl+C during multi-step agent operations may leave partial state. Exit code 128+2=130 is normal for SIGINT.

# Check for orphan processes
ps aux | grep scorpiox

# Clean up any partial state
rm -f ~/.scorpiox/locks/*.lock

# Resume conversation
sx agent --resume

The provider returned invalid JSON. This usually indicates a network intermediary (proxy, firewall) corrupted the response, or the provider is experiencing issues.

# Test provider directly
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

# Check for proxy interference
curl -v https://api.anthropic.com 2>&1 | head -30

# Enable trace logging
LOG_LEVEL=TRACE sx agent