opencode-chromium

社区与路线图

路线图由用户驱动——在 GitHub Discussions 上提出提案、用表情符号投票，并关注公告：

• 功能请求 — 发起提案（模板可保持结构清晰）： 描述问题以及它应解锁的工作流程；其他人用 👍/❤️ 表情符号投票。 维护者将获得投票的提案分类到后续工作中，并标记其状态（planned、in progress、released）。 发起提案 →

• 公告 — 版本发布、路线图状态和维护者说明。 关注公告 →

• 协议 — 功能请求涉及本仓库发布的内容 （运行时、扩展、原生主机、技能）；错误报告和安全发现 应提交到 GitHub Issues。

Related MCP server: chrome-devtools-mcp

提供的功能

• 四个紧凑的默认工具：browser_run、browser_observe、browser_session 和 browser_finalize。

• 完整的多操作浏览器引擎，支持显式的兼容性和能力模式。

• 上下文精简的证据：观察摘要省略空字段、重复文本和冗长的 html/styles（仅可通过 detail: "debug" 获取），内联响应保持在 4,096 字符预算内，超大的输出溢出到工件资源。

• 原生悬停、带批准门控的 JavaScript 对话框处理，以及带质量控制的 png/jpeg/webp 截图。

• 非侵入式后台自动化：点击、输入和导航从不激活标签页或将其窗口带到前台，因此工具驱动后台标签页时你可以继续工作。

• 服务器级来源策略（允许/阻止的来源通配符）和上传的文件根限制。

• 持久会话模拟（视口、网络、CPU、地理位置、配色方案、用户代理、请求头、初始化脚本），在 finalize 时自动重置。

• 按 requestId 进行网络请求下钻，支持工件支持的正文溢出，以及带源映射的控制台堆栈跟踪。

• 性能诊断：browser_observe 的 diagnostic 模式在原生主机中记录 CDP 跟踪并计算 LCP、CLS、长任务、TBT 等；原始跟踪以工件优先，CrUX/现场数据保持关闭。

• Snowflake 默认页面搜索，提供显式的词法/自动替代方案，以及无需在扩展中加载模型的 Qwen 深度检索。

• 配置文件感知的会话、标签页所有权、过期目标恢复、有界读取重试、条件稳定、批准和工件资源。

• MCP stdio 和回环/认证 HTTP 传输，具有协议干净的 stdout。

• 原生 OpenCode V2 适配器，以及共享的 OpenAI、Anthropic、Gemini 和 MCP 模式适配器。

快速开始（npm）

安装已发布的包一次，然后连接任何受支持的客户端。该 包附带 CLI（opencode-chromium）、MCP 服务器二进制文件 （opencode-chromium-mcp）、浏览器扩展和原生主机 安装程序：

npx -y opencode-chromium-mcp

1. 安装包

npm install -g opencode-chromium

2. 加载浏览器扩展

从 Chrome 网上应用店安装 opencode-chromium。 以下未打包流程仍可用于开发和本地测试。

打开 chrome://extensions，启用开发者模式，然后从已安装的包中加载未打包的 extension/ 文件夹：

npm root -g
# load "<that path>\opencode-chromium\extension" as an unpacked extension

扩展 ID 由加载路径派生，因此请将文件夹保留在原处。 记下 chrome://extensions 中显示的 ID。

3. 安装原生消息传递主机

node "$(npm root -g)/opencode-chromium/scripts/install-native-host.js" --extension-id <extension-id> --browsers chrome

4. 连接客户端

OpenCode V2 — 将包名添加到全局 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

Codex — 注册所需的 MCP 服务器：

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp

任何 MCP 客户端 — 添加 stdio 服务器：

{
  "mcpServers": {
    "opencode-browser-plugin": {
      "command": "npx",
      "args": ["-y", "opencode-chromium-mcp"]
    }
  }
}

直接 JavaScript — 以编程方式导入 SDK 运行时或 MCP 服务器 （参见 docs/direct-sdk.md）。

5. 验证

opencode-chromium doctor --json
opencode-chromium verify

所有四个工具（browser_run、browser_observe、browser_session、 browser_finalize）随后在每个连接的客户端中可用。除非有意使用重复工具， 否则不要在一个客户端会话中同时启用原生 OpenCode 适配器和 MCP 服务器。

要求

• 使用 npm 包和 SDK 需要 Node.js 20 或更高版本。

• 从源码构建或运行仓库脚本时需要 Bun 1.1 或更高版本。

• 加载了未打包的 extension/ 的 Chromium 系列浏览器。

• 为扩展 ID 安装原生消息传递主机。

安装与构建

bun install --frozen-lockfile
bun run build
bun test
bun run check

该包以 npm 名称 opencode-chromium 发布为 1.6.1。稳定的运行时和 MCP 服务器标识仍为 opencode-browser-plugin，以保持客户端兼容性。

MCP

通过 stdio 运行四工具服务器：

bun run mcp

或使用打包的二进制文件：

opencode-chromium-mcp

回环 Streamable HTTP 可通过以下方式使用：

bun run mcp:http

非回环 HTTP 需要在 AGENT_BROWSER_AUTH_TOKEN 中提供不记名令牌（或使用 --auth-token-env 选择的变量）。默认服务器名称为 opencode-browser-plugin。来源和文件根安全配置是服务器级的：传递 --allowed-origin / --blocked-origin 通配符，或设置 AGENT_BROWSER_ALLOWED_ORIGINS、AGENT_BROWSER_BLOCKED_ORIGINS 和 AGENT_BROWSER_ALLOWED_FILE_ROOTS（参见 docs/mcp.md）。

OpenCode V2

包根目录使用 OpenCode 1.18.x 的官方 { id, server() } 路径插件模块形状导出原生适配器，以及 V2 设置契约：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

对于本地构建，将客户端指向 dist/adapters/opencode/index.js，或 使用 opencode-chromium install --client opencode 命令。该适配器 恰好注册四个工具，设置 codemode: false，并返回用于重载的清理 函数。

相同的浏览器运行时可通过 MCP 兼容模式使用；除非有意使用重复工具，否则不要在一个客户端会话中同时启用两个界面。

Codex

从 npm 包注册 MCP 服务器：

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp
codex mcp list

从本地检出，使用 Bun 注册 dist/adapters/mcp/server.js：

codex mcp add opencode-browser-plugin -- bun C:\absolute\path\to\dist\adapters\mcp\server.js

捆绑的技能是 skills/opencode-browser-plugin/SKILL.md。它遵循开放的 Agent Skills 标准，涵盖连接器优先路由、配置文件选择、操作批处理、Snowflake 默认搜索、批准令牌、工件和最终化。它附带 agents/openai.yaml，用于 ChatGPT/Codex 桌面 Skills 选择器和 MCP 依赖元数据。

一次为所有支持技能的客户端安装：

opencode-chromium install --client skills
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client skills

这会将技能复制到 ~/.codex/skills/、~/.claude/skills/ 和 ~/.agents/skills/（位于 opencode-browser-plugin/ 下），并在 ~/.codex/config.toml 中注册一个启用的 [[skills.config]] 条目，同时移除任何过期的 opencode-browser-adapter 条目。

原生主机和扩展

将 extension/ 作为未打包扩展加载，然后安装主机：

bun run install:native-host -- --extension-id <extension-id> --browsers chrome
bun run check:native-host -- --json

使用 AGENT_BROWSER_* 环境变量进行新配置。较旧的 OPENCODE_BROWSER_* 名称在 1.x 兼容窗口期内仍作为较低优先级的别名。

CLI

opencode-chromium doctor --json
opencode-chromium verify
opencode-chromium install --client opencode --dry-run
opencode-chromium install --client opencode-mcp --dry-run
opencode-chromium install --client codex --dry-run
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client codex --dry-run
opencode-chromium uninstall --client skills --dry-run

安装和卸载在更改前备份命名配置，仅触及规范条目，支持试运行，并报告更改的文件。

上下文和能力

默认工具模式保持精简。通过以下方式请求高级描述：

{"mode":"capabilities","pack":"downloads"}

通过 browser_run 执行高级工作，无需添加顶层工具：

{
  "steps": [{
    "action": "capability",
    "capability": "downloads.events",
    "input": {}
  }]
}

对于深入的请求/响应调试，仅在需要时请求惰性网络包：

{"mode":"capabilities","pack":"network"}

然后在 browser_run 中使用目标 tabId 执行 network.inspect。它遵循标签页的 CDP 请求/响应生命周期，支持 URL/方法/类型/状态/requestId 过滤器，并且仅在请求 includeHeaders 时返回脱敏的请求头。除非显式请求并批准，否则正文保持禁用；bodyDelivery: "artifact" 将选择加入的正文溢出到工件存储，而不是内联预览。browser_observe 的 inspect 模式配合 target.requestId 返回单个请求的生命周期详情。

大型结果和截图以工件优先。MCP 客户端通过 browser://sessions/<session-id>/artifacts/<artifact-id> 检索它们；OpenCode 可以使用 browser_observe 的 artifact 模式请求相同的 URI。

仓库布局

src/core/                 shared runtime, schemas, safety, artifacts, versions
src/browser/              profile-aware IPC client, policies, and operation engine
src/adapters/mcp/         universal MCP server and transports
src/adapters/opencode/    native OpenCode V2 adapter
src/adapters/sdk/         provider schema adapters and direct agent API
src/cli/                  install, configure, uninstall, doctor, verify
extension/                Manifest V3 browser integration
native-host/              native messaging host and semantic workers
skills/                   provider-neutral browser skill
tests/                    unit, contract, browser, and adapter regression tests
docs/                     architecture, compatibility, security, and migration guides

验证与发布

bun run build
bun run check:schemas
bun run check:package
bun run check:mcp
bun run test:contracts
bun run test:opencode
bun run pack
bun run test:tarball
bun run check:release

发布检查拒绝过期的 V1 路径、个人状态、重复的旧包界面、超出预算的模式增长，以及缺少构建适配器的 tarball。

GitHub Actions 在拉取请求和 master 推送上运行相同的验证。发布仅从匹配的 v* 标签通过受保护的 npm-production 环境使用 npm Trusted Publishing 发布；仓库或工作流中不存储 npm 令牌。

安全

浏览器内容是不可信的。重大操作需要短期不可变的批准令牌；在不确定执行后从不自动重复写入。工件是会话范围的、会过期、拒绝路径遍历，并且不会写入日志。MCP 协议数据保持在 stdout 上，诊断信息保持在 stderr 上。

参见 docs/architecture.md、docs/security.md、docs/compatibility.md 和 docs/migration-1.0.md。

许可证

MIT