longbridge · huacnlee · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/docs/en/skill/install/index.md b/docs/en/skill/install/index.md
@@ -16,55 +16,24 @@ Once installed, you can say things like this to your AI assistant and get real a
 
 ---
 
-## Step 1 — Install the Skill
+The quickest way to get started is with a terminal-based AI tool — Claude Code, Codex, opencode, or OpenClaw. Install the CLI, authenticate once, and the AI runs `longbridge` commands on your behalf.
 
-The Skill is a set of instruction files that tell your AI assistant what Longbridge can do. Three ways to install:
+If you'd rather not install local software, connect via MCP instead — just add a URL to your AI tool's config.
 
-**Via Claude Code plugin (recommended for Claude Code users):**
-
-In Claude Code, run these two commands:
-
-```text
-/plugin marketplace add longbridge/skills
-/plugin install longbridge@longbridge-skills
-```
-
-This installs all Longbridge skills through the Claude Code plugin system and keeps them up to date automatically.
-
-**Via npx / bunx (global install):**
-
-```bash
-# Node.js
-npx skills add longbridge/skills -g
-# Bun
-bunx skills add longbridge/skills -g
-```
-
-> Requires [Node.js](https://nodejs.org) or [Bun](https://bun.sh).
-
-**Or download the ZIP and install manually:**
-
-Download [longbridge-all.zip](https://open.longbridge.com/skill/longbridge-all.zip) and unzip it, then place the files in your AI tool's Skill directory (Claude Code: `.claude/skills/`, Cursor: paste into the Rules editor, other tools: see the README).
-
-**OpenClaw** — send this message in chat and it handles everything automatically:
-
-```
-Install the Longbridge Developers Skill from this zip file:
-https://open.longbridge.com/skill/longbridge-all.zip
-```
+Either way, also install the Skill: a set of instruction files that tells your AI what Longbridge can do and how to use it.
 
 ---
 
-## Step 2 — Connect your Longbridge account
+## Step 1 — Connect to the Longbridge platform
 
-The Skill tells the AI what's possible. To actually fetch live data or execute trades, you need one of two capabilities:
+CLI and MCP are both ways to access the Longbridge Developers platform. Pick one:
 
-- **Shell execution** — the AI runs `longbridge` commands directly in a terminal
-- **MCP integration** — the AI connects to the Longbridge MCP server over the network
+- **CLI** — best experience; the AI runs `longbridge` commands directly in your terminal; requires installing software on your system
+- **MCP** — easier to connect; just add a URL to your AI tool's config; no local install needed
 
-### Method A — Install the CLI
+### Method A — CLI (recommended)
 
-For AI tools that can execute shell commands (Claude Code, Codex, Gemini CLI, Warp, etc.).
+Works with Claude Code, Codex (Work locally), opencode, OpenClaw, Gemini CLI, Warp, and any tool that can run shell commands.
 
 **Install the CLI:**
 
@@ -88,7 +57,7 @@ scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbri
 iwr https://open.longbridge.com/longbridge/longbridge-terminal/install.ps1 | iex
 ```
 
-**Connect your Longbridge account:**
+**Authenticate:**
 
 ```bash
 longbridge auth login
@@ -98,16 +67,18 @@ That's it. The AI can now call `longbridge` commands on your behalf.
 
 > See the [CLI reference](/docs/cli) for the full command list and installation details.
 
-### Method B — Connect the MCP server
+### Method B — MCP
 
-For AI tools that support MCP (Claude Desktop, Cursor, Zed, Gemini CLI, Warp, etc.).
+Works with Claude Desktop, Cursor, Zed, Gemini CLI, Warp, and any tool that supports MCP.
 
 Add the following as a remote MCP server in your AI tool:
 
 ```
 https://openapi.longbridge.com/mcp
 ```
 
+> Users in mainland China can use the accelerated endpoint: `https://openapi.longbridge.cn/mcp`
+
 Where to find the MCP configuration in each client:
 
 | Client         | Where to configure                                                                                                                        |
@@ -122,11 +93,68 @@ The first time you ask a Longbridge question, your client will open a browser ta
 
 ---
 
-## Why Claude.ai and ChatGPT.com don't work
+## Step 2 — Install the Skill
+
+The Skill is a set of instruction files that tell your AI assistant what Longbridge can do.
+
+**Via Claude Code plugin (recommended for Claude Code users):**
+
+In Claude Code, run these two commands:
+
+```text
+/plugin marketplace add longbridge/skills
+/plugin install longbridge@longbridge-skills
+```
+
+This installs all Longbridge skills through the Claude Code plugin system and keeps them up to date automatically.
+
+**Via npx / bunx (global install):**
+
+```bash
+# Node.js
+npx skills add longbridge/skills -g
+# Bun
+bunx skills add longbridge/skills -g
+```
+
+> Requires [Node.js](https://nodejs.org) or [Bun](https://bun.sh).
+
+**Or download the ZIP and install manually:**
+
+Download [longbridge-all.zip](https://open.longbridge.com/skill/longbridge-all.zip) and unzip it, then place the files in your AI tool's Skill directory (Claude Code: `.claude/skills/`, Cursor: paste into the Rules editor, other tools: see the README).
+
+**OpenClaw** — send this message in chat and it handles everything automatically:
+
+```
+Install the Longbridge Developers Skill from this zip file:
+https://open.longbridge.com/skill/longbridge-all.zip
+```
+
+---
+
+## Known restrictions by tool
+
+Some environments have network whitelists or sandboxing that block CLI installation and MCP server connections. If things aren't working, check here first.
+
+### Claude Desktop — use the Code tab
+
+**Chat and Cowork modes** in Claude Desktop have network restrictions that prevent CLI installation and MCP server connections. Do not try to install from either of these modes — it will not work no matter how many times you retry.
+
+Switch to the **Code** tab in Claude Desktop (this is Claude Code embedded in the app). From the Code tab, you have full terminal access — you can install the CLI, connect MCP, and install the Skill all in one session.
+
+<img src="https://assets.lbctrl.com/uploads/76a34f28-9000-4e3e-8250-e992c516ce80/claude.png" alt="Claude Desktop — switch to the Code tab" />
+
+### Codex — select "Work locally"
+
+Codex in **Cloud** mode has the same network whitelist restrictions. When starting a new session, select **Work locally** instead of Cloud. This gives the agent full access to your shell and network.
+
+<img src="https://assets.lbctrl.com/uploads/ccd412df-d312-45c3-a926-e3d466c9a479/codex.png" alt="Codex — select Work locally" />
+
+### Claude.ai and ChatGPT.com (web)
 
-**Claude.ai** (web) and **ChatGPT.com** (web) are browser-based interfaces with no access to your local system. They cannot run shell commands or connect to external MCP servers, so the Skill has no way to fetch live market data or execute trades.
+Browser-based interfaces have no access to your local system. They cannot run shell commands or connect to external MCP servers.
 
-If you use Claude, install [Claude Desktop](https://claude.ai/download) and use the MCP method above.
+For Claude, use [Claude Desktop](https://claude.ai/download) and switch to the **Code** tab.
 
 ---
 
@@ -152,7 +180,7 @@ Some clients require a restart or a new conversation to load the Skill. Confirm
 
 **Prompted for authorization when querying data**
 
-Run `longbridge auth login` in your terminal and complete the OAuth flow — no API Key required.
+Run `longbridge auth login` in your terminal and complete the OAuth flow.
 
 **Trading operations not working**
 

diff --git a/docs/zh-CN/skill/install/index.md b/docs/zh-CN/skill/install/index.md
@@ -16,52 +16,24 @@ description: 在 OpenClaw、Claude Code、Cursor、Codex 等 AI 工具中安装
 
 ---
 
-## 第一步：安装 Skill
+最快的上手方式是使用终端类 AI 工具——Claude Code、Codex、opencode 或 OpenClaw。安装好 CLI、完成一次授权，AI 就能直接代你运行 `longbridge` 命令。
 
-Skill 是一组指令文件，告诉 AI 助手 Longbridge 能做什么。安装方式有三种：
+如果不想在本地安装软件，也可以通过 MCP 接入——只需在 AI 工具的配置中填入一个 URL 即可。
 
-**通过 Claude Code 插件安装（Claude Code 用户推荐）：**
-
-在 Claude Code 中依次执行以下两条命令：
-
-```text
-/plugin marketplace add longbridge/skills
-/plugin install longbridge@longbridge-skills
-```
-
-此方式通过 Claude Code 插件系统安装全部 Longbridge Skill，并可自动保持最新版本。
-
-**通过 npx / bunx（全局安装）：**
-
-```bash
-# Node.js
-npx skills add longbridge/skills -g
-# Bun
-bunx skills add longbridge/skills -g
-```
-
-> 需要 [Node.js](https://nodejs.org) 或 [Bun](https://bun.sh) 环境。
-
-**或下载 ZIP 手动安装：**
-
-下载 [longbridge-all.zip](https://open.longbridge.com/skill/longbridge-all.zip) 并解压，将文件放入你的 AI 工具指定的 Skill 目录（Claude Code 放 `.claude/skills/`，Cursor 粘贴到 Rules 编辑框，其他工具参考 README）。
-
-**OpenClaw** 直接在对话中发送以下消息，自动完成安装：
-
-```
-从以下 zip 文件安装 Longbridge Developers Skill：
-https://open.longbridge.com/skill/longbridge-all.zip
-```
+两种方式都建议同时安装 Skill：一组指令文件，告诉 AI 助手 Longbridge 能做什么、怎么用。
 
 ---
 
-## 第二步：连接 Longbridge 账户
+## 第一步：连接 Longbridge 平台
+
+CLI 和 MCP 都是接入 Longbridge Developers 平台的方式，两者均可，选其一即可：
 
-Skill 只是让 AI 知道能做什么，要真正获取行情数据或执行交易，还需要连接 Longbridge 账户。根据你的 AI 工具选择接入方式：
+- **CLI**：体验最佳，AI 直接在终端运行 `longbridge` 命令；需要在系统上安装软件
+- **MCP**：接入更简便，只需在 AI 工具配置中填入一个 URL；无需本地安装
 
-### 方式 A：安装 CLI（适用于有 shell 执行能力的工具）
+### 方式 A：CLI（推荐）
 
-Claude Code、Codex、Gemini CLI、Warp 等可以直接在终端执行命令的工具适用此方式。
+适用于 Claude Code、Codex（Work locally 模式）、opencode、OpenClaw、Gemini CLI、Warp 等可在终端执行命令的工具。
 
 ```bash
 # macOS（需要 Homebrew，未安装请先访问 https://brew.sh）
@@ -83,15 +55,19 @@ scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbri
 iwr https://open.longbridge.com/longbridge/longbridge-terminal/install.ps1 | iex
 ```
 
+**授权登录：**
+
 ```bash
 longbridge auth login
 ```
 
+完成后，AI 即可代你调用 `longbridge` 命令。
+
 > 详细安装说明及完整命令列表参见 [CLI 文档](/zh-CN/docs/cli)。
 
-### 方式 B：连接 MCP 服务器（适用于支持 MCP 的工具）
+### 方式 B：MCP
 
-Claude Desktop、Cursor、Zed、Gemini CLI、Warp 等支持 MCP 的工具适用此方式。
+适用于 Claude Desktop、Cursor、Zed、Gemini CLI、Warp 等支持 MCP 的工具。
 
 在 AI 工具的 MCP 配置中添加以下服务器地址：
 
@@ -111,15 +87,72 @@ https://openapi.longbridge.com/mcp
 | Gemini CLI     | `~/.gemini/settings.json` 中的 `mcpServers` 字段                                                                                           |
 | Warp           | Settings → AI → MCP Servers → Add                                                                                                          |
 
-首次提问时客户端会自动弹出浏览器完成 OAuth 授权，无需配置 API Key。
+首次提问时客户端会自动弹出浏览器完成 OAuth 授权。
 
 ---
 
-## 为什么 Claude.ai 和 ChatGPT.com 无法使用
+## 第二步：安装 Skill
+
+Skill 是一组指令文件，告诉 AI 助手 Longbridge 能做什么。
+
+**通过 Claude Code 插件安装（Claude Code 用户推荐）：**
+
+在 Claude Code 中依次执行以下两条命令：
+
+```text
+/plugin marketplace add longbridge/skills
+/plugin install longbridge@longbridge-skills
+```
+
+此方式通过 Claude Code 插件系统安装全部 Longbridge Skill，并可自动保持最新版本。
+
+**通过 npx / bunx（全局安装）：**
+
+```bash
+# Node.js
+npx skills add longbridge/skills -g
+# Bun
+bunx skills add longbridge/skills -g
+```
+
+> 需要 [Node.js](https://nodejs.org) 或 [Bun](https://bun.sh) 环境。
+
+**或下载 ZIP 手动安装：**
+
+下载 [longbridge-all.zip](https://open.longbridge.com/skill/longbridge-all.zip) 并解压，将文件放入你的 AI 工具指定的 Skill 目录（Claude Code 放 `.claude/skills/`，Cursor 粘贴到 Rules 编辑框，其他工具参考 README）。
+
+**OpenClaw** 直接在对话中发送以下消息，自动完成安装：
+
+```
+从以下 zip 文件安装 Longbridge Developers Skill：
+https://open.longbridge.com/skill/longbridge-all.zip
+```
+
+---
+
+## 各工具的已知限制
+
+部分环境存在网络白名单或沙箱限制，会阻止 CLI 安装和 MCP 服务器连接。遇到问题请先查阅本节。
+
+### Claude Desktop — 切换到 Code 标签页
+
+Claude Desktop 的 **Chat 和 Cowork 模式**都存在网络限制，无法安装 CLI 或连接 MCP 服务器。不要在这两种模式下反复尝试，这样不会成功。
+
+切换到 Claude Desktop 的 **Code 标签页**（即 App 内嵌的 Claude Code）。在 Code 标签页下，你拥有完整的终端访问权限，可以在同一个会话中完成 CLI 安装、MCP 连接和 Skill 安装。
+
+<img src="https://assets.lbctrl.com/uploads/76a34f28-9000-4e3e-8250-e992c516ce80/claude.png" alt="Claude Desktop — 切换到 Code 标签页" />
+
+### Codex — 选择「Work locally」
+
+Codex 的 **Cloud 模式**存在同样的网络白名单限制。启动新会话时，请选择 **Work locally** 而非 Cloud。本地模式下 AI 可完整访问你的 shell 和网络。
+
+<img src="https://assets.lbctrl.com/uploads/ccd412df-d312-45c3-a926-e3d466c9a479/codex.png" alt="Codex — 选择 Work locally" />
+
+### Claude.ai 和 ChatGPT.com（网页版）
 
-**Claude.ai**（网页版）和 **ChatGPT.com**（网页版）是基于浏览器的界面，无法访问你的本地系统，既不能执行 shell 命令，也无法连接外部 MCP 服务器，因此 Skill 无法获取实时行情或执行交易。
+基于浏览器的界面无法访问本地系统，既不能执行 shell 命令，也无法连接外部 MCP 服务器。
 
-如果你使用 Claude，请安装 [Claude Desktop](https://claude.ai/download) 并通过上方的 MCP 方式接入。
+如果你使用 Claude，请安装 [Claude Desktop](https://claude.ai/download) 并切换到 **Code 标签页**。
 
 ---
 
@@ -145,7 +178,7 @@ https://openapi.longbridge.com/mcp
 
 **查询数据时需要授权**
 
-在终端中运行 `longbridge auth login` 完成 OAuth 授权即可，无需配置 API Key。
+在终端中运行 `longbridge auth login` 完成 OAuth 授权即可。
 
 **交易操作无法执行**