Wang Kai Multi-Agent Browser Matrix Architecture (v1.1 Practical Guide)

One-sentence definition:Matrix architecture = "one computer × N independent identities × 1 browser + 1 cdp-proxy process + M agents per identity". Identities are isolated across four dimensions: browser/account/IP/fingerprint; multiple agents under the same identity do not interfere with each other via chrome-mcp-proxy's sessionId routing.

Key corrections from v1.0 to v1.1:

• Port allocation changed from "platform-based dimension" to "identity-based dimension"
• Shared browser model replaces "one browser per agent"
• All global configuration paths use the actually tested paths for Claude Code v2.1.x
• Added hub coordination layer, fingerprint tools, residential proxies, and CDP security
• Tool calls must go through mcp__chrome__* mandatory constraint

Applicable to: Claude Code v2.1.126+ (v2 tool discovery mechanism). Verified environment: macOS + Chrome 147 + chrome-mcp-proxy v1.0 (William Wang).

1. Core Definitions

身份 (Identity)  = 一个浏览器 app + 一套登录态 + 一个住宅 IP + 一个 cdp-proxy 进程
   ↓
工种 (Role)      = 一个 Claude Code agent(独立工作目录),跟同身份其他 agent 共享同一个浏览器实例

Here, "agent" = one independent Claude Code terminal window/session, not a sub-agent / Task tool inside Claude Code; it literally means "open a new terminal and run the claude command once".

2. Architecture Overview

graph TB
    A[一台电脑] --> B[全局共享层 ~/.claude/]
    A --> C[身份 A: Chrome + US-East 住宅 IP]
    A --> D[身份 B: Arc + US-West 住宅 IP]
    A --> E[身份 C: Brave + UK 住宅 IP]
    A --> F[hub 协调层 ~/agents/_hub/]
    
    B --> B1[~/.claude.json mcpServers]
    B --> B2[~/.claude/CLAUDE.md 全局偏好]
    B --> B3[~/.claude/skills/ 全局 skill]
    
    C --> C1[cdp-proxy 9401 → Chrome 9222]
    C1 --> C2[agent A1 publisher]
    C1 --> C3[agent A2 engager]
    C1 --> C4[agent A3 researcher]
    
    F --> F1[不接浏览器,只读 logs + memory<br/>做调度]

3. Port Pair Allocation (v1.1 identity-based)

Identity	Browser app	Proxy port	Chrome debugging port	User data directory	Residential proxy exit
identity-A	Chrome	9401	9222	~/agents/identity-A/browser-data/	US-East
identity-B	Arc	9402	9223	~/agents/identity-B/browser-data/	US-West
identity-C	Brave	9403	9224	~/agents/identity-C/browser-data/	UK
identity-D	Edge	9404	9225	~/agents/identity-D/browser-data/	DE
identity-E	Vivaldi	9405	9226	~/agents/identity-E/browser-data/	JP
...	...	+1	+1	...	...
identity-J	(Optional)	9410	9231	...	...

Reserve 9450+/9270+ for experimental/temporary use.

Multiple agents under the same identity: all agents' .mcp.json point to the same proxy port(e.g., all agents under identity-A point to 9401). chrome-mcp-proxy ensures the events they see do not interfere with each other through sessionId routing.

4. Three-Layer Configuration Hierarchy (tested on v2.1.x)

Layer	MCP configuration	Skill path	CLAUDE.md path	Loading method
Enterprise	(managed)	(managed)	/Library/Application Support/ClaudeCode/CLAUDE.md	Highest priority
User (global)	~/.claude.json's mcpServers	~/.claude/skills/<name>/SKILL.md	~/.claude/CLAUDE.md	Automatically inherited by all agents
Project	./.mcp.json	./.claude/skills/<name>/SKILL.md	./CLAUDE.md	Only takes effect under that working directory
Local	./.claude/settings.local.json	—	./CLAUDE.local.md	Not committed to git, appended last

Key rules

• MCP write command:claude mcp add <name> -s user|project|local <command> [args...],Do not hand-edit JSON
• Skill priority:Enterprise > Personal > Project > Plugin
• CLAUDE.md is concatenated, not overwritten — all content written in the global CLAUDE.md will appear in every agent,so it must be kept extremely minimal

4 questions to decide which layer to put things in

1. 这个能力绑定特定资源吗?(如某个浏览器端口)  → Project
2. 不同身份/agent 凭证不一样吗?(如各自 API key)→ Project
3. 不同身份/agent 行为不一样吗?(如不同语气)   → Project
4. 纯逻辑、所有 agent 都用同一份?               → User(全局共享)

Example layering for MCP / Skill / CLAUDE.md

Asset	Layer	Reason
chrome MCP (port 9401/9222)	Project	Different identities point to different proxy port pairs
filesystem MCP	User	Pure local tools
fetch MCP	User	Pure network tools
notion MCP (for hub agent)	User (enabled in the hub project)	Single workspace
Skill:markdown-writer	User	General writing
Skill:youtube-publish	Project (identity-level)	Rules specific to that identity's YT account
Skill:identity-A-tone	Project	That identity's tone
Global CLAUDE.md	User,Only write cross-agent preferences	Concatenated into every agent, must be extremely minimal
Project CLAUDE.md	Project	Agent persona, bound browser, ironclad rules

5. Single Identity Directory Structure

~/agents/identity-A/
├── _identity/                   ← 身份级共享资产
│   ├── start-browser.sh         ← 启动浏览器 + cdp-proxy
│   ├── stop-browser.sh
│   ├── browser-data/            ← user-data-dir
│   ├── identity.env             ← 身份元数据
│   ├── .browser.pid
│   └── .proxy.pid
│
├── publisher/                   ← Agent A1:管发布
│   ├── .mcp.json                ← 指向 9401
│   ├── CLAUDE.md                ← 该 agent 人设
│   ├── .claude/
│   │   └── skills/
│   │       ├── publish-youtube/SKILL.md
│   │       ├── publish-tiktok/SKILL.md
│   │       └── publish-instagram/SKILL.md
│   ├── feedback.md
│   ├── memory/
│   └── logs/
│
├── engager/                     ← Agent A2:管评论互动
│   └── (结构同上,skill 不同)
│
└── researcher/                  ← Agent A3:监控同行
    └── (结构同上)

6. Key File Templates

6.1 start-browser.sh (key excerpts)

#!/bin/bash
set -e
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
mkdir -p "$DIR/browser-data" "$DIR/logs"

IDENTITY_NAME="identity-A"
PROXY_PORT=9401
CHROME_PORT=9222
BROWSER_EXEC="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
PROXY_HOST="residential.example.com"
PROXY_USER="your-user"
PROXY_PASS="your-pass"
PROXY_PORT_RESIDENTIAL=22225
PROXY_SCHEME="socks5"

CDP_PROXY_SCRIPT="$HOME/chrome-mcp-proxy/chrome-mcp-proxy.sh"

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY

# 启动浏览器
"$BROWSER_EXEC" \
  --remote-debugging-port=$CHROME_PORT \
  --remote-debugging-address=127.0.0.1 \
  --user-data-dir="$DIR/browser-data" \
  --proxy-server="${PROXY_SCHEME}://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT_RESIDENTIAL}" \
  --no-first-run --no-default-browser-check --window-size=1280,800 \
  > "$DIR/logs/browser.log" 2>&1 &

# 启动 cdp-proxy
nohup bash "$CDP_PROXY_SCRIPT" $PROXY_PORT $CHROME_PORT > "$DIR/logs/proxy.log" 2>&1 &

For the complete version, see sources/learning/wangkai/方案探讨/multi-agent-browser-matrix-v1.1.md, §5.1.

6.2 identity.env (identity metadata)

IDENTITY_NAME="identity-A"
BROWSER="Chrome"
PROXY_PORT=9401
CHROME_PORT=9222
RESIDENTIAL_PROXY_REGION="US-East"

ACCOUNTS_YOUTUBE="creator-yt-A@example.com"
ACCOUNTS_TIKTOK="@creatorA_us"
# ... 15 平台清单

STATUS_YOUTUBE="active"
STATUS_TIKTOK="active"
# 风控状态记录

6.3.mcp.json (per agent)

{
  "mcpServers": {
    "chrome": {
      "command": "bash",
      "args": [
        "/Users/lilimeng/chrome-mcp-proxy/chrome-mcp-proxy.sh",
        "9401",
        "9222"
      ]
    }
  }
}

Or use the command line (recommended):

cd ~/agents/identity-A/publisher
claude mcp add chrome -s project bash $HOME/chrome-mcp-proxy/chrome-mcp-proxy.sh 9401 9222

6.4 Project CLAUDE.md template (key ironclad rules)

# Agent 人设:identity-A / publisher

## 身份
我是身份 A 的 publisher agent,负责该身份在 15 个平台的内容发布。
身份 A 的浏览器是 Chrome(住宅代理 US-East),由 cdp-proxy 9401 → 9222 控制。

## 工具铁律
- 只能用 mcp__chrome__* 工具操作浏览器
- 禁止用 Bash 写脚本绕路调 CDP(端口 9222 / 9401)
- 禁止操作其他端口(9402/9403/...)或其他浏览器 app
- 禁止登录与 identity-A 无关的账号

## 合规铁律(违反一次账号就废)
- TikTok / IG Reels:禁止任何 NSFW 暗示
- 不发硬广,不发政治/宗教
- 不让 Claude 替我润色发挥(让 Claude 翻译,不发挥)
- 发布前自审一次

## 出错处理
- 浏览器加载失败 → 重试 1 次 → 仍失败写 logs/error-YYYYMMDD.log
- 检测到限流/风控提示 → 立即停止 + 更新 STATUS_<平台>="throttled"
- chrome MCP 工具找不到 → 不要绕路,停下来报错,让人类来 fix

6.5 Global ~/.claude/CLAUDE.md (must be extremely minimal)

# 全局偏好(影响所有项目,请极简)
- 语言:中文优先,技术名词用英文原文
- 代码风格:函数命名 snake_case,注释解释为什么不解释做什么
- token 风格:宁可多问一次,不要假设
- 不主动 commit / push git,等明确指令

Prohibited to write in global CLAUDE.md: anything other than project names, product names, platform accounts, keys, and personal preferences.

7. Hub Coordination Layer

A hub is mandatory once the matrix scale reaches ≥ 3 identities.The hub agent does not connect to a browser; it only reads each identity's logs / memory / identity.env to perform scheduling and monitoring.

~/agents/_hub/
├── CLAUDE.md           ← "你是 hub,不操作浏览器,只调度"
├── .mcp.json           ← 只装 filesystem 和 fetch(无 chrome)
├── inbox/              ← 人类下发任务的目录
├── outbox/             ← hub 给各 identity 下发任务
├── dashboard/          ← hub 生成的状态报告
├── memory/
└── feedback.md

Hub workflow

1. After startup, first scan all identity.env and aggregate the current matrix status
2. Read task files placed by humans in ./inbox/ task file
3. Decompose tasks → decide which agents of which identities to dispatch to
4. Write task files to the corresponding agent's ./inbox/
5. Generate a dashboard report every day at 9:00 / 18:00

Alert rules

• Any STATUS_* shows throttled / banned → highlight
• Any agent has no new feedback.md entry for 24h → warning (indicates it is stuck)
• Any logs/error-*.log has a new entry in the past 1h → warning

8. Browser Fingerprint Tools

Selection (by budget)

Tool	Price	When to use
GoLogin	Free for 3 profiles / paid from $24/mo	Getting started, matrix ≤ 3 identities
AdsPower	Free for 5 profiles / paid from $5.4/mo	Widely used by Chinese teams going overseas
Multilogin	From $99/mo	During TikTok / X crackdown periods, matrix ≥ 5 identities
BitBrowser	(Price not provided)	Alternative option

Why they are needed: The fingerprints of 5 different Chromium browsers (Chrome / Arc / Brave / Edge / Vivaldi)only differ on the surface; deep fingerprints (Canvas / WebGL / fonts / AudioContext) are extremely similar, and TikTok / X / Instagram risk control can identify them.

Integration method

Fingerprint tools replace the part in start-browser.sh that directly launches Chrome:

# GoLogin 示例
PROFILE_ID="65a1b2c3d4e5f6789"
GOLOGIN_TOKEN="$(cat ~/.gologin-token)"

RESPONSE=$(curl -s -X POST "http://localhost:36912/browser/${PROFILE_ID}/start" \
  -H "Authorization: Bearer ${GOLOGIN_TOKEN}")
CHROME_PORT=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['port'])")

Create one profile per identity in the fingerprint tool, configured with:

• Different user-agent / OS combinations
• Different time zones (matching the geographic location of the residential proxy)
• Different Canvas / WebGL / Audio noise
• Independent cookie / localStorage storage
• Bound residential proxy

9. Residential Proxies

Provider	Price	Notes
Bright Data	$8.4/GB	Established brand, largest IP pool
Soax	$7/GB	Decent cost-performance
IPRoyal	$7/GB	Low starting price
Smartproxy	$7/GB	Beginner-friendly

Datacenter proxies are absolutely forbidden — X / TikTok / Reddit ban accounts registered on datacenter IPs immediately.

Proxy endpoint format

http://user-xxx:pass-xxx@gate.smartproxy.com:7000
socks5://user-xxx:pass-xxx@residential.brightdata.com:22225

Geographic consistency (the easiest point for risk control to catch)

The geographic location of the proxy IP must match that identity's "persona":

• identity-A = US East Coast user
• → US-East residential IP
• → Time zone America/New_York (set in the fingerprint tool)
• → All platform accounts post using EST time

Geographic inconsistency is the easiest point for risk control to catch.

Verification

After launching the browser, verify the exit IP using chrome MCP:

mcp__chrome__navigate_page("https://api.ipify.org")
mcp__chrome__take_screenshot()

10. CDP Security (must read)

Exposing a CDP port (9222 / 9223 /...) means all cookies / tab content / JS execution rights of that browser are completely public.

Listening on 127.0.0.1 by default is safe, but:

# start-browser.sh 必须写:
--remote-debugging-address=127.0.0.1

Prohibited

• ❌ Changing to 0.0.0.0 to connect from another machine
• ❌ Doing port mapping for -p 9222:9222 when using Docker
• ❌ Writing port 9222/9401 into any externally-facing script/screenshot/configuration

Additional recommendations

• Matrix browsers are forbidden from logging into your important personal accounts(personal Gmail / work email / bank)
• Do not install npm packages of unknown origin (there are attack cases that scan local CDP ports stealthily)

11. Complete Workflow

11.1 First-time setup (one-time)

# 1. 全局共享层
mkdir -p ~/.claude/skills
claude mcp add filesystem -s user npx -y @modelcontextprotocol/server-filesystem $HOME
claude mcp add fetch -s user npx -y @modelcontextprotocol/server-fetch

cat > ~/.claude/CLAUDE.md << 'EOF'
# 全局偏好(影响所有项目,请极简)
- 语言:中文优先
- ...
EOF

# 2. 模板目录
mkdir -p ~/agents/_template/{_identity,publisher,engager,researcher}
chmod +x ~/agents/_template/_identity/*.sh

# 3. hub
mkdir -p ~/agents/_hub/{inbox,outbox,dashboard,memory}

11.2 Adding a new identity (5 minutes)

cp -r ~/agents/_template ~/agents/identity-A
# 改 _identity/start-browser.sh / identity.env 里的端口、代理、账号清单
$EDITOR ~/agents/identity-A/_identity/start-browser.sh
$EDITOR ~/agents/identity-A/_identity/identity.env

# 给每个 role agent 注册 chrome MCP
for role in publisher engager researcher; do
  cd ~/agents/identity-A/$role
  claude mcp add chrome -s project bash $HOME/chrome-mcp-proxy/chrome-mcp-proxy.sh 9401 9222
  $EDITOR CLAUDE.md   # 改人设、改身份名
done

# 启动浏览器(一次性,常驻)
cd ~/agents/identity-A/_identity && ./start-browser.sh

11.3 Daily agent startup

# iTerm2 开多 tab
cd ~/agents/identity-A/publisher && claude
cd ~/agents/identity-A/engager && claude
cd ~/agents/identity-A/researcher && claude
cd ~/agents/_hub && claude

The browser and cdp-proxy run persistently;only run start-browser.sh.

once after restarting the computer

# Chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
# Arc
"/Applications/Arc.app/Contents/MacOS/Arc"
# Brave
"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
# Edge
"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
# Vivaldi
"/Applications/Vivaldi.app/Contents/MacOS/Vivaldi"
# Opera
"/Applications/Opera.app/Contents/MacOS/Opera"

.mcp.json does not need to be changed — chrome-devtools-mcp takes over via the CDP protocol, and all Chromium-based browsers are supported.

12. Verification Checklist

# 1. 目录结构
tree ~/agents/identity-A -L 3

# 2. 浏览器和 proxy 启动
cd ~/agents/identity-A/_identity && ./start-browser.sh

# 3. CDP 端口可达
curl http://127.0.0.1:9222/json/version

# 4. proxy 状态
curl http://127.0.0.1:9401/proxy/status

# 5. 出口 IP 是住宅代理(在 publisher agent 里)
# "用 mcp__chrome__navigate_page 打开 https://api.ipify.org,然后截图"

# 6. MCP 工具直接可用(关键!)
# /mcp,展开 chrome,应该看到 29 tools

# 7. 多 agent 不串台
# 同时开 publisher / engager 两个 tab,检查 proxy/status 应 clients: 2

13. Common Pitfalls

13.1 Port conflicts

lsof -i :9222
# 占用了就换端口或 kill 进程

13.2 user-data-dir lock

"profile in use" → ps aux | grep -i chrome → kill residual processes / delete browser-data/SingletonLock

13.3 MCP loses connection after closing the browser window

• The proxy has a 5-second automatic reconnection
• If it still does not work:./stop-browser.sh && ./start-browser.sh

13.4 Chrome is already running

Fully quit your daily-use Chrome (Cmd+Q) before running start-browser.sh, or start all matrix Chrome instances from 9223+ to avoid 9222

13.5 Slow npx startup

npm install -g chrome-devtools-mcp

13.6 Chrome MCP tools not called by the agent (v1.1 key point)

Symptom: after the agent sees the task,it detours to write Node.js/Python scripts to call raw CDP

Cause: Claude Code v2.x's tool discovery mechanism does not eager-load MCPs registered only at the user level

Forced registration method(also register a copy of chrome in each agent project directory):

cd ~/agents/identity-A/publisher
claude mcp add chrome -s project bash $HOME/chrome-mcp-proxy/chrome-mcp-proxy.sh 9401 9222

If it still detours → send /mcp as the first message after startup, and assign tasks only after confirming chrome is listed

13.7 Global CLAUDE.md pollution

Symptom: the agent suddenly replies about project B while in project A → check ~/.claude/CLAUDE.md, and cut it down to only preferences

13.8 Skill name conflicts

When a global and project-level skill share the same name, the project-level one overrides. Avoid duplicate names in naming (global markdown-writer, project-level markdown-writer-tiktok)

13.9 Multiple identities stealing focus

chrome-mcp-proxy already prevents focus stealing when agents make calls. But browsers will pop up on first launch → --window-position=$((PROXY_PORT - 9400))00,100 stagger the windows; or use the fingerprint tool's headless mode

14. Setup Order for New Handover Recipients

1. Read sections 1-2 to understand the architecture
2. Verify Claude Code version:claude --version must be ≥ v2.1.126
3. Verify chrome-mcp-proxy is installed:ls ~/chrome-mcp-proxy/chrome-mcp-proxy.sh
4. Build the global layer (11.1)
5. Build the hub (copy the template)
6. Build the first identity (11.2)
7. Successfully run the MCP tool call verification in 13.6 — the biggest correction point in v1.1, must confirm it passes
8. Add fingerprint tools + residential proxies (sections 8 / 9)
9. Copy and scale: for each additional identity, repeat steps 6-8

15. Index of Wang Kai's Original Posts

Post	Date	Core point
#1278	2026-03-11	HN Agent auto-registration closed loop
#1296-1300	2026-03	Control the browser to use the browser on your behalf
#1297	2026-03	iTerm2 always keeps 10 tabs open
#1319	2026-04-06	"Killer Chrome MCP" transformation (focus-stealing fix)
#1326	2026-04-08	"Different agent windows on each computer control different browsers" — core of the architecture
#1327	2026-04-09	Split one project into multiple windows → departments → positions → functions
#1330	2026-04-13	"Open multiple terminal windows to run Claude Code, multiple browsers on one computer"
#1331	2026-04-14	Ultimate roadmap of 10 computers × 5 browsers × 15 platforms
#1336	2026-04-21	Division of labor: 5 operation windows + 5 video production windows
#1339	2026-04-28	Write knowledge as code and put it into skills

16. Wang Kai Says

"Identity isolation relies on the four-piece set (browser app + residential IP + fingerprint + account); multi-agent collaboration under the same identity relies on chrome-mcp-proxy's sessionId routing."

"In Claude Code, an agent is its working directory: the directory is the agent's body, CLAUDE.md is its persona,.mcp.json is its tools, and feedback.md is its growth record."

"Any scheme that tries to skip account nurturing and post links in bulk will be instantly killed by anti-cheat systems."

---

References

• Wang Kai's Claude Code Terminal Workflow Methodology (Complete Edition) - Complete Claude Code workflow (the methodological foundation of this wiki)
• Wang Kai's 6-Platform Overseas Operations SOP - 6-platform SOP (the application layer of this wiki)
• Wang Kai's Agent Engineering Practice - Main Agent Engineering wiki (overview)
• Wang Kai's Overseas Promotion SOP and Multi-Account Matrix Combat Practice - Overseas promotion (the target scenario for matrixed operations)