Stuck on Paperclip Onboarding (Need to bypass OpenAI/Claude requirement for local OpenCode/free models)

[Wdavi24]

Hi paperclip community, I'm having trouble getting Paperclip (v2026.1012.0) properly configured on Windows and could use some advice.

My goal is to run Paperclip using free OpenCode models and eventually experiment with local LLMs.

Current Setup & What's Working:

• npm and opencode are installed and operating as expected.
• Installed Paperclip via npx.
• Paperclip launches fine and serves the UI at localhost.

I’m stuck on the "Connect a Model" onboarding screen, which only gives me two choices: OpenAI or Claude.

• I previously used a $0 balance OpenAI API key to bypass this screen, but OpenAI now rejects $0 balance keys ('The provider rejected this API key'), so I can't pass validation.
• Setting "source": "configure" (or trying CLI arguments) still routes me back to the same "Connect a Model" screen.

Is there a way to bypass this onboarding gate or configure Paperclip directly to point to a local OpenCode instance or free provider without needing a funded OpenAI/Claude key? Appreciate any tips!

[leenlbma]

I don't think you need to bypass the gate. Here are a few supported paths that avoid a funded OpenAI or Claude key. I haven't tested these on Windows.

1. Create the agent with the OpenCode adapter directly

Paperclip ships an opencode_local adapter that runs your local opencode CLI, in provider/model format. See docs/adapters/overview.md and docs/agents-runtime.md. Paperclip assumes the CLI is already installed and authenticated, so check that opencode works in a terminal with your free model first.

From the source, the new-agent page accepts an adapter preselect:

http://localhost:<port>/<your-company-prefix>/agents/new?adapterType=opencode_local

I found that query parameter in ui/src/components/new-agent/NewAgentSetup.tsx, not in the docs. Treat it as unofficial, and it may change.

2. Use test-drive with OpenCode

The README documents an OpenCode harness for a pre-initialized instance:

OPENROUTER_API_KEY=... npx paperclipai test-drive --harness opencode --model openrouter/<model>

OpenRouter has free models, so you can pick one of those for --model. In PowerShell, set the key first with $env:OPENROUTER_API_KEY="...".

3. Local LLMs later

Point OpenCode at Ollama or any other OpenAI-compatible local endpoint in OpenCode's own config. Paperclip then just runs opencode, and the model choice stays on the OpenCode side.

Please don't use the $0-key trick. The validation is meant to catch keys that will fail at run time anyway.

If option 1 still bounces you back to "Connect a model", post your version and what the page shows. That would look like a bug rather than a configuration problem.

[Wdavi24]

Thank you kindly. I'm not sure that I understood all the instructions you provided, but it did give me the motivation to persist. Thank you.

In the end I started a new installation from scratch and used the help documents you referenced along with ChatGPT reading those documents to help with the set-up. It seems like their was a lot of additional steps related to getting the npm, npx installed and configured correctly.

Further, it seems that opencode needs to be configured via the CLI tool rather than in the GUI. So, far, I've passed the agent 'test', and now I'm working on getting my first 'task' executed.

Thank you again.

[techiem2]

Mind sharing how you got it to work? Thanks to the above I was able to bypass the gate, but I'm still struggling to get OpenCode working. I create the Agent, pick Opencode - but that wants a connection..so I picked the local endpoint, started opencode in server mode, and entered that info. Paperclip connects, but won't let me select a model. It has the freeform model box, but that doesn't work because it automatically prepends paperclip to any model entered..which of course causes the verification to fail since that's not a proper provider (only opencode/modelname and ollama/modelname according to the test output.

[Wdavi24]

Indeed I've struggled with this, and have had several failed attempts. Here are the steps I wrote down, maybe it'll work for you.

1. install opencode and config for you model.
2. install nodejs
3. install npm
4. npx --yes paperclipai@latest install
5. paperclipai install
6. paperclipai onboard (-> quickstart option)
7. paperclipai llm agent-configuration:adapter opencode_local
8. Now go to the dashboard in the GUI and create the company only
9. Return to CLI
   paperclipai agent create --company-id <> --payload-json '{"name":"CEO","role":"ceo","adapterType":"opencode_local","adapterConfig":{"model":"opencode/big-pickle","command":"/home/user/.opencode/bin/opencode","cwd":"/home/user/paperclip-workspace","dangerouslySkipPermissions":false}}'
10. Refresh browser, and hopefully/maybe you'll see the GUI dashboard.

[grozmus]

I've just hit the same wall and I can't believe someone made onboarding so limited. OpenAI or Anthropic and no other options? No option to provide custom api url? I was eager to try it but I think I'm done. If someone made this decision then probably made more as bad.