---
title: "GET /settings"
method: GET
path: "/settings"
tags: ["settings"]
---

# GET /settings

`GET /settings`

Returns the current application settings as a typed Settings struct.

## Response `200`

Current application settings

- SettingsEnvelope — Canonical success envelope: `{ "data": T, "ts": <unix millis i64> }`. `ts` is `chrono::Utc::now().timestamp_millis()`, set in the webserver handler via [`ApiEnvelope::now`] (the contract carries only the type + the clock helper, not a hard dependency on when the handler reads the clock). `rename_all = "camelCase"` is a no-op for the single-word fields here but is declared for forward-compat. IMPORTANT (utoipa v4): every concrete `ApiEnvelope<X>` that needs a named OpenAPI component is declared in the `#[aliases(...)]` block below. Add a new alias line whenever a new payload type needs enveloping. NEVER register the bare `ApiEnvelope` in `components(schemas(...))` — utoipa errors on a bare generic, and an un-aliased generic inlines an anonymous schema.
  - `data` SettingsDto, required
    - `fileSync` FileSyncSettingsDto, required
      - `autoSaveDir` string, nullable — Directory where inbound files are saved. `null` = managed storage.
      - `fileAutoCleanup` boolean, required
      - `fileCacheQuotaPerDevice` integer, required
      - `fileRetentionHours` integer, required
      - `fileSyncEnabled` boolean, required
      - `maxFileSize` integer, required
      - `smallFileThreshold` integer, required
    - `general` GeneralSettingsDto, required
      - `autoCheckUpdate` boolean, required
      - `autoDownloadUpdate` boolean — Whether to download the next available update in the background. Persisted alongside `auto_check_update`; consumed by the frontend's `UpdateContext` after a successful `check_for_update` to decide whether to start a silent download.
      - `autoStart` boolean, required
      - `debugMode` boolean — Persistent local diagnostic logging mode. Takes effect after restart.
      - `deviceName` string, nullable
      - `language` string, nullable
      - `restoreLastEntryOnStartup` boolean — Whether to push the most recent clipboard history entry back onto the OS clipboard once the daemon connection is confirmed at startup. Added after initial launch; `#[serde(default)]` keeps old wire payloads compatible.
      - `startupMode` 'normal' | 'silent' | 'lightweight'
      - `telemetryEnabled` boolean, required — Whether anonymous diagnostic telemetry is enabled.
      - `theme` 'light' | 'dark' | 'system', required
      - `themeColor` string, nullable — 旧版"统一主题预设"字段（v0.7 之前唯一字段）。新前端不再写入, 但 wire 仍透传以便老 daemon ↔ 新前端 / 新 daemon ↔ 老前端兼容。 该兼容字段将在旧版客户端支持窗口结束后删除。
      - `themeColorDark` string, nullable — Dark 模式下的主题预设名（如 `"zinc"`）；为 `None` 时 daemon 端 将回退到 `theme_color`。wire 字段名 `themeColorDark`（camelCase）。
      - `themeColorLight` string, nullable — Light 模式下的主题预设名（如 `"zinc"`）；为 `None` 时 daemon 端 将回退到 `theme_color`。wire 字段名 `themeColorLight`（camelCase）。
      - `themeOverridesDark` object — Dark 模式下用户对预设 token 的自定义覆盖（语义同 light）。wire 字段名 `themeOverridesDark`。
      - `themeOverridesLight` object — Light 模式下用户对预设 token 的自定义覆盖（`{ tokenName: oklchString }`）。 为空 map 表示完全跟随 preset。wire 字段名 `themeOverridesLight`。
      - `updateChannel` 'stable' | 'alpha' | 'beta' | 'rc'
      - `usageAnalyticsEnabled` boolean — Whether anonymous product usage analytics is enabled. 与 `telemetry_enabled` 拆开（schema doc §6.4）：前者控制 Sentry 错误 上报，本字段控制产品 telemetry（漏斗 / 留存 / 同步可靠性事件）。
    - `keyboardShortcuts` object, required
    - `network` NetworkSettingsDto, required — LAN-only Mode（v0.7.0）DTO 镜像。 反向命名规则（Pitfall 1）：业务正向语义 `allow_relay_fallback`， 不在此层重命名为 `lan_only` 或类似镜像。wire 字段 = `allowRelayFallback` （camelCase 自动转换）。取反唯一发生在 `uc-bootstrap/src/network_policy.rs`。 `allow_overlay_network_addrs` 控制是否把 VPN/overlay 类虚拟网卡 IP（CGNAT 100.64.0.0/10、Tailscale ULA fd7a:115c:a1e0::/48）作为 iroh 直连候选发布 给对端。默认 `false`（过滤）。专业用户在两端都接入同一 VPN 时可开启。 `custom_relay_urls` 为空时继续使用 iroh 默认 relay；非空时只使用这些 用户配置的 relay URL。LAN-only 模式关闭 relay 时该列表保留但不生效。
      - `allowOverlayNetworkAddrs` boolean
      - `allowRelayFallback` boolean, required
      - `congestionController` 'cubic' | 'bbr3' — Algorithm for network flow control. Wire form: `"cubic"` | `"bbr3"`.
      - `customRelayUrls` string[]
    - `pairing` PairingSettingsDto, required
      - `maxRetries` integer, required
      - `protocolVersion` string, required
      - `sessionTimeout` integer, required
      - `stepTimeout` integer, required
      - `userVerificationTimeout` integer, required
    - `quickPanel` QuickPanelSettingsDto — 快捷面板（Spotlight 风格）功能偏好 DTO。 wire 字段命名为 camelCase。`#[serde(default)]` 让旧客户端缺少新增字段时 回退到领域默认值，避免 wire 与磁盘真相分裂。
      - `doubleTapModifier` 'disabled' | 'alt' | 'control' | 'meta'
      - `enabled` boolean
      - `position` 'center' | 'follow_cursor' — 快捷面板出现位置 DTO。wire form: `center` | `follow_cursor`。
    - `retentionPolicy` RetentionPolicyDto, required
      - `enabled` boolean, required
      - `evaluation` 'anyMatch' | 'allMatch', required
      - `rules` RetentionRuleDto[], required
        - union
          - object
            - `byAge` object, required — 按时间清理
              - …
          - object
            - `byCount` object, required — 按总数量上限
              - …
          - object
            - `byContentType` object, required — 按内容类型的最大存活时间
              - …
          - object
            - `byTotalSize` object, required — 按磁盘占用大小
              - …
          - object
            - `sensitive` object, required — 敏感内容快速过期
              - …
      - `skipPinned` boolean, required
    - `schemaVersion` integer, required
    - `security` SecuritySettingsDto, required
      - `autoUnlockEnabled` boolean — 是否启用启动时自动解锁 仅用于 UI 与流程判断 需要用户在系统弹窗中选择“始终允许”才能静默生效
      - `encryptionEnabled` boolean, required — 是否启用本地数据加密
      - `passphraseConfigured` boolean, required — 是否已经在 keyring 中设置过口令 仅用于 UI 与流程判断 不代表当前口令是否“可用”
    - `sync` SyncSettingsDto, required
      - `autoSync` boolean, required
      - `contentTypes` ContentTypesDto, required
        - `codeSnippet` boolean, required
        - `file` boolean, required
        - `image` boolean, required
        - `link` boolean, required
        - `richText` boolean, required
        - `text` boolean, required
      - `syncFrequency` 'realtime' | 'interval', required
      - `syncOnRestore` boolean, required
  - `ts` integer, required — Server time when the response was built (unix epoch milliseconds).

## Other responses

- `500` — Internal server error

---

[API](https://skmtc.net/uniclipboard/apis/uniclipboard-daemon-api.md) · [All operations](https://skmtc.net/uniclipboard/apis/uniclipboard-daemon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uniclipboard/uniclipboard-daemon-api/versions/10dd20bcf330/schema)