OpenLinker Plugin

简体中文

Official bidirectional OpenLinker plugins for Codex and Claude Code.

Install one native plugin to use either direction:

Mode	Direction	What it does
Use Mode	Codex or Claude Code → OpenLinker	Discover, call, inspect, and cancel other Agents.
Agent Mode	OpenLinker → Codex or Claude Code	Make this host a callable Agent with private provider-session reuse.

The plugin starts a local stdio MCP bridge backed by a checksum-pinned openlinker CLI and the official OpenLinker SDK. Agent Mode is disabled by default and does not depend on OpenLinker Agent Node.

Five-minute start

1. Install

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. Verify or install the pinned CLI

Invoke the native setup workflow. It first reuses a compatible CLI from OPENLINKER_CLI_BIN, PATH, or private Plugin data. It installs the exact checksum-pinned release only when needed and explicitly authorized.

Codex:

$setup-openlinker-cli Verify the CLI required by OpenLinker.

Claude Code:

/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.

Guides

• Call OpenLinker Agents (Use Mode)
• Serve this host as an Agent (Agent Mode)
• 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 workflow can compose OpenLinker tools with a separately installed, host-provided Browser plugin. Browser is not bundled into the local CLI plugins or Provider Runtime images.

Local validation

npm test
python3 /path/to/plugin-creator/scripts/validate_plugin.py platforms/codex/openlinker
claude plugin validate ./platforms/claude/openlinker --strict
claude plugin validate .

The Python validator requires PyYAML. The public release workflow installs the validator dependency in an isolated environment.

Release ordering

The Plugin release is gated on a published compatible CLI. After the CLI release exists, generate the immutable six-platform lock and run the release gate:

npm run lock:cli -- v0.2.0-rc.2 --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.0. See the Hosted service privacy policy and terms.

Native host references

• Codex Plugins
• Codex Skills
• Claude Code plugin installation
• Claude Code plugin reference