OpenCLI: a practical guide to browser, adapter, and local-tool workflows
OpenCLI is an open-source command-line project for turning supported websites, logged-in browser sessions, desktop apps, and registered local tools into interfaces that people and AI agents can use. For an OpenClaw operator, it is useful when a task needs a known command or structured browser access instead of a fresh, screenshot-driven automation loop.
The name is ambiguous in search results. This guide covers jackwener/OpenCLI, the browser-and-agent project. It does not cover the OpenCLI specification at opencli.org or the unrelated open-cli npm package. That distinction matters before you install anything or hand a tool to an agent.
Contents
- What OpenCLI gives an agent
- Choose the right OpenCLI interface
- Set up OpenCLI without guessing
- Use profiles, sessions, and output deliberately
- Keep account actions under review
- Troubleshoot the actual failed layer
- FAQ
What OpenCLI gives an agent
OpenCLI has more than one operating mode. That is its practical advantage and the source of most confusion.
Its upstream README describes four useful surfaces: built-in adapters for supported sites, browser primitives for live Chrome interaction, plugins for reusable extensions, and a registry for local command-line tools. The right choice depends on whether the job is already modeled as a command, needs a real page, or belongs to a local program that already has a CLI.
| Interface | Use it when | What the agent receives | Main constraint |
|---|---|---|---|
| Built-in adapter | The target site and action are already supported | A named command and structured output | It cannot cover an arbitrary custom page flow |
opencli browser | The agent must inspect or operate a live page | Browser commands such as open, state, click, fill, and extract | It acts through a real logged-in browser context |
| Plugin or adapter | A repeatable site workflow is missing | A reusable command surface | It needs implementation and verification work |
| External tool registration | A local binary already does the job | A common discovery path for that binary | The binary still owns its own credentials and side effects |
The earlier OpenCLI skill workflow guide focuses on a narrower decision: when an agent should reuse an existing Chrome login rather than rebuild browser automation. This article is the broader map. Start with the interface that exposes the smallest safe surface for the task.
For example, a supported Hacker News query can use opencli hackernews top --limit 5. A custom form or a page that needs visual confirmation belongs in a browser session. If the same custom workflow will be used repeatedly, a plugin or adapter can turn it into a defined command instead of asking an agent to rediscover the page each time.
Choose the right OpenCLI interface
A good OpenCLI workflow begins with a boundary, not a command.
Prefer an adapter for known site actions
OpenCLI ships adapters for many services, including Reddit, Hacker News, X, Bilibili, LinkedIn, NotebookLM, and others. These are the best starting point when the site and action already exist because the output can be structured instead of extracted from a changing page.
Use opencli list to inspect the registered commands before asking an agent to browse manually. For data that will be passed into another tool or model, request a machine-readable format such as JSON. The upstream project documents table, json, yaml, md, and csv output formats.
Use browser commands for a real page, not as a default
opencli browser is the right interface when the task needs a site that has no adapter, a custom flow, or a visual state that structured output cannot show. The project documents page actions such as opening a URL, reading state, clicking, typing, filling forms, selecting options, waiting, extracting, and inspecting tabs.
Browser control still needs a scope. OpenCLI requires an explicit browser session name, and browser commands can be routed to a chosen tab. Give a task a bounded session and keep it close to the page it needs. Do not let a research task inherit an unrelated work profile merely because that profile is available.
The same rule applies to site permissions. A browser session may be logged in, but a logged-in session is not an instruction to publish, follow, delete, or change settings. For a broader model of limiting browser access, see AI browser agent privacy and per-tab access.
Build an adapter only after the workflow repeats
OpenCLI’s adapter-author guidance starts with reconnaissance, selecting an access pattern, deciding how authentication should work, decoding response fields, and verifying the resulting command. That sequence is useful because it separates a vague request, such as “get the daily trend,” from a testable interface with known fields and failure behavior.
If the result will be reused by multiple agents, keep the adapter source in version control and treat its permissions as part of the interface. A command that can write to an account deserves a different review path from a command that only reads public data.
Set up OpenCLI without guessing
The upstream project recommends its desktop app for macOS and Windows; a global npm install is the CLI path for servers and CI, with Node.js 20 or newer.
node --version
npm install -g @jackwener/opencli
opencli doctorBrowser-backed work also needs the OpenCLI Browser Bridge extension. Run opencli doctor before putting it into an agent workflow.
OpenClaw users should use the canonical OpenCLI skill page for the installed skill and its supported workflow guidance. The skill should describe when the agent may call OpenCLI; it should not become a blanket permission to access every account available in Chrome. How OpenClaw works explains the related distinction between a tool being connected and a tool action being authorized.
Use profiles, sessions, and output deliberately
Chrome profiles are operational boundaries. OpenCLI can list connected profiles, assign local aliases, and select the profile to use. When several profiles are connected and no default exists, it asks for a choice rather than guessing. Preserve that rule in the agent task: name the account context and use the matching profile.
For a browser task, make the plan explicit:
- Choose the intended profile before opening the site.
- Create a short-lived session name for the task.
- Inspect the page state before clicking or filling anything.
- Request JSON or CSV when downstream analysis needs structured data.
- Close the session or let its idle cleanup release the tab lease after the task finishes.
The project documents exit code 66 for an empty result, 69 for a Browser Bridge problem, 75 for a timeout, 77 for required authentication, and 78 for configuration errors. An agent should surface the class of failure rather than retrying every one as a network issue.
Keep account actions under review
For posting, replying, following, deleting, or changing settings, keep a human checkpoint before the final command. Show the target account, action, and content or record that will change. A login proves identity, not intent.
The principle carries beyond OpenCLI. AI agent skills and tools have different jobs: a skill can describe an operating procedure, while a tool call performs the action. Keeping those layers visible makes automation easier to audit and easier to stop.
Troubleshoot the actual failed layer
Start with the failed layer instead of reinstalling everything.
| Symptom | Likely layer | First check |
|---|---|---|
Extension not connected | Browser Bridge | Confirm the extension is installed and enabled, then run opencli doctor |
| Empty data or unauthorized result | Site login | Open the target site in the selected Chrome profile and confirm the session is still valid |
| Old-Node startup error | Runtime | Check that the npm installation uses Node.js 20 or newer |
| Timeout | Browser connection or page operation | Check the selected profile, target tab, and the command’s timeout before rerunning |
| Unexpected account context | Profile selection | List connected profiles and select the intended alias explicitly |
The OpenCLI v1.8.6 release also includes browser command deadlines, safe transport retries, and fixes for stale default profiles. Those are useful reliability improvements, but they do not eliminate the need to identify the affected profile and page before retrying an action.
FAQ
What is OpenCLI?
OpenCLI is the browser-and-agent project maintained at jackwener/OpenCLI. It exposes supported websites, logged-in browser sessions, desktop apps, and registered local tools through command-line interfaces that humans and AI agents can use.
When should an AI agent use OpenCLI instead of a browser automation framework?
Use a built-in OpenCLI adapter when the site and action are already supported and you want defined commands or structured output. Use opencli browser when the task needs a custom live-page interaction. Use a full browser framework when the workflow is outside OpenCLI’s coverage or needs its own implementation and testing model.
Does OpenCLI let an agent use every Chrome account automatically?
No. OpenCLI can work with connected browser profiles, but the operator should select the intended profile and constrain the session to the task. A logged-in profile does not grant blanket authority to publish, change settings, or act across accounts.