TypeClawEnvironment variables
Every TYPECLAW_* env var the runtime reads
Host stage
| Variable | Read by | Default | Effect |
|---|---|---|---|
TYPECLAW_HOME | hostd, CLI | ~/.typeclaw | Override the host daemon state directory; primarily for tests |
TYPECLAW_LOG_LEVEL | CLI | info | debug / info / warn / error |
TYPECLAW_DEBUG | CLI | unset | Anything truthy enables verbose tracing |
Container stage (set by typeclaw start)
| Variable | Set on docker run | Effect |
|---|---|---|
TYPECLAW_CONTAINER_NAME | always | The container's name; container code uses it to identify itself to hostd |
TYPECLAW_HOSTD_URL | when hostd HTTP control is enabled | http://host.docker.internal:<port> — used by the agent's restart tool |
TYPECLAW_HOSTD_TOKEN | per-container, generated at start | Bearer token for the HTTP control surface; per-container restart RPC |
TYPECLAW_HOSTD_BROKER_TOKEN | per-container, generated at start | Auth token for the portbroker WebSocket connection |
TYPECLAW_NETWORK_BLOCK_INTERNAL | when network.blockInternal: true | 1 — entrypoint shim installs the iptables egress filter |
TYPECLAW_SANDBOX_SYMLINKS | when sandbox.symlinks is non-empty | base64-encoded JSON of the sandbox.symlinks array; the entrypoint shim decodes it and creates each from -> /agent/<to> symlink at the real container $HOME for unsandboxed bash |
DISPLAY | when docker.file.xvfb is enabled | :99 — points at the in-container Xvfb server |
Provider credentials
Set in the host stage; injected into the container via --env-file .env.
These env vars override a stored API-key credential in secrets.json (env-wins). The exception is dual-auth providers (anthropic, xai): a stored OAuth credential takes precedence over the env var, since OAuth is stateful and refreshed on disk. See /concepts/secrets-policy for the full resolution order.
| Variable | Provider | Notes |
|---|---|---|
FIREWORKS_API_KEY | fireworks | |
OPENAI_API_KEY | openai | |
ANTHROPIC_API_KEY | anthropic | OAuth credential on disk wins over this env var (dual-auth provider). |
ZAI_API_KEY | zai | Z.AI pay-as-you-go. |
ZAI_CODING_API_KEY | zai-coding | Z.AI GLM Coding Plan — separate billing surface from zai. |
XAI_API_KEY | xai | xAI (Grok). OAuth credential on disk wins over this env var (dual-auth provider). |
MINIMAX_API_KEY | minimax | Accepts either a pay-as-you-go API key or a Token Plan Subscription Key (sk-cp-…) — same slot. |
DEEPSEEK_API_KEY | deepseek | DeepSeek pay-as-you-go. |
| (others) | Each known provider has a canonical env var; see /reference/secrets-json |
Custom env-var names are supported via the Secret's env field — { "key": { "env": "MY_OPENAI" } }. See /concepts/secrets-policy for resolution order.
Provider endpoint overrides
Set in the host stage; injected into the container via --env-file .env.
| Variable | Provider | Default | Effect |
|---|---|---|---|
ANTHROPIC_BASE_URL | anthropic | https://api.anthropic.com | Point the Anthropic provider at an Anthropic-compatible endpoint. |
OPENAI_BASE_URL | openai | https://api.openai.com/v1 | Point the OpenAI provider at an OpenAI-compatible endpoint. |
ANTHROPIC_BASE_URL routes the anthropic provider through a proxy that speaks the native Anthropic Messages protocol (/v1/messages, x-api-key or OAuth Bearer) — e.g. LiteLLM, Cloudflare AI Gateway, or a corporate gateway. It is a base-URL swap only; it does not enable raw AWS Bedrock, which requires SigV4 signing and a different request path.
OPENAI_BASE_URL does the same for the openai provider, routing it through an OpenAI-compatible endpoint (LiteLLM, Azure-style gateways, corporate proxies). It targets the api-key openai provider only — the OAuth-only openai-codex ChatGPT backend is unaffected.
Both follow the same rules: trailing slashes are stripped; a non-http(s) value fails the agent at boot. The same endpoint is used by typeclaw init's API-key validation probe.
Channel credentials (env-wins)
| Variable | Adapter | Field |
|---|---|---|
SLACK_BOT_TOKEN | slack-bot | botToken |
SLACK_APP_TOKEN | slack-bot | appToken |
DISCORD_BOT_TOKEN | discord-bot | token |
TELEGRAM_BOT_TOKEN | telegram-bot | token |
GITHUB_TOKEN | github | PAT path |
KakaoTalk does not have an env-wins path — credentials live exclusively in secrets.json#channels.kakaotalk because the renewal cron needs the structured per-account record.
Container-side standard variables
| Variable | Set by | Effect |
|---|---|---|
TZ | passed through from host or typeclaw.json#docker.runArgs.append | cron schedule timezone if no per-job override |
HOME | container default | /root |
SHELL | container default | /bin/bash if installed, else /bin/sh |