通过 MDM 部署 Gnista，
一个描述文件就够。

有了团队版，你们的 IT 团队可以用一个配置描述文件下发 Gnista 的密钥并锁定它的设置，任何能安装自定义描述文件的 MDM 都行。这里的一切都是可选的：没有 MDM 的团队，把密钥发给大家就好。

下载模板描述文件

更新于

工作原理

Gnista 读取它自己的域 sh.gnista.Gnista 里的受管偏好设置，由一个带 com.apple.ManagedClient.preferences 负载的配置描述文件下发（有些 MDM 里叫自定义设置或偏好设置文件）。描述文件管理的设置，在 Gnista 里显示“由你的组织管理”，无法在那里更改。

受管设置只在团队密钥下生效。LicenceKey 对任何密钥都有效；如果是个人密钥，Gnista 会忽略其余设置，设置里显示“统一配置需要团队版。”描述文件里同时有密钥和设置时，Gnista 先激活密钥，再应用设置。

除 LicenceKey 和 DisplayMode 外，每个键只有在描述文件强制设置它时才生效，也就是像模板那样放在 Forced 下。每个键都是可选的，Gnista 不认识的键会被忽略。

键

键类型作用
LicenceKey字符串激活 Gnista，不用任何人手动输入密钥：只要这台 Mac 还没有许可证，每次启动都会尝试。任何密钥都有效。
EnabledAgents字符串数组只有这些 Agent 能接入 Gnista，也只显示它们的会话。名称见下文。
ApprovalsAllowed布尔值false 会彻底关闭“在 Gnista 中回应提示”：每个 Agent 都在自己的提示里询问。
ApprovalAgents字符串数组可以在 Gnista 中回应提示的 Agent。
CrashReportsMode字符串Gnista 如何处理崩溃报告：ask（崩溃后询问）、always 或 never。
AutomaticUpdates布尔值true 打开自动更新并锁定这个开关；false 让 Gnista 不再自己检查更新，方便你们自行推送更新。
RemoteMachinesAllowed布尔值false 会关闭远程机器：Gnista 关闭其 SSH 隧道，任何人都无法在设置中连接服务器。
RemoteConnection字符串远程机器的连接方式：automatic（Gnista 自己的 ssh，转发）、relay（Gnista 自己的 ssh，从不转发：一条普通命令）或 manual（Gnista 不建自己的 ssh：由用户自己的会话承载，靠其 ssh 配置中的一行）。
ListSummaryAllowed布尔值false 会关闭“描述智能体在做什么”：Apple 智能在这些 Mac 上从不替任何一行写描述。
DisplayMode字符串Gnista 显示在哪里：notch、menuBar 或 both。强制设置，就会锁定；像模板那样只设置一次，则是大家可以自己改的默认值。

Agent 名称

EnabledAgents 和 ApprovalAgents 里的 Agent 名称，和 Gnista 辅助程序用的一样：

名称Agent
claudeClaude Code
coworkClaude Cowork
codexCodex
geminiGemini CLI
copilotGitHub Copilot
opencodeOpenCode
devinDevin
qwenQwen Code
qwenworkQwenWork
qoderQoder CLI
qoder-cnQoder CN
qoderworkQoderWork
droidFactory Droid
cursorCursor
antigravityAntigravity
vibeMistral Vibe
codebuddyCodeBuddy
workbuddyWorkBuddy
kimiKimi Code
kiloKilo Code
mimocodeMiMoCode
zcodeZCode
ampAmp
auggieAuggie
gooseGoose
piPi
ompOh My Pi
openhandsOpenHands
grokGrok Build
traeTrae
trae-cnTrae CN
codewhaleCodewhale
aiderAider
dshDeepSeek Harness

VS Code 里的 Copilot 算作 copilot。自定义 Agent 用它文件的名字。“在 Gnista 中回应提示”支持 claude、codex、devin、opencode、qwen、qoder、qoder-cn、codebuddy、workbuddy、droid、kilo、mimocode、zcode、kimi 和 omp；ApprovalAgents 里写别的名字不起作用。

描述文件

一个包含所有键的完整描述文件。模板内容相同，每个键都附有注释。留下你想管理的键，填上你的密钥，再给两个 PayloadUUID 换上你自己的值（在终端里运行 uuidgen）。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadDisplayName</key>
  <string>Gnista</string>
  <key>PayloadDescription</key>
  <string>Gnista's licence key and settings for your team.</string>
  <key>PayloadIdentifier</key>
  <string>sh.gnista.Gnista.profile</string>
  <key>PayloadOrganization</key>
  <string>Your organisation</string>
  <key>PayloadScope</key>
  <string>System</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>00000000-0000-4000-8000-000000000001</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadDisplayName</key>
      <string>Gnista settings</string>
      <key>PayloadIdentifier</key>
      <string>sh.gnista.Gnista.profile.preferences</string>
      <key>PayloadType</key>
      <string>com.apple.ManagedClient.preferences</string>
      <key>PayloadUUID</key>
      <string>00000000-0000-4000-8000-000000000002</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>PayloadContent</key>
      <dict>
        <key>sh.gnista.Gnista</key>
        <dict>
          <key>Forced</key>
          <array>
            <dict>
              <key>mcx_preference_settings</key>
              <dict>
                <key>LicenceKey</key>
                <string>GNISTA-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</string>
                <key>EnabledAgents</key>
                <array>
                  <string>claude</string>
                  <string>codex</string>
                </array>
                <key>ApprovalsAllowed</key>
                <true/>
                <key>ApprovalAgents</key>
                <array>
                  <string>claude</string>
                </array>
                <key>CrashReportsMode</key>
                <string>never</string>
                <key>AutomaticUpdates</key>
                <false/>
                <key>RemoteMachinesAllowed</key>
                <true/>
                <key>RemoteConnection</key>
                <string>relay</string>
              </dict>
            </dict>
          </array>
          <key>Set-Once</key>
          <array>
            <dict>
              <key>mcx_data_timestamp</key>
              <date>2026-10-15T00:00:00Z</date>
              <key>mcx_preference_settings</key>
              <dict>
                <key>DisplayMode</key>
                <string>notch</string>
              </dict>
            </dict>
          </array>
        </dict>
      </dict>
    </dict>
  </array>
</dict>
</plist>

作用范围设为 Mac（设备级别，和模板一样），不要设为用户。

Jamf Pro

  1. 在 Jamf Pro 里，依次进入 Computers、Configuration Profiles，选择 Upload，选中你改好的 gnista.mobileconfig。
  2. 检查 General 负载：级别为 Computer，分发方式为 Install Automatically。
  3. 把作用范围设为运行 Gnista 的电脑或智能组，然后保存。

想直接在 Jamf 里建？新建一个描述文件，添加 Application & Custom Settings，上传只含这些键的属性列表，偏好设置域填 sh.gnista.Gnista。

Kandji

  1. 在 Kandji 里打开 Library，添加一个 Custom Profile。
  2. 上传你改好的 gnista.mobileconfig，确认它会安装到 Mac 上。
  3. 把它分配给包含运行 Gnista 的 Mac 的 Blueprints，然后保存。

Microsoft Intune

  1. 在 Intune 管理中心，依次进入 Devices、macOS、Configuration，新建一个策略。
  2. 描述文件类型选 Templates，再选 Custom。
  3. 起个名字，选择设备通道，上传你改好的 gnista.mobileconfig。
  4. 把它分配给包含运行 Gnista 的 Mac 的设备组，然后创建。

Intune 的 Preference file 模板也可以：偏好设置域填 sh.gnista.Gnista，上传只含这些键的属性列表。

Mosyle

  1. 在 Mosyle 里，依次进入 Management、Custom Profiles，添加一个新的描述文件。
  2. 上传你改好的 gnista.mobileconfig。
  3. 把它分配给运行 Gnista 的设备或设备组，然后保存。

在 Mac 上检查

描述文件显示在“系统设置 ▸ 通用 ▸ 设备管理”里。它的设置会写进这台 Mac 的受管偏好设置：

defaults read "/Library/Managed Preferences/sh.gnista.Gnista"

在 Gnista 里，设置会把受管的设置显示为“由你的组织管理”，设置 ▸ 关于 ▸ 许可证显示团队许可证。正式推送前想先试试？在一台测试 Mac 上双击描述文件，然后在系统设置里安装。