Access Path Check

When clients cannot reach FinClaw, troubleshoot the access path layer by layer, working from the outside in.

1. Entry Gateway

curl -v http://<host>:26100/health

Confirm that the API Gateway (26100) is reachable, that TLS (if enabled) works correctly, and that JWT validation is not blocking legitimate requests.

2. Inbound Conversation Path

The inbound request path is: api-gateway -> ag-ui-server -> orchestrator -> ai-infra-rs -> delivery. Verify it hop by hop:

curl http://localhost:26103/health   # ag-ui-server
curl http://localhost:26102/health   # orchestrator
curl http://localhost:26450/health   # ai-infra-rs

3. Infrastructure Connectivity

Confirm that PostgreSQL (26110), TimescaleDB (26111), NATS (26112), Redis (26114), and others are reachable. For the full list of ports, see Deployment Components.

4. Firewall and Ports

Single-node

firewall-cmd --list-ports    # RHEL/CentOS
ufw status                   # Ubuntu

Open 26100 for external access, and 261xx-265xx for internal use.

K8s

kubectl -n <ns> get svc           # Check NodePort / LoadBalancer
kubectl -n <ns> get networkpolicy  # NetworkPolicy troubleshooting

The dynamic port range 26463-26549 for CLAW_FLEET_MANAGER_BASE_PORT must be reserved in K8s NodePort mode.

5. SELinux

Symptom

Containers cannot write to volumes, bwrap refuses to execute, FinSAFE/hermes-adapter fails to start.

Troubleshooting

getenforce                          # Current mode
ausearch -m avc -ts recent          # Recent AVC denials

Resolution

setenforce 0                        # Temporarily switch to Permissive (lost on reboot)

Or customize the SELinux policy. FinSAFE/hermes-adapter requires --privileged, which is mutually exclusive with SELinux. For production, the recommended approach is permissive mode plus audit logging.

6. Container Network

Single-node

docker network inspect chatkit-network
docker exec <a> ping <b>
docker exec <a> nslookup identity-service

K8s

kubectl -n <ns> exec -it <pod> -- nslookup identity-service
kubectl -n kube-system get pods -l k8s-app=kube-dns    # CoreDNS

Cross-namespace: <svc>.<ns>.svc.cluster.local.

7. TLS and Certificates

openssl s_client -connect <host>:26100

Common Issues

• Self-signed certificates: browser warnings, SDK reports x509: certificate signed by unknown authority
• Incomplete certificate chain: complete the intermediate CA
• Intranet proxy MITM certificates: containers need CA injection (NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, Rust SSL_CERT_FILE)

8. DNS Resolution

Single-node

The dns: section of docker-compose.yml points to the host machine or an internal DNS.

K8s

Customize stub domains in the CoreDNS ConfigMap:

kubectl -n kube-system edit configmap coredns

Intranet Scenarios

Add registry.finogeeks.internal resolution to the internal DNS.

References

• Service Health Check (K8s command collection)
• Deployment Components