OpenLinker Plugin

Native MCP and Agent/Browser execution are delivered by the Plugin-owned openlinker-plugin-host. The platform CLI is a separate caller tool.

简体中文

Official bidirectional OpenLinker plugins for Codex and Claude Code.

Install one native plugin to use either direction:

The plugin starts local stdio MCP bridges in its checksum-verified openlinker-plugin-host, using the official OpenLinker SDK. Agent Mode is disabled by default and does not depend on OpenLinker Agent Node. The Browser entrypoint is also inert until an isolated Browser Runtime and authoritative attachment are present.

Source and delivery boundaries

This repository owns both small native host packages and the reusable Go module github.com/OpenLinker-ai/openlinker-plugin. packages/agent-adapters contains Provider/session execution and SDK application composition; packages/browser-runtime contains pure Browser protocols/services, engine/native assets, and egress. The SDK remains the only Runtime Worker implementation. The Plugin host consumes these packages; CLI has no execution dependency on Plugin. Plugin cannot depend on CLI, and Cobra stays in the host composition root; pure Browser packages cannot transitively depend on SDK. Standalone Agents need no native plugin installation; Browser stays a separate process/image.

Dockerfiles, portable compose, and regression gates are owned here. Native installation archives contain the pinned host installer, without Go sources, foreign-platform hosts or Browser engine binaries. Credentials, volumes, Profile formats, and identities remain unchanged.

Related MCP server: Multi-CLI MCP

Five-minute start

1. Install

Git marketplace and release packages both include an explicit host installer and host-lock.json. Setup downloads only your platform's fixed GitHub release and checks its archive and binary SHA-256, source commit and capability metadata. Node.js 20+, curl and tar are required; Go, administrator rights and the platform CLI are not. Ordinary task/tool startup never downloads executables.

For Codex:

codex plugin marketplace add OpenLinker-ai/openlinker-plugin
codex plugin add openlinker@openlinker

Start a new Codex task or CLI session after installation. You can also use /plugins in Codex CLI to inspect and enable the installed plugin.

For Claude Code:

claude plugin marketplace add OpenLinker-ai/openlinker-plugin
claude plugin install openlinker@openlinker

Run /reload-plugins in Claude Code after installation. Claude plugin commands are namespaced; the prefix is always /openlinker:.

2. Install the pinned Plugin host

After installing or updating the Plugin, run this setup Skill even if MCP reports that its host is missing. Skills and slash commands do not depend on MCP startup.

Codex:

$setup-plugin-host

Claude Code:

/openlinker:install-plugin-host

The installer shows its version, release URL, platform and private destination. Reload plugins or start a new task after setup. For manual setup, run node "<installed-plugin-root>/scripts/install-plugin-host.mjs" --plan, then repeat without --plan. See HOST.md for cache paths and repair. Standalone caller Skills can optionally install the platform CLI using $setup-openlinker-cli or /openlinker:openlinker-setup.

3. Initialize Use Mode

Provide the Core URL and a least-privilege User Token to the host process, not to a prompt or project file:

export OPENLINKER_API_BASE=https://api.openlinker.ai
export OPENLINKER_USER_TOKEN='ol_user_<redacted>'

Set the variables before starting Codex CLI or Claude Code. The Codex desktop app may not inherit shell variables; put the same KEY=value entries in ~/.codex/.env, restart the app, and start a new task. Do not commit that file.

Call OpenLinker through the native host surface:

Codex:

$openlinker Find a callable research Agent for this task, but do not run it yet.

Claude Code:

/openlinker:openlinker Find a callable research Agent for this task, but do not run it yet.

Discovery is read-only. Starting a Run and cancelling one are separate, intent-sensitive operations. Continue with the Use Mode guide.

4. Initialize Agent Mode

Agent Mode requires an existing OpenLinker Agent UUID, an Agent Token, a minimal workspace, and an authenticated codex or claude provider CLI. Inject secrets before starting the host:

export OPENLINKER_AGENT_TOKEN='ol_agent_<redacted>'
# Optional when the provider CLI is not already logged in:
export CODEX_API_KEY='<redacted>'
# For Claude Code provider mode use ANTHROPIC_API_KEY instead.

Direct secrets also support mutually exclusive _FILE alternatives. Never put an Agent Token or provider key in a Skill invocation.

Configure only non-secret values, diagnose, and then enable explicitly:

Codex:

$serve-openlinker-agent Configure Codex with Agent ID <agent-uuid>, workspace /absolute/minimal/workspace, and URL https://openlinker.ai. Do not enable it yet.
$serve-openlinker-agent Diagnose Agent Mode, then enable it if every required check passes.

Claude Code:

/openlinker:openlinker-agent Configure Claude Code with Agent ID <agent-uuid>, workspace /absolute/minimal/workspace, and URL https://openlinker.ai. Do not enable it yet.
/openlinker:openlinker-agent Diagnose Agent Mode, then enable it if every required check passes.

OPENLINKER_NODE_ID is optional. The Runtime generates and privately persists one when it is absent. Continue with the Agent Mode guide.

5. Use the isolated Browser

Browser is a tool of the executing Codex or Claude client. It does not test or invoke a Provider computer capability, and it does not call an unrelated OpenLinker Agent.

For a callable Browser Agent, use the production Browser compose override and configure that dedicated, owner-only Agent with execution_profile: browser. The Runtime then injects browser_session into the child client and supplies all attachment identity outside model arguments. The Browser container never receives the Provider key.

Codex:

$use-isolated-browser Explain Browser Agent readiness without opening a page.

Claude Code:

/openlinker:use-isolated-browser Explain Browser Agent readiness without opening a page.

Continue with the isolated Browser guide.

Guides

• Call OpenLinker Agents (Use Mode)

• Serve this host as an Agent (Agent Mode)

• Use the isolated Browser

• Browser architecture overview

• Configuration reference

English is the canonical documentation language. Each guide links to its secondary Chinese translation.

Packages

• platforms/codex/openlinker: native Codex plugin package.

• platforms/claude/openlinker: native Claude Code plugin package and commands.

• shared/skills: canonical Skills mirrored byte-for-byte into both packages.

• shared/contracts: caller, Agent Mode, and CLI release contracts.

• shared/assets: shared brand assets.

• chatgpt: authenticated ChatGPT App readiness contract and Browser workflow.

The ChatGPT package is intentionally not installable yet. ChatGPT expects an authenticated MCP app that exposes user data or write tools to use OAuth 2.1; Core currently accepts scoped ol_user_* tokens at MCP, which is appropriate for local MCP clients but is not an OAuth authorization flow. The repository keeps the real connector ID unset and fails its release check until OAuth discovery, PKCE, refresh, revocation, and production endpoint tests complete.

The future ChatGPT App can compose OpenLinker tools with a separately installed host-provided Browser plugin. Ordinary Codex and Claude installs do not declare the isolated Browser MCP entrypoint; the authoritative Runtime injects it only for an attached Browser Agent. Chromium remains in a separate isolated Runtime container and is never bundled into the Provider image.

Local validation

Building or validating native Runtime packages requires Node.js and the Go version in go.mod. Build tools resolve the exact Agent Node module in go.mod/go.sum with GOWORK=off, verify its checksum and module cache, and read its canonical openlinker.agent-host.v1 contract. They do not use a sibling checkout or copied protocol definition. This is a build-only dependency: installed native packages and final Provider images gain no Go toolchain or Agent Node service requirement. Codex schema refresh now belongs to the Agent Node repository; this repository's generator command only supports --check against its pinned module.

Codex app-server execution uses the pinned Node module's codexturn leaf for native environment/home preparation, the complete turn protocol, cancellation and shutdown. Plugin supplies its Browser installation hook, launch arguments and progress observer; it does not run an Agent Node process. Provider session policy and result metadata remain owned by Plugin.

npm test
npm run test:go
npm run check:go-boundaries
npm run check:agent-runtime-integration
python3 /path/to/plugin-creator/scripts/validate_plugin.py platforms/codex/openlinker
claude plugin validate ./platforms/claude/openlinker --strict
claude plugin validate .

The optional Python validator requires PyYAML in its own environment. The same-tree integration gate generates both minimal native packages and runs the Go consumer against their actual manifests, Skills, and Browser wiring.

Release ordering

Publish the Node protocol module before consuming its exact pin. The Plugin tag builds/tests its module independently of CLI. Host publication builds six per-platform archives from an immutable Plugin tag. Generate all three host locks from those publicly downloadable archives before merging the native installer update. Git marketplace and native packages share the same locks and install only the current platform. Provider images build their host from an explicitly identified Plugin archive and expose host build evidence. CLI release locks are only for caller Skills, not the MCP/Worker executable. Before native publication, run:

npm run lock:cli -- <published-cli-version> --write
npm run release:check

The installer follows only approved public GitHub release hosts, honors standard HTTP/HTTPS proxy variables through curl, verifies both the adjacent checksum and the digest pinned in cli-lock.json, extracts only the expected executable, validates its JSON capability surface, rejects symlinked destinations, and replaces the previous binary atomically.

Local marketplace testing

For Codex:

codex plugin marketplace add /absolute/path/to/openlinker-plugin
codex plugin add openlinker@openlinker

For Claude Code:

claude plugin marketplace add /absolute/path/to/openlinker-plugin
claude plugin install openlinker@openlinker

Release archives and checksums are available from v0.1.2. See the Hosted service privacy policy and terms.

Native host references

• Codex Plugins

• Codex Skills

• Claude Code plugin installation

• Claude Code plugin reference