PKU harnessTroubleshooting
Common problems with PKU harness and how to solve them — the campus network, verification codes at sign-in, AI provider and voice input errors, attached files, late reminders, app updates, the payment code and Copilot setup.
This page lists common problems, with the cause of each and what to do.
Campus services and sign-in
Finance portal: campus network only
The finance portal (cwfw.pku.edu.cn) only works on the PKU campus network. Connect to the campus network (PKU or PKU Secure) and try again. The app connects to campus services directly, without the system proxy. Every plugin marked Campus network only in the plugin list has this limit.
Can't reach a site
The message names the site and the cause. The site may be under maintenance or not open yet, or it may only work on the campus network. Check your connection and try again later.
Asked for a code at sign-in
The university's sign-in sometimes asks for an SMS code, an email code or an authenticator code. This is normal, and it can also happen when the app refreshes a session in the background. Enter the code when asked; see Campus account and authenticator → Verification codes.
If a code is needed during a background refresh, the app says the campus sign-in needs a code and asks you to open the app. Open it and enter the code.
Treehole asks for its own SMS check from time to time. Reading your timetable and grades may also need an authenticator or SMS code.
Authenticator required but not set up
Your account uses the mobile authenticator, but this app isn't your authenticator. Enter the code from the authenticator app you use now, or make this app your authenticator; see Authenticator. Note that your old authenticator stops working once you do.
Plugin shows Needs sign-in
The plugin needs your campus account. Sign in under Settings → Campus account.
AI provider
Connect AI service on the Chat tab
No AI provider is set up yet. Tap the button or open Settings → AI provider; see AI provider.
Errors when testing the connection
| Message | What to do |
|---|---|
| The API key is invalid or has been disabled | Check that the key is complete and still active on the provider's website |
| Your account balance is too low | Top up on the provider's website first |
| That address doesn't look right | Check the base URL; it usually ends in /v1 |
| Too many requests | Wait a moment and try again |
| The connection timed out / Can't reach the service | Check your network and the base URL |
For Alibaba Cloud Bailian, a key only works in the region where you created it; the base URL in
AI provider is for the Beijing region. For
Baidu Qianfan, copy the whole key, including bce-v3/. If the test says the model doesn't exist,
check the spelling of Model ID against the provider's model list.
Can't send images
The current model doesn't accept images. For example, DeepSeek-V4-Pro doesn't and DeepSeek-V4.1-Flash does. The attachment sheet says so and offers Switch when another model can. The app doesn't offer images for models connected through OpenAI-compatible.
Voice input and files
Voice input doesn't start
The message tells you what is missing: a service, an API key or microphone access. See Voice input → When voice input doesn't work.
A file can't be read
| Message | Cause |
|---|---|
| This PDF is scanned images without text… | The PDF holds only pictures of pages, and no DeepSeek API key is saved. Add one in Settings → AI provider to have it recognised, or take photos of the pages and send them as images |
| DeepSeek OCR couldn't recognise this scanned PDF: … | The reason comes from DeepSeek. Check that your DeepSeek account has a balance and the file is at most 100 MiB and 1,000 pages, or take photos of the pages instead |
| This file is password protected… | Remove the password, then attach it again |
| This file is damaged or not the type its name says. | Open it on a computer and save it again |
| File too large… | Text files can be up to 200 KB, documents up to 30 MB, audio up to 50 MB |
| … only transcribes live speech… | Alibaba Cloud Bailian (live) can't transcribe audio files. Choose SiliconFlow in Settings → Voice input |
Reminders and scheduled tasks
Reminders are late or missing
- Open Settings → Reminders and alerts.
- Check that Notifications says Allowed and Exact alarms says "Reminders arrive on time".
- For Unrestricted battery, tap Turn on, then Allow in the system dialog.
- Tap Send a test reminder, go to the home screen and wait 10 seconds to check that it arrives.
Scheduled check paused
A scheduled check pauses itself after 10 failures in a row. Common causes are an expired sign-in, a service that needs the campus network, or a site under maintenance. Once the cause is fixed, turn its switch back on under Reminders and scheduled tasks on the Schedule tab.
Updates
Can't install an update
The first time you update through the app, Android asks you to allow PKU harness to install apps. Turn that switch on and go back to the app; the installer continues. If you didn't see the request, find PKU harness in Android's app info and allow it under "Install unknown apps".
Download failed
Check your connection, then tap "Version X.Y.Z is available" at the top of Settings to try again, or check again in Settings → About → Check for updates. You can also download the APK from the download page and install it over the app; your data stays.
Campus Card
Payment code needs digital card
Payment codes only work in digital card mode (数字卡). Tap Switch to digital card. Your physical card or phone NFC may stop working afterwards; you can switch back under Card mode.
Balance unchanged after top-up
After paying at the cashier, tap your card once on a canteen POS for the balance to update. After a bath card top-up, tap the bath card on a top-up kiosk.
Copilot
For a full walk-through, see Copilot.
Copilot needs Android 12 or later
Copilot uses features that Android added in version 12. On older phones the rest of the app works, but Copilot doesn't.
Can't find Developer options or Wireless debugging
Use the search box at the top of Android's Settings: search for build number, tap it seven times, then search for wireless debugging. Each brand puts these in a different place; see Where the switches are on your phone.
The pairing code doesn't work
The code changes each time the pairing dialog opens, and it stops working when the dialog closes. Keep the dialog open, pull down the notification shade, and type the code shown now. If the notification says the code was wrong or expired, tap Pair device with pairing code again and enter the new code.
The phone helper doesn't connect
- Connect to Wi-Fi, and allow Wireless debugging on this network when Android asks.
- If the Copilot screen says "Pairing authorization is no longer valid", pair again.
- If Copilot keeps disconnecting, set PKU harness to unrestricted battery use, and on Xiaomi phones also allow Autostart.
Can't turn on Copilot accessibility
For apps installed from an APK, Android treats turning on an accessibility service as a restricted setting. There are two ways around it:
- Connect the Phone helper first. It turns accessibility on by itself; if not, tap Turn on in the accessibility step.
- On the Copilot screen, tap Turn on in Settings instead, then Open App info, tap ⋮ in the top corner, choose Allow restricted settings, then turn on Copilot in Android's accessibility settings.
On OPPO and OnePlus phones, also turn on Disable permission monitoring in Developer options. See Copilot → Accessibility.
"Turn on PKU harness in Settings > Accessibility"
Copilot checks its accessibility service before every action and turns it back on when it can. If it can't, for example because the phone helper isn't connected, the assistant asks you to turn it on and stops. Open Settings → Accessibility, turn on Copilot, and send your request again.
Copilot reads the app, but taps and typing do nothing
On Xiaomi, Redmi and POCO phones, turn on USB debugging (Security settings) in Developer options and restart the phone. On OPPO and OnePlus phones, turn on Disable permission monitoring. See Known blockers by brand.
WeChat is blocking automated operation
WeChat's own anti-automation checks have flagged Copilot. Copilot says so and stops; do that step yourself in WeChat. This is decided on Tencent's servers, and Copilot doesn't try to get around it. See Copilot → WeChat.
The keyboard needs two taps per key
Copilot's accessibility service makes some keyboards, such as Samsung Keyboard, switch to screen-reader typing. Copilot switches the service off between tasks, which needs the phone helper to be connected. Open the Copilot screen so the helper reconnects. See The keyboard needs two taps per key.
Enable Copilot switch is disabled
All of these must be true: the phone helper is connected, the accessibility service is on, at least one app is allowed, and any Unavailable apps have been removed.
Settings and your data
Everything on the Settings tab — account, AI provider, voice input, cloud, usage, plugins, reminders and alerts, appearance, language, time zone, haptics, exporting and erasing data, updates and the About page — and how the assistant changes settings for you in chat.
Architecture
The PKU harness core is an agent loop, a design system and a set of host services. Every feature comes from a plugin, and all plugins use the same interface.