macOS Universal Clipboard Repair

简体中文

Development note

The code, interface, build scripts, and documentation for this project were completed with OpenAI Codex collaboration, with the repository kept public for review, reproducible builds, and independent compilation. The repair actions remain limited to macOS-native operations described in this README.

Download the latest macOS DMG

macOS Universal Clipboard Repair is a small, local-only diagnostic and repair app for Apple Continuity features:

• Universal Clipboard / Handoff
• Continuity Camera
• Wi‑Fi and Bluetooth readiness
• System proxy status
• Recent Continuity Camera state: magic, usable, nearby, wired

It is designed for the narrow failure mode where macOS discovers another Apple device but a Continuity service is stuck. It does not replace Universal Clipboard, store clipboard history, or synchronize clipboard data itself.

The app includes Simplified Chinese and English UI languages. It follows the macOS language on first launch, and the language can be switched from the upper-right control; the choice is saved locally for the next launch.

Ready to use: no installer and no sudo required. Download the Release DMG, open it, and drag the app to Applications. A ZIP archive is also provided. The app bundle is about 2.3 MB, making it a few-megabyte lightweight utility. Actual idle RSS includes macOS/AppKit frameworks; it measured about 91 MB RSS on the development Mac and varies by macOS version.

The downloads badge above shows the cumulative download count for all GitHub Release assets. The Releases page also shows the count for each version archive.

The bottom of the app window shows the current version, a link to the GitHub repository, and a Check for updates entry. Clicking it opens the GitHub Releases page; the app does not continuously access system data or make background network requests.

Typical symptoms and search terms

This project is intended for symptoms such as:

• Mac, iPhone, or iPad cannot copy and paste across devices
• Universal Clipboard, shared clipboard, or Handoff / 接力 stops working while devices are still discoverable
• Universal Clipboard fails in only one direction: Mac to iPhone works but iPhone to Mac does not, or vice versa
• ClipboardSharingEnabled is 0, disabled, or missing
• useractivityd, sharingd, or pboard is not running as expected
• Continuity Camera / shared camera is unavailable, or the camera works while Universal Clipboard does not
• ContinuityCaptureAgent is missing, repeatedly exits, or reports magic, usable, nearby, or wired as UNKNOWN
• A proxy or scientific-networking plugin makes Continuity recover after switching between Global and Rule mode

Search terms include: Universal Clipboard not working, Handoff not working, shared clipboard Mac iPhone, ClipboardSharingEnabled 0, useractivityd, sharingd, pboard, Continuity Camera not working, ContinuityCaptureAgent, macOS clipboard sharing, 通用剪贴板失效, 接力失效, and 共享摄像头无法使用.

Recommended troubleshooting order

Start with the simplest and lowest-risk action. Most temporary failures do not require signing out of iCloud, resetting networking, or modifying Keychain data.

Step 1: Restart each side

1. First restart the device that cannot send its clipboard content. After it starts and is unlocked, wait about 30 seconds, then copy a short plain-text sample from Apple Notes and test again.
2. If the problem remains, restart the other device that receives and pastes the content, then retest.
3. If you cannot tell which side is faulty, restart both the iPhone or iPad and the Mac.

A one-way failure helps identify the affected side:

• Mac → iPhone works, but iPhone → Mac fails: restart the iPhone first.
• iPhone → Mac works, but Mac → iPhone fails: restart the Mac first; if restarting does not help, run this app's Handoff / Universal Clipboard repair.

This project has recorded a confirmed one-way incident: Mac → iPhone worked while iPhone → Mac failed. The Mac discovered the iPhone, but the phone did not advertise shared clipboard availability. Restarting the iPhone restored the feature. In this situation, repeatedly restarting useractivityd, sharingd, and pboard on the Mac cannot repair the phone-side service.

Step 2: Check the prerequisites

• Both devices use the same Apple Account.
• Wi-Fi, Bluetooth, and Handoff are enabled on both devices.
• Keep both devices unlocked and nearby, and test with a small plain-text selection first.
• If either device runs beta system software, install the latest available update first.

Step 3: Repair the Mac services

If restarting does not help and the Mac still cannot send or receive clipboard content, run the app's Handoff / Universal Clipboard repair. The button can restart only the relevant macOS services; it cannot restart or repair clipboard services inside an iPhone or iPad.

Try proxy-mode changes only after these steps. A USB cable does not replace the Bluetooth discovery and nearby Wi-Fi link used by Universal Clipboard, so connecting a cable normally does not repair shared clipboard failures.

Safety boundary

The app:

• uses no sudo;
• does not sign out of iCloud or Apple Account;
• does not reset networking;
• does not modify Keychain data;
• does not make network requests;
• keeps Handoff and Continuity Camera repairs as separate actions.

The Handoff repair uses the following user-level operations:

defaults delete ~/Library/Preferences/com.apple.coreservices.useractivityd.plist ClipboardSharingEnabled
defaults write ~/Library/Preferences/com.apple.coreservices.useractivityd.plist ClipboardSharingEnabled 1
killall useractivityd
killall sharingd
killall pboard

The camera repair only restarts ContinuityCaptureAgent and waits for it to return.

Proxy tools

Final tip: try switching the scientific-networking/proxy plugin back and forth between Global and Rule mode. If none of the steps above works, restart both devices separately—the final of the Thirty-Six Stratagems and the last resort. The app intentionally uses generic wording and only reads system proxy state; it cannot reliably determine the internal mode of every proxy plugin.

Camera state

The camera panel reads recent ContinuityCaptureAgent logs. The expected wireless-ready state is:

magic:1
usable:1
nearby:1
wired:0

If there is no matching log entry in the recent window, the app shows UNKNOWN instead of presenting stale data as current.

Build

Requirements:

• macOS 13 or newer
• Apple Command Line Tools (clang)

Build the app locally:

./build-app.sh
open "build/Universal Clipboard Repair.app"

First launch and Gatekeeper override for end users

When signing credentials are not configured, this repository still produces a transparent, testable unsigned app. If macOS says it cannot verify the developer, blocks the app, or suggests moving it to the Trash after download, follow these steps:

1. Download the DMG from a GitHub Release, open it, and drag the app to Applications. The ZIP asset may be used instead, but do not run the app from the archive preview window.

2. Double-click the app in Applications once so macOS records the blocked launch.

3. Open System Settings → Privacy & Security, scroll to Security, click Open Anyway, and confirm Open. This button normally appears for a short time after you try to launch the app.

4. Alternatively, right-click the app, choose Open, and confirm Open again.

5. If Open Anyway is still not available, and you trust the download source, you can remove the quarantine flag for this file in Terminal. Adjust the path if the app is stored elsewhere:

   xattr -dr com.apple.quarantine "/Applications/Universal Clipboard Repair.app"

   If the app has a different name or location, replace the final path with the actual path. This only removes the downloaded-file quarantine flag; it does not disable Gatekeeper for the whole Mac.

After one successful approval, macOS will normally allow the same app to open by double-clicking it. Only override Gatekeeper for a copy whose source you trust and whose contents have not been altered.

For a true double-click launch without any user-side override, the repository must publish a build signed with a Developer ID Application certificate and notarized by Apple. Putting an unsigned app in a DMG does not bypass Gatekeeper. The workflow includes an opt-in signing, notarization, and stapling path; if it is not enabled, it does not pretend that the artifact is signed.

GitHub Actions

To build a downloadable app from GitHub:

1. Open the Actions tab.
2. Select Build macOS App and DMG.
3. Leave the version field blank to use the latest v* tag, or enter a version such as 1.0.3.
4. Choose Run workflow.
5. Download the versioned Universal-Clipboard-Repair-v*-macOS-assets artifact from the completed run.

Pushing a version tag such as v1.0.3 runs the same build and creates or updates the matching GitHub Release. Each release contains:

• Universal-Clipboard-Repair-v*-macOS.dmg for the standard drag-to-Applications flow;
• Universal-Clipboard-Repair-v*-macOS.zip containing the app bundle;
• Universal-Clipboard-Repair-Script-v*-macOS.zip for script-only repair;
• SHA256SUMS-v*.txt for integrity verification.

Unless the signing secrets below are configured, both the DMG and ZIP contain the same unsigned, unnotarized app and require the first-launch Gatekeeper approval described above.

Script-only mode

Every GitHub Actions build also creates a standalone script archive:

Universal-Clipboard-Repair-Script-v*-macOS.zip

It does not require opening the GUI app. Unzip it and double-click Fix-Universal-Clipboard.command, or run it from Terminal:

zsh ./Fix-Universal-Clipboard.command

The script-only version handles Universal Clipboard / Handoff only: it resets ClipboardSharingEnabled, restarts useractivityd, sharingd, and pboard, waits about 8 seconds, and checks their state. It does not use sudo, sign out of iCloud, reset networking, modify Keychain data, or touch Continuity Camera.

The script archive is uploaded alongside the App archive and DMG as both a GitHub Actions artifact and a GitHub Release asset.

Enabling signing and notarization

Maintainers can add these GitHub Actions Secrets in the repository settings:

• SIGNING_ENABLED: set to true to enable the signing path
• APPLE_CERTIFICATE_BASE64: Base64 content of the Developer ID Application .p12 certificate
• APPLE_CERTIFICATE_PASSWORD: password for the .p12 file
• APPLE_SIGNING_IDENTITY: certificate name, such as Developer ID Application: Example (TEAMID)
• APPLE_ID: Apple account used for notarization
• APPLE_TEAM_ID: Apple Developer Team ID
• APPLE_APP_PASSWORD: app-specific password for that Apple account

Keep certificates, passwords, and private keys in GitHub Secrets only. Never commit them or paste them into an Issue, README, or chat.

Similar projects and scope

This project is intentionally different from clipboard synchronization apps. Public projects found during the initial search include:

• A Universal Clipboard repair gist, which documents the ClipboardSharingEnabled reset but is not a full diagnostic app.
• Machete, a broad macOS tuning/debloating toolkit that includes Continuity-related service controls; it is much broader and more invasive than this project.
• UniClipboard and Uniclip, which implement alternative clipboard synchronization rather than repairing Apple's native Continuity stack.

The goal here is a small, transparent, reversible repair and observation tool for Apple's native services.

Contributing and changelog

• Contributing guide
• Changelog
• Report a bug

License

MIT. See LICENSE.