Environment Variables

This reference lists the environment variables most projects need when running KsADK locally or in a release pipeline. Use placeholders in committed files and put real values in local .env files or CI secrets.

Model Provider

OpenAI-compatible provider and hosted runtime model policy variables.

Variable	Purpose
`OPENAI_API_KEY`	API key for an OpenAI-compatible model provider
`OPENAI_BASE_URL`	provider base URL, usually ending in `/v1`
`OPENAI_API_BASE`	compatibility alias for `OPENAI_BASE_URL`
`OPENAI_MODEL_NAME`	default model name used by local runners and UI
`AGENTENGINE_MODEL_POLICY_JSON`	model policy JSON injected by hosted runtimes to declare primary / multimodal / fallback defaults
`OPENAI_FALLBACK_MODEL_NAME`	compatibility fallback model variable read by Hermes-style runtimes
`HERMES_DEFAULT_MODEL`	explicit Hermes default model override
`HERMES_FALLBACK_MODEL`	explicit Hermes fallback model override
`HERMES_MODEL_CATALOG_JSON`	Hermes model catalog JSON; overrides policy default catalog
`OPENCLAW_DEFAULT_MODEL`	explicit OpenClaw default model override
`OPENCLAW_FALLBACK_MODEL`	explicit OpenClaw fallback model override
`OPENCLAW_IMAGE_MODEL`	explicit OpenClaw multimodal / image model override
`OPENCLAW_MODEL_CATALOG_JSON`	OpenClaw model catalog JSON; overrides policy default catalog
`MODEL_NAME`	compatibility alias used by some projects

Example:

bash

OPENAI_API_KEY=sk-test
OPENAI_BASE_URL=https://api.example.com/v1
OPENAI_MODEL_NAME=my-model

Unified Model Policy And Fallback (0.6.6+)

Hosted deployments can inject a shared policy through AGENTENGINE_MODEL_POLICY_JSON. Hermes, OpenClaw, and generic agents share one default semantics. In 0.6.6, model policy v1 defaults to glm-5.2 as the primary model, kimi-k2.7-code as the multimodal model, and deepseek-v4-pro as the fallback model. Explicit request fields and explicit environment-variable overrides (such as HERMES_DEFAULT_MODEL / OPENCLAW_FALLBACK_MODEL) still take precedence over policy defaults.

Fallback retry semantics: the conversation runtime automatically retries once with the fallback model on recoverable errors (timeout, rate limit, 5xx, model unavailable, permission/quota); 400 parameter errors, business errors, and tool errors are not swallowed.
Reasoning declaration (0.6.7): DEFAULT_MODEL_POLICY adds a reasoning: true declaration per model, and the catalog output exposes a reasoning field so the console can tell whether a model supports thinking.
Thinking-disable injection (0.6.7): when model_options.thinking is disabled (reasoning.effort=none, or thinking.type=disabled, or max_reasoning_tokens<=0), the runtime auto-injects enable_thinking=false and chat_template_kwargs.enable_thinking=false into extra_body (DeepSeek-style compatibility) and filters reasoning output items from the stream.

Project And Local UI

Variable	Purpose
`KSADK_PROJECT_DIR`	project directory resolved by `agentengine web`
`AGENTENGINE_UI_DIR`	local UI state directory; defaults under `.agentengine/ui`
`KSADK_UI_PROFILE`	Agent UI profile selector; `custom` exposes custom UI bootstrap (0.6.7)
`KSADK_UI_PATH`	custom UI mount path, e.g. `/` or `/research`; `/chat` is auto-rewritten to `/` for custom profile (0.6.7)
`KSADK_UI_URL`	external custom UI URL (0.6.7)
`KSADK_UI_BUNDLE_PATH`	custom UI static bundle path relative to project; local auto-detects `research-ui/dist` (0.6.7)
`KSYUN_REGION`	region used by cloud actions and some SDK clients

Cloud Account Identity Resolution

Variable	Purpose
`KSYUN_IAM_ENDPOINT`	Optional public IAM endpoint override; defaults to `iam.api.ksyun.com` when unset
`KSYUN_IAM_INTRANET_URL`	Optional IAM intranet endpoint fallback override; defaults to `iam.inner.api.ksyun.com` when unset
`IAM_INTRANET_URL`	Compatibility alias for `KSYUN_IAM_INTRANET_URL`

When public IAM returns an error such as “inner account can only access through intranet”, the runtime retries the intranet endpoint. Public environments normally do not hit this branch; internal environments can override the address with KSYUN_IAM_INTRANET_URL or IAM_INTRANET_URL.

Session Storage

Variable	Purpose
`KSADK_SESSION_BACKEND`	session backend, for example `local` or `postgres`
`AGENTENGINE_SESSION_BACKEND`	compatibility alias for session backend
`KSADK_SESSION_DSN`	PostgreSQL or shared backend DSN
`KSADK_SESSION_PATH`	local session database path
`KSADK_SESSION_NAMESPACE`	namespace for shared session backends
`KSADK_SESSION_CONNECT_TIMEOUT`	PostgreSQL session backend connect timeout in seconds, default `5`; on failure raises `SessionBackendUnavailable` and server returns 503 instead of 500 (0.6.7)
`KSADK_STM_BACKEND`	short-term memory/session backend compatibility variable
`KSADK_STM_PATH`	local SQLite path for UI/session state
`KSADK_STM_DB_PATH`	compatibility alias for local SQLite path
`KSADK_STM_URL`	compatibility DSN for database-backed session state
`KSADK_STM_DB_URL`	compatibility DSN for database-backed session state
`KSADK_ADK_SESSION_BACKEND`	ADK-native session backend selector
`KSADK_ADK_SESSION_PATH`	ADK-native SQLite session path
`KSADK_ADK_SESSION_URL`	ADK-native database session URL
`KSADK_TENANT_ID`	tenant id used for session namespace scoping
`KSADK_WORKSPACE_ID`	workspace id used for session namespace scoping
`AGENTENGINE_TENANT_ID`	compatibility tenant id
`AGENTENGINE_WORKSPACE_ID`	compatibility workspace id

Local UI usually sets:

bash

KSADK_STM_BACKEND=sqlite
KSADK_STM_PATH=.agentengine/ui/sessions.sqlite

Checkpoint Storage

Variable	Purpose
`KSADK_CHECKPOINT_BACKEND`	checkpoint backend: `local` / `sqlite` / `memory` / `postgres`; default `local` (0.6.7)
`KSADK_CHECKPOINT_PATH`	local SQLite checkpoint path, default `.agentengine/ui/checkpoints.sqlite` (0.6.7)
`KSADK_LANGGRAPH_CHECKPOINT_DSN`	LangGraph PostgreSQL checkpoint DSN; required when backend is `postgres` (0.6.7)

Local agentengine web defaults to local session backend and SQLite LangGraph checkpoints, reducing the local resume path's dependency on PostgreSQL (0.6.7).

Ambient Runtime Context

Variable	Purpose
`KSADK_KB_AMBIENT_ENABLED`	enable runtime-injected knowledge context; default enabled
`KSADK_KB_AMBIENT_POLICY`	`on_demand`, `always`, or `disabled`
`KSADK_LTM_AMBIENT_ENABLED`	enable runtime-injected memory context; default enabled
`KSADK_LTM_AMBIENT_POLICY`	`on_demand`, `always`, or `disabled`
`KSADK_LTM_AUTO_SAVE`	save completed turns to long-term memory when supported
`KSADK_LTM_AGENT_ID`	agent id recorded with memory entries

Workspace Files

Variable	Purpose
`KSADK_WORKSPACE_FILES_ENABLED`	enable workspace file routes
`KSADK_WORKSPACE_ROOT_LABEL`	display label for the workspace root
`KSADK_WORKSPACE_MAX_UPLOAD_BYTES`	single upload size limit

Long-Term Memory

Variable	Purpose
`KSADK_LTM_BACKEND`	memory backend: `local`, `http`, or `sdk`
`KSADK_LTM_TOP_K`	default number of memories to retrieve
`KSADK_LTM_INDEX`	local or generic memory index name
`KSADK_LTM_APP_NAME`	application name used by memory service
`KSADK_LTM_HTTP_URL`	HTTP memory backend URL
`KSADK_LTM_HTTP_TOKEN`	HTTP memory backend token
`KSADK_LTM_ACCESS_KEY`	SDK memory access key; can fall back to cloud AK env vars
`KSADK_LTM_SECRET_KEY`	SDK memory secret key; can fall back to cloud SK env vars
`KSADK_LTM_REGION`	SDK memory region
`KSADK_LTM_ENDPOINT`	SDK memory endpoint
`KSADK_LTM_SCHEME`	SDK memory scheme, usually `https`
`KSADK_LTM_NAMESPACE`	SDK memory namespace
`KSADK_LTM_AGENT_ID`	agent id recorded with memory entries
`KSADK_LTM_SCENE_ID`	scene id, default `_sys_general`
`KSADK_LTM_AUTO_SAVE`	enable automatic memory saving when supported
`KSADK_MEMORY_BACKEND`	generic memory backend selector for legacy integrations
`KSADK_MEMORY_URL`	generic memory backend URL
`KSADK_MEMORY_PREFIX`	generic memory key prefix
`KSADK_MEMORY_TTL`	generic memory TTL in seconds

Knowledge Base

Variable	Purpose
`KSADK_KB_DATASET_ID`	enable a knowledge dataset integration
`KSADK_KB_TOP_K`	number of snippets to retrieve
`KSADK_KB_ACCESS_KEY`	optional knowledge SDK access key
`KSADK_KB_SECRET_KEY`	optional knowledge SDK secret key
`KSADK_KB_REGION`	knowledge service region
`KSADK_KB_ENDPOINT`	knowledge service endpoint
`KSADK_KB_SEARCH_METHOD`	retrieval method, default `intelligence_search`
`KSADK_KB_SCORE_THRESHOLD`	optional score threshold
`KSADK_KB_RERANKING_ENABLE`	enable reranking when supported

Skill Runtime

Variable	Purpose
`KSADK_SKILL_SPACE_IDS`	comma-separated Skill Space ids
`SKILL_SPACE_ID`	compatibility alias for a single Skill Space id
`KSADK_PUBLIC_SKILL_SPACE_IDS`	comma-separated public Skill Space ids appended after user spaces
`KSADK_PUBLIC_SKILL_ALLOWLIST`	comma-separated public Skill names to expose
`KSADK_LOCAL_SKILLS_DIR`	local directory containing `SKILL.md` packages
`KSADK_SELECTED_SKILL_NAMES`	comma-separated Skill names selected by an outer agent
`KSADK_SKILLS_MODE`	Skill loading mode: `auto`, `local`, or `sandbox`
`KSADK_SKILL_SERVICE_URL`	Skill Service endpoint
`KSADK_SKILL_SERVICE_TOKEN`	Skill Service bearer token when token auth is used
`KSADK_SKILL_SERVICE_ACCESS_KEY`	signed Skill Service access key
`KSADK_SKILL_SERVICE_SECRET_KEY`	signed Skill Service secret key
`KSADK_SKILL_SERVICE_ACCOUNT_ID`	account id for signed requests
`KSADK_SKILL_SERVICE_REGION`	Skill Service region
`KSADK_SKILL_SERVICE_API_VERSION`	Skill Service API version
`KSADK_SKILL_SERVICE_SIGN_SERVICE`	signing service name
`KSADK_SKILL_CACHE_DIR`	local cache for downloaded skill packages
`KSADK_SKILL_ALLOW_HASH_MISMATCH`	allow unverified skill package preview
`KSADK_SKILL_MANIFEST_TIMEOUT`	remote Skill manifest listing timeout in seconds
`KSADK_SKILL_MANIFEST_LIMIT`	maximum manifests injected into agent instructions
`KSADK_SKILL_RUNTIME_BACKEND`	isolated execution backend, for example `local_process` or `e2b`
`KSADK_SKILL_RUNTIME_TEMPLATE_ID`	runtime template id
`KSADK_SANDBOX_BACKEND`	sandbox backend selector used as a compatibility fallback
`KSADK_SANDBOX_TEMPLATE_ID`	sandbox template id; also enables E2B-style backend
`KSADK_SKILL_RUNTIME_TIMEOUT`	isolated execution timeout in seconds
`KSADK_SANDBOX_TIMEOUT`	sandbox timeout compatibility variable
`KSADK_SKILL_RUNTIME_ALLOW_INTERNET_ACCESS`	allow internet access for sandbox execution
`KSADK_SKILL_RUNTIME_AGENT_PATH`	local process runtime agent path
`KSADK_SKILL_WORKDIR`	workspace directory exposed to skill execution
`KSADK_SKILL_ARTIFACT_PROJECT`	artifact project name for generated outputs

Tool Gateway

Variable	Purpose
`KSADK_TOOL_APPROVAL_MODE`	tool approval mode; set to `strict` to make medium / high / critical risk tools return `approval_required` before execution

MCP

Variable	Purpose
`KSADK_ENABLE_MCP_TOOLS`	enable or disable MCP tools
`KSADK_MCP_SERVERS`	JSON array of MCP server definitions
`KSADK_BUILD_ENABLE_MCP`	include MCP runtime dependencies during code build

Example:

bash

KSADK_ENABLE_MCP_TOOLS=1
KSADK_MCP_SERVERS='[{"name":"docs","url":"http://127.0.0.1:9000/mcp"}]'

Build And Packaging

Variable	Purpose
`KSADK_BUILD_PIP_INSTALL_TIMEOUT_SECONDS`	pip install timeout in build flows
`KSADK_BUILD_ENABLE_ATTACHMENT_OCR`	include OCR-related attachment dependencies
`KSADK_BUILD_ENABLE_POSTGRES_SESSION`	include PostgreSQL session dependencies

Object Storage Credentials (KS3)

Variable	Purpose
`KS3_BUCKET`	KS3 bucket name; derived from `account_id` + `region` when unset
`KS3_REGION`	KS3 region; falls back to `KSYUN_REGION`, default `cn-beijing-6`
`KS3_ACCESS_KEY`	KS3 access key; can fall back to cloud AK env vars (sensitive)
`KS3_SECRET_KEY`	KS3 secret key; can fall back to cloud SK env vars (sensitive)

Image Registry Credentials

Variable	Purpose
`KCR_REGISTRY`	image registry address
`KCR_ENDPOINT`	image registry endpoint
`KCR_USERNAME`	image registry username; required for enterprise KCR and third-party registries (sensitive)
`KCR_PASSWORD`	image registry password; required for enterprise KCR and third-party registries (sensitive)

Personal KCR (*.kce.ksyun.com) allows KSYUN_ACCOUNT_ID to fall back as the username; enterprise KCR (*.ksyunkcr.com) and third-party registries must set KCR_USERNAME / KCR_PASSWORD explicitly, to avoid wrongly using the cloud account id as an enterprise image username (0.6.5).

Build Context .env Boundary

agentengine deploy and agentengine launch support --env KEY=VALUE (repeatable) and --env-file for runtime environment variables; explicit env goes into the deploy payload env_vars. Real .env / .env.local files are excluded from Code, Container, and MCP build contexts; only .env.example / .env.sample / .env.template template files are kept (0.6.5).

Web UI Static Sync

Variable	Purpose
`KSADK_WEB_VERSION`	`@kingsoftcloud/ksadk-web` npm dist-tag or version used by `make sync-ksadk-web-static`; default `latest`
`KSADK_WEB_PACKAGE`	npm package name used for local UI static sync; default `@kingsoftcloud/ksadk-web`
`KSADK_WEB_TARBALL_NAME`	saved filename when `KSADK_WEB_RELEASE_URL` is set; npm pack mode uses the real tarball filename returned by npm
`KSADK_WEB_RELEASE_URL`	optional fallback; when set, skips npm pack and downloads from this tarball URL
`KSADK_WEB_CACHE_DIR`	KsADK Web package extraction cache directory; default `.cache/ksadk-web`

make build / make build-wheel automatically run sync-ksadk-web-static; no manual sync needed.

Observability

Variable	Purpose
`OTEL_SERVICE_NAME`	OpenTelemetry service name; also used as an agent name fallback
`OTEL_RESOURCE_ATTRIBUTES`	OpenTelemetry resource attributes as comma-separated `key=value` pairs
`OTEL_EXPORTER_OTLP_ENDPOINT`	generic OTLP HTTP endpoint; KsADK derives `/v1/traces` when no traces endpoint is set
`OTEL_EXPORTER_OTLP_PROTOCOL`	generic OTLP protocol; KsADK auto HTTP exporter supports `http/protobuf`
`OTEL_EXPORTER_OTLP_HEADERS`	generic OTLP HTTP headers, comma-separated with URL-encoded values; may contain auth data
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	traces-specific OTLP HTTP endpoint; takes precedence over the generic endpoint
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	traces-specific OTLP protocol; takes precedence over the generic protocol
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	traces-specific OTLP HTTP headers; takes precedence over generic headers and may contain auth data
`KSADK_OTLP_MAX_EXPORT_BATCH_SIZE`	maximum spans exported per OTLP batch, default `64`, to avoid oversized collector requests
`LANGFUSE_PUBLIC_KEY`	compatibility path for older Langfuse tracing auto-configuration
`LANGFUSE_SECRET_KEY`	Langfuse secret
`LANGFUSE_BASE_URL`	Langfuse base URL
`LANGFUSE_HOST`	compatibility alias for Langfuse host
`LANGFUSE_USE_CALLBACK`	use framework callback mode instead of direct OTLP path
`SESSION_TITLE_MODEL`	model override for generated local session titles
`COMPACTION_DISABLE_SEMANTIC`	disable semantic session summary compaction
`COMPACTION_SUMMARY_TIMEOUT_MS`	timeout for summary generation
`COMPACTION_SUMMARY_MAX_GROUPS`	maximum message groups summarized
`COMPACTION_SUMMARY_MODEL`	model override for semantic summaries

CloudMonitor Dual-Write (CLOUD_MONITOR_*)

From 0.6.7, setup_tracing() auto-detects CLOUD_MONITOR_* environment variables and mounts the CloudMonitor OTLP exporter and the CloudMonitor Langfuse SDK CallbackHandler in parallel; neither suppresses self-hosted Langfuse or standard OTLP, and a single span can be reported to both the self-hosted cluster and the CloudMonitor trace platform at once.

Variable	Purpose
`CLOUD_MONITOR_APP_KEY`	CloudMonitor OTLP AppKey; injected as the `Ksc-Appkey` auth header (sensitive)
`CLOUD_MONITOR_OTLP_ENABLED`	explicitly enable or disable the CloudMonitor OTLP exporter; auto-detected by default
`CLOUD_MONITOR_OTLP_ENDPOINT`	CloudMonitor generic OTLP HTTP endpoint; derives `/v1/traces` when no traces endpoint is set
`CLOUD_MONITOR_OTLP_PROTOCOL`	CloudMonitor generic OTLP protocol; currently supports `http/protobuf`
`CLOUD_MONITOR_OTLP_HEADERS`	CloudMonitor OTLP extra headers, comma-separated and URL-encoded (sensitive)
`CLOUD_MONITOR_OTLP_TRACES_ENDPOINT`	CloudMonitor traces-specific endpoint; takes precedence over the generic endpoint
`CLOUD_MONITOR_OTLP_TRACES_PROTOCOL`	CloudMonitor traces-specific protocol; takes precedence over the generic protocol
`CLOUD_MONITOR_LANGFUSE_ENABLED`	explicitly enable or disable the CloudMonitor Langfuse SDK callback; auto-detected by default
`CLOUD_MONITOR_LANGFUSE_HOST`	CloudMonitor AppMonitor Langfuse SDK host; falls back to `CLOUD_MONITOR_OTLP_ENDPOINT`
`CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY`	CloudMonitor Langfuse public key (sensitive)
`CLOUD_MONITOR_LANGFUSE_SECRET_KEY`	CloudMonitor Langfuse secret key (sensitive)

Set CLOUD_MONITOR_OTLP_ENABLED=false or CLOUD_MONITOR_LANGFUSE_ENABLED=false to disable the corresponding path.

Safety Rules

Never commit real values for keys, tokens, DSNs, private endpoints, customer dataset ids, or kubeconfigs.
Prefer local .env for development and CI secrets for automation.
Keep public docs on placeholders such as sk-test, my-model, and https://api.example.com/v1.

Environment Variables

On this page