故障排除
首次启动被阻止
“无法打开‘MacroSIP’，因为无法验证开发者”：应用使用临时 (ad hoc) 签名，未经公证。在“应用程序”中右键点按 MacroSIP 并选择打开 (Open)，或执行一次 xattr -dr com.apple.quarantine /Applications/MacroSIP.app。详见 安装。由应用自身安装的更新打开时不会出现此对话框。
没人听到我：麦克风权限
通话面板显示“麦克风访问已关闭”和打开系统设置 (Open System Settings)。请在系统设置 › 隐私与安全性 › 麦克风中允许 MacroSIP。由于临时签名，macOS 在每次更新后都会再次询问；更新后第一次通话时再允许一次即可。然后在说话时检查设置 › 音频中的电平表。
账户显示“403”或“401”
| 状态 | 含义 | 处理方法 |
|---|---|---|
| 401 Unauthorized、403 Forbidden | 服务器拒绝了凭据。设置 › 账户显示“REGISTER 于 14:52 被拒绝。请检查用户名和密码。” | 检查用户名 (Username)、密码 (Password)，以及如果您的 PBX 使用单独的认证名称，检查“高级”组中的认证用户名 (Auth username)。在编辑器中按测试 (Test)：“注册成功 (120 ms)”确认问题已修复。 |
| “无响应”（测试）或“Office · 8 秒后重试” | 服务器没有应答。 | 检查服务器名称和端口、传输 (Transport)（UDP、TCP 或 TLS；PBX 必须在您选择的那一种上监听）和防火墙。引擎按退避策略重试。 |
| 永不结束的“正在注册…” | 数据包发出但没有应答返回。 | 同上；尝试另一种传输，或设置 STUN 服务器 (STUN server)。 |
所有状态见 账户。
TLS 证书错误
使用传输：TLS时，引擎根据系统根证书验证服务器证书。与主机不匹配、已过期或自签名的证书会导致注册永久失败（不重试），状态和日志中给出 TLS 原因。请修复服务器上的证书，或者对于您信任的自签名证书，关闭编辑器“高级”组中的验证服务器证书 (Verify server certificate)（“仅对使用自签名证书的服务器关闭。”）。
没有声音或单向音频
通常是您与 PBX 之间的 NAT 或防火墙所致。设置 STUN 服务器，保持使用 ICE (Use ICE) 和使用 rport (Use rport) 开启，允许本地 SIP 端口和 RTP 端口范围上的 UDP，并检查设置 › 音频中的设备。完整的检查清单在 音频 中。
网络变化时通话中断
网络变化或唤醒时，引擎立即重新注册并发送 re-INVITE，使通话在 IP 变化后得以存续；期间通话面板显示“正在重新连接… 12 秒”，状态栏显示“Office · 8 秒后重试”。如果媒体在 60 秒内未恢复，通话结束并在通话记录中注明“连接已断开”。如果中断持续发生，请降低设置 › 网络中的保活间隔 (Keep-alive interval)。
耳机按键无效
MacroSIP 读取 USB 耳机的 HID 电话控制（摘挂机、闪断、保持、静音、重拨）。请检查设置 › 音频中的耳机按键 (Headset buttons) 已开启，并且该行显示了您的设备名称（“已连接：Jabra Evolve2 65”）；“没有带通话控制键的耳机”表示没有已连接的设备提供电话控制。设备被识别时，日志文件中有“headset buttons: connected, …”一行；macOS 拒绝打开设备时有“headset buttons: cannot open …”，这可能与“输入监控”权限有关（系统设置 › 隐私与安全性）。按键通过免提配置文件工作的蓝牙耳机由 macOS 处理，不受支持。同一面板中的耳机自动切换是独立的功能，不需要按键。
对方听不到保持音乐
检查设置 › 音频 › 保持音乐中的来源 (Source)：关闭 (Off) 发送静音。许多 PBX 会用自己的音乐替换电话在保持时发送的内容，因此对方听到的是服务器的音乐而非 MacroSIP 的；这是服务器端的设置。引擎无法读取的文件会保留之前的来源，组页脚会说明原因（“无法使用此文件：…”）。您自己永远听不到保持音乐。
铃声不是我选的那一个
- 打开设置 › 音频 › 铃声，点按播放 (Play)。预听播放的是真正的选择，音量为所设音量，所以您听到的就是来电时响的声音。经典、数字和柔和是三段不同的旋律。
- 如果弹出式菜单显示的是您自己的文件（“自定：office-bell.m4a”），响的却是原来的声音，请看该组下方是否有“无法使用铃声文件：…”。无法读取的文件（已损坏、受保护，或 macOS 无法打开的格式）会保留之前的选择。请使用 WAV、AIFF、M4A 或 MP3 文件。
- 完全没有声音：检查音量 (Volume)（0 即静音）和铃声设备 (Ringtone device)；它只是铃声的输出，可能指向耳机或另一个扬声器。
- 26.3 之前，所选旋律只用于预听，来电总是用默认的铃声。请更新到 26.3.0 或更新版本（安装）。
见 音频。
消息显示“已发送”，但手机没有收到
已发送 (Sent) 只表示 SIP 服务器（或对方）接受了消息，并不表示手机已收到：送达手机取决于服务器及其后面的环节（通过 Asterisk chan_dongle 发短信时：调制解调器、SIM 卡和运营商）。请查看服务器的日志。未被接受的消息会显示未发送、原因和重试 (Retry)。见 消息。
如果根本没有“消息”标签页，说明消息功能是关闭的：请在设置 › 通用中打开文字消息 (SIP MESSAGE)。
来电者姓名错误或缺失
姓名依次来自 SIP 显示名称、与其任一号码匹配的联系人，然后是最多查询一秒的目录来源。请将号码添加到联系人，或添加目录来源（目录）。
目录与 LDAP 错误
| 文本 | 含义 |
|---|---|
| “无法连接到 ldap.example.com” | 主机不可达或端口错误。 |
| “已超时” | 3 秒内无应答（导入为 30 秒）。 |
| “Bind DN 或密码无效” | 简单绑定被拒绝。匿名搜索请将 Bind DN 留空。 |
| “服务器必须为 ldap://host 或 ldaps://host” | “服务器”字段没有协议前缀。 |
| “请输入 http、https 或 file URL”、“HTTP 404” | URL 来源不可达或错误。 |
| “标题行中没有号码列”、“文件不是文本” | CSV 没有可识别的号码列，或不是文本文件。 |
| “文件不是有效的 JSON”、“JSON 中没有联系人数组” | JSON 来源格式错误。 |
| “访问被拒绝”、“尚未请求通讯录访问权限” | macOS 通讯录权限；请在系统设置 › 隐私与安全性 › 通讯录中允许 MacroSIP。 |
| “需要登录” | 没有有效令牌的 Google 通讯录（尚未登录，或访问被撤销）。在设置 › 目录中选中该来源并按登录… (Sign In…)；浏览器会打开 Google 的授权页面。 |
| “此构建未配置 Google 登录” | 该构建没有 Google 客户端 ID，因此无法登录 Google 通讯录；其他来源类型可以使用。请安装配置了 Google 登录的构建。 |
MacroSIP 无法翻译的库消息（LDAP 诊断信息）按原样显示。失败的来源会被跳过 60 秒，然后重试。
日志文件与拷贝诊断信息
MacroSIP 将日志写入 ~/Library/Logs/MacroSIP/MacroSIP.log（每个文件 2 MB，保留 3 个文件）。设置 › 通用 › 高级 › 打开日志文件夹 (Open Log Folder) 在访达中显示它；拷贝诊断信息 (Copy Diagnostics) 将版本、macOS、不含密码的账户和设置拷贝到剪贴板（“诊断信息已拷贝到剪贴板。”）。如需更深入的 SIP 跟踪，请用 open /Applications/MacroSIP.app --args --log-level 5（0–6）启动应用。应用也会以子系统 com.hsmm.macrosip 写入统一日志。
调试模式与诊断归档
调试模式会向日志写入更多细节，包括 SIP 消息。问题需要更细致地排查时请打开它，然后向开发者发送一个归档：
- 打开 Settings › General › Advanced › Troubleshooting，开启 Debug mode。它立即生效，无需重启，并会跨启动保持，直到您将其关闭。此时日志文件每个增长到 8 MB，保留 3 个文件。如果 MacroSIP 是以
--log-level或MACROSIP_LOG_LEVEL启动的，则以该级别为准：开关被禁用，并显示启动时的级别。 - 重现问题：拨打出现故障的通话，或尝试出现故障的注册。
- 在同一组中点按 Create Archive…，并选择保存 ZIP 的位置。默认文件名为
MacroSIP-diagnostics-YYYYMMDD-HHmm.zip，位于桌面。保存后，MacroSIP 会在访达中显示该归档，并弹出横幅“Diagnostics archive saved: …”。 - 将 ZIP 随问题报告一同发送，方法见下文“报告问题”。请只发送给您信任的人。
- 关闭 Debug mode。在关闭之前，日志会持续增长。
归档包含：
logs/：所有日志文件，包括轮转的旧文件；diagnostics.txt：诊断报告（版本、账户、设置和日志级别）；crash-reports/：MacroSIP 最近 30 天的崩溃报告，最多 5 个，原样包含。
电话号码和服务器地址会保留在归档中。副本中的密码和认证值会被移除（替换为 <redacted>）：digest 的 response、nonce、cnonce 和 opaque 值，Basic 与 Bearer 凭据，以及 URL 中的密码。您 Mac 上的日志文件不会被更改。
设置与联系人的存储位置
| 内容 | 位置 |
|---|---|
| 账户（不含密码）、联系人、通话记录、设置、快捷键 | ~/Library/Application Support/MacroSIP/ 中的 accounts.json、contacts.json、calllog.json、settings.json；照片在 photos/ 中。原子写入；损坏的文件被搁置为 <name>.broken-<date>.json 或 contacts.damaged-<date>.json，应用以能读取的内容启动。 |
| 密码（SIP 账户、LDAP 绑定） | 登录钥匙串，服务名 com.hsmm.macrosip，每个账户 ID 一项。删除账户会移除其钥匙串项。 |
| 录音 | ~/Music/MacroSIP Recordings 或设置 › 录音中选择的文件夹。 |
| 日志 | ~/Library/Logs/MacroSIP/。 |
要迁移到另一台 Mac，请拷贝 Application Support 文件夹并重新输入密码。
报告问题
在 github.com/HSMM/MacroSIP/issues 创建 issue，并附上：
- MacroSIP 版本（MacroSIP › 关于）和 macOS 版本。
- 拷贝诊断信息的输出（不含密码）。
- 您做了什么、期望发生什么、实际发生了什么，以及时间，以便在
MacroSIP.log中找到对应的行。对于通话或注册故障请附上日志，并删除任何隐私内容。 - PBX 或服务商类型（Asterisk、FreePBX、3CX 等），如果您知道的话。
功能请求也在同一位置提出；计划见路线图。