本页列出本地运行和发布流水线中最常用的 KsADK 环境变量。提交到仓库的文件只放占位值，真实值放本地 .env 或 CI secrets。
OpenAI 兼容 provider 与托管运行时模型策略相关变量。
变量 用途 OPENAI_API_KEYOpenAI 兼容模型 provider 的 API Key OPENAI_BASE_URLprovider base URL，通常以 /v1 结尾 OPENAI_API_BASEOPENAI_BASE_URL 的兼容别名OPENAI_MODEL_NAME本地 runner 和 UI 使用的默认模型 AGENTENGINE_MODEL_POLICY_JSON托管运行时注入的模型策略 JSON，可统一声明 primary / multimodal / fallback 默认值 OPENAI_FALLBACK_MODEL_NAME通用 fallback 模型兼容变量，Hermes 等运行时可读取 HERMES_DEFAULT_MODELHermes 显式默认模型覆盖 HERMES_FALLBACK_MODELHermes 显式 fallback 模型覆盖 HERMES_MODEL_CATALOG_JSONHermes 模型 catalog JSON，覆盖策略默认 catalog OPENCLAW_DEFAULT_MODELOpenClaw 显式默认模型覆盖 OPENCLAW_FALLBACK_MODELOpenClaw 显式 fallback 模型覆盖 OPENCLAW_IMAGE_MODELOpenClaw 显式多模态 / 图像模型覆盖 OPENCLAW_MODEL_CATALOG_JSONOpenClaw 模型 catalog JSON，覆盖策略默认 catalog MODEL_NAME一些项目使用的兼容别名
示例：
OPENAI_API_KEY = sk-test OPENAI_BASE_URL = https://api.example.com/v1 OPENAI_MODEL_NAME = my-model 托管部署中，平台可以通过 AGENTENGINE_MODEL_POLICY_JSON 注入统一模型策略，Hermes、OpenClaw 和通用 Agent 共用同一套默认语义。0.6.6 默认策略 v1 使用 glm-5.2 作为主模型、kimi-k2.7-code 作为多模态模型、deepseek-v4-pro 作为 fallback；显式请求参数或显式环境变量（如 HERMES_DEFAULT_MODEL / OPENCLAW_FALLBACK_MODEL）仍优先于策略默认值。
fallback 重试语义 ：conversation runtime 对超时、限流、5xx、模型不可用、权限/配额等可恢复错误自动 fallback 重试一次；400 参数错误、业务错误和 tool 错误不会被吞掉。reasoning 声明（0.6.7） ：DEFAULT_MODEL_POLICY 每个模型新增 reasoning: true 声明，catalog 输出暴露 reasoning 字段，供控制台判断模型是否支持思考能力。thinking disable 注入（0.6.7） ：当 model_options.thinking 为 disabled（reasoning.effort=none 或 thinking.type=disabled 或 max_reasoning_tokens<=0）时，runtime 自动向 extra_body 注入 enable_thinking=false 和 chat_template_kwargs.enable_thinking=false（DeepSeek 等模型兼容），并在流式输出中过滤 reasoning 类 output item。
变量 用途 KSADK_PROJECT_DIRagentengine web 解析出的项目目录AGENTENGINE_UI_DIR本地 UI 状态目录，默认在 .agentengine/ui 下 KSADK_UI_PROFILEAgent UI profile 选择器，custom 时 runtime 暴露自定义 UI bootstrap（0.6.7） KSADK_UI_PATH自定义 UI 挂载路径，例如 / 或 /research；custom profile 的 /chat 自动修正为 /（0.6.7） KSADK_UI_URL外部自定义 UI URL（0.6.7） KSADK_UI_BUNDLE_PATH自定义 UI 静态 bundle 相对项目路径；本地默认自动探测 research-ui/dist（0.6.7） KSYUN_REGION云端 action 和部分 SDK client 使用的区域
变量 用途 KSYUN_IAM_ENDPOINT可选：覆盖 IAM 公网 endpoint；未配置时使用 iam.api.ksyun.com KSYUN_IAM_INTRANET_URL可选：覆盖 IAM 内网 endpoint fallback；未配置时使用默认 iam.inner.api.ksyun.com IAM_INTRANET_URLKSYUN_IAM_INTRANET_URL 的兼容别名
当公网 IAM 返回“inner account can only access through intranet”这类错误时，
运行时会尝试内网 endpoint。外部环境通常不会命中该分支；内部环境如需覆盖地址，
可设置 KSYUN_IAM_INTRANET_URL 或 IAM_INTRANET_URL。
变量 用途 KSADK_SESSION_BACKENDsession backend，例如 local 或 postgres AGENTENGINE_SESSION_BACKENDsession backend 兼容别名 KSADK_SESSION_DSNPostgreSQL 或共享后端 DSN KSADK_SESSION_PATH本地 session 数据库路径 KSADK_SESSION_NAMESPACE共享 session 后端命名空间 KSADK_SESSION_CONNECT_TIMEOUTPostgreSQL session backend 连接超时秒数，默认 5；连接失败抛 SessionBackendUnavailable，server 返回 503 而非 500（0.6.7） KSADK_STM_BACKEND短期记忆/session backend 兼容变量 KSADK_STM_PATH本地 SQLite UI/session 状态路径 KSADK_STM_DB_PATH本地 SQLite 路径兼容别名 KSADK_STM_URL数据库型 session 状态 DSN 兼容变量 KSADK_STM_DB_URL数据库型 session 状态 DSN 兼容变量 KSADK_ADK_SESSION_BACKENDADK 原生 session backend 选择器 KSADK_ADK_SESSION_PATHADK 原生 SQLite session 路径 KSADK_ADK_SESSION_URLADK 原生数据库 session URL KSADK_TENANT_IDsession 命名空间租户 id KSADK_WORKSPACE_IDsession 命名空间 workspace id AGENTENGINE_TENANT_ID租户 id 兼容变量 AGENTENGINE_WORKSPACE_IDworkspace id 兼容变量
本地 UI 通常设置：
KSADK_STM_BACKEND = sqlite KSADK_STM_PATH = .agentengine/ui/sessions.sqlite 变量 用途 KSADK_CHECKPOINT_BACKENDcheckpoint backend：local / sqlite / memory / postgres，默认 local（0.6.7） KSADK_CHECKPOINT_PATH本地 SQLite checkpoint 路径，默认 .agentengine/ui/checkpoints.sqlite（0.6.7） KSADK_LANGGRAPH_CHECKPOINT_DSNLangGraph PostgreSQL checkpoint DSN；postgres backend 时必传（0.6.7）
本地 agentengine web 默认使用 local session backend，LangGraph checkpoint 默认走 SQLite，降低本地恢复链路对 PostgreSQL 的依赖（0.6.7）。
变量 用途 KSADK_KB_AMBIENT_ENABLED启用运行时注入知识库上下文，默认启用 KSADK_KB_AMBIENT_POLICYon_demand、always 或 disabledKSADK_LTM_AMBIENT_ENABLED启用运行时注入记忆上下文，默认启用 KSADK_LTM_AMBIENT_POLICYon_demand、always 或 disabledKSADK_LTM_AUTO_SAVE支持时把完整对话轮次保存到长期记忆 KSADK_LTM_AGENT_ID记忆条目关联的 agent id
变量 用途 KSADK_WORKSPACE_FILES_ENABLED启用 workspace 文件路由 KSADK_WORKSPACE_ROOT_LABELworkspace 根目录显示名称 KSADK_WORKSPACE_MAX_UPLOAD_BYTES单文件上传大小上限
变量 用途 KSADK_LTM_BACKEND记忆 backend：local、http 或 sdk KSADK_LTM_TOP_K默认检索记忆条数 KSADK_LTM_INDEX本地或通用记忆索引名 KSADK_LTM_APP_NAME记忆服务应用名 KSADK_LTM_HTTP_URLHTTP 记忆 backend 地址 KSADK_LTM_HTTP_TOKENHTTP 记忆 backend token KSADK_LTM_ACCESS_KEYSDK 记忆 AK，可回退到云账号 AK 环境变量 KSADK_LTM_SECRET_KEYSDK 记忆 SK，可回退到云账号 SK 环境变量 KSADK_LTM_REGIONSDK 记忆区域 KSADK_LTM_ENDPOINTSDK 记忆 endpoint KSADK_LTM_SCHEMESDK 记忆协议，通常为 https KSADK_LTM_NAMESPACESDK 记忆 namespace KSADK_LTM_AGENT_ID记忆条目关联的 agent id KSADK_LTM_SCENE_ID场景 id，默认 _sys_general KSADK_LTM_AUTO_SAVE支持时启用自动记忆保存 KSADK_MEMORY_BACKEND旧版通用 memory backend 选择器 KSADK_MEMORY_URL旧版通用 memory backend URL KSADK_MEMORY_PREFIX旧版通用 memory key 前缀 KSADK_MEMORY_TTL旧版通用 memory TTL，单位秒
变量 用途 KSADK_KB_DATASET_ID启用知识库数据集集成 KSADK_KB_TOP_K检索片段数量 KSADK_KB_ACCESS_KEY可选知识库 SDK AK KSADK_KB_SECRET_KEY可选知识库 SDK SK KSADK_KB_REGION知识库服务区域 KSADK_KB_ENDPOINT知识库服务 endpoint KSADK_KB_SEARCH_METHOD检索方式，默认 intelligence_search KSADK_KB_SCORE_THRESHOLD可选分数阈值 KSADK_KB_RERANKING_ENABLE支持时启用 reranking
变量 用途 KSADK_SKILL_SPACE_IDS逗号分隔的 Skill Space id SKILL_SPACE_ID单个 Skill Space id 的兼容别名 KSADK_PUBLIC_SKILL_SPACE_IDS追加的公共 Skill Space id KSADK_PUBLIC_SKILL_ALLOWLIST允许暴露的公共 Skill 名称 KSADK_LOCAL_SKILLS_DIR包含 SKILL.md 包的本地目录 KSADK_SELECTED_SKILL_NAMES外层 Agent 选择的 Skill 名称 KSADK_SKILLS_MODESkill 加载模式：auto、local 或 sandbox KSADK_SKILL_SERVICE_URLSkill Service endpoint KSADK_SKILL_SERVICE_TOKENtoken 鉴权时的 Skill Service token KSADK_SKILL_SERVICE_ACCESS_KEY签名请求使用的 Skill Service AK KSADK_SKILL_SERVICE_SECRET_KEY签名请求使用的 Skill Service SK KSADK_SKILL_SERVICE_ACCOUNT_ID签名请求账号 id KSADK_SKILL_SERVICE_REGIONSkill Service 区域 KSADK_SKILL_SERVICE_API_VERSIONSkill Service API 版本 KSADK_SKILL_SERVICE_SIGN_SERVICE签名 service 名称 KSADK_SKILL_CACHE_DIR已下载 skill 包本地缓存目录 KSADK_SKILL_ALLOW_HASH_MISMATCH允许预览 hash 不匹配的 skill 包 KSADK_SKILL_MANIFEST_TIMEOUT远程 Skill manifest 列表超时时间，单位秒 KSADK_SKILL_MANIFEST_LIMIT注入到 Agent 指令中的 manifest 数量上限 KSADK_SKILL_RUNTIME_BACKEND隔离执行 backend，例如 local_process 或 e2b KSADK_SKILL_RUNTIME_TEMPLATE_IDruntime template id KSADK_SANDBOX_BACKENDsandbox backend 选择器兼容变量 KSADK_SANDBOX_TEMPLATE_IDsandbox template id，也会启用 E2B 风格 backend KSADK_SKILL_RUNTIME_TIMEOUT隔离执行超时时间，单位秒 KSADK_SANDBOX_TIMEOUTsandbox timeout 兼容变量 KSADK_SKILL_RUNTIME_ALLOW_INTERNET_ACCESSsandbox 执行是否允许访问互联网 KSADK_SKILL_RUNTIME_AGENT_PATHlocal process runtime 使用的 agent 路径 KSADK_SKILL_WORKDIR暴露给 skill 执行的工作目录 KSADK_SKILL_ARTIFACT_PROJECT产物项目名称
变量 用途 KSADK_TOOL_APPROVAL_MODE工具审批模式；设置为 strict 时 medium / high / critical 风险工具先返回 approval_required
变量 用途 KSADK_ENABLE_MCP_TOOLS启用或禁用 MCP tools KSADK_MCP_SERVERSMCP server 定义 JSON 数组 KSADK_BUILD_ENABLE_MCPcode build 时包含 MCP runtime 依赖
示例：
KSADK_ENABLE_MCP_TOOLS = 1 KSADK_MCP_SERVERS = '[{"name":"docs","url":"http://127.0.0.1:9000/mcp"}]' 变量 用途 KSADK_BUILD_PIP_INSTALL_TIMEOUT_SECONDSbuild 流程中 pip install 超时时间 KSADK_BUILD_ENABLE_ATTACHMENT_OCR包含 OCR 附件依赖 KSADK_BUILD_ENABLE_POSTGRES_SESSION包含 PostgreSQL session 依赖
变量 用途 KS3_BUCKETKS3 bucket 名；未设置时由 account_id + region 派生 KS3_REGIONKS3 区域，回退 KSYUN_REGION，默认 cn-beijing-6 KS3_ACCESS_KEYKS3 AK，可回退到云账号 AK 环境变量（敏感） KS3_SECRET_KEYKS3 SK，可回退到云账号 SK 环境变量（敏感）
变量 用途 KCR_REGISTRY镜像仓库地址 KCR_ENDPOINT镜像仓库 endpoint KCR_USERNAME镜像仓库用户名；企业版 KCR 和第三方 registry 必传（敏感） KCR_PASSWORD镜像仓库密码；企业版 KCR 和第三方 registry 必传（敏感）
个人版 KCR（*.kce.ksyun.com）允许 KSYUN_ACCOUNT_ID 兜底用户名；企业版 KCR（*.ksyunkcr.com）和第三方 registry 必须显式设置 KCR_USERNAME / KCR_PASSWORD，避免错误把云账号 ID 当企业镜像用户名（0.6.5）。
agentengine deploy 和 agentengine launch 支持 --env KEY=VALUE（可重复）和 --env-file 传入运行时环境变量，显式传入的 env 进入部署 payload env_vars。真实 .env / .env.local 不进入 Code、Container 或 MCP 构建上下文，只保留 .env.example / .env.sample / .env.template 模板文件（0.6.5）。
变量 用途 KSADK_WEB_VERSIONmake sync-ksadk-web-static 使用的 @kingsoftcloud/ksadk-web npm dist-tag 或版本，默认 latestKSADK_WEB_PACKAGE本地 UI static 同步使用的 npm 包名，默认 @kingsoftcloud/ksadk-web KSADK_WEB_TARBALL_NAME设置 KSADK_WEB_RELEASE_URL 时作为下载保存文件名；npm pack 模式使用 npm 返回的真实 tarball 文件名 KSADK_WEB_RELEASE_URL可选兜底；设置后跳过 npm pack，改从该 tarball URL 下载 KSADK_WEB_CACHE_DIRKsADK Web 包解压缓存目录，默认 .cache/ksadk-web
make build / make build-wheel 会自动执行 sync-ksadk-web-static，无需手动同步。
变量 用途 OTEL_SERVICE_NAMEOpenTelemetry service name，也可作为 agent name fallback OTEL_RESOURCE_ATTRIBUTESOpenTelemetry resource attributes，逗号分隔的 key=value OTEL_EXPORTER_OTLP_ENDPOINT通用 OTLP HTTP endpoint；未设置 traces endpoint 时会派生 /v1/traces OTEL_EXPORTER_OTLP_PROTOCOL通用 OTLP protocol；KsADK 自动 HTTP exporter 支持 http/protobuf OTEL_EXPORTER_OTLP_HEADERS通用 OTLP HTTP headers，逗号分隔且 value URL encoded，可能包含鉴权信息 OTEL_EXPORTER_OTLP_TRACES_ENDPOINTtraces 专用 OTLP HTTP endpoint，优先于通用 endpoint OTEL_EXPORTER_OTLP_TRACES_PROTOCOLtraces 专用 OTLP protocol，优先于通用 protocol OTEL_EXPORTER_OTLP_TRACES_HEADERStraces 专用 OTLP HTTP headers，优先于通用 headers，可能包含鉴权信息 KSADK_OTLP_MAX_EXPORT_BATCH_SIZEOTLP 单次 export 最大 span 数，默认 64，用于避免 collector 请求过大 LANGFUSE_PUBLIC_KEY兼容旧 Langfuse tracing 自动配置 LANGFUSE_SECRET_KEYLangfuse secret LANGFUSE_BASE_URLLangfuse base URL LANGFUSE_HOSTLangfuse host 兼容别名 LANGFUSE_USE_CALLBACK使用框架 callback 模式，而不是直接 OTLP 路径 SESSION_TITLE_MODEL本地会话标题生成模型覆盖 COMPACTION_DISABLE_SEMANTIC禁用语义摘要压缩 COMPACTION_SUMMARY_TIMEOUT_MS摘要生成超时时间 COMPACTION_SUMMARY_MAX_GROUPS摘要消息分组上限 COMPACTION_SUMMARY_MODEL语义摘要模型覆盖
0.6.7 起 setup_tracing() 自动探测 CLOUD_MONITOR_* 环境变量，并行挂载 CloudMonitor OTLP exporter 和 CloudMonitor Langfuse SDK CallbackHandler，与自建 Langfuse / 标准 OTLP 互不压制，单条 span 可同时上报自建集群与云监控 trace 平台。
变量 用途 CLOUD_MONITOR_APP_KEY云监控 OTLP AppKey，注入 Ksc-Appkey 鉴权 header（敏感） CLOUD_MONITOR_OTLP_ENABLED显式启用或禁用 CloudMonitor OTLP exporter，默认自动判断 CLOUD_MONITOR_OTLP_ENDPOINTCloudMonitor 通用 OTLP HTTP endpoint；未设 traces endpoint 时派生 /v1/traces CLOUD_MONITOR_OTLP_PROTOCOLCloudMonitor 通用 OTLP 协议，当前支持 http/protobuf CLOUD_MONITOR_OTLP_HEADERSCloudMonitor OTLP 附加 headers，逗号分隔且 URL encoded（敏感） CLOUD_MONITOR_OTLP_TRACES_ENDPOINTCloudMonitor traces 专用 endpoint，优先于通用 endpoint CLOUD_MONITOR_OTLP_TRACES_PROTOCOLCloudMonitor traces 专用协议，优先于通用 protocol CLOUD_MONITOR_LANGFUSE_ENABLED显式启用或禁用 CloudMonitor Langfuse SDK callback，默认自动判断 CLOUD_MONITOR_LANGFUSE_HOSTCloudMonitor AppMonitor Langfuse SDK host，回退 CLOUD_MONITOR_OTLP_ENDPOINT CLOUD_MONITOR_LANGFUSE_PUBLIC_KEYCloudMonitor Langfuse public key（敏感） CLOUD_MONITOR_LANGFUSE_SECRET_KEYCloudMonitor Langfuse secret key（敏感）
显式设置 CLOUD_MONITOR_OTLP_ENABLED=false 或 CLOUD_MONITOR_LANGFUSE_ENABLED=false 可分别禁用对应路径。
不提交真实 key、token、DSN、私有 endpoint、客户数据集 id 或 kubeconfig。
开发环境用本地 .env，自动化用 CI secrets。
公开文档只使用 sk-test、my-model、https://api.example.com/v1 这类占位值。