jackwener · Mr0bean · May 5, 2026 · May 5, 2026 · May 5, 2026 · May 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Breaking Changes
+
+* **daemon** — removed `OPENCLI_DAEMON_PORT`; use `opencli config set daemon.port <port>` and set the same port in the Browser Bridge extension popup.
+* **browser** — removed `OPENCLI_BROWSER_CONNECT_TIMEOUT` / `OPENCLI_BROWSER_COMMAND_TIMEOUT` / `OPENCLI_CDP_ENDPOINT`; use `opencli config set browser.connect_timeout|command_timeout|cdp_endpoint <value>`.
+* **flags** — renamed `OPENCLI_LIVE` to `OPENCLI_WINDOW_LIVE` for parity with `OPENCLI_WINDOW_FOCUSED`. The `--live` flag is unchanged.
+
 ### Features
 
 * **observation** — add trace artifact primitives, `browser console`, `browser network --since/--follow/--failed`, and adapter `--trace=retain-on-failure` for failure-retained browser evidence.

diff --git a/README.md b/README.md
@@ -196,17 +196,30 @@ OpenCLI is not only for websites. It can also:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `OPENCLI_DAEMON_PORT` | `19825` | HTTP port for the daemon-extension bridge |
 | `OPENCLI_PROFILE` | — | Browser Bridge profile alias/contextId to use when multiple Chrome profiles are connected |
 | `OPENCLI_WINDOW_FOCUSED` | `false` | Set to `1` to open the automation container in the foreground (useful for debugging). The `--focus` flag sets this. |
-| `OPENCLI_LIVE` | `false` | Set to `1` to keep the automation lease open after an adapter command finishes (useful for inspection). The `--live` flag sets this. |
-| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | Seconds to wait for browser connection |
-| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | Seconds to wait for a single browser command |
-| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol endpoint for remote browser or Electron apps |
+| `OPENCLI_WINDOW_LIVE` | `false` | Set to `1` to keep the automation lease open after an adapter command finishes (useful for inspection). The `--live` flag sets this. |
 | `OPENCLI_CDP_TARGET` | — | Filter CDP targets by URL substring (e.g. `detail.1688.com`) |
 | `OPENCLI_VERBOSE` | `false` | Enable verbose logging (`-v` flag also works) |
 | `DEBUG_SNAPSHOT` | — | Set to `1` for DOM snapshot debug output |
 
+Persistent OpenCLI config is stored in `~/.opencli/config.yaml`.
+
+```bash
+opencli config set browser.connect_timeout 45
+opencli config set browser.command_timeout 90
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
+```
+
+To change the Browser Bridge daemon port:
+
+```bash
+opencli config set daemon.port 23456
+opencli daemon restart
+```
+
+Set the same port in the Browser Bridge extension popup.
+
 `--focus` works for both `opencli browser *` and browser-backed adapter commands. `--live` is mainly for adapter commands: browser subcommands already keep the automation lease open until you run `opencli browser close` or the idle timeout expires.
 
 ## Update

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -180,16 +180,29 @@ OpenCLI 不只是网站 CLI，还可以：
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
-| `OPENCLI_DAEMON_PORT` | `19825` | daemon-extension 通信端口 |
 | `OPENCLI_WINDOW_FOCUSED` | `false` | 设为 `1` 时 automation 窗口在前台打开（适合调试）。`--focus` 标志会设置此变量 |
-| `OPENCLI_LIVE` | `false` | 设为 `1` 时 adapter 命令执行完后保留 automation 窗口不关闭（适合检查页面）。`--live` 标志会设置此变量 |
-| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | 浏览器连接超时（秒） |
-| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | 单个浏览器命令超时（秒） |
-| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol 端点，用于远程浏览器或 Electron 应用 |
+| `OPENCLI_WINDOW_LIVE` | `false` | 设为 `1` 时 adapter 命令执行完后保留 automation 窗口不关闭（适合检查页面）。`--live` 标志会设置此变量 |
 | `OPENCLI_CDP_TARGET` | — | 按 URL 子串过滤 CDP target（如 `detail.1688.com`） |
 | `OPENCLI_VERBOSE` | `false` | 启用详细日志（`-v` 也可以） |
 | `DEBUG_SNAPSHOT` | — | 设为 `1` 输出 DOM 快照调试信息 |
 
+持久化 OpenCLI 配置位于 `~/.opencli/config.yaml`。
+
+```bash
+opencli config set browser.connect_timeout 45
+opencli config set browser.command_timeout 90
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
+```
+
+修改 Browser Bridge daemon 端口：
+
+```bash
+opencli config set daemon.port 23456
+opencli daemon restart
+```
+
+同时在 Browser Bridge 扩展 popup 里设置相同端口。
+
 `--focus` 同时适用于 `opencli browser *` 和浏览器型 adapter 命令。`--live` 主要是给 adapter 命令用的：`browser` 子命令本来就会一直保留 automation window，直到你手动执行 `opencli browser close` 或等空闲超时。
 
 ## 更新

diff --git a/docs/adapters/desktop/antigravity.md b/docs/adapters/desktop/antigravity.md
@@ -19,7 +19,7 @@ Start the Antigravity desktop app with the Chrome DevTools `remote-debugging-por
 Then set the target port:
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9224
 ```
 
 ## Commands

diff --git a/docs/adapters/desktop/chatgpt-app.md b/docs/adapters/desktop/chatgpt-app.md
@@ -32,10 +32,10 @@ ChatGPT Desktop is also an Electron app and can be launched with a remote debugg
 ```
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9224
 ```
 
-> The CDP approach is primarily for advanced automation and future desktop-only commands. The built-in command set above still works in the default AppleScript path unless you explicitly route through `OPENCLI_CDP_ENDPOINT`.
+> The CDP approach is primarily for advanced automation and future desktop-only commands. The built-in command set above still works in the default AppleScript path unless you explicitly route through `browser.cdp_endpoint`.
 
 ## How It Works
 

diff --git a/docs/adapters/desktop/chatwise.md b/docs/adapters/desktop/chatwise.md
@@ -14,7 +14,7 @@ Control the **ChatWise Desktop App** from the terminal via Chrome DevTools Proto
 ## Setup
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9228"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9228
 ```
 
 ## Commands

diff --git a/docs/adapters/desktop/codex.md b/docs/adapters/desktop/codex.md
@@ -14,7 +14,7 @@ Control the **OpenAI Codex Desktop App** headless or headfully via Chrome DevToo
 ## Setup
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
 ```
 
 ## Commands

diff --git a/docs/adapters/desktop/cursor.md b/docs/adapters/desktop/cursor.md
@@ -13,7 +13,7 @@ Control the **Cursor IDE** from the terminal via Chrome DevTools Protocol (CDP).
 ## Setup
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9226"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9226
 ```
 
 ## Commands

diff --git a/docs/adapters/desktop/discord.md b/docs/adapters/desktop/discord.md
@@ -12,7 +12,7 @@ Launch with remote debugging port:
 ## Setup
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9232"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9232
 ```
 
 ## Commands

diff --git a/docs/adapters/desktop/doubao-app.md b/docs/adapters/desktop/doubao-app.md
@@ -10,7 +10,7 @@ Control the **Doubao AI Desktop App** via Chrome DevTools Protocol (CDP).
    ```
 2. Set the CDP endpoint:
    ```bash
-   export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9225"
+   opencli config set browser.cdp_endpoint http://127.0.0.1:9225
    ```
 
 ## Commands

diff --git a/docs/adapters/desktop/notion.md b/docs/adapters/desktop/notion.md
@@ -12,7 +12,7 @@ Launch with remote debugging port:
 ## Setup
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9230"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9230
 ```
 
 ## Commands

diff --git a/docs/advanced/android-chrome.md b/docs/advanced/android-chrome.md
@@ -80,7 +80,7 @@ A successful response lists the open tabs:
 ### 4. Run any OpenCLI command
 
 ```bash
-export OPENCLI_CDP_ENDPOINT=http://localhost:9222
+opencli config set browser.cdp_endpoint http://localhost:9222
 opencli hackernews top --limit 5
 ```
 
@@ -97,7 +97,8 @@ OPENCLI_CDP_TARGET="twitter" opencli twitter trending
 You can also connect directly to a specific tab's WebSocket URL (from `/json`):
 
 ```bash
-OPENCLI_CDP_ENDPOINT=ws://localhost:9222/devtools/page/3941 opencli ...
+opencli config set browser.cdp_endpoint ws://localhost:9222/devtools/page/3941
+opencli ...
 ```
 
 ---
@@ -154,8 +155,10 @@ adb -s <device1-serial> forward tcp:9222 localabstract:chrome_devtools_remote
 adb -s <device2-serial> forward tcp:9223 localabstract:chrome_devtools_remote
 
 # Run commands targeting each device
-OPENCLI_CDP_ENDPOINT=http://localhost:9222 opencli twitter trending
-OPENCLI_CDP_ENDPOINT=http://localhost:9223 opencli twitter trending
+opencli config set browser.cdp_endpoint http://localhost:9222
+opencli twitter trending
+opencli config set browser.cdp_endpoint http://localhost:9223
+opencli twitter trending
 ```
 
 ---

diff --git a/docs/advanced/cdp.md b/docs/advanced/cdp.md
@@ -79,12 +79,12 @@ This will print a forwarding URL, such as `https://abcdef.ngrok.app`. **Copy thi
 
 Now switch to your **Remote Server** where OpenCLI is installed. 
 
-Depending on the network tunnel method you chose in Phase 2, set the `OPENCLI_CDP_ENDPOINT` environment variable and run your commands.
+Depending on the network tunnel method you chose in Phase 2, set `browser.cdp_endpoint` in OpenCLI config and run your commands.
 
 ### If you used Method A (SSH Tunnel):
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
+opencli config set browser.cdp_endpoint http://localhost:9222
 opencli doctor                    # Verify connection
 opencli bilibili hot --limit 5    # Test a command
 ```
@@ -93,11 +93,11 @@ opencli bilibili hot --limit 5    # Test a command
 
 ```bash
 # Use the URL you copied from ngrok earlier
-export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
+opencli config set browser.cdp_endpoint https://abcdef.ngrok.app
 opencli doctor                    # Verify connection
 opencli bilibili hot --limit 5    # Test a command
 ```
 
 > *Tip: If you provide a standard HTTP/HTTPS CDP endpoint, OpenCLI requests the `/json` target list and picks the most likely inspectable app/page target automatically. If multiple app targets exist, you can further narrow selection with `OPENCLI_CDP_TARGET` (for example `antigravity` or `codex`).*
 
-If you plan to use this setup frequently, you can persist the environment variable by adding the `export` line to your `~/.bashrc` or `~/.zshrc` on the server.
+If you need to change back to Browser Bridge mode, run `opencli config unset browser.cdp_endpoint`.
diff --git a/docs/advanced/electron.md b/docs/advanced/electron.md
@@ -82,7 +82,7 @@ await page.wait(1); // Wait for re-render
 
 ## Environment Variable
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
 ```
 
 ## Non-Electron Pattern (AppleScript)

diff --git a/docs/advanced/remote-chrome.md b/docs/advanced/remote-chrome.md
@@ -34,7 +34,7 @@ Use `127.0.0.1` instead of `localhost` in the SSH command to avoid IPv6 resoluti
 ### 3. Configure OpenCLI
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
 ```
 
 ### 4. Verify

diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md
@@ -106,7 +106,7 @@ This path is used for:
 
 ### Direct CDP mode
 
-Used when OpenCLI talks directly to a Chrome or Electron debugging endpoint through `OPENCLI_CDP_ENDPOINT`.
+Used when OpenCLI talks directly to a Chrome or Electron debugging endpoint through `browser.cdp_endpoint` config.
 
 Typical uses:
 

diff --git a/docs/guide/browser-bridge.md b/docs/guide/browser-bridge.md
@@ -25,6 +25,19 @@ That's it! The daemon auto-starts when you run any browser command. No tokens, n
 opencli doctor            # Check extension + daemon connectivity
 ```
 
+## Custom Daemon Port
+
+The default Browser Bridge port is `19825`.
+
+If another local service occupies that port, set a persistent OpenCLI daemon port:
+
+```bash
+opencli config set daemon.port 23456
+opencli daemon restart
+```
+
+Then open the OpenCLI extension popup, edit the **Port** field to the same value, and click **Save**. Click **Reset** to return the extension to `19825`.
+
 ## Tab Targeting
 
 Browser commands run inside the shared `browser:default` workspace unless you explicitly choose another tab target.

diff --git a/docs/guide/electron-app-cli.md b/docs/guide/electron-app-cli.md
@@ -41,7 +41,7 @@ If Electron is present, the next step is usually to launch the app with a debugg
 Then point OpenCLI at that CDP endpoint:
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
 ```
 
 ### 3. Start with the 5-command pattern

diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
@@ -48,7 +48,7 @@ opencli doctor
 For Electron/CDP-based adapters (Cursor, Codex, etc.):
 
 1. Make sure the app is launched with `--remote-debugging-port=XXXX`
-2. Verify the endpoint is set: `echo $OPENCLI_CDP_ENDPOINT`
+2. Verify the endpoint is set: `opencli config get browser.cdp_endpoint`
 3. Test the endpoint: `curl http://127.0.0.1:XXXX/json/version`
 
 ### Build errors

diff --git a/docs/superpowers/plans/2026-03-31-daemon-lifecycle-redesign.md b/docs/superpowers/plans/2026-03-31-daemon-lifecycle-redesign.md
@@ -171,9 +171,10 @@ In `src/daemon.ts`, replace the idle timeout section (lines 27, 29-57) with:
 
 Replace the `IDLE_TIMEOUT` constant (line 27):
 ```typescript
-import { DEFAULT_DAEMON_PORT, DEFAULT_DAEMON_IDLE_TIMEOUT } from './constants.js';
+import { DEFAULT_DAEMON_IDLE_TIMEOUT } from './constants.js';
+import { getConfiguredDaemonPort } from './config.js';
 
-const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+const PORT = getConfiguredDaemonPort();
 const IDLE_TIMEOUT = DEFAULT_DAEMON_IDLE_TIMEOUT;
 ```
 
@@ -423,10 +424,9 @@ Create `src/commands/daemon.ts`:
  */
 
 import chalk from 'chalk';
-import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { getConfiguredDaemonPort } from '../config.js';
 
-const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
+const DAEMON_URL = `http://127.0.0.1:${getConfiguredDaemonPort()}`;
 
 interface DaemonStatus {
   ok: boolean;
@@ -793,7 +793,7 @@ private async _ensureDaemon(timeoutSeconds?: number): Promise<void> {
   throw new Error(
     'Failed to start opencli daemon. Try running manually:\n' +
     `  node ${daemonPath}\n` +
-    `Make sure port ${DEFAULT_DAEMON_PORT} is available.`,
+    `Make sure the configured daemon port is available.`,
   );
 }
 ```

diff --git a/docs/superpowers/specs/2026-03-31-daemon-lifecycle-redesign.md b/docs/superpowers/specs/2026-03-31-daemon-lifecycle-redesign.md
@@ -184,7 +184,7 @@ and shows:
 ## Backward Compatibility
 
 - No breaking changes to CLI commands or Extension protocol
-- Existing `OPENCLI_DAEMON_PORT` environment variable continues to work
+- Daemon port configuration is handled by `opencli config set daemon.port <port>`
 - The only observable behavior change: daemon stays alive longer
 - New `daemon` subcommands are additive
 

diff --git a/docs/zh/advanced/android-chrome.md b/docs/zh/advanced/android-chrome.md
@@ -80,7 +80,7 @@ curl http://localhost:9222/json
 ### 第四步：执行 OpenCLI 命令
 
 ```bash
-export OPENCLI_CDP_ENDPOINT=http://localhost:9222
+opencli config set browser.cdp_endpoint http://localhost:9222
 opencli hackernews top --limit 5
 ```
 
@@ -97,7 +97,8 @@ OPENCLI_CDP_TARGET="twitter" opencli twitter trending
 也可直接使用 `/json` 返回的 WebSocket 地址精确连接某个标签页：
 
 ```bash
-OPENCLI_CDP_ENDPOINT=ws://localhost:9222/devtools/page/3941 opencli ...
+opencli config set browser.cdp_endpoint ws://localhost:9222/devtools/page/3941
+opencli ...
 ```
 
 ---
@@ -154,8 +155,10 @@ adb -s <设备1序列号> forward tcp:9222 localabstract:chrome_devtools_remote
 adb -s <设备2序列号> forward tcp:9223 localabstract:chrome_devtools_remote
 
 # 分别执行命令
-OPENCLI_CDP_ENDPOINT=http://localhost:9222 opencli twitter trending
-OPENCLI_CDP_ENDPOINT=http://localhost:9223 opencli twitter trending
+opencli config set browser.cdp_endpoint http://localhost:9222
+opencli twitter trending
+opencli config set browser.cdp_endpoint http://localhost:9223
+opencli twitter trending
 ```
 
 ---

diff --git a/docs/zh/guide/electron-app-cli.md b/docs/zh/guide/electron-app-cli.md
@@ -37,7 +37,7 @@ ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
 然后把 OpenCLI 指到这个端口：
 
 ```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+opencli config set browser.cdp_endpoint http://127.0.0.1:9222
 ```
 
 ### 3. 先做 5 个基础命令