codex-paperclip

Standalone Codex gateway and Paperclip onboarding CLI.

It provides two things:

• a remote Codex gateway compatible with Paperclip's openclaw_gateway adapter
• a simple onboarding command that accepts a Paperclip invite URL and registers the agent automatically

Install

Global install:

npm install -g codex-paperclip

One-shot with npx:

npx --yes codex-paperclip --help

Requirements

• Node.js 20+
• Tailscale installed if you want automatic publish of the gateway URL
• access to a Codex-capable host
• a Paperclip invite URL for onboarding

codex-paperclip can:

• install @openai/codex automatically if codex is missing
• run codex login --device-auth if login is required
• generate and persist a gateway token automatically

Quick Start

Install the gateway as a service:

codex-paperclip install-service

If you run as a normal user, it installs a user service.

Useful commands:

systemctl --user status codex-paperclip-gateway.service
systemctl --user restart codex-paperclip-gateway.service
journalctl --user -u codex-paperclip-gateway.service -f

If you run as root, it installs a global service and uses system paths:

systemctl status codex-paperclip-gateway.service
systemctl restart codex-paperclip-gateway.service
journalctl -u codex-paperclip-gateway.service -f

Connect the agent to Paperclip:

codex-paperclip connect \
  --invite-url="https://paperclip.example/api/invites/token/onboarding.txt" \
  --agent-name="Codex Gateway"

Get the Invite URL

In Paperclip, go to Company -> Settings and click Generate OpenClaw Invite Prompt.

Paperclip will show a prompt like this:

You're invited to join a Paperclip organization.

The URLs you should try are:
- https://clawdbot.tail13fff8.ts.net/api/invites/pcp_invite_mzq0gqip/onboarding.txt

Copy the onboarding.txt URL and pass it directly to codex-paperclip connect:

codex-paperclip connect \
  --invite-url="https://clawdbot.tail13fff8.ts.net/api/invites/pcp_invite_mzq0gqip/onboarding.txt" \
  --agent-name="Codex Gateway"

Commands

Show help:

codex-paperclip --help
codex-paperclip connect --help

Run the gateway directly without systemd:

codex-paperclip gateway \
  --gateway-port=18789 \
  --gateway-host=127.0.0.1

Tokens and State

If you do not pass --gateway-token, the CLI generates one and stores it in:

~/.config/codex-paperclip/gateway.json

It also writes:

• ~/.config/codex-paperclip/gateway.env
• ~/.codex-paperclip/paperclip-join-state.json
• ~/.codex-paperclip/paperclip-claimed-api-key.json

When running as root, service-related paths use system locations such as:

• /etc/codex-paperclip
• /var/lib/codex-paperclip
• /etc/systemd/system/codex-paperclip-gateway.service

Tailscale

If there is no existing tailscale serve configuration for the gateway, connect can try to publish it automatically.

Typical local health endpoint:

curl -fsS http://127.0.0.1:18789/health

Package Notes

This repository contains the standalone packaged runtime for codex-paperclip, intended to be distributed and used independently from the original development workspace.