[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7939ASEQ5W8XDGK60X8AVXF":3,"skill-same:01M7939ASEQ5W8XDGK60X8AVXF":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7939ASEQ5W8XDGK60X8AVXF","agentos-ai-gateway",null,"Install, configure, inspect, recover, rotate, or retire the optional AgentOS Fleet AI Gateway for pooled Codex subscriptions and an explicit OpenAI API-key fallback. Use when a First or Second Mate considers shared AI capacity, server-owned provider OAuth, native Pi or Codex routing through Agentgateway with projected workload identity, quota-aware account routing, operator access, or gateway 401\u002F403\u002F429 failures.","akua-dev\u002Fagentos","akua-dev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F173261869?v=4","01M7938GS2G2Q6E2M9PRW7QWRJ","Akua - Build autonomous companies ","01M7938GT412SS56QZVCE0Z7FV",8,"MIT","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-ai-gateway\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: agentos-ai-gateway\ndescription: Install, configure, inspect, recover, rotate, or retire the optional AgentOS Fleet AI Gateway for pooled Codex subscriptions and an explicit OpenAI API-key fallback. Use when a First or Second Mate considers shared AI capacity, server-owned provider OAuth, native Pi or Codex routing through Agentgateway with projected workload identity, quota-aware account routing, operator access, or gateway 401\u002F403\u002F429 failures.\n---\n\n# Operate the Fleet AI Gateway\n\nKeep direct per-Agent provider login as the complete minimal topology and\nrecovery path. Recommend the AI gateway for a delegation-ready Fleet when\nseveral approved Agents or trusted harness automations need model capacity and\nthe Captain accepts one additional credential authority and service lifecycle.\n\nThe gateway chooses credentials for the requested model; it never chooses a\nmodel, queues a prompt or hides the provider response. PostgreSQL remains Fleet\ncoordination truth. The gateway's retained PVC owns only its OAuth vault,\nplus canonical `codex-router` SQLite session assignments, quota or transient\nblocks and active reservations. Bounded quota observations remain process-local\nand refresh after restart. The vault's `needsReauth` flag is the single\nauthentication-eligibility authority and is reconciled into router state after\na fresh Gateway-owned login.\n\nUse `ai-gateway` for the provider broker and `agentgateway-openai` for its\npolicy-enforcement point. Agent clients carry\n`agentos.akua.dev\u002Fagentgateway-client: \"true\"`; only Agentgateway carries\n`agentos.akua.dev\u002Fai-gateway-upstream: \"true\"`. Never create a second\nStatefulSet or copy the AI Gateway credential vault during an upgrade.\n\nThe pre-release identity replacement is intentionally breaking. Do not apply\nthis topology over an existing differently named experimental gateway: there\nis no automated PVC or OAuth-vault migration. Return its clients to verified\ndirect authentication, retire the old topology under the Captain's authority,\nthen install and authenticate this gateway fresh.\n\n## Choose the capacity posture\n\nEvaluate the least distributed complete posture first:\n\n| Order | Posture                                   | Use when                                                                            | Capacity and telemetry authority                                                                                                  |\n| ----- | ----------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| 1     | **Direct per-Agent OAuth**                | One Agent, independent credentials, or recovery                                     | Each native harness owns its subscription; AgentOS observes the client operation                                                  |\n| 2     | **In-cluster multi-subscription Gateway** | Several approved Agents should share quota-aware subscription capacity              | One Fleet AI Gateway owns the pool and routing; AgentOS OpenTelemetry owns the complete in-cluster view                           |\n| 3     | **Mixed in-cluster routing**              | Mates should retain direct auth while selected workers or automation share capacity | Direct harnesses and the Gateway own separate credential boundaries; AgentOS observes both                                        |\n| 4     | **External Cloudflare Worker**            | The same deliberately external router must also serve clients outside AgentOS       | The Worker owns its separate pool and router telemetry; AgentOS observes only its clients unless an explicit export is configured |\n\nFor an AgentOS-only Fleet, posture 2 or 3 is stronger than posture 4: Agents\ncan operate the Gateway with native Kubernetes, no inference path leaves the\ncluster before reaching OpenAI, and the Fleet-local Collector receives the\nfull privacy-bounded trace. Posture 4 is an exceptional integration described\nlast, not an upgrade to the in-cluster service.\n\nThe OpenAI API-key fallback is not a multi-subscription posture. It remains a\nseparately approved last-resort credential source for the in-cluster Gateway.\n\n## Decide and inspect\n\n1. Resolve the exact AgentOS revision, Kubernetes context, `agentos` namespace,\n   intended clients and current provider authentication.\n2. Inspect whether `StatefulSet\u002Fai-gateway`, `Service\u002Fai-gateway`,\n   `Secret\u002Fai-gateway-operator`, `Service\u002Fagentgateway-openai`,\n   `Service\u002Fagentos-egress-authz`, the retained PVC and their NetworkPolicies\n   already exist. Inspect only metadata and non-secret status; do not print\n   Secret data, projected tokens, grants or the vault.\n3. Compare the four complete postures above. For pooled capacity inside an\n   AgentOS Fleet, prefer the in-cluster Gateway or mixed posture. Keep direct\n   native authentication available for at least one approved recovery path.\n4. Reject pooled routing when the endpoint would require a public Ingress, the\n   storage cannot remain single-writer, selected Pods cannot be isolated, or a\n   third-party policy forbids subscription proxying. Do not claim that pooled\n   personal subscription use is provider-endorsed; treat it as an explicit\n   experimental Captain choice.\n5. After the Captain chooses, record the capacity posture and non-secret client\n   classes in the owning Mate's private context through `$agentos-memory` as\n   fallible guidance for later dispatch and trusted harness automation. Record\n   exact approval or coupled state changes through Inbox with\n   `$agentos-decisions`; memory never grants authority. Ask again when a\n   client, credential source, cost or blast radius falls outside the exact\n   recorded authority.\n6. A Second Mate may inspect and report gateway state but must route Fleet-wide\n   installation, account changes and shared Secret changes through First Mate\n   unless its exact charter and standing authorization cover them.\n\nAsk before installing the service, initially creating its operator Secret,\nstarting each provider login, enabling API-key fallback,\nchanging an Agent's provider\u002Fenvironment, interrupting a live harness, deleting\nan account, or removing retained state unless exact durable standing authority\ncovers that client and action. State the credential blast radius and whether\nthe action can incur provider cost.\n\n## Install the optional service\n\nUse the reviewed topology at\n`services\u002Fai-gateway\u002Fkubernetes`. Render and inspect it before\napply. It must remain one non-root replica, a ClusterIP without Ingress, a\nretained ReadWriteOnce PVC and an upstream-only NetworkPolicy. The production\npath is usable only when the fail-closed Agentgateway and authorization\nadapter are deployed; never expose the AI Gateway directly to Agents as a\ntemporary substitute.\n\nCreate a high-entropy operator token in a mode-`0600` file outside Git. Use\n`$agentos-secrets` with owner `ai-gateway`, scope `operator`, schema\n`token-v1`, and key `token` to create, retry, rotate, take over, or revoke\n`Secret\u002Fai-gateway-operator`. That lifecycle keeps the value out of argv and\nterminal output, rejects conflicting metadata, preserves UID during rotation,\nand never adds a credential-bearing annotation. The Secret is mounted only in\nthe AI Gateway and protects operator status endpoints; it is never valid for\ninference and is never distributed to Agents or Agentgateway. Then install the\nservice from the reviewed render:\n\n```console\nkubectl --context \u003Ccontext> kustomize services\u002Fai-gateway\u002Fkubernetes\nkubectl --context \u003Ccontext> --namespace agentos apply --filename \u003Creviewed-render>\n```\n\nThe empty gateway is live but intentionally not ready, so wait for its named\nPod and container to start here rather than weakening readiness or waiting for\nthe StatefulSet rollout to complete. Add an approved credential below, verify\nreadiness, and only then run `kubectl rollout status`.\n\nDelete the private token file only after the live Secret metadata and service\ntakeover are verified. Never put the operator token, projected workload token\nor authorization grant in argv, chat, an Assignment, a manifest or a log.\n\nAdd each subscription with a fresh device login owned by the gateway Pod:\n\n```console\n# Repeat this login once for every approved subscription in the pool.\nkubectl --context \u003Ccontext> --namespace agentos exec -it statefulset\u002Fai-gateway \\\n  --container ai-gateway -- ai-gateway login \u003Cnon-secret-label>\nkubectl --context \u003Ccontext> --namespace agentos exec statefulset\u002Fai-gateway \\\n  --container ai-gateway -- ai-gateway list\nkubectl --context \u003Ccontext> --namespace agentos exec statefulset\u002Fai-gateway \\\n  --container ai-gateway -- ai-gateway status\n```\n\nShow the device verification URI and one-time user code through the\nauthenticated Captain surface after the exact login is authorized; do not\nforce a terminal attachment merely to read those two interactive instructions.\nKeep them out of durable work records and generated artifacts, and show no\naccess or refresh token. OAuth chains rotate on refresh; never copy a local Pi\nor Codex auth file into the gateway. Readiness becomes healthy after at least\none eligible OAuth account or an explicitly enabled API-key fallback exists.\nAfter every login, inspect the bounded account list and status before starting\nthe next login. Use a unique non-secret operational label for each managed\nslot. Do not reuse one provider account in two Gateway slots or split the same\nrefresh chain between independent routers.\n\nKeep `OPENAI_API_KEY` in a separate Kubernetes Secret. Enable\n`AI_GATEWAY_ALLOW_API_KEY_FALLBACK=true` only through an approved workload\npatch. The fallback is considered only when no OAuth account is eligible. It\ndoes not substitute another model and its real OpenAI response remains visible.\n\n## Connect a selected Agent\n\nPatch only explicitly approved or standing-authorized client Pods with this\ncommon client boundary:\n\n- label `agentos.akua.dev\u002Fagentgateway-client: \"true\"`;\n- `AI_GATEWAY_URL=http:\u002F\u002Fagentgateway-openai.agentos.svc.cluster.local:8788`;\n- `AGENTOS_EGRESS_TOKEN_FILE=\u002Fvar\u002Frun\u002Fsecrets\u002Fagentos-egress\u002Ftoken`.\n\nThe token is kubelet-rotated, audience-bound workload identity from the\nstandard projected ServiceAccount volume. No client Secret is created or\ncopied into a domain namespace. Agentgateway sends the token to the\nTokenReview\u002FOpenFGA authorizer and replaces every grant header with the closed\ndecision returned by that adapter. The grant expires within 15 seconds. The AI\nGateway validates it, strips identity and decision headers, then injects only\nthe selected upstream provider credential.\n\nThe First- and Second-Mate patches additionally set\n`AGENTOS_PI_PROVIDER_MODE=ai-gateway` on `prepare-home` and the Mate runtime so\nthe retained Pi configuration has one explicit transport authority. The Codex\nCrewmate uses its native provider configuration below and does not receive Pi\nprovider mode.\n\nThe AI Gateway NetworkPolicy admits only the core Agentgateway Pods. Domain\nAgents need ordinary network reachability to the private Agentgateway Service;\nunrelated Internet egress remains direct and available. Second Mates may manage\nCrewmates in their own namespace without gaining the operator Secret, provider\nOAuth vault, another domain's identity or Fleet-root credentials.\n\nThe default distribution ships one additive client patch for each workload:\n\n| Client      | Base                                                           | Optional patch                                                                           | StatefulSet          |\n| ----------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------- |\n| First Mate  | `packages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fbase`   | `packages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml`   | `agentos-firstmate`  |\n| Second Mate | `packages\u002Fagentos\u002Fresources\u002Froles\u002Fsecondmate\u002Fkubernetes\u002Fdomain` | `packages\u002Fagentos\u002Fresources\u002Froles\u002Fsecondmate\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml` | `agentos-secondmate` |\n| Crewmate    | `packages\u002Fagentos\u002Fresources\u002Fcrewmates\u002Fdefault\u002Fkubernetes\u002Fbase` | `packages\u002Fagentos\u002Fresources\u002Fcrewmates\u002Fdefault\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml` | `agentos-crewmate`   |\n\nCompose the approved client's base and patch in its reviewed per-Agent\nKustomize overlay. For example, the First Mate overlay contains:\n\n```yaml\napiVersion: kustomize.config.k8s.io\u002Fv1beta1\nkind: Kustomization\nresources:\n  - \u003Cagentos-checkout>\u002Fpackages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fbase\npatches:\n  - path: \u003Cagentos-checkout>\u002Fpackages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml\n    target:\n      group: apps\n      version: v1\n      kind: StatefulSet\n      name: agentos-firstmate\n```\n\nUse the exact base, patch, and StatefulSet from the table for Second Mate or\nCrewmate. Select the owning namespace in that overlay; never rely on the core\nnamespace as an implicit default. Render the overlay with\n`kubectl --context \u003Ccontext> kustomize --load-restrictor LoadRestrictionsNone\n\u003Creviewed-client-overlay>` and apply that reviewed render through the Fleet's\nnormal native Kubernetes workflow.\n\nPosture 2 composes the patch for every approved pooled client. Posture 3\ncomposes it only for selected workers or trusted automation and leaves the\nother Mates' workload plus native harness authentication unchanged. A workload\nwithout the patch has no Agentgateway provider route; its ordinary Internet\negress remains unchanged.\n\nRender the effective StatefulSet and inspect the diff. Environment changes need\na real process\u002FPod restart; Pi `\u002Freload` cannot change environment. Ask before\ninterrupting a Mate and preserve its native session reference through the\nnormal recovery procedure.\n\n## Hermes workload-proxy migration\n\nBefore any Hermes migration, read the [Hermes integration\ncontract](..\u002F..\u002F..\u002F..\u002Fdocs\u002Fintegrations\u002Fhermes-ai-gateway.md) and verify that\nthe selected pinned revision passes its deployment gate. Do not deploy or\nupdate this integration while that gate is unmet; auxiliary requests remain out\nof scope until the selected revision satisfies the contract's no-retry,\nno-redirect and no-fallback requirements.\n\n1. Keep Hermes on verified direct OAuth while deploying the reviewed\n   Agentgateway plus `agentos-egress-authz` topology and registering the Hermes\n   workload identity\u002Faccess profile.\n2. Build and publish the reviewed AgentOS revision, then update the Hermes\n   manifest with the exact immutable adapter image digest and projected token\n   wiring. Do not copy any client credential into the workload.\n3. Render and review the StatefulSet and NetworkPolicies. Confirm the proxy is\n   loopback-only, Agentgateway is the only AI Gateway ingress, and ordinary\n   Internet egress is unchanged.\n4. After explicit rollout approval, start a new Hermes session with the exact\n   selected model and authorize one short fixed no-tool response. Verify the\n   effective provider\u002Fmodel and failure fidelity without reading prompts,\n   responses, tokens, account IDs, or vault state.\n5. Keep direct OAuth intact until that evidence is accepted. Roll back by\n   restoring the prior Hermes config\u002Fworkload revision; do not delete provider\n   auth or retained homes as part of route rollback.\n6. Keep every selected client either on the workload-identity route or verified\n   direct authentication. Secret removal, deployment, restart, and provider\n   login are separate human approval gates.\n\nFor First and Second Mate, the additive client patch sets\n`AGENTOS_PI_PROVIDER_MODE=ai-gateway` on `prepare-home`. Before Pi can start,\nAgentOS atomically reconciles only its marker-owned `openai-codex` transport\noverride in `~\u002F.pi\u002Fagent\u002Fmodels.json`, validates the staged file with the pinned\nnative Pi runtime, and records non-secret ownership in\n`~\u002F.local\u002Fstate\u002Fagentos\u002Fpi-provider.json`. It preserves unrelated providers,\nsettings, and direct `auth.json`. An existing unmarked `openai-codex` entry or a\ndivergent marked entry is an ownership collision and stops startup; never adopt\nor overwrite it manually.\n\nThe reconciled provider entry is:\n\n```json\n{\n  \"providers\": {\n    \"openai-codex\": {\n      \"baseUrl\": \"http:\u002F\u002Fagentgateway-openai.agentos.svc.cluster.local:8788\",\n      \"apiKey\": \"eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJodHRwczovL2FwaS5vcGVuYWkuY29tL2F1dGgiOnsiY2hhdGdwdF9hY2NvdW50X2lkIjoiZmxlZXQtZ2F0ZXdheSJ9fQ.placeholder\"\n    }\n  }\n}\n```\n\nThe JWT-shaped API key is a public, non-secret transport placeholder required\nfor Pi to construct the request. AgentOS's first `before_provider_headers` behavior\nremoves that placeholder and every client-supplied decision header, rereads the\nprojected token file for each request, and supplies it only in memory. A\nmissing, malformed or stale projection fails closed before network I\u002FO. Direct\nprovider mode remains untouched.\n\nThe Gateway patch never chooses a model or thinking level. When the Captain has\nselected either axis, follow `$agentos-harnesses` and add\n`AGENTOS_MODEL=openai-codex\u002F\u003Cmodel>` and, if selected,\n`AGENTOS_THINKING=\u003Clevel>` to the reviewed `prepare-home` overlay separately.\nThe reconciler requires an exact pinned Pi provider\u002Fmodel and fails before\ncommit on an unknown selection. Verify the effective live provider\u002Fmodel after\nthe rollout; readiness itself makes no model request. Do not edit the managed\nprovider entry or ownership marker directly.\n\nThe shared AgentOS session-lifecycle extension independently adds server-side\ncompaction while preserving Pi's built-in transport; its artifact and fallback\ncontract is documented in [`ARCHITECTURE.md`](..\u002F..\u002F..\u002F..\u002FARCHITECTURE.md).\n\nA selected Mate may retain its direct Pi login as a recovery path while a\nCodex Crewmate or trusted automation explicitly uses the managed provider.\nConfigure and verify that process through the same selected\nclient boundary; do not require an unrelated second browser login merely\nbecause the automation uses another harness.\n\nFor a Codex Crewmate, `prepare-home` atomically owns the reserved\n`model_providers.agentos-gateway` entry in `~\u002F.codex\u002Fconfig.toml`. It uses the\nnative Responses wire API and Codex's command-backed provider authentication:\n\n```toml\n[model_providers.agentos-gateway]\nname = \"AgentOS Gateway\"\nbase_url = \"http:\u002F\u002Fagentgateway-openai.agentos.svc.cluster.local:8788\u002Fv1\"\nwire_api = \"responses\"\nsupports_websockets = false\nrequest_max_retries = 0\nstream_max_retries = 0\nenv_http_headers = { \"x-agentos-assignment-id\" = \"AGENTOS_ASSIGNMENT_ID\" }\n\n[model_providers.agentos-gateway.auth]\ncommand = \"\u002Fhome\u002Fagent\u002F.local\u002Fshare\u002Fmise\u002Fshims\u002Fbun\"\nargs = [\"\u002Fopt\u002Fagentos\u002Fpackages\u002Fagentos\u002Fruntime\u002Fcodex-token.ts\"]\ntimeout_ms = 5000\nrefresh_interval_ms = 60000\n```\n\nCodex invokes that helper natively, refreshes proactively and retries auth once.\nThe helper prints only the current validated projected token on success. It\ndoes not wrap Codex and never persists the token. The managed entry can expose\na different model-picker surface than ChatGPT login, so select and verify the\nexact model before dispatch.\n\n## Verify, recover and retire\n\nVerify public `\u002Freadyz`, operator-authenticated `\u002Freadyz\u002Fclient`,\n`ai-gateway status`, the selected Agent environment and one separately\nauthorized short fixed no-tool response. Both readiness endpoints are local,\nread-only eligibility diagnostics and never refresh a credential, probe quota,\nsend a prompt or reserve an account. The client endpoint uses the operator\nSecret and does not prove inference authorization. `ready` means a locally\neligible route or explicit API-key fallback exists; `degraded` keeps the Pod\nready when valid credentials exist\nbut cached capacity is unknown or temporarily blocked; `not_ready` means the\noperator identity or provider credential boundary is unavailable. Pass the\noperator token through a header without printing it. Record only effective\nprovider\u002Fmodel, the opaque managed account label\u002FID\nand success. `quota-axi` may provide additional read-only provider observations;\nit never selects accounts or mutates the gateway.\n\n### Gateway-only First Mate recovery\n\nWhen a direct `pi -ne` control succeeds but First Mate fails through the\nGateway, change only the Gateway client boundary:\n\n1. Preserve the non-secret shape of `~\u002F.pi\u002Fagent\u002Fmodels.json`,\n   `~\u002F.local\u002Fstate\u002Fagentos\u002Fpi-provider.json`, and the effective StatefulSet\n   render as rollback evidence without recording Secret values.\n2. Replace `ai-gateway-client.yaml` in First Mate's overlay with\n   `patches\u002Fai-gateway-direct-auth.yaml`. That patch supplies only\n   `AGENTOS_PI_PROVIDER_MODE=direct` to `prepare-home`; the reconciler removes\n   only its marker-owned provider entry and ownership marker while preserving\n   `auth.json`, unrelated providers, saved model\u002Fthinking settings, and every\n   AgentOS extension. Do not edit either JSON file by hand.\n3. Render the replacement and confirm it removes `AI_GATEWAY_URL`,\n   `AGENTOS_EGRESS_TOKEN_FILE`, and\n   `agentos.akua.dev\u002Fagentgateway-client`, keeps the\n   standard `OTEL_*` environment, and does not remove the\n   `@akua-dev\u002Fagentos` package or its `agentos-observability`, `mate-memory`,\n   `openai-server-compaction`, background-task, or supervision registrations.\n4. Keep `AGENTOS_OPENAI_SERVER_COMPACTION_ENABLED` unset or true so portable\n   summary plus direct-provider server compaction remains active and observable.\n5. Roll out only First Mate, verify that `pi-provider.json` and only the managed\n   `openai-codex` override are absent, resume its native session, select the\n   direct provider\u002Fmodel, and run one short fixed no-tool response.\n6. After that successful direct reconciliation, remove\n   `ai-gateway-direct-auth.yaml`, roll out once more, and repeat the direct\n   provider\u002Fmodel check. Removing the Gateway patch before this handoff causes\n   `prepare-home` to fail closed instead of silently retaining stale routing.\n   Compare the same fresh\u002Fresumed session matrix before attributing the fault\n   to the Gateway.\n\nThis recovery does not disable a generic “Mate AI extension”: the Gateway is a\nprovider transport override, while AgentOS behavior remains independently\nloaded through the normal Pi extension entrypoint.\n\nAn upstream `401`, `429`, timeout or provider error is expected to reach the\nharness. Inspect the native harness error, `ai-gateway status`, Pod\u002FPVC state\nand non-secret account list. Reauthenticate the affected opaque account with a\nfresh `ai-gateway login`; do not delete the old chain until replacement is\nverified. Do not restart an Agent merely to hide quota failure and do not add a\nsilent cross-account retry.\n\nTo retire the capability, first return every client to verified direct auth and\nremove its gateway provider environment\u002Flabel. Then stop the StatefulSet, revoke\nor remove managed accounts and the operator Secret, and ask separately before\ndeleting the retained PVC. A rollback that leaves provider credentials or an\nuntracked authorization route behind is incomplete.\n\n## External Cloudflare Worker\n\nUse this final posture only when the Captain deliberately chooses one\nexternally hosted `codex-router` Worker as a separate capacity authority,\nnormally because non-AgentOS clients must use it too. An AgentOS-only Fleet\nshould use the in-cluster Gateway instead.\n\nBefore connecting any Agent:\n\n1. Verify the exact `akua-dev\u002Fcodex-router` release supports standalone direct\n   Cloudflare egress, subscription OAuth, the AgentOS correlation-header\n   boundary, and byte-preserving Responses streaming. Do not infer support from\n   an OpenAI-compatible URL.\n2. Keep the Worker's OAuth pool and routing state separate from the in-cluster\n   Gateway. Never share one refresh chain between both authorities.\n3. Never route the Worker into `Service\u002Fai-gateway`, route the in-cluster\n   Gateway through the Worker, or expose the Fleet Gateway with an Ingress.\n4. Give a selected Pi client the external HTTPS base URL and\n   `X-AI-Router-Token: $AI_GATEWAY_TOKEN`; give native Codex the external\n   `\u002Fv1` base URL with `env_key=\"AI_GATEWAY_TOKEN\"`. Keep the Secret-backed\n   environment and explicit provider\u002Fmodel verification from the in-cluster\n   procedure.\n5. Treat Cloudflare Workers Observability as the router's default log and trace\n   view. Native Workers logs and traces are available on Free with their\n   documented event and retention limits. External OTLP export is a separate\n   Workers Paid feature. AgentOS's Collector remains authoritative for the\n   in-cluster client spans; do not claim one joined trace until deployed\n   propagation evidence proves it.\n6. Preserve privacy-safe AgentOS operation and attempt identifiers only through\n   the Worker's reviewed bounded correlation contract. Never export prompts,\n   response bodies, credentials, headers, provider account identity, or\n   arbitrary errors.\n\nSee the official Cloudflare documentation for\n[Workers Logs](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Flogs\u002Fworkers-logs\u002F),\n[Workers Traces](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Ftraces\u002F),\n[OpenTelemetry export](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Fexporting-opentelemetry-data\u002F),\nand current\n[trace-propagation limitations](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Ftraces\u002Fknown-limitations\u002F).\n","# Operate the Fleet AI Gateway\n\nKeep direct per-Agent provider login as the complete minimal topology and\nrecovery path. Recommend the AI gateway for a delegation-ready Fleet when\nseveral approved Agents or trusted harness automations need model capacity and\nthe Captain accepts one additional credential authority and service lifecycle.\n\nThe gateway chooses credentials for the requested model; it never chooses a\nmodel, queues a prompt or hides the provider response. PostgreSQL remains Fleet\ncoordination truth. The gateway's retained PVC owns only its OAuth vault,\nplus canonical `codex-router` SQLite session assignments, quota or transient\nblocks and active reservations. Bounded quota observations remain process-local\nand refresh after restart. The vault's `needsReauth` flag is the single\nauthentication-eligibility authority and is reconciled into router state after\na fresh Gateway-owned login.\n\nUse `ai-gateway` for the provider broker and `agentgateway-openai` for its\npolicy-enforcement point. Agent clients carry\n`agentos.akua.dev\u002Fagentgateway-client: \"true\"`; only Agentgateway carries\n`agentos.akua.dev\u002Fai-gateway-upstream: \"true\"`. Never create a second\nStatefulSet or copy the AI Gateway credential vault during an upgrade.\n\nThe pre-release identity replacement is intentionally breaking. Do not apply\nthis topology over an existing differently named experimental gateway: there\nis no automated PVC or OAuth-vault migration. Return its clients to verified\ndirect authentication, retire the old topology under the Captain's authority,\nthen install and authenticate this gateway fresh.\n\n## Choose the capacity posture\n\nEvaluate the least distributed complete posture first:\n\n| Order | Posture                                   | Use when                                                                            | Capacity and telemetry authority                                                                                                  |\n| ----- | ----------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| 1     | **Direct per-Agent OAuth**                | One Agent, independent credentials, or recovery                                     | Each native harness owns its subscription; AgentOS observes the client operation                                                  |\n| 2     | **In-cluster multi-subscription Gateway** | Several approved Agents should share quota-aware subscription capacity              | One Fleet AI Gateway owns the pool and routing; AgentOS OpenTelemetry owns the complete in-cluster view                           |\n| 3     | **Mixed in-cluster routing**              | Mates should retain direct auth while selected workers or automation share capacity | Direct harnesses and the Gateway own separate credential boundaries; AgentOS observes both                                        |\n| 4     | **External Cloudflare Worker**            | The same deliberately external router must also serve clients outside AgentOS       | The Worker owns its separate pool and router telemetry; AgentOS observes only its clients unless an explicit export is configured |\n\nFor an AgentOS-only Fleet, posture 2 or 3 is stronger than posture 4: Agents\ncan operate the Gateway with native Kubernetes, no inference path leaves the\ncluster before reaching OpenAI, and the Fleet-local Collector receives the\nfull privacy-bounded trace. Posture 4 is an exceptional integration described\nlast, not an upgrade to the in-cluster service.\n\nThe OpenAI API-key fallback is not a multi-subscription posture. It remains a\nseparately approved last-resort credential source for the in-cluster Gateway.\n\n## Decide and inspect\n\n1. Resolve the exact AgentOS revision, Kubernetes context, `agentos` namespace,\n   intended clients and current provider authentication.\n2. Inspect whether `StatefulSet\u002Fai-gateway`, `Service\u002Fai-gateway`,\n   `Secret\u002Fai-gateway-operator`, `Service\u002Fagentgateway-openai`,\n   `Service\u002Fagentos-egress-authz`, the retained PVC and their NetworkPolicies\n   already exist. Inspect only metadata and non-secret status; do not print\n   Secret data, projected tokens, grants or the vault.\n3. Compare the four complete postures above. For pooled capacity inside an\n   AgentOS Fleet, prefer the in-cluster Gateway or mixed posture. Keep direct\n   native authentication available for at least one approved recovery path.\n4. Reject pooled routing when the endpoint would require a public Ingress, the\n   storage cannot remain single-writer, selected Pods cannot be isolated, or a\n   third-party policy forbids subscription proxying. Do not claim that pooled\n   personal subscription use is provider-endorsed; treat it as an explicit\n   experimental Captain choice.\n5. After the Captain chooses, record the capacity posture and non-secret client\n   classes in the owning Mate's private context through `$agentos-memory` as\n   fallible guidance for later dispatch and trusted harness automation. Record\n   exact approval or coupled state changes through Inbox with\n   `$agentos-decisions`; memory never grants authority. Ask again when a\n   client, credential source, cost or blast radius falls outside the exact\n   recorded authority.\n6. A Second Mate may inspect and report gateway state but must route Fleet-wide\n   installation, account changes and shared Secret changes through First Mate\n   unless its exact charter and standing authorization cover them.\n\nAsk before installing the service, initially creating its operator Secret,\nstarting each provider login, enabling API-key fallback,\nchanging an Agent's provider\u002Fenvironment, interrupting a live harness, deleting\nan account, or removing retained state unless exact durable standing authority\ncovers that client and action. State the credential blast radius and whether\nthe action can incur provider cost.\n\n## Install the optional service\n\nUse the reviewed topology at\n`services\u002Fai-gateway\u002Fkubernetes`. Render and inspect it before\napply. It must remain one non-root replica, a ClusterIP without Ingress, a\nretained ReadWriteOnce PVC and an upstream-only NetworkPolicy. The production\npath is usable only when the fail-closed Agentgateway and authorization\nadapter are deployed; never expose the AI Gateway directly to Agents as a\ntemporary substitute.\n\nCreate a high-entropy operator token in a mode-`0600` file outside Git. Use\n`$agentos-secrets` with owner `ai-gateway`, scope `operator`, schema\n`token-v1`, and key `token` to create, retry, rotate, take over, or revoke\n`Secret\u002Fai-gateway-operator`. That lifecycle keeps the value out of argv and\nterminal output, rejects conflicting metadata, preserves UID during rotation,\nand never adds a credential-bearing annotation. The Secret is mounted only in\nthe AI Gateway and protects operator status endpoints; it is never valid for\ninference and is never distributed to Agents or Agentgateway. Then install the\nservice from the reviewed render:\n\n```console\nkubectl --context \u003Ccontext> kustomize services\u002Fai-gateway\u002Fkubernetes\nkubectl --context \u003Ccontext> --namespace agentos apply --filename \u003Creviewed-render>\n```\n\nThe empty gateway is live but intentionally not ready, so wait for its named\nPod and container to start here rather than weakening readiness or waiting for\nthe StatefulSet rollout to complete. Add an approved credential below, verify\nreadiness, and only then run `kubectl rollout status`.\n\nDelete the private token file only after the live Secret metadata and service\ntakeover are verified. Never put the operator token, projected workload token\nor authorization grant in argv, chat, an Assignment, a manifest or a log.\n\nAdd each subscription with a fresh device login owned by the gateway Pod:\n\n```console\n# Repeat this login once for every approved subscription in the pool.\nkubectl --context \u003Ccontext> --namespace agentos exec -it statefulset\u002Fai-gateway \\\n  --container ai-gateway -- ai-gateway login \u003Cnon-secret-label>\nkubectl --context \u003Ccontext> --namespace agentos exec statefulset\u002Fai-gateway \\\n  --container ai-gateway -- ai-gateway list\nkubectl --context \u003Ccontext> --namespace agentos exec statefulset\u002Fai-gateway \\\n  --container ai-gateway -- ai-gateway status\n```\n\nShow the device verification URI and one-time user code through the\nauthenticated Captain surface after the exact login is authorized; do not\nforce a terminal attachment merely to read those two interactive instructions.\nKeep them out of durable work records and generated artifacts, and show no\naccess or refresh token. OAuth chains rotate on refresh; never copy a local Pi\nor Codex auth file into the gateway. Readiness becomes healthy after at least\none eligible OAuth account or an explicitly enabled API-key fallback exists.\nAfter every login, inspect the bounded account list and status before starting\nthe next login. Use a unique non-secret operational label for each managed\nslot. Do not reuse one provider account in two Gateway slots or split the same\nrefresh chain between independent routers.\n\nKeep `OPENAI_API_KEY` in a separate Kubernetes Secret. Enable\n`AI_GATEWAY_ALLOW_API_KEY_FALLBACK=true` only through an approved workload\npatch. The fallback is considered only when no OAuth account is eligible. It\ndoes not substitute another model and its real OpenAI response remains visible.\n\n## Connect a selected Agent\n\nPatch only explicitly approved or standing-authorized client Pods with this\ncommon client boundary:\n\n- label `agentos.akua.dev\u002Fagentgateway-client: \"true\"`;\n- `AI_GATEWAY_URL=http:\u002F\u002Fagentgateway-openai.agentos.svc.cluster.local:8788`;\n- `AGENTOS_EGRESS_TOKEN_FILE=\u002Fvar\u002Frun\u002Fsecrets\u002Fagentos-egress\u002Ftoken`.\n\nThe token is kubelet-rotated, audience-bound workload identity from the\nstandard projected ServiceAccount volume. No client Secret is created or\ncopied into a domain namespace. Agentgateway sends the token to the\nTokenReview\u002FOpenFGA authorizer and replaces every grant header with the closed\ndecision returned by that adapter. The grant expires within 15 seconds. The AI\nGateway validates it, strips identity and decision headers, then injects only\nthe selected upstream provider credential.\n\nThe First- and Second-Mate patches additionally set\n`AGENTOS_PI_PROVIDER_MODE=ai-gateway` on `prepare-home` and the Mate runtime so\nthe retained Pi configuration has one explicit transport authority. The Codex\nCrewmate uses its native provider configuration below and does not receive Pi\nprovider mode.\n\nThe AI Gateway NetworkPolicy admits only the core Agentgateway Pods. Domain\nAgents need ordinary network reachability to the private Agentgateway Service;\nunrelated Internet egress remains direct and available. Second Mates may manage\nCrewmates in their own namespace without gaining the operator Secret, provider\nOAuth vault, another domain's identity or Fleet-root credentials.\n\nThe default distribution ships one additive client patch for each workload:\n\n| Client      | Base                                                           | Optional patch                                                                           | StatefulSet          |\n| ----------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------- |\n| First Mate  | `packages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fbase`   | `packages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml`   | `agentos-firstmate`  |\n| Second Mate | `packages\u002Fagentos\u002Fresources\u002Froles\u002Fsecondmate\u002Fkubernetes\u002Fdomain` | `packages\u002Fagentos\u002Fresources\u002Froles\u002Fsecondmate\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml` | `agentos-secondmate` |\n| Crewmate    | `packages\u002Fagentos\u002Fresources\u002Fcrewmates\u002Fdefault\u002Fkubernetes\u002Fbase` | `packages\u002Fagentos\u002Fresources\u002Fcrewmates\u002Fdefault\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml` | `agentos-crewmate`   |\n\nCompose the approved client's base and patch in its reviewed per-Agent\nKustomize overlay. For example, the First Mate overlay contains:\n\n```yaml\napiVersion: kustomize.config.k8s.io\u002Fv1beta1\nkind: Kustomization\nresources:\n  - \u003Cagentos-checkout>\u002Fpackages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fbase\npatches:\n  - path: \u003Cagentos-checkout>\u002Fpackages\u002Fagentos\u002Fresources\u002Froles\u002Ffirstmate\u002Fkubernetes\u002Fpatches\u002Fai-gateway-client.yaml\n    target:\n      group: apps\n      version: v1\n      kind: StatefulSet\n      name: agentos-firstmate\n```\n\nUse the exact base, patch, and StatefulSet from the table for Second Mate or\nCrewmate. Select the owning namespace in that overlay; never rely on the core\nnamespace as an implicit default. Render the overlay with\n`kubectl --context \u003Ccontext> kustomize --load-restrictor LoadRestrictionsNone\n\u003Creviewed-client-overlay>` and apply that reviewed render through the Fleet's\nnormal native Kubernetes workflow.\n\nPosture 2 composes the patch for every approved pooled client. Posture 3\ncomposes it only for selected workers or trusted automation and leaves the\nother Mates' workload plus native harness authentication unchanged. A workload\nwithout the patch has no Agentgateway provider route; its ordinary Internet\negress remains unchanged.\n\nRender the effective StatefulSet and inspect the diff. Environment changes need\na real process\u002FPod restart; Pi `\u002Freload` cannot change environment. Ask before\ninterrupting a Mate and preserve its native session reference through the\nnormal recovery procedure.\n\n## Hermes workload-proxy migration\n\nBefore any Hermes migration, read the [Hermes integration\ncontract](..\u002F..\u002F..\u002F..\u002Fdocs\u002Fintegrations\u002Fhermes-ai-gateway.md) and verify that\nthe selected pinned revision passes its deployment gate. Do not deploy or\nupdate this integration while that gate is unmet; auxiliary requests remain out\nof scope until the selected revision satisfies the contract's no-retry,\nno-redirect and no-fallback requirements.\n\n1. Keep Hermes on verified direct OAuth while deploying the reviewed\n   Agentgateway plus `agentos-egress-authz` topology and registering the Hermes\n   workload identity\u002Faccess profile.\n2. Build and publish the reviewed AgentOS revision, then update the Hermes\n   manifest with the exact immutable adapter image digest and projected token\n   wiring. Do not copy any client credential into the workload.\n3. Render and review the StatefulSet and NetworkPolicies. Confirm the proxy is\n   loopback-only, Agentgateway is the only AI Gateway ingress, and ordinary\n   Internet egress is unchanged.\n4. After explicit rollout approval, start a new Hermes session with the exact\n   selected model and authorize one short fixed no-tool response. Verify the\n   effective provider\u002Fmodel and failure fidelity without reading prompts,\n   responses, tokens, account IDs, or vault state.\n5. Keep direct OAuth intact until that evidence is accepted. Roll back by\n   restoring the prior Hermes config\u002Fworkload revision; do not delete provider\n   auth or retained homes as part of route rollback.\n6. Keep every selected client either on the workload-identity route or verified\n   direct authentication. Secret removal, deployment, restart, and provider\n   login are separate human approval gates.\n\nFor First and Second Mate, the additive client patch sets\n`AGENTOS_PI_PROVIDER_MODE=ai-gateway` on `prepare-home`. Before Pi can start,\nAgentOS atomically reconciles only its marker-owned `openai-codex` transport\noverride in `~\u002F.pi\u002Fagent\u002Fmodels.json`, validates the staged file with the pinned\nnative Pi runtime, and records non-secret ownership in\n`~\u002F.local\u002Fstate\u002Fagentos\u002Fpi-provider.json`. It preserves unrelated providers,\nsettings, and direct `auth.json`. An existing unmarked `openai-codex` entry or a\ndivergent marked entry is an ownership collision and stops startup; never adopt\nor overwrite it manually.\n\nThe reconciled provider entry is:\n\n```json\n{\n  \"providers\": {\n    \"openai-codex\": {\n      \"baseUrl\": \"http:\u002F\u002Fagentgateway-openai.agentos.svc.cluster.local:8788\",\n      \"apiKey\": \"eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJodHRwczovL2FwaS5vcGVuYWkuY29tL2F1dGgiOnsiY2hhdGdwdF9hY2NvdW50X2lkIjoiZmxlZXQtZ2F0ZXdheSJ9fQ.placeholder\"\n    }\n  }\n}\n```\n\nThe JWT-shaped API key is a public, non-secret transport placeholder required\nfor Pi to construct the request. AgentOS's first `before_provider_headers` behavior\nremoves that placeholder and every client-supplied decision header, rereads the\nprojected token file for each request, and supplies it only in memory. A\nmissing, malformed or stale projection fails closed before network I\u002FO. Direct\nprovider mode remains untouched.\n\nThe Gateway patch never chooses a model or thinking level. When the Captain has\nselected either axis, follow `$agentos-harnesses` and add\n`AGENTOS_MODEL=openai-codex\u002F\u003Cmodel>` and, if selected,\n`AGENTOS_THINKING=\u003Clevel>` to the reviewed `prepare-home` overlay separately.\nThe reconciler requires an exact pinned Pi provider\u002Fmodel and fails before\ncommit on an unknown selection. Verify the effective live provider\u002Fmodel after\nthe rollout; readiness itself makes no model request. Do not edit the managed\nprovider entry or ownership marker directly.\n\nThe shared AgentOS session-lifecycle extension independently adds server-side\ncompaction while preserving Pi's built-in transport; its artifact and fallback\ncontract is documented in [`ARCHITECTURE.md`](..\u002F..\u002F..\u002F..\u002FARCHITECTURE.md).\n\nA selected Mate may retain its direct Pi login as a recovery path while a\nCodex Crewmate or trusted automation explicitly uses the managed provider.\nConfigure and verify that process through the same selected\nclient boundary; do not require an unrelated second browser login merely\nbecause the automation uses another harness.\n\nFor a Codex Crewmate, `prepare-home` atomically owns the reserved\n`model_providers.agentos-gateway` entry in `~\u002F.codex\u002Fconfig.toml`. It uses the\nnative Responses wire API and Codex's command-backed provider authentication:\n\n```toml\n[model_providers.agentos-gateway]\nname = \"AgentOS Gateway\"\nbase_url = \"http:\u002F\u002Fagentgateway-openai.agentos.svc.cluster.local:8788\u002Fv1\"\nwire_api = \"responses\"\nsupports_websockets = false\nrequest_max_retries = 0\nstream_max_retries = 0\nenv_http_headers = { \"x-agentos-assignment-id\" = \"AGENTOS_ASSIGNMENT_ID\" }\n\n[model_providers.agentos-gateway.auth]\ncommand = \"\u002Fhome\u002Fagent\u002F.local\u002Fshare\u002Fmise\u002Fshims\u002Fbun\"\nargs = [\"\u002Fopt\u002Fagentos\u002Fpackages\u002Fagentos\u002Fruntime\u002Fcodex-token.ts\"]\ntimeout_ms = 5000\nrefresh_interval_ms = 60000\n```\n\nCodex invokes that helper natively, refreshes proactively and retries auth once.\nThe helper prints only the current validated projected token on success. It\ndoes not wrap Codex and never persists the token. The managed entry can expose\na different model-picker surface than ChatGPT login, so select and verify the\nexact model before dispatch.\n\n## Verify, recover and retire\n\nVerify public `\u002Freadyz`, operator-authenticated `\u002Freadyz\u002Fclient`,\n`ai-gateway status`, the selected Agent environment and one separately\nauthorized short fixed no-tool response. Both readiness endpoints are local,\nread-only eligibility diagnostics and never refresh a credential, probe quota,\nsend a prompt or reserve an account. The client endpoint uses the operator\nSecret and does not prove inference authorization. `ready` means a locally\neligible route or explicit API-key fallback exists; `degraded` keeps the Pod\nready when valid credentials exist\nbut cached capacity is unknown or temporarily blocked; `not_ready` means the\noperator identity or provider credential boundary is unavailable. Pass the\noperator token through a header without printing it. Record only effective\nprovider\u002Fmodel, the opaque managed account label\u002FID\nand success. `quota-axi` may provide additional read-only provider observations;\nit never selects accounts or mutates the gateway.\n\n### Gateway-only First Mate recovery\n\nWhen a direct `pi -ne` control succeeds but First Mate fails through the\nGateway, change only the Gateway client boundary:\n\n1. Preserve the non-secret shape of `~\u002F.pi\u002Fagent\u002Fmodels.json`,\n   `~\u002F.local\u002Fstate\u002Fagentos\u002Fpi-provider.json`, and the effective StatefulSet\n   render as rollback evidence without recording Secret values.\n2. Replace `ai-gateway-client.yaml` in First Mate's overlay with\n   `patches\u002Fai-gateway-direct-auth.yaml`. That patch supplies only\n   `AGENTOS_PI_PROVIDER_MODE=direct` to `prepare-home`; the reconciler removes\n   only its marker-owned provider entry and ownership marker while preserving\n   `auth.json`, unrelated providers, saved model\u002Fthinking settings, and every\n   AgentOS extension. Do not edit either JSON file by hand.\n3. Render the replacement and confirm it removes `AI_GATEWAY_URL`,\n   `AGENTOS_EGRESS_TOKEN_FILE`, and\n   `agentos.akua.dev\u002Fagentgateway-client`, keeps the\n   standard `OTEL_*` environment, and does not remove the\n   `@akua-dev\u002Fagentos` package or its `agentos-observability`, `mate-memory`,\n   `openai-server-compaction`, background-task, or supervision registrations.\n4. Keep `AGENTOS_OPENAI_SERVER_COMPACTION_ENABLED` unset or true so portable\n   summary plus direct-provider server compaction remains active and observable.\n5. Roll out only First Mate, verify that `pi-provider.json` and only the managed\n   `openai-codex` override are absent, resume its native session, select the\n   direct provider\u002Fmodel, and run one short fixed no-tool response.\n6. After that successful direct reconciliation, remove\n   `ai-gateway-direct-auth.yaml`, roll out once more, and repeat the direct\n   provider\u002Fmodel check. Removing the Gateway patch before this handoff causes\n   `prepare-home` to fail closed instead of silently retaining stale routing.\n   Compare the same fresh\u002Fresumed session matrix before attributing the fault\n   to the Gateway.\n\nThis recovery does not disable a generic “Mate AI extension”: the Gateway is a\nprovider transport override, while AgentOS behavior remains independently\nloaded through the normal Pi extension entrypoint.\n\nAn upstream `401`, `429`, timeout or provider error is expected to reach the\nharness. Inspect the native harness error, `ai-gateway status`, Pod\u002FPVC state\nand non-secret account list. Reauthenticate the affected opaque account with a\nfresh `ai-gateway login`; do not delete the old chain until replacement is\nverified. Do not restart an Agent merely to hide quota failure and do not add a\nsilent cross-account retry.\n\nTo retire the capability, first return every client to verified direct auth and\nremove its gateway provider environment\u002Flabel. Then stop the StatefulSet, revoke\nor remove managed accounts and the operator Secret, and ask separately before\ndeleting the retained PVC. A rollback that leaves provider credentials or an\nuntracked authorization route behind is incomplete.\n\n## External Cloudflare Worker\n\nUse this final posture only when the Captain deliberately chooses one\nexternally hosted `codex-router` Worker as a separate capacity authority,\nnormally because non-AgentOS clients must use it too. An AgentOS-only Fleet\nshould use the in-cluster Gateway instead.\n\nBefore connecting any Agent:\n\n1. Verify the exact `akua-dev\u002Fcodex-router` release supports standalone direct\n   Cloudflare egress, subscription OAuth, the AgentOS correlation-header\n   boundary, and byte-preserving Responses streaming. Do not infer support from\n   an OpenAI-compatible URL.\n2. Keep the Worker's OAuth pool and routing state separate from the in-cluster\n   Gateway. Never share one refresh chain between both authorities.\n3. Never route the Worker into `Service\u002Fai-gateway`, route the in-cluster\n   Gateway through the Worker, or expose the Fleet Gateway with an Ingress.\n4. Give a selected Pi client the external HTTPS base URL and\n   `X-AI-Router-Token: $AI_GATEWAY_TOKEN`; give native Codex the external\n   `\u002Fv1` base URL with `env_key=\"AI_GATEWAY_TOKEN\"`. Keep the Secret-backed\n   environment and explicit provider\u002Fmodel verification from the in-cluster\n   procedure.\n5. Treat Cloudflare Workers Observability as the router's default log and trace\n   view. Native Workers logs and traces are available on Free with their\n   documented event and retention limits. External OTLP export is a separate\n   Workers Paid feature. AgentOS's Collector remains authoritative for the\n   in-cluster client spans; do not claim one joined trace until deployed\n   propagation evidence proves it.\n6. Preserve privacy-safe AgentOS operation and attempt identifiers only through\n   the Worker's reviewed bounded correlation contract. Never export prompts,\n   response bodies, credentials, headers, provider account identity, or\n   arbitrary errors.\n\nSee the official Cloudflare documentation for\n[Workers Logs](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Flogs\u002Fworkers-logs\u002F),\n[Workers Traces](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Ftraces\u002F),\n[OpenTelemetry export](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Fexporting-opentelemetry-data\u002F),\nand current\n[trace-propagation limitations](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fobservability\u002Ftraces\u002Fknown-limitations\u002F).\n",{"name":5,"description":7},"main","a30d855b06853c98477c6121238e4202e3b0b26a","packages\u002Fagentos\u002Fskills\u002Fagentos-ai-gateway",0,"https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos","https:\u002F\u002Fagentos.akua.dev","https:\u002F\u002Fgithub.com\u002Fakua-dev","https:\u002F\u002Fakua.dev","The product factory for Agentic organizations. On infrastructure you own. Production safe.","2026-11-09 00:04:56",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add akua-dev\u002Fagentos --skill agentos-ai-gateway",{"tool":40,"command":41},"bunx","bunx skills add akua-dev\u002Fagentos --skill agentos-ai-gateway",{"tool":43,"command":44},"pnpm","pnpm dlx skills add akua-dev\u002Fagentos --skill agentos-ai-gateway","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-ai-gateway\u002FSKILL.md",true,[48],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"agents\u002Fopenai.yaml","REFERENCE","参考文档",216,"https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-ai-gateway\u002Fagents\u002Fopenai.yaml",[55,62,69,76,83,90],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M793C3FRBZDFZK0XB78SFEJN","example-replacement","Reconcile the example replacement AgentOS distribution.","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Ftests\u002Ffixtures\u002Freplacement-package\u002Fskills\u002Fexample-replacement\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M793C1KCJE8E61R5PR5RWR6G","example-additive","Inspect the example additive AgentOS behavior.","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Ftests\u002Ffixtures\u002Fadditive-package\u002Fskills\u002Fexample-additive\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M793BW3E0NPHQKV45PRTTMKN","agentos-upgrade","Upgrade one persistent AgentOS Mate or, from First Mate with exact Captain authority, every active persistent Mate in one Fleet to an exact published stable release, including its run-once released database migrations. Use for stable First- or Second-Mate updates, resumed post-replacement verification, and authorized rollback boundaries. Do not use for dogfood, Crewmates, provisioning, retired Mates, services, or another Fleet.","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-upgrade\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M793BPJ6SKYM1NWACHYG0TRM","agentos-supervision","Reconcile and supervise an AgentOS Mate's direct reports across PostgreSQL, Kubernetes, Herdr, PVCs, and Git. Use at every First- or Second-Mate session start, after restart or compaction, while delegated work is active, when Inbox or runtime state changes, and for blocked, stale, stuck, failed, interrupted, or recovering agents.","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-supervision\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M793BGQANFJYYX8NBHCRKPKM","agentos-secrets","Safely create, retry, rotate, take over, roll back, project, and revoke AgentOS-managed Kubernetes Secrets without retaining or printing credential bytes. Use whenever an AgentOS workflow moves credential files into Kubernetes, changes an existing managed Secret, verifies a projected credential, encounters conflicting Secret ownership or legacy annotations, or retires a Kubernetes-delivered credential.","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-secrets\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M793BCNKCQAKK00BK32651HC","agentos-runtime","Inspect, create, and operate AgentOS runtime pods, Kustomize overlays, Herdr sessions, Mise toolchains, agent worktrees, terminals, PVCs, Kubernetes health, attach paths and runtime recovery. Use for normal First- or Second-Mate Kubernetes operations, child-Agent workload creation, tool resolution, stuck-agent debugging, remote terminal access, pod or session recovery, and readiness diagnosis.","https:\u002F\u002Fgithub.com\u002Fakua-dev\u002Fagentos\u002Fblob\u002Fmain\u002Fpackages\u002Fagentos\u002Fskills\u002Fagentos-runtime\u002FSKILL.md",[],[]]