# Agent Bridge Authentication Troubleshooting

## Symptom

Feishu returns: `操作失败:SEND_TO_CC - effect SEND_TO_CC 失败: Agent error`

## Root-Cause Chain

```
User message → agent bridge → Claude API call → 401 authentication_failed
                                    ↓
                         Error text forwarded to Feishu
```

## Diagnostic Steps (in order)

1. **Check pm2 logs for the actual error**
   ```bash
   tail -100 ~/.pm2/logs/<agent-name>-error.log
   tail -100 ~/.pm2/logs/<agent-name>-out.log
   ```
   Look for `system:api_retry` with `error_status:401`.

2. **Verify Claude Code auth status directly**
   ```bash
   claude -p "test"          # Should return 401 if token expired
   claude auth status        # Shows current auth state
   ```

3. **Check token expiry in macOS keychain**
   ```bash
   security find-generic-password -s "Claude Code-credentials" -w | head -c 500
   ```
   Look for `expiresAt` field (milliseconds since epoch). Convert:
   ```bash
   date -r <epoch_seconds>   # macOS
   date -d @<epoch_seconds>   # Linux
   ```

## Fixes

### Fix A: OAuth Re-authentication (requires browser access)

```bash
claude auth login --claudeai --email <your_email>
```
Or open Chrome, visit https://claude.ai, confirm login, then retry.

### Fix B: API Key (works without browser)

1. Visit https://console.anthropic.com/settings/keys
2. Generate a new key
3. Configure Claude Code:
   ```bash
   claude auth setup-token
   # Paste the API key when prompted
   ```

### Fix C: Restore from backup (if credentials were accidentally deleted)

```bash
# Restore keychain entry from backup
security add-generic-password -s "Claude Code-credentials" -a "$USER" -w "$(cat /tmp/claude-creds-backup.json)"
```

## Prevention

- OAuth tokens expire periodically; Claude Code should auto-refresh via `refreshToken`, but this can fail during Anthropic outages.
- API keys do not expire and are more reliable for headless/agent setups.
- Consider switching agent bridge to API-key auth if OAuth refresh proves flaky.