跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

参数

最后更新 查看 MarkdownAgent 设置

无论采用何种部署机制,每个 Cloudflare One Client(原名 WARP)部署时都支持以下参数。

完整使用 Cloudflare Zero Trust 功能的必需设置

要使用大多数 Cloudflare Zero Trust 功能,必须指定团队名称。依赖团队名称的功能包括 HTTP 策略、Browser Isolation 和设备状态。

organization

指示客户端向你的组织注册设备。注册时需要通过身份提供程序 (IdP)或服务身份验证进行身份验证。

值类型: string

值: 你的 团队名称。

强制执行仅 DNS 策略的必需设置

在 DoH-only 模式下部署客户端时,此字段用于强制执行 DNS 策略。

gateway_unique_id

指示客户端将所有 DNS 查询发送到特定的 Gateway DNS 位置。如果部署时不提供团队名称,或组织中有多个 DNS 位置,则必须设置此值。如果未提供 DoH 子域,系统会自动使用组织的默认 Gateway DNS 位置。

值类型: string

值: 你的 DoH 子域。

组织参数

你可以使用以下参数配置特定的 Zero Trust 组织。

allow_managed_deployments

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低客户端版本
Windows ✅ 2026.6.0
macOS ✅ 2026.6.0
Linux ❌ —
iOS ❌ —
Android ❌ —
ChromeOS ❌ —

由本地开关控制通过 Cloudflare 控制面板推送的客户端版本分配。无论控制面板中的配置如何,均可使用此参数让设备退出控制面板管理的版本变更。

默认情况下,设备会应用控制面板发送的任何分配。如果没有分配项面向此设备,则此参数不起作用。

值类型: boolean

值:

  • true —(默认值)设备会应用 Cloudflare 控制面板为其配置的客户端版本分配。如果没有分配项面向此设备,此设置不起作用。
  • false — 设备会忽略客户端版本分配,并保留当前安装的版本,无论控制面板中的配置如何。

allow_updates

指定客户端是否应在首次注册前检查更新。

值类型: boolean

值:

  • true —(默认值)客户端会自动检查更新,并提示用户安装更新。
  • false — 客户端不会自动检查更新。

auth_client_id

使用服务令牌将设备注册到你的 Zero Trust 组织。 需要 auth_client_secret 参数。

值类型: string

值: 服务令牌的客户端 ID。

配置示例:

<key>auth_client_id</key>
<string>88bf3b6d86161464f6509f7219099e57.access</string>
<key>auth_client_secret</key>
<string>bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5</string>

auth_client_secret

使用服务令牌将设备注册到你的 Zero Trust 组织。 需要 auth_client_id 参数。

值类型: string

值: 服务令牌的客户端密钥。

auto_connect

用户关闭开关后,客户端会在指定分钟数后自动重新开启。建议将此值设得很低,通常只需足够用户登录酒店或机场 Wi-Fi 即可。如果为 auto_connect 指定任何值,Cloudflare One Client 的默认状态始终为已连接(例如初次安装后或重启后)。

值类型: integer

值:

  • 0 — 允许开关无限期保持关闭状态,直到用户重新开启。
  • 1 到 1440 — 在指定分钟数后自动重新开启开关。

display_name

当客户端部署到多个组织时,此参数用于在 Cloudflare One Client GUI 中标识 Zero Trust 组织。如果在 configs 数组中指定了 organization 参数,则此参数为必填项。

值类型: string

值: 显示在 Cloudflare One Client GUI 中供用户查看的组织昵称(例如 Test environment)。

enable_netbt

NetBIOS over TCP/IP (NetBT) 是 Windows 的旧版功能,主要用于某些罕见场景中的名称解析。出于安全原因,Cloudflare One Client 默认会在隧道接口上禁用 NetBT。如果组织仍依赖需要 NetBT 的旧版应用程序,可以覆盖默认行为并启用 NetBT。

值类型: boolean

值:

  • false —(默认值)在 Cloudflare One Client 隧道接口上禁用 NetBT。
  • true — 在 Cloudflare One Client 隧道接口上启用 NetBT。

enable_pmtud

路径 MTU 探测 (PMTUD)可帮助 Cloudflare One Client 探测当前网络可传输的最大数据包,并优化连接性能。

值类型: boolean

值:

  • false — 禁用 PMTUD。
  • true — 在 Cloudflare One Client 隧道接口上启用 PMTUD。Cloudflare One Client 2026.6.822.0 及更高版本默认启用此功能。

在较早版本中,默认值为 false。

enable_post_quantum

功能可用性

客户端模式 Zero Trust 计划 ↗
  • 流量和 DNS 模式
  • 仅流量模式
所有计划
系统 可用性 最低 WARP 版本
Windows ✅ 2025.5.735.1
macOS ✅ 2025.5.735.1
Linux ✅ 2025.5.735.1
iOS ✅ 1.10
Android ✅ 2.4
ChromeOS ✅ 2.4

Cloudflare One Client 使用后量子密码学保护设备与 Cloudflare 网络之间的连接。后量子密码学需要使用 MASQUE 协议,并且默认在所有使用 MASQUE 的设备上启用。

值类型: boolean

值:

  • false — 禁用后量子密钥协商。
  • true — 为通过 WARP 隧道传输的所有流量启用后量子密钥协商。

environment

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低 WARP 版本
Windows ✅ 2025.9.558.0
macOS ✅ 2025.9.558.0
Linux ✅ 2025.9.558.0
iOS ✅ 1.12.0
Android ✅ 2.5.1
ChromeOS ✅ 2.5.1

配置 Cloudflare One Client 连接到 Cloudflare 的 FedRAMP High 授权环境。

值类型: string

值:

  • normal —(默认值)Cloudflare One Client 连接到标准 API 端点、IP 和域(例如 <ACCOUNT_ID>.cloudflare-gateway.com),并将流量转发到全球 Cloudflare 数据中心。
  • fedramp_high — Cloudflare One Client 连接到 FedRAMP 专用 API 端点、IP 和域(例如 <ACCOUNT_ID>.fed.cloudflare-gateway.com)。流量会转发到符合 FedRAMP High 要求的数据中心进行处理。如需配置 FedRAMP High 环境,必须在防火墙中允许通过 FedRAMP 专用端点、IP 和域。

同一组织使用多个配置时,所有配置都必须指定相同的 environment 值。一个组织不能同时运行于普通环境和 FedRAMP High 环境。

在 2026.5.0 及更高版本中,请使用 organization_configs 为每个组织设置一次 environment,而不必在每个配置条目中重复设置:

<dict>
  <key>organization_configs</key>
  <dict>
    <key>mycompany-gov</key>
    <dict>
      <key>environment</key>
      <string>fedramp_high</string>
    </dict>
  </dict>
  <key>configs</key>
  <array>
    <dict>
      <key>organization</key>
      <string>mycompany-gov</string>
      <key>display_name</key>
      <string>Production</string>
    </dict>
    <dict>
      <key>organization</key>
      <string>mycompany-gov</string>
      <key>display_name</key>
      <string>Staging</string>
    </dict>
    <dict>
      <key>organization</key>
      <string>test-org</string>
      <key>display_name</key>
      <string>Test</string>
      <key>environment</key>
      <string>normal</string>
    </dict>
  </array>
</dict>

在较早版本中,该组织的每项配置都必须明确包含 environment:

<dict>
  <key>configs</key>
  <array>
    <dict>
      <key>organization</key>
      <string>mycompany-gov</string>
      <key>display_name</key>
      <string>Production</string>
      <key>environment</key>
      <string>fedramp_high</string>
    </dict>
    <dict>
      <key>organization</key>
      <string>mycompany-gov</string>
      <key>display_name</key>
      <string>Staging</string>
      <key>environment</key>
      <string>fedramp_high</string>
    </dict>
    <dict>
      <key>organization</key>
      <string>test-org</string>
      <key>display_name</key>
      <string>Test</string>
      <key>environment</key>
      <string>normal</string>
    </dict>
  </array>
</dict>

external_emergency_signal_fingerprint

Cloudflare One Client 用于验证 external_emergency_signal_url HTTPS 端点的 SHA-256 指纹。有关提取此指纹的详细信息,请参阅外部紧急断开连接。

值类型: string

值: HTTPS 服务器证书的 SHA-256 指纹(例如 DD4F4806C57A5BBAF1AA5B080F0541DA75DB468D0A1FE731310149500CCD8662)。

external_emergency_signal_interval

Cloudflare One Client 轮询 external_emergency_signal_url 以获取外部紧急断开连接信号的频率。

值类型: integer

值: 轮询频率(秒)(最小 30,默认 300)

external_emergency_signal_url

Cloudflare One Client 为获取外部紧急断开连接信号而轮询的 HTTPS 端点。

值类型: string

值: https://192.0.2.1:3333/status/disconnect

URL 必须使用 https://,并以 IPv4 或 IPv6 地址作为主机(不能使用域名)。

hardware_backed_registration

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低 WARP 版本
Windows ✅ 2026.6.0
macOS ✅(仅限 Apple 芯片) 2026.6.0
Linux ✅ 2026.6.0
iOS ❌ 不适用
Android ❌ 不适用
ChromeOS ❌ 不适用

将注册绑定到存储在设备硬件(Secure Enclave 或 TPM 2.0)中的不可导出密钥,并使用 mTLS 验证 API 请求。有关详细信息,请参阅硬件支持的注册。

值类型: boolean

值:

  • false —(默认)Cloudflare One Client 将其 API 令牌存储在设备密钥库中。
  • true — Cloudflare One Client 在注册期间生成硬件支持的密钥,并为后续 API 调用使用 mTLS。

local_emergency_signal_enabled

启用本地紧急断开连接。启用后,Cloudflare One Client 会监控设备上固定路径的 JSON 文件,以获取紧急断开连接信号。

值类型: boolean

值:

  • false —(默认)禁用本地信号文件监控。
  • true — 客户端监控本地信号文件中的紧急断开连接信号。

managed_network_probe_count

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低客户端版本
Windows ✅ 2026.9.1555.1
macOS ✅ 2026.9.1555.1
Linux ✅ 2026.9.1555.1
iOS ❌ —
Android ❌ —
ChromeOS ❌ —

设置 Cloudflare One Client 在一次检查未发现托管网络后额外检查的次数。客户端会在设备注册和网络更改时检查托管网络。检查期间的临时连接故障可能导致应用错误的设备配置文件,直到下次网络更改。额外探测可让客户端在网络未更改时纠正设备配置文件。每次探测都会检查所有托管网络。

要设置探测之间的等待时间,请使用 managed_network_probe_interval_secs。

值类型: integer

值:

  • 0 — 关闭额外探测。与 2026.9.1555.1 之前的版本一样,客户端只在注册和网络更改时检查托管网络。
  • 1 —(默认)运行一次额外探测。
  • 2 到 10 — 最多运行此数量的额外探测。客户端会将大于 10 的值视为 10。
  • -1 — 持续探测,直到客户端找到托管网络。

managed_network_probe_interval_secs

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低客户端版本
Windows ✅ 2026.9.1555.1
macOS ✅ 2026.9.1555.1
Linux ✅ 2026.9.1555.1
iOS ❌ —
Android ❌ —
ChromeOS ❌ —

Cloudflare One Client 在一次托管网络检查未发现托管网络后,再次探测前等待的时长。不会启动新检查的网络更改会重新开始待处理的等待。

要设置探测次数,请使用 managed_network_probe_count。

值类型: integer

值: 等待时间(秒)(最小 30,最大 300,默认 30)

客户端会将超出此范围的值替换为最接近的限制值。

mdm_file_debounce_secs

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低客户端版本
Windows ✅ 2026.9.1555.1
macOS ✅ 2026.9.1555.1
Linux ✅ 2026.9.1555.1
iOS ❌ —
Android ❌ —
ChromeOS ❌ —

MDM 文件(mdm.xml 或 com.cloudflare.warp.plist)更改后,Cloudflare One Client 在应用新配置前等待的时长。每次新更改都会重新开始等待,因此客户端会一起应用短时间内的多项更改。

值类型: integer

值: 等待时间(秒)(最小 1,最大 60,默认 10)

客户端会将超出此范围的值替换为最接近的限制值。

mdm_file_unavailable_debounce_secs

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低客户端版本
Windows ✅ 2026.9.1555.1
macOS ✅ 2026.9.1555.1
Linux ✅ 2026.9.1555.1
iOS ❌ —
Android ❌ —
ChromeOS ❌ —

MDM 文件丢失或无法读取后,Cloudflare One Client 保留上次应用的 MDM 配置的时长。等待从第一次使文件不可用的文件更改开始。如果等待结束时文件仍不可用,客户端会移除 MDM 配置,包括所有托管注册。

某些 MDM 工具会先删除文件,再重新创建来替换文件。设置长于该间隔的等待时间可以防止客户端移除注册。

值类型: integer

值: 等待时间(秒)(最小 0,最大 300)

客户端会将超出此范围的值替换为最接近的限制值。如果未设置此参数,客户端在 macOS 上会等待 20 秒。在 Windows 和 Linux 上,客户端一旦无法读取文件就会移除 MDM 配置。

onboarding

控制应用首次启动时要求用户查看隐私政策的引导页面是否可见。

值类型: boolean

值:

  • false — 隐藏页面。
  • true —(默认)显示页面。

override_api_endpoint

覆盖 Cloudflare One Client 用于与客户端编排 API 通信的 IP 地址。如果设置此参数,请务必更新组织的防火墙,确保允许新 IP 通过。

此功能用于 Cloudflare 中国本地网络合作伙伴或其他能够维护网络流量完整性的第三方网络合作伙伴。大多数 IT 管理员不应设置此项,因为它会将所有 API 流量重定向到新的 IP。

值类型: string

值: 1.2.3.4 — 将所有客户端编排 API 调用重定向到 1.2.3.4。

该字符串必须是有效的 IPv4 或 IPv6 地址,否则 Cloudflare One Client 将无法解析整个 MDM 文件。

override_doh_endpoint

覆盖 Cloudflare One Client 用于通过 DNS over HTTPS (DoH) 解析 DNS 查询的 IP 地址。如果设置此参数,请务必更新组织的防火墙,确保允许新 IP 通过。

此功能用于 Cloudflare 中国本地网络合作伙伴或其他能够维护网络流量完整性的第三方网络合作伙伴。大多数 IT 管理员不应设置此项,因为它会将所有 DoH 流量重定向到新的 IP。

值类型: string

值: 1.2.3.4 — 将所有 DNS over HTTPS 查询重定向到 1.2.3.4。

该字符串必须是有效的 IPv4 或 IPv6 地址,否则 Cloudflare One Client 将无法解析整个 MDM 文件。

override_warp_endpoint

覆盖 Cloudflare One Client 用于将流量发送到 Cloudflare 边缘的 IP 地址和 UDP 端口。如果设置此参数,请务必更新组织的防火墙,确保允许新 IP 通过。

此功能用于 Cloudflare 中国本地网络合作伙伴或其他能够维护网络流量完整性的第三方网络合作伙伴。大多数 IT 管理员不应设置此项,因为它会将所有 Cloudflare One Client 流量重定向到新的 IP。

值类型: string

值: 203.0.113.0:500 — 将所有 Cloudflare One Client 流量重定向到 203.0.113.0 的端口 500。

该字符串必须是有效的 IPv4 或 IPv6 套接字地址(包含 IP 地址和端口号),否则 Cloudflare One Client 将无法解析整个 MDM 文件。

service_mode

允许你选择客户端的运行模式。

值类型: string

值:

support_url

通过 MDM 部署 Cloudflare One Client 时,应用内的 Send Feedback 按钮默认禁用。此参数允许你重新启用该按钮,并将反馈发送给你的组织。

值类型: string

值:

  • https://<support.example.com> — 使用 https:// 链接打开公司的内部帮助网站。
  • mailto:<[email protected]> — 使用 mailto: 链接打开默认邮件客户端。

switch_locked

允许用户关闭客户端开关并断开 Cloudflare One Client。

值类型: boolean

值:

  • false —(默认)用户可以自行打开或关闭开关。开关关闭时,用户将无法访问受 Access 保护且使用某些设备状态检查的网站。
  • true — 阻止用户关闭开关。Cloudflare One Client 会自动以已连接状态启动。

在新部署中,还必须包含值至少为 0 的 auto_connect 参数。这样可以防止客户端以关闭状态部署,同时用户又无法手动启用客户端。

unique_client_id

为设备分配唯一标识符,用于设备 UUID 状态检查。

值类型: string

值: 设备的 UUID(例如 496c6124-db89-4735-bc4e-7f759109a6f1)。

use_in_app_webview

使用应用内 WebView 而不是默认系统浏览器进行 Zero Trust 身份验证。启用带 Lockdown 模式的 Always-on VPN 时,必须使用此设置。

值类型: boolean

值:

  • false —(默认)使用默认系统浏览器进行 Zero Trust 身份验证。
  • true — 使用应用内 WebView 进行 Zero Trust 身份验证。

warp_tunnel_protocol

配置用于将 IP 流量从设备路由到 Cloudflare Gateway 的协议。有关详细信息,请参阅设备隧道协议。

值类型: string

值:

顶级参数

顶级参数决定 Cloudflare One Client 如何管理设备注册。

configs

允许用户在 Cloudflare One Client GUI 中切换 Zero Trust 组织。使用 multi_user 或 pre_login 等其他顶级参数时,也必须提供 configs 数组,即使只指定一个组织。

值类型: array

值: 包含一个或多个 Zero Trust 组织的数组。

multi_user

在 Windows 设备上启用多个用户注册。

值类型: boolean

值:

  • false —(默认)每台设备只存储一个 Cloudflare One Client 注册。用户登录 Cloudflare One Client 后,其设置和身份将应用于该设备的所有流量。
  • true — 每个 Windows 用户都有自己的 Cloudflare One Client 注册。有关详细信息,请参阅 Windows 设备上的多个用户。

organization_configs

功能可用性

客户端模式 Zero Trust 计划 ↗
所有模式 所有计划
系统 可用性 最低 WARP 版本
Windows ✅ 2026.5.0
macOS ✅ 2026.5.0
Linux ✅ 2026.5.0
iOS ❌ 不适用
Android ❌ 不适用
ChromeOS ❌ 不适用

定义适用于给定组织所有 configs 条目的组织范围设置,并覆盖各配置条目中设置的任何冲突值。

值类型: dict

值: 一个字典,其中每个键是组织名称(团队名称),每个值是组织范围设置的字典。

支持的设置:

键 说明
environment 覆盖属于此组织的所有配置的 environment 值。
hardware_backed_registration 覆盖属于此组织的所有配置的 hardware_backed_registration 值。

当同一组织有多个配置,并且希望在所有配置中强制使用同一个 environment 值时,请使用 organization_configs。该组织单个 configs 条目内设置的任何 environment 值都会被 organization_configs 中指定的值覆盖。

以下示例配置中,test-org 有两个配置(Production 和 Staging),两者都通过 organization_configs 强制使用 fedramp_high:

<dict>
  <key>organization_configs</key>
  <dict>
    <key>test-org</key>
    <dict>
      <key>environment</key>
      <string>fedramp_high</string>
    </dict>
  </dict>
  <key>configs</key>
  <array>
    <dict>
      <key>organization</key>
      <string>test-org</string>
      <key>display_name</key>
      <string>Production</string>
    </dict>
    <dict>
      <key>organization</key>
      <string>test-org</string>
      <key>display_name</key>
      <string>Staging</string>
    </dict>
  </array>
</dict>

pre_login

允许 Cloudflare One Client 在用户完成初始 Windows 登录前使用服务令牌连接。有关详细信息,请参阅在 Windows 登录前连接 Cloudflare One Client。

每应用 VPN 参数(Android)

每应用 VPN ↗ 参数允许你选择可以通过 WARP 隧道发送流量的 Android 应用。管理员可以通过任何支持将 Android 应用部署到托管设备或工作资料的 MDM 工具配置这些参数。

app_identifier

在 Google Play 商店中唯一标识应用的应用包名称/捆绑包标识符。此应用将通过 Cloudflare One Client 服务建立隧道。

值类型:string

值:可以在特定应用 Play 商店 URL 的 ID 查询参数中找到应用标识符。例如,对于 https://play.google.com/store/apps/details?id=com.cloudflare.cloudflareoneagent,Cloudflare One Agent 应用的应用标识符为 com.cloudflare.cloudflareoneagent。

is_browser

一个可选属性。is_browser 可帮助 Cloudflare One Agent 应用决定针对重新身份验证和 Gateway 阻止通知等特定功能打开哪个浏览器,而不是使用默认浏览器。如果需要,管理员应明确指示给定的 tunneled_app 是浏览器,而不是依赖自动浏览器检测。

值类型:boolean

值:如果值为 true,则将 app_identifier 中定义的应用标识为浏览器。默认值为 false,is_browser 是可选属性。

Footnotes

  1. 客户端版本 2025.2.664.0 及更低版本支持流量和 DNS 模式。在 2025.4.589.1 及更高版本中,此参数不适用于流量和 DNS 模式,因为所有 DoH 流量都在 WARP 隧道内传输。 ↩

这篇文档对您有帮助吗?