CH 01 · Anatomy of an AI Agent · 07/12
Read as one pageReal code: OpenClaw checks the caller before any agent work
Step 1 of the turn belongs to the surrounding system: decide who is calling, before any model or prompt is involved. OpenClaw runs on your own machine. Its Control UI, CLI, and TUI (a terminal interface) connect to a local server it calls the Gateway, and this function is that server's shared token or password check. Chat channels such as Telegram and Slack are a different door: the Gateway connects out to them, and those senders do not present this secret.
async function authorizeSharedSecretAuth(params: {
method: "token" | "password";
configuredSecret?: string;
providedSecret?: string;
limiter?: AuthRateLimiter;
ip?: string;
rateLimitScope: string;
deferRateLimitFailure?: boolean;
resetOnSuccess?: boolean;
}): Promise<GatewayAuthResult> {
// ... (9 lines: fail when the gateway has no usable secret configured)
if (!params.providedSecret) {
// Missing credentials do not consume the wrong-credential rate limit.
return { ok: false, reason: `${params.method}_missing` }; // [1]
}
if (!safeEqualSecret(params.providedSecret, params.configuredSecret)) { // [2]
if (!params.deferRateLimitFailure) {
await params.limiter?.recordFailureAndDelay(params.ip, params.rateLimitScope); // [3]
}
return { ok: false, reason: `${params.method}_mismatch` };
}
if (params.resetOnSuccess !== false) {
params.limiter?.reset(params.ip, params.rateLimitScope); // [4]
}
return { ok: true, method: params.method }; // [5]
}
Source: openclaw/openclaw, src/gateway/auth.ts (MIT)
What to notice
- [1] A request with no credential is refused but not counted as a failed guess. A client that simply forgot its token should not lock itself out.
- [2]
safeEqualSecretcompares using Node'stimingSafeEqual, after padding both values to the same length. A plain===can return sooner when the first characters differ, and an attacker who times many responses can recover a secret one character at a time. The padding also keeps the secret's length from leaking. - [3] A wrong secret is recorded against the caller's address and a scope (a named counter, so token failures do not share a budget with device pairing). With the defaults in
auth-rate-limit.ts, 10 failures inside 60 seconds lock that address out for 5 minutes. Loopback callers (connections from this same machine to itself, such as127.0.0.1) are not locked out by default. Each of their failures waits longer instead, from 250 milliseconds, doubling up to 5 seconds. A client on the same machine that arrives through a LAN address is not exempt.deferRateLimitFailurepostpones the record for a caller that still has other credentials to try. - [4] When
resetOnSuccessis notfalse(the default), a correct secret clears that scope's failure history for that address. - [5] Every outcome is a returned object, not a thrown error. Failures include a
reasonsuch astoken_missingortoken_mismatch. Success is{ ok: true, method }, with noreason.
The check for an address that is already locked out runs just before this function, in authorizeGatewayConnectCore. The naive version, if (token !== config.token) return 401, leaks timing, lets anyone guess forever, and tells you nothing when a real user gets refused.
Read it yourself: in src/gateway/auth.ts, read authorizeGatewayConnectCore and write down the order of checks a request passes before its token is compared. Then open src/gateway/auth-rate-limit.ts and read the comment on recordFailureAndDelay: why does it record failures only after checking credentials?
Finished this idea?
Your learning progress stays in this browser.