无极开物Docs

环境变量

Kaiwu 服务端配置。

本页是 apps/server 的运行时环境变量参考文档。

说明：

  • 文中列出的带有 KAIWU_ 或 HAPPY_ 前缀的旧版别名仍然有效，但推荐优先使用 KAIWU_。
  • 计费与订阅提供商相关的密钥有意未在本页收录。

入门指南：必填项与推荐项

服务端支持多种存储、身份验证与网络拓扑，因此环境变量较多。绝大多数部署只需配置其中一小部分。

多数生产环境部署的必填项

  • HANDY_MASTER_SECRET apps/server 的必填项，用于保护服务端管理的密钥。请使用长随机字符串，并在多次重启之间保持稳定不变。
  • DATABASE_URL（完整版 / 外部数据库） KAIWU_DB_PROVIDER=postgres|mysql 时必填。
  • KAIWU_DB_PROVIDER 选择数据库后端（.env.example 中默认为 postgres）。
  • 所选后端的文件存储配置：
    • KAIWU_FILES_BACKEND=local：无需额外环境变量，或
    • KAIWU_FILES_BACKEND=s3：需要 S3_* 凭据 + S3_PUBLIC_URL

强烈推荐（避免配对及移动端 URL 混淆）

  • KAIWU_PUBLIC_SERVER_URL 服务端的规范/共享 URL，用于嵌入二维码与深层链接，并通过 GET /v1/features 对外公布。该地址应为手机能够直接访问的 URL（推荐使用 https://...）。
  • KAIWU_WEBAPP_URL（自托管 Web UI 或用于 OAuth 重定向回跳） Web 客户端和 OAuth 重定向的基础 URL。如果使用托管在 https://kaiwu.wujilabs.cn 的 Web 应用，则为可选项。

置于反向代理后时的推荐配置

  • KAIWU_SERVER_TRUST_PROXY=1：适用于常见的单代理架构（Caddy/Nginx/Traefik），以便服务端能安全地利用 X-Forwarded-* 进行 request.ip 与协议检测。

可选优化项

  • API 速率限制：KAIWU_API_RATE_LIMITS_*（下文附有推荐基准配置）
  • 指标监控：METRICS_*

规范模板

请使用 /apps/server/.env.example 作为规范模板。

典型工作流程：

cp apps/server/.env.example apps/server/.env

随后：

  • 本地/开发环境：从 apps/server/.env 加载配置值，
  • Docker/Compose/各部署平台：将同一套键值对复制到环境或密钥管理器中。

核心运行时

  • PORT（默认值 3005）
  • KAIWU_SERVER_HOST（别名：HAPPY_SERVER_HOST，默认值 0.0.0.0）
  • NODE_ENV
  • SERVER_ROLE（all | api | worker，默认值 all） 其他任何值（包括拼写错误）都会解析为 all 而非报错退出。 除非启用了 Redis 适配器（REDIS_URL 配合 KAIWU_SOCKET_ADAPTER=redis-streams），否则 worker 会拒绝启动。
  • HANDY_MASTER_SECRET（轻量版自动生成时除外，否则必填）
  • DATABASE_URL（完整版必填；轻量版可选）
  • KAIWU_DB_PROVIDER（别名：HAPPY_DB_PROVIDER） 可选值：postgres | mysql | pglite | sqlite
  • KAIWU_FILES_BACKEND（别名：HAPPY_FILES_BACKEND） 可选值：s3 | local
  • KAIWU_SOCKET_ADAPTER（别名：HAPPY_SOCKET_ADAPTER） 可选值：memory | redis-streams
  • KAIWU_SOCKET_REDIS_ADAPTER（别名：HAPPY_SOCKET_REDIS_ADAPTER） 旧版布尔开关；建议优先使用 KAIWU_SOCKET_ADAPTER=redis-streams
  • REDIS_URL（启用 Redis 适配器时必填）
  • KAIWU_INSTANCE_ID（别名：HAPPY_INSTANCE_ID） 用于日志记录及集群行为的稳定进程标识符
  • METRICS_ENABLED（默认值 true）
  • METRICS_PORT（默认值 9090）

网络与反向代理

  • KAIWU_SERVER_TRUST_PROXY（可选） 控制服务端运行在反向代理之后时，是否信任 X-Forwarded-* 请求头以获取客户端 IP 和协议。
    • 未设置：使用框架默认行为（不信任转发头）
    • true：信任所有代理跳（仅在服务端无法被外部直接访问时才安全）
    • false：永不信任转发头
    • ⟦K5⟧：信任最后 N 跳（0 等同于 false；典型单代理架构推荐设置为 1）

WebSocket（实时通信及“设备在线”必需）

Kaiwu 的实时同步（以及设备在线状态检测）通过 Socket.IO 实现，路径为：

  • GET /v1/updates（轮询 + WebSocket 升级）

若反向代理（或 CDN）未能正确转发 /v1/updates 的 WebSocket 升级请求，客户端可能表面上连接成功，但设备会一直显示离线。

常见症状：

  • 界面/手机端显示无在线设备或“需要操作”
  • 服务端诊断信息包含 machine.none_online
  • 守护进程日志显示“正在连接至……”，但 /v1/machines 报告 active: false

Nginx（配置示例）

如果在 Nginx 上终止 TLS，请确保其正确转发 WebSocket 升级请求（针对所有路径，或至少针对 /v1/updates）：

location /v1/updates/ {
  # Use the server's HTTP port (usually 3005; some managed/self-host flows use 53288).
  proxy_pass http://127.0.0.1:<port>;
  proxy_http_version 1.1;

  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";

  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

快速检查（WebSocket 升级是否正常？）

在任何能够访问公共 HTTPS URL 的设备上运行：

KEY="$(openssl rand -base64 16)"
curl -i -sS \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $KEY" \
  "https://api.example.com/v1/updates/?EIO=4&transport=websocket" | head -n 5

预期输出：HTTP/1.1 101 Switching Protocols。

临时融通方案（守护进程端）

如果无法立即调整反向代理，可以先强制守护进程通过轮询方式连接：

KAIWU_SOCKET_TRANSPORTS=polling,websocket kaiwu daemon restart --takeover

规范 URL（二维码/深层链接，推荐配置）

  • KAIWU_PUBLIC_SERVER_URL 服务端的规范/共享 URL。客户端会将此地址嵌入终端连接的深层链接和二维码中，服务端也会通过 GET /v1/features 在 capabilities.server.canonicalServerUrl 下对外公布。
    • 请使用手机可正常访问的 URL（推荐 https://...）。
    • 若有意仅在局域网内运行，使用 http://⟦K6⟧:3005 即可，但二维码与深层链接将仅在同一局域网或 VPN 内有效。
    • 若未设置该项，或当前活动的服务端 URL 解析为仅回环地址（localhost、127.0.0.1、::1、*.localhost），Kaiwu 可能会在面向移动端的二维码/深层链接中特意省略服务端 URL，以避免嵌入无法访问的失效地址。
  • KAIWU_WEBAPP_URL（别名：HAPPY_WEBAPP_URL） Web 客户端的基础 URL。服务端会通过 GET /v1/features 在 capabilities.server.webappUrl 下对外公布。
    • 使用托管版 Web 应用：保持默认值 https://kaiwu.wujilabs.cn。
    • 自托管 UI：请设置为 UI 的源地址（通常与 KAIWU_PUBLIC_SERVER_URL 相同）。

对用户体验的影响：

  • 添加手机
  • 恢复账号
  • CLI/移动端身份验证二维码链接
  • 配置服务端链接

当嵌入的服务端 URL 可被目标手机/设备直接访问时，上述功能体验最佳。

如果用户看到提示要求在手机上手动配置服务端，通常意味着当前服务端 URL 为仅回环地址，无法安全地跨设备共享。

Tailscale Serve 自动推断（可选）

如果未设置 KAIWU_PUBLIC_SERVER_URL 且服务端通过 tailscale serve 暴露，服务端可以在启动时尽力推断 https://⟦K7⟧.⟦K8⟧.ts.net URL。

  • KAIWU_TAILSCALE_INFER_PUBLIC_URL（默认值 true） 设置为 0 可禁用自动推断。
  • KAIWU_TAILSCALE_BIN（默认值 tailscale） 覆盖 tailscale 二进制文件的路径或名称。
  • KAIWU_TAILSCALE_SERVE_STATUS_TIMEOUT_MS（默认值 750） tailscale serve status 探测的超时时间（上限为 1..10000）。

API 速率限制

速率限制基于 @fastify/rate-limit。所有 *_WINDOW 值均支持人类可读的时间长度，如 30 seconds、1 minute、5 minutes。

全部 33 个端点的具体限制（包括默认值、计入维度以及对应的两组环境变量）均根据服务端的速率限制目录自动生成，详见 API rate limits。这些变量名在运行时由端点 ID 推导而来，并未以字面量形式出现在源码中，手动配置部署时极易遗漏。

全局控制项：

  • KAIWU_API_RATE_LIMITS_ENABLED（默认值 true） 设置为 0 或 false 可禁用全部 API 速率限制。
  • KAIWU_API_RATE_LIMITS_GLOBAL_MAX（默认值 0） 作用于所有路由的可选全局限制。设置为 0 可将其禁用。
  • KAIWU_API_RATE_LIMITS_GLOBAL_WINDOW（默认值 1 minute）

存储后端

  • S3_HOST
  • S3_PORT（可选）
  • S3_USE_SSL（true/false，默认值 true）
  • S3_BUCKET
  • S3_PUBLIC_URL
  • S3_ACCESS_KEY
  • S3_SECRET_KEY

轻量版路径

  • KAIWU_SERVER_LIGHT_DATA_DIR（别名：HAPPY_SERVER_LIGHT_DATA_DIR）
  • KAIWU_SERVER_LIGHT_DB_DIR（别名：HAPPY_SERVER_LIGHT_DB_DIR）
  • KAIWU_SERVER_LIGHT_FILES_DIR（别名：HAPPY_SERVER_LIGHT_FILES_DIR）
  • PUBLIC_URL（可选；用于轻量版默认值）

错误报告

  • KAIWU_FEATURE_BUG_REPORTS__ENABLED（默认值 1）
  • KAIWU_FEATURE_BUG_REPORTS__PROVIDER_URL（默认值 https://kaiwu.wujilabs.cn）
  • KAIWU_FEATURE_BUG_REPORTS__DEFAULT_INCLUDE_DIAGNOSTICS（默认值 1）
  • KAIWU_FEATURE_BUG_REPORTS__MAX_ARTIFACT_BYTES（默认值 10485760）
  • KAIWU_FEATURE_BUG_REPORTS__UPLOAD_TIMEOUT_MS（默认值 120000）
  • KAIWU_FEATURE_BUG_REPORTS__CONTEXT_WINDOW_MS（默认值 1800000；最小值 1000，最大值 86400000）
  • KAIWU_FEATURE_BUG_REPORTS__ACCEPTED_ARTIFACT_KINDS（逗号分隔的允许列表）

服务端诊断快照控制

  • KAIWU_BUG_REPORTS_SERVER_DIAGNOSTICS_ENABLED（默认值 0）
  • KAIWU_BUG_REPORTS_SERVER_DIAGNOSTICS_ACCESS_MODE（默认值 owner，允许值：authenticated、owner）
  • KAIWU_SERVER_OWNER_USER_IDS（逗号分隔的用户 ID 列表；访问模式为 owner 时生效）
  • KAIWU_BUG_REPORTS_SERVER_LOG_PATH
  • KAIWU_SELF_HOST_LOG_DIR（server.log 的备用目录）
  • KAIWU_BUG_REPORTS_SERVER_LOG_MAX_BYTES（默认值 262144）
  • KAIWU_DIAGNOSTICS_BUG_REPORT_SNAPSHOT_RATE_LIMIT_MAX（默认值 30）
  • KAIWU_DIAGNOSTICS_BUG_REPORT_SNAPSHOT_RATE_LIMIT_WINDOW（默认值 1 minute）

所有者 ID 说明：

  • KAIWU_SERVER_OWNER_USER_IDS 接收 Kaiwu 账号 ID。
  • 所有者可在应用中的“设置 → 账号”下查看自己的账号 ID。

OAuth 与身份验证

策略行为与配置示例详见 Server Auth。

全局身份验证策略

  • AUTH_ANONYMOUS_SIGNUP_ENABLED
  • AUTH_SIGNUP_PROVIDERS（CSV）
  • AUTH_REQUIRED_LOGIN_PROVIDERS（CSV）
  • AUTH_OFFBOARDING_ENABLED
  • AUTH_OFFBOARDING_INTERVAL_SECONDS
  • AUTH_OFFBOARDING_STRICT
  • KAIWU_FEATURE_AUTH_RECOVERY__PROVIDER_RESET_ENABLED
  • KAIWU_FEATURE_AUTH_UI__AUTO_REDIRECT_ENABLED
  • KAIWU_FEATURE_AUTH_UI__AUTO_REDIRECT_PROVIDER_ID
  • KAIWU_FEATURE_AUTH_UI__RECOVERY_KEY_REMINDER_ENABLED
  • AUTH_PROVIDERS_CONFIG_PATH
  • AUTH_PROVIDERS_CONFIG_JSON
  • AUTH_ACCOUNT_DISABLED_TTL_SECONDS

旧版别名（仍受支持）：

  • AUTH_RECOVERY_PROVIDER_RESET_ENABLED
  • AUTH_UI_AUTO_REDIRECT
  • AUTH_UI_AUTO_REDIRECT_PROVIDER_ID
  • AUTH_UI_RECOVERY_KEY_REMINDER_ENABLED

内置密钥质询登录路由

Kaiwu 默认的“设备密钥”注册与登录流程使用 POST /v1/auth。

服务端运维人员可以禁用此内置登录路由（例如当所有访问均需经由 GitHub 或 OIDC 等提供商时）。

  • KAIWU_FEATURE_AUTH_LOGIN__KEY_CHALLENGE_ENABLED（默认值 1）

注意：若禁用密钥质询路由，请确保已配置至少一个可用的提供商（否则服务端会在启动时快速失败以防止锁定）。

无密钥 OAuth 登录（可选）

Kaiwu 支持将 OAuth 提供商（GitHub/OIDC）作为无密钥登录方式，账号无需设备密钥即可存在（专为企业版与明文存储部署设计）。

无密钥 OAuth 受以下特性环境变量控制：

  • KAIWU_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED（默认值 0）
  • KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED（默认值 0）
  • KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS（逗号分隔的提供商 ID 允许列表，例如 github,okta）
  • KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION（默认值 0）

说明：

  • KAIWU_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1 控制是否允许在首次登录时创建新的无密钥账号。
  • 无密钥自动置备要求同时启用无密钥账号与明文默认配置（当前先决条件详见 Server Auth）。

GitHub OAuth

  • GITHUB_CLIENT_ID
  • GITHUB_CLIENT_SECRET
  • GITHUB_REDIRECT_URL（旧版别名：GITHUB_REDIRECT_URI）
  • GITHUB_HTTP_TIMEOUT_SECONDS
  • GITHUB_STORE_ACCESS_TOKEN
  • GITHUB_WEBHOOK_SECRET
  • GITHUB_APP_ID
  • GITHUB_PRIVATE_KEY
  • GITHUB_OAUTH_PENDING_TTL_SECONDS（待处理 TTL 的旧版回退项）
  • KAIWU_WEBAPP_URL（别名：HAPPY_WEBAPP_URL）
  • KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE（别名：HAPPY_WEBAPP_OAUTH_RETURN_URL_BASE）
  • KAIWU_OAUTH_RETURN_ALLOWED_SCHEMES（别名：HAPPY_OAUTH_RETURN_ALLOWED_SCHEMES）
  • OAUTH_PENDING_TTL_SECONDS
  • OAUTH_STATE_TTL_SECONDS

关于“可选”Web 应用 URL 环境变量的说明：

  • KAIWU_WEBAPP_URL / KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE 仅在您使用托管在 https://kaiwu.wujilabs.cn 的客户端时才是“可选”的。
    • 如果自托管 Web 应用或使用本地开发的 Web UI，则必须设置其中之一，以便服务端在完成 OAuth 后重定向回客户端。

双向 TLS (mTLS) 身份验证（企业版）

完整配置指南详见 Server → mTLS Auth。

  • KAIWU_FEATURE_AUTH_MTLS__ENABLED（默认值 0）
  • KAIWU_FEATURE_AUTH_MTLS__MODE（forwarded | direct）
  • KAIWU_FEATURE_AUTH_MTLS__AUTO_PROVISION（默认值 0）
  • KAIWU_FEATURE_AUTH_MTLS__IDENTITY_SOURCE（san_email | san_upn | subject_cn | fingerprint）
  • KAIWU_FEATURE_AUTH_MTLS__ALLOWED_EMAIL_DOMAINS（CSV）
  • KAIWU_FEATURE_AUTH_MTLS__ALLOWED_ISSUERS（CSV；以逗号/换行符分隔的签发者值；用于与转发的签发者字符串中提取出的签发者 CN 进行比对）
  • KAIWU_FEATURE_AUTH_MTLS__TRUST_FORWARDED_HEADERS（默认值 0）
  • KAIWU_FEATURE_AUTH_MTLS__FORWARDED_EMAIL_HEADER
  • KAIWU_FEATURE_AUTH_MTLS__FORWARDED_UPN_HEADER
  • KAIWU_FEATURE_AUTH_MTLS__FORWARDED_SUBJECT_HEADER
  • KAIWU_FEATURE_AUTH_MTLS__FORWARDED_FINGERPRINT_HEADER
  • KAIWU_FEATURE_AUTH_MTLS__FORWARDED_ISSUER_HEADER
  • KAIWU_FEATURE_AUTH_MTLS__RETURN_TO_ALLOW_PREFIXES（CSV）
  • KAIWU_FEATURE_AUTH_MTLS__CLAIM_TTL_SECONDS

GitHub 资格限制

  • AUTH_GITHUB_ALLOWED_USERS
  • AUTH_GITHUB_ALLOWED_ORGS
  • AUTH_GITHUB_ORG_MATCH
  • AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE
  • AUTH_GITHUB_APP_ID
  • AUTH_GITHUB_APP_PRIVATE_KEY
  • AUTH_GITHUB_APP_INSTALLATION_ID_BY_ORG

账号/终端身份验证 TTL 控制

  • ACCOUNT_AUTH_REQUEST_TTL_SECONDS
  • TERMINAL_AUTH_REQUEST_TTL_SECONDS
  • TERMINAL_AUTH_CLAIM_RETRY_WINDOW_SECONDS
  • VENDOR_TOKEN_MAX_LEN

加密与明文存储（停用端到端加密）

概览与运维指南详见 Server → Encryption & plaintext storage。

全服务端存储策略：

  • KAIWU_FEATURE_ENCRYPTION__STORAGE_POLICY（默认值 required_e2ee） 可选值：required_e2ee | optional | plaintext_only

账号级停用（仅在策略为 optional 时生效）：

  • KAIWU_FEATURE_ENCRYPTION__ALLOW_ACCOUNT_OPTOUT（默认值 0）
  • KAIWU_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODE（默认值 e2ee） 可选值：e2ee | plain

明文静态封存（仅限明文/无密钥账号；数据库存储）：

  • KAIWU_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_SETTINGS_AT_REST（默认值 server_sealed） 可选值：none | server_sealed
  • KAIWU_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_CREDENTIALS_AT_REST（默认值 server_sealed） 可选值：none | server_sealed

会话 Agent 切换

  • KAIWU_FEATURE_SESSIONS_AGENT_SWITCHING__ENABLED（默认值 1）

此项采用选择性停用机制：除非显式禁用，否则默认对外公布就地 Agent 切换功能。关于该特性的具体作用，详见 Continue with another Agent。

好友与社交

  • KAIWU_FEATURE_SOCIAL_FRIENDS__ENABLED
  • KAIWU_FEATURE_SOCIAL_FRIENDS__ALLOW_USERNAME
  • KAIWU_FEATURE_SOCIAL_FRIENDS__IDENTITY_PROVIDER
  • FRIENDS_USERNAME_MIN_LEN
  • FRIENDS_USERNAME_MAX_LEN
  • FRIENDS_USERNAME_REGEX

语音

Kaiwu 语音与服务端令牌生成控制项：

  • KAIWU_FEATURE_VOICE__ENABLED
  • KAIWU_FEATURE_VOICE__REQUIRE_SUBSCRIPTION
  • VOICE_FREE_SESSIONS_PER_MONTH
  • VOICE_FREE_MINUTES_PER_MONTH
  • VOICE_MAX_CONCURRENT_SESSIONS
  • VOICE_MAX_SESSION_SECONDS
  • VOICE_MAX_MINUTES_PER_DAY
  • KAIWU_VOICE_TOKEN_RATE_LIMIT_MAX
  • KAIWU_VOICE_TOKEN_RATE_LIMIT_WINDOW
  • KAIWU_VOICE_SESSION_COMPLETE_RATE_LIMIT_MAX
  • KAIWU_VOICE_SESSION_COMPLETE_RATE_LIMIT_WINDOW
  • KAIWU_SERVER_RETENTION__VOICE_SESSION_LEASES__MODE
  • KAIWU_SERVER_RETENTION__VOICE_SESSION_LEASES__DAYS
  • ELEVENLABS_API_KEY
  • ELEVENLABS_AGENT_ID
  • ELEVENLABS_AGENT_ID_PROD

UI 与静态文件托管

  • KAIWU_SERVER_UI_DIR（别名：KAIWU_SERVER_LIGHT_UI_DIR）
  • KAIWU_SERVER_UI_PREFIX（别名：KAIWU_SERVER_LIGHT_UI_PREFIX）
  • KAIWU_SERVER_UI_REQUIRED（别名：KAIWU_SERVER_LIGHT_UI_REQUIRED）
  • KAIWU_SERVER_UI_DEBUG_PATH（调试备用路径可见性）

后台与维护任务

语音租约清理与账号变更清理此前为独立任务，拥有各自的变量。现在它们已作为保留期工作进程（retention worker）的管理范畴，其配置方式与其余保留数据表一致——完整范畴列表及限制单次清理范围的全局参数详见 Server retention policies。

  • KAIWU_SERVER_RETENTION__ACCOUNT_CHANGES__MODE
  • KAIWU_SERVER_RETENTION__ACCOUNT_CHANGES__DAYS
  • HAPPY_PRESENCE_STREAM_MAXLEN

特性门控

以下每项决定了服务端是否对外公布对应的能力。它们默认开启：客户端仍需启用相应的开关，且其中数项在客户端属于实验性功能，因此通常保持默认即可。若希望在部署中彻底禁用某项能力（无论客户端如何请求），可将其设置为 0。

包含无对应环境变量项在内的完整门控能力清单，详见 Feature flags。

  • KAIWU_FEATURE_ATTACHMENTS_UPLOADS__ENABLED（默认值 1）
  • KAIWU_FEATURE_AUTOMATIONS__ENABLED（默认值 1）
  • KAIWU_FEATURE_AUTH_PAIRING__DESKTOP_QR_MOBILE_SCAN_ENABLED（默认值 1）
  • KAIWU_FEATURE_CHANNEL_BRIDGES__ENABLED（默认值 1）
  • KAIWU_FEATURE_CHANNEL_BRIDGES_TELEGRAM__ENABLED（默认值 1）
  • KAIWU_FEATURE_CONNECTED_SERVICES_ACCOUNT_GROUPS__ENABLED（默认值 1）——账号池
  • KAIWU_FEATURE_CONNECTED_SERVICES_ACCOUNT_FALLBACK__ENABLED（默认值 1）
  • KAIWU_FEATURE_SESSIONS_DRAFTS__ENABLED（默认值 1）——同步已有与新建会话草稿
  • KAIWU_FEATURE_SESSIONS_FOLDERS__ENABLED（默认值 1）
  • KAIWU_FEATURE_SESSIONS_HANDOFF__ENABLED（默认值 1）
  • KAIWU_FEATURE_SESSIONS_USAGE_LIMIT_RECOVERY__ENABLED（默认值 1）
  • KAIWU_FEATURE_TERMINAL_EMBEDDED_PTY__ENABLED（默认值 1）
  • KAIWU_FEATURE_UPDATES_OTA__ENABLED（默认值 1）

设备间传输

  • KAIWU_FEATURE_MACHINES_TRANSFER_DIRECT_PEER__ENABLED（默认值 1）
  • KAIWU_FEATURE_MACHINES_TRANSFER_SERVER_ROUTED__ENABLED（默认值 1）
  • KAIWU_FEATURE_MACHINES_TRANSFER_SERVER_ROUTED__MAX_BYTES（硬性上限 8 GiB）
  • KAIWU_FEATURE_MACHINES_TRANSFER_SERVER_ROUTED__MAX_ACTIVE_TRANSFERS_PER_SOCKET（默认值 128；最小值 1，最大值 10000）

电子宠物包限制

宠物同步默认关闭（KAIWU_FEATURE_PETS_SYNC__ENABLED）。开启后，以下参数用于限制账号可导入的内容：

  • KAIWU_FEATURE_PETS_SYNC__MAX_MANIFEST_BYTES（默认值 16384）
  • KAIWU_FEATURE_PETS_SYNC__MAX_CANONICAL_SPRITESHEET_BYTES（默认值 5242880）
  • KAIWU_FEATURE_PETS_SYNC__MAX_CANONICAL_PACKAGE_BYTES（默认值 6291456）
  • KAIWU_FEATURE_PETS_SYNC__MAX_IMPORTED_PETS_PER_ACCOUNT（默认值 20）
  • KAIWU_FEATURE_PETS_SYNC__MAX_IMPORTED_PET_BYTES_PER_ACCOUNT（默认值 104857600）
  • KAIWU_FEATURE_PETS_SYNC__ENCRYPTED_CUSTOM_PET_SYNC_POLICY

高级与调试控制

  • HAPPY_EXIT_ON_FATAL
  • HAPPY_SOCKET_ROOMS_ONLY
  • KAIWU_RPC_FORWARD_TIMEOUT_MS
  • KAIWU_RPC_FORWARD_CAPABILITIES_TIMEOUT_MS
  • DANGEROUSLY_LOG_TO_SERVER_FOR_AI_AUTO_DEBUGGING

版本形态与内部标记

  • KAIWU_SERVER_FLAVOR（别名：HAPPY_SERVER_FLAVOR） 服务端启动时设置的运行时标记；通常无需用户配置。
© 乾元执中（南京）科技有限公司 · WUJI-Labs

Docker

使用 Docker / Docker Compose 部署 Kaiwu 服务器。

API rate limits

Every rate-limited endpoint, its default, what it counts against, and the two environment variables that change it.

On this page

入门指南：必填项与推荐项规范模板核心运行时网络与反向代理WebSocket（实时通信及“设备在线”必需）Nginx（配置示例）快速检查（WebSocket 升级是否正常？）临时融通方案（守护进程端）规范 URL（二维码/深层链接，推荐配置）Tailscale Serve 自动推断（可选）API 速率限制存储后端轻量版路径错误报告服务端诊断快照控制OAuth 与身份验证全局身份验证策略内置密钥质询登录路由无密钥 OAuth 登录（可选）GitHub OAuth双向 TLS (mTLS) 身份验证（企业版）GitHub 资格限制账号/终端身份验证 TTL 控制加密与明文存储（停用端到端加密）会话 Agent 切换好友与社交语音UI 与静态文件托管后台与维护任务特性门控设备间传输电子宠物包限制高级与调试控制版本形态与内部标记