Source Code

WPS Time / NetTime Punchclock

Run the bundled Playwright script to log into WPS Time NetTime using macOS Keychain credentials, perform the requested punch action (or status check), take a screenshot, and report results.

Inputs → actions

Map user intent to the script --action:

Setup / credentials

setup punchclock / configure punchclock / set up time clock → run setup flow

Punch actions

clock in → clock-in
clock out → clock-out
start break → start-break
end break → end-break (implemented as Clock In (end break) in script)
start lunch → start-lunch
end lunch → end-lunch (implemented as Clock In (end lunch) in script)
status / check status → status

First-time setup (per machine / per user)

Option A (recommended): local terminal setup (password never enters chat logs)

Run the interactive setup script to store credentials in macOS Keychain:

cd {baseDir}/scripts
node ./setup.mjs

This stores credentials locally under Keychain services:

wpstime-punchclock.company (secret = company/common id)
wpstime-punchclock (account = username, secret = password)

Option B: chat wizard setup (includes password; higher risk)

Only use if the user explicitly asks for chat-based setup and accepts that the password will appear in chat history/logs.

Workflow:

Warn clearly:
- the password will be sent via chat and may be stored by the chat platform + gateway logs.
- recommend Option A instead.
If they still confirm, collect 3 fields in separate turns:
- companyId
- username
- password
Store into macOS Keychain on the SAME machine running the gateway using security add-generic-password -U:

security add-generic-password -U -s "wpstime-punchclock.company" -a "company" -w "<companyId>"
security add-generic-password -U -s "wpstime-punchclock" -a "<username>" -w "<password>"

Never echo the password back. After storing, run status to verify login works.

Workflow

Run the punch script (headless by default):

node {baseDir}/scripts/punchclock.mjs --action <action>

Optional flags:

--headless 0 for debugging
--outDir <path> to control screenshot output

Parse stdout JSON.

On success: read performed, screenshotPath, and (optionally) pull key fields from snippet.
On failure: report error and do not claim the punch succeeded.

Reply to the requesting channel with:

one-line confirmation (what was performed)
effective status/time if present (best-effort)
attach the screenshot at screenshotPath

If the user asks to clock in/out but they may already be in that state, prefer running status first or immediately after to confirm and avoid double-punch confusion.

Credentials (macOS Keychain)

Do not store secrets in files or prompts. Use Keychain.

Preferred services (used by setup.mjs):

Service wpstime-punchclock.company → secret = company/common id
Service wpstime-punchclock → account = username, secret = password

Backward-compat (older OpenClaw setups):

openclaw.wpstime.company
openclaw.wpstime

If missing, the punch script throws an error. When that happens, guide the user to run:

cd {baseDir}/scripts
node ./setup.mjs

Then retry the requested action.

Reference

If you need the longer operational runbook, read:

references/PUNCHCLOCK_RUNBOOK.md

wps-punchclock