下面以 OpenClaw v2026.3.13 版本为例, 介绍其在 WSL2/Debian 系统中的安装配置过程

1. 前置条件/Prerequisite​

1.1. 安装基础工具集​

WSL2/Debian 为例:

sudo apt-get install build-essential procps curl file git

OpenClaw 安装及 Skill 安装依赖 git

1.2. 安装 Node.js - OpenClaw 运行环境​

Debian/nvm 为例, 其他环境请参考: https://nodejs.org/en/download

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24

OpenClaw 依赖的 node 版本是 22.12.0+, 如果没有版本选择倾向, 可以让 OpenClaw 安装脚本自动安装

1.3. 安装 Homebrew - 某些 Skill 安装需要​

参考: https://brew.sh/, https://docs.brew.sh/Homebrew-on-Linux

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装结束时按照提示添加 brew 到 PATH:

echo >> /home/zhangsan/.bashrc
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"' >> /home/zhangsan/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"

1.4. 安装 golang shell - 某些 Skill 安装需要​

rm -rf /usr/local/go && tar -C /usr/local -xzf go1.26.1.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

参考: https://go.dev/doc/install

2. 安装过程中的主要配置​

OpenClaw 提供了多种安装方式, 比如可以通过npm i -g openclaw的方式安装, 或Hackable的源码方式安装等. 这里选择最方便的one-liner安装方式, 直接在 linux shell 环境启动安装:

curl -fsSL https://openclaw.ai/install.sh | bash

更多介绍请参考文档: https://docs.openclaw.ai/start/getting-started

2.1. Step by step 的介绍​

1. 启安装后会先检测并安装基础的软件环境, 然后进入配置向导. 首先是一个风险提示, 想安装就输入 y 或 yes

◆  I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
│  ● Yes / ○ No

2. 配置方式, 可以选择 QuickStart, 后期通过openclaw configure再配置其它, 或通过openclaw onboard重启配置向导. 这里选择 Manual (通过上下方向键移动选中项后回车)

注: 选择 Manual 的目的是把相关配置一次性配置完. 后续的这些步骤是没有次序和依赖关系的, 都可以先选择 Skip for now 或 Finished 跳过向导后再次启动配置, 设置步骤编号只是为了读起来有次序感.

◆  Onboarding mode
│  ○ QuickStart
│  ● Manual (Configure port, network, Tailscale, and auth options.)

3. 选择 Local gateway 在本地安装 gateway, 而不是连接到其它 gateway

◆  What do you want to set up?
│  ● Local gateway (this machine) (No gateway detected (ws://127.0.0.1:18789))
│  ○ Remote gateway (info-only)

4. 设定工作目录, 没有特殊要求用默认值即可

◆  Workspace directory
│  /home/zhangsan/.openclaw/workspace

5. 配置模型提供者

• 这里有必要说明一下模型的选择, 如果你是想试玩一下 OpenClaw, 感受一下其能力, 但又没有购买 token 包, 可以暂时先选择Qwen (OAuth), 可以很方便的打开浏览器完成邮箱认证获取小部分免费额度并可投入使用一小会儿, 不过聊几个回合就会把免费额度用完了, 仅够体验
• 还有另一个获取免费 token 的渠道就是 nVidia, 登录 build.nvidia.com/models 并使用手机号注册(可能要海外手机号), 可以获得Up to 40 rpm的 API 调用额度, 在平台上可以免费使用标记为 Free Endpoint 的模型. 比如qwen/qwen3.5-122b-a10b, moonshotai/kimi-k2.5 等都可以使用. 注意 OpenClaw 中需要选择的 provider 是Custom Provider
• 其它非在列的第三方 API 厂商都选择Custom Provider, 指定Base URL和API key后, 再根据 API 类型设置是OpenAI-compatible还是Anthropic-compatible, 如果是openai-responses类型的API, 则需要直接修改配置文件openclaw.json
• 也可以选择Skip for now, 稍后通过openclaw configure重新启动配置

◆  Model/auth provider
│  ○ OpenAI
│  ○ Anthropic
│  ○ Chutes
│  ○ MiniMax
│  ○ Moonshot AI (Kimi K2.5)
│  ○ Google
│  ○ xAI (Grok)
│  ○ Mistral AI
│  ○ Volcano Engine
│  ○ BytePlus
│  ○ OpenRouter
│  ○ Kilo Gateway
│  ● Qwen (OAuth)
│  ○ Z.AI
│  ○ Qianfan
│  ○ Alibaba Cloud Model Studio
│  ○ Copilot
│  ○ Vercel AI Gateway
│  ○ OpenCode
│  ○ Xiaomi
│  ○ Synthetic
│  ○ Together AI
│  ○ Hugging Face
│  ○ Venice AI
│  ○ LiteLLM
│  ○ Cloudflare AI Gateway
│  ○ Custom Provider
│  ○ Ollama
│  ○ SGLang
│  ○ vLLM
│  ○ Skip for now

这是选择Qwen (OAuth)后出现的配置步骤, 根据提示的链接完成认证即可:

◒  Starting Qwen OAuth…│
◇  Qwen OAuth ─────────────────────────────────────────────────────────────────────────╮
│                                                                                      │
│  Open https://chat.qwen.ai/authorize?user_code=XXXXXXXX&client=qwen-code to approve  │
│  access.                                                                             │
│  If prompted, enter the code XXXXXXXX.                                               │
│                                                                                      │
├──────────────────────────────────────────────────────────────────────────────────────╯
◐  Waiting for Qwen OAuth approval….

◇  Qwen OAuth complete
│
◇  Provider notes ──────────────────────────────────────────────────────────────────────╮
│                                                                                       │
│  Qwen OAuth tokens auto-refresh. Re-run login if refresh fails or access is revoked.  │
│  Base URL defaults to https://portal.qwen.ai/v1. Override                             │
│  models.providers.qwen-portal.baseUrl if needed.                                      │
│                                                                                       │
├───────────────────────────────────────────────────────────────────────────────────────╯
│
◇  Model configured ─────────────────────────────╮
│                                                │
│  Default model set to qwen-portal/coder-model  │
│                                                │
├────────────────────────────────────────────────╯
│
◆  Default model
│  ○ Keep current (qwen-portal/coder-model)
│  ○ Enter model manually
│  ○ qwen-portal/coder-model
│  ● qwen-portal/vision-model (Qwen Vision · ctx 125k)

6. 设定网关端口, 默认即可

◆  Gateway port
│  18789

7. 设定网关服务绑定的 IP, 如果需要向外部提供服务, 可选择LAN (0.0.0.0), 体验推荐Loopback (127.0.0.1)

◆  Gateway bind
│  ● Loopback (127.0.0.1)
│  ○ LAN (0.0.0.0)
│  ○ Tailnet (Tailscale IP)
│  ○ Auto (Loopback → LAN)
│  ○ Custom IP

8. 连接网关的认证方式, Token 即可

◆  Gateway auth
│  ● Token (Recommended default (local + remote))
│  ○ Password

9. 这一步是设定是否通过 Tailscale 服务把网关端口暴露到公网, 强烈建议 Off, 除非你了解并愿意承担其风险

◆  Tailscale exposure
│  ● Off (No Tailscale exposure)
│  ○ Serve
│  ○ Funnel

10. 设置 Gateway token 的保存方式. 测试环境用第一项; 生产环境用 SecretRef, 防止 openclaw.json 文件中存储明文 token

◆  How do you want to provide the gateway token?
│  ● Generate/store plaintext token (Default)
│  ○ Use SecretRef

细节参见: https://docs.openclaw.ai/gateway/secrets

11. 让你选择使用指定的 token (粘贴已有的token), 或自动生成一个 token (保持空白后回车)

◆  Gateway token (blank to generate)
│  Needed for multi-machine or non-loopback access

12. 是否现在配置 Channel? Yes

◆  Configure chat channels now?
│  ● Yes / ○ No

Channel 的作用是让你设置可以通过哪个社交软件(聊天工具)来给 OpenClaw 发指令并获取交互输出

13. 这里我们选择在国内比较方便配置的飞书

在 OpenClaw v2026.3.13 版本中, 飞书插件安装有一个小坑需要注意一下: 如果 openclaw 安装时使用的是 one-liner 安装, 安装飞书插件那里一定选择Use local plugin path, 不要再从 npm 库下载一个, 否则后面一直会有一个令人讨厌的 Warning 跟着你: Config warnings:\n- plugins.entries.feishu: plugin feishu: duplicate plugin id detected; later plugin may be overridden (/home/zhangsan/.openclaw/extensions/feishu/index.ts)

◆  Select a channel
│  ○ Telegram (Bot API)
│  ○ WhatsApp (QR link)
│  ○ Discord (Bot API)
│  ○ IRC (Server + Nick)
│  ○ Google Chat (Chat API)
│  ○ Slack (Socket Mode)
│  ○ Signal (signal-cli)
│  ○ iMessage (imsg)
│  ○ LINE (Messaging API)
│  ● Feishu/Lark (飞书) (plugin · install)
│  ○ Nostr (NIP-04 DMs)
│  ○ Microsoft Teams (Bot Framework)
│  ○ Mattermost (plugin)
│  ○ Nextcloud Talk (self-hosted)
│  ○ Matrix (plugin)
│  ○ BlueBubbles (macOS app)
│  ○ Zalo (Bot API)
│  ○ Zalo (Personal Account)
│  ○ Synology Chat (Webhook)
│  ○ Tlon (Urbit)
│  ○ Finished
│
◆ Install Feishu plugin?
│ ○ Download from npm (@openclaw/feishu)
│ ● Use local plugin path (/home/zhangsan/.nvm/versions/node/v24.14.0/lib/node_modules/openclaw/extensions/feishu)
│ ○ Skip for now
12:01:27 [plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load: feishu (/home/zhangsan/.nvm/versions/node/v24.14.0/lib/node_modules/openclaw/extensions/feishu/index.ts). Set plugins.allow to explicit trusted ids.

注: 据说 OpenClaw 在 2026.3.22 ~ 2026.3.23 版本的更新中，对底层的插件架构和扩展目录进行了大规模重构, 新版本中已经不存有 /home/zhangsan/.nvm/versions/node/v24.14.0/lib/node_modules/openclaw/extensions这样的路径, 所以安装选项也会发生变化, 请自行斟酌

14. 开始配置飞书

• 启用飞书 Channel 需要在飞书开放平台创建应用和机器人, 获取 App ID 和 App Secret, 需要注意的是权限设置, 确保可以向机器人私发消息
• 飞书开放平台配置参考文档:
  • https://docs.openclaw.ai/channels/feishu#step-1-create-a-feishu-app
  • https://copaw.agentscope.io/docs/channels/#飞书
• 除了文档中介绍的权限之外, 还是开通 tenant/租户 级别的这些权限: contact:contact.base:readonly, contact:contact:access_as_app, contact:contact:readonly, contact:contact:readonly_as_app

获取到 App ID 和 App Secret 后, 跟随配置向导完成如下设置:

• 直接粘贴飞书 App Secret 和 App ID (敏感正式环境可选择 external secret provider)
• 设置连接方式 WebSocket
• 根据所在环境选择飞书域名, 国内为 feishu.cn, 国外为 larksuite.com
• 安全设置, 设置哪些群聊可以使用飞书机器人. 可以通过 Allowlist 来设置群 ID, 或设置为 Open 允许所有群使用. 群聊的会话 ID 可以在飞书群 -> 设置界面的最底部查看

◇  Feishu credentials ──────────────────────────────────────────────────────────────╮
│                                                                                   │
│  1) Go to Feishu Open Platform (open.feishu.cn)                                   │
│  2) Create a self-built app                                                       │
│  3) Get App ID and App Secret from Credentials page                               │
│  4) Enable required permissions: im:message, im:chat, contact:user.base:readonly  │
│  5) Publish the app or add it to a test group                                     │
│  Tip: you can also set FEISHU_APP_ID / FEISHU_APP_SECRET env vars.                │
│  Docs: feishu                 │
│                                                                                   │
├───────────────────────────────────────────────────────────────────────────────────╯
│
◆  How do you want to provide this App Secret?
│  ● Enter App Secret (Stores the credential directly in OpenClaw config)
│  ○ Use external secret provider

◇  Enter Feishu App Secret
│  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
│
◇  Enter Feishu App ID
│  cli_xxxxxxxxxxxxxxxx
[info]: [ 'client ready' ]
│
◇  Feishu connection test ───────────────────────────╮
│                                                    │
│  Connected as ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  │
│                                                    │
├────────────────────────────────────────────────────╯
│
◆  Feishu connection mode
│  ● WebSocket (default)
│  ○ Webhook

◆  Which Feishu domain?
│  ● Feishu (feishu.cn) - China
│  ○ Lark (larksuite.com) - International

◆  Group chat policy
│  ● Allowlist - only respond in specific groups
│  ○ Open - respond in all groups (requires mention)
│  ○ Disabled - don't respond in groups
│
◆  Group chat allowlist (chat_ids)
│  oc_xxxxx, oc_yyyyy

飞书配置完成后如果不再配置其他 Channel, 就在 Channel 配置界面选择 Finished 继续.

15. 接下来向导会问你是否要配置私聊（Direct Message, DM）访问策略: Yes 无疑

◆  Configure DM access policies now? (default: pairing)
│  ● Yes / ○ No

16. 设置飞书私聊策略, 对应的选择分别是: 一一配对, 白名单, 全开放

如果选择一一配对, 某个用户给机器人私发消息时会弹出配对指令, 通过 openclaw 执行该指令授权后才会有响应: openclaw pairing approve feishu <CODE>

◆  Feishu DM policy
│  ● Pairing (recommended)
│  ○ Allowlist (specific users only)
│  ○ Open (public inbound DMs)
│  ○ Disabled (ignore DMs)

17. 为 openclaw 配置联网搜索功能, 这也是一个必要的基本能力

个人使用的话, 推荐可以免费薅羊毛的 Brave Search, 方法也比较简单:

• 注册登录brave search api 平台: https://brave.com/search/api/
• 在 Billing -> Payment method 中绑定一个卡, 支持银联, 绑定后会预扣一个美金
• 在 Usage limits 中可以设置每月使用限额, 设置为 5 美金. Brave Search 会每月赠送你 5 美金的额度. 这样就互抵了, 免费使用
• 进入API keys, 点击Add API key, 创建一下 key 并复制, 选中Brave Search并在接下来的步骤填入复制的 key, Brave Search 就配置完成了

◆  Search provider
│  ● Brave Search (Structured results · country/language/time filters)
│  ○ Gemini (Google Search)
│  ○ Grok (xAI)
│  ○ Kimi (Moonshot)
│  ○ Perplexity Search
│  ○ Skip for now

◇  Brave Search API key
│  BSAxxxxxx_XXXXXXXXX_xxxxxxxxxxx

18. Skill 配置步骤, 暂不需要什么高级功能, 可以选择跳过, 相应 Skill 需要的 KEY 也全部选 No, 如需要可以后期再配置

◇  Skills status ─────────────╮
│                             │
│  Eligible: 18               │
│  Missing requirements: 31   │
│  Unsupported on this OS: 7  │
│  Blocked by allowlist: 0    │
│                             │
├─────────────────────────────╯
│
◆  Configure skills now? (recommended)
│  ○ Yes / ● No

◇  Set GOOGLE_PLACES_API_KEY for goplaces?
│  No
│
◇  Set GEMINI_API_KEY for nano-banana-pro?
│  No
│
◇  Set NOTION_API_KEY for notion?
│  No
│
◇  Set OPENAI_API_KEY for openai-image-gen?
│  No
│
◇  Set OPENAI_API_KEY for openai-whisper-api?
│  No
│
◆  Set ELEVENLABS_API_KEY for sag?
│  ○ Yes / ● No

19. Hooks 建议启用 command-logger 和 session-memory, 主要用于实现命令日志记录和会话记忆功能

复选框的选择方式是: 方向键移动到高亮选项, 然后通过空格键选中或取消选中

◆  Enable hooks?
│  ◻ Skip for now
│  ◻ 🚀 boot-md
│  ◻ 📎 bootstrap-extra-files
│  ◼ 📝 command-logger (Log all command events to a centralized audit file)
│  ◼ 💾 session-memory (Save session context to memory when /new or /reset command is issued)

20. 是否在 Service 形式安装 gateway: Yes, 安装后可以像管理普通 systemd 服务的形式进行管理, 比如通过 systemctl --user status openclaw-gateway 来查询状态

◆  Install Gateway service (recommended)
│  ● Yes / ○ No

21. 完成安装

• 接下来根据向导完成安装就行了
• 需要记录下 Gateway 的 token, 可以直接点击 Web UI 链接打开 OpenClaw Web UI
• 最后的bash shell completion for openclaw可以根据个人习惯选择装或不装, 没啥大用, 就那几个命令

◆  Gateway service runtime
│  ● Node (recommended) (Required for WhatsApp + Telegram. Bun can corrupt memory on reconnect.)

◒  Installing Gateway service…
Installed systemd service: /home/zhangsan/.config/systemd/user/openclaw-gateway.service
◇  Gateway service installed.
│
◇
Health check failed: gateway closed (1006 abnormal closure (no close frame)): no close reason
  Gateway target: ws://127.0.0.1:18789
  Source: local loopback
  Config: /home/zhangsan/.openclaw/openclaw.json
  Bind: lan
│
◇  Health check help ────────────────────────────────╮
│                                                    │
│  Docs:                                             │
│  https://docs.openclaw.ai/gateway/health           │
│  https://docs.openclaw.ai/gateway/troubleshooting  │
│                                                    │
├────────────────────────────────────────────────────╯
│
◇  Optional apps ────────────────────────╮
│                                        │
│  Add nodes for extra features:         │
│  - macOS app (system + notifications)  │
│  - iOS app (camera/canvas)             │
│  - Android app (camera/canvas)         │
│                                        │
├────────────────────────────────────────╯
│
◇  Control UI ───────────────────────────────────────────────────────────────────────╮
│                                                                                    │
│  Web UI: http://127.0.0.1:18789/                                                 │
│  Web UI (with token):                                                              │
│  http://127.0.0.1:18789/#token=25637d07f8f36fe427c6de1d9f2214fc564f2be49809359d  │
│  Gateway WS: ws://127.0.0.1:18789                                                │
│  Gateway: not detected (SECURITY ERROR: Gateway URL "ws://127.0.0.1:18789" uses  │
│  plaintext ws:// to a non-loopback address.)                                       │
│  Docs: https://docs.openclaw.ai/web/control-ui                                     │
│                                                                                    │
├────────────────────────────────────────────────────────────────────────────────────╯
│
◇  Workspace backup ────────────────────────────────────────╮
│                                                           │
│  Back up your agent workspace.                            │
│  Docs: https://docs.openclaw.ai/concepts/agent-workspace  │
│                                                           │
├───────────────────────────────────────────────────────────╯
│
◇  Security ──────────────────────────────────────────────────────╮
│                                                                 │
│  Running agents on your computer is risky — harden your setup:  │
│  https://docs.openclaw.ai/security                              │
│                                                                 │
├─────────────────────────────────────────────────────────────────╯
│
◆  Enable bash shell completion for openclaw?
│  ● Yes / ○ No

2.2. 配置文件​

除了一些凭证或 token 信息, OpenClaw 的配置内容都保存在 .openclaw/openclaw.json 文件中, 如果你对该文件结构足够熟悉, 可以直接修改该文件, 然后执行openclaw daemon restart重启生效即可.

下面是一个配置文件示例:

{
  "meta": {
    "lastTouchedVersion": "2026.3.23-2",
    "lastTouchedAt": "2026-03-25T07:13:31.449Z"
  },
  "wizard": {
    "lastRunAt": "2026-03-25T07:13:31.416Z",
    "lastRunVersion": "2026.3.23-2",
    "lastRunCommand": "onboard",
    "lastRunMode": "local"
  },
  "auth": {
    "profiles": {
      "qwen-portal:default": {
        "provider": "qwen-portal",
        "mode": "oauth"
      },
      "ollama:default": {
        "provider": "ollama",
        "mode": "api_key"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "mycompany-openai": {
        "baseUrl": "https://ai.mycompany.com/openai/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.3-chat",
            "name": "gpt-5.3-chat (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 100000,
            "maxTokens": 16000
          },
          {
            "id": "gpt-5.4",
            "name": "gpt-5.4 (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1000000,
            "maxTokens": 128000
          }
        ]
      },
      "mycompany-anthropic": {
        "baseUrl": "https://ai.mycompany.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxx",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-haiku-4-5",
            "name": "claude-haiku-4-5 (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 64000
          },
          {
            "id": "claude-sonnet-4-6",
            "name": "claude-sonnet-4-6 (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1000000,
            "maxTokens": 64000
          },
          {
            "id": "claude-opus-4-6",
            "name": "claude-opus-4-6 (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1000000,
            "maxTokens": 128000
          }
        ]
      },
      "mycompany-google": {
        "baseUrl": "https://ai.mycompany.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxx",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3.1-flash-lite",
            "name": "gemini-3.1-flash-lite (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1000000,
            "maxTokens": 65000
          },
          {
            "id": "gemini-3.1-pro",
            "name": "gemini-3.1-pro (Custom Provider)",
            "reasoning": true,
            "input": [
              "text",
              "image"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1000000,
            "maxTokens": 65000
          }
        ]
      },
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434",
        "apiKey": "OLLAMA_API_KEY",
        "api": "ollama",
        "models": [
          {
            "id": "glm-4.7-flash",
            "name": "glm-4.7-flash",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "qwen3-embedding:4b",
            "name": "qwen3-embedding:4b",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 40960,
            "maxTokens": 8192
          },
          {
            "id": "qwen3.5:2b",
            "name": "qwen3.5:2b",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 262144,
            "maxTokens": 8192
          },
          {
            "id": "qwen2.5:3b",
            "name": "qwen2.5:3b",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 32768,
            "maxTokens": 8192
          },
          {
            "id": "nomic-embed-text:latest",
            "name": "nomic-embed-text:latest",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 2048,
            "maxTokens": 8192
          },
          {
            "id": "qwen3.5:4b",
            "name": "qwen3.5:4b",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 262144,
            "maxTokens": 8192
          },
          {
            "id": "qwen3:4b",
            "name": "qwen3:4b",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 262144,
            "maxTokens": 8192
          },
          {
            "id": "qwen3:8b",
            "name": "qwen3:8b",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 40960,
            "maxTokens": 8192
          }
        ]
      },
      "nvidia-nim": {
        "baseUrl": "https://integrate.api.nvidia.com/v1",
        "apiKey": "nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "moonshotai/kimi-k2.5",
            "name": "moonshotai/kimi-k2.5 (Custom Provider)",
            "api": "openai-completions",
            "reasoning": false,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          },
          {
            "id": "qwen/qwen3.5-397b-a17b",
            "name": "qwen/qwen3.5-397b-a17b (Custom Provider)",
            "reasoning": true,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16000,
            "maxTokens": 4096
          },
          {
            "id": "qwen/qwen3-5-122b-a10b",
            "name": "qwen / qwen3-5-122b-a10b (Custom Provider)",
            "reasoning": true,
            "input": [
              "text"
            ],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 16384,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "mycompany-anthropic/claude-sonnet-4-6",
        "fallbacks": [
          "mycompany-anthropic/claude-haiku-4-5",
          "mycompany-openai/gpt-5.3-chat",
          "mycompany-anthropic/claude-opus-4-6",
          "mycompany-google/gemini-3.1-pro",
          "mycompany-google/gemini-3.1-flash-lite",
          "mycompany-openai/gpt-5.4",
          "nvidia-nim/qwen/qwen3.5-122b-a10b",
          "nvidia-nim/qwen/qwen3.5-397b-a17b",
          "nvidia-nim/moonshotai/kimi-k2.5",
          "ollama/qwen3:4b",
          "ollama/qwen3.5:4b",
          "ollama/qwen3.5:2b",
          "ollama/qwen3:8b",
          "ollama/qwen2.5:3b"
        ]
      },
      "models": {
        "ollama/qwen3:4b": {},
        "ollama/qwen3.5:4b": {},
        "ollama/qwen3.5:2b": {},
        "ollama/qwen3:8b": {},
        "ollama/qwen2.5:3b": {},
        "nvidia-nim/moonshotai/kimi-k2.5": {},
        "nvidia-nim/qwen/qwen3.5-397b-a17b": {},
        "nvidia-nim/qwen/qwen3.5-122b-a10b": {},
        "mycompany-openai/gpt-5.4": {},
        "mycompany-openai/gpt-5.3-chat": {},
        "mycompany-anthropic/claude-opus-4-6": {},
        "mycompany-anthropic/claude-haiku-4-5": {},
        "mycompany-anthropic/claude-sonnet-4-6": {},
        "mycompany-google/gemini-3.1-flash-lite": {},
        "mycompany-google/gemini-3.1-pro": {}
      },
      "workspace": "/home/zhangsan/.openclaw/workspace",
      "memorySearch": {
        "enabled": true,
        "provider": "ollama",
        "remote": {
          "baseUrl": "http://127.0.0.1:11434",
          "apiKey": "ollama"
        },
        "model": "nomic-embed-text"
      }
    },
    "list": [
      {
        "id": "main",
        "model": "mycompany-openai/gpt-5.4"
      }
    ]
  },
  "tools": {
    "profile": "full",
    "web": {
      "search": {
        "enabled": true,
        "provider": "brave"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "command-logger": {
          "enabled": true
        },
        "session-memory": {
          "enabled": true
        }
      }
    }
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "connectionMode": "websocket",
      "domain": "feishu",
      "groupPolicy": "allowlist",
      "groupAllowFrom": [
        "oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789"
      ]
    },
    "auth": {
      "mode": "token",
      "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "allow": [
      "feishu",
      "qwen-portal-auth",
      "brave"
    ],
    "load": {
      "paths": []
    },
    "entries": {
      "qwen-portal-auth": {
        "enabled": true
      },
      "feishu": {
        "enabled": true
      },
      "brave": {
        "enabled": true,
        "config": {
          "webSearch": {
            "apiKey": "BSAxxxxxx_xxxxxxxxx_xxxxxxxxxxx"
          }
        }
      }
    }
  }
}

3. 自定义模型 Provider 及 API 兼容模式​

OpenClaw 安装完成后, 可以通过openclaw configure命令重新启动配置向导. 如果你有购买第三方的模型服务 API, 或公司内部有统一付费的模型 API 代理, 可以通过Custom Provider途径对接.

3.1 向导配置说明​

启动配置向导后的选择路径: Where will the Gateway run?: Local -> Select sections to configure: Model -> Model/auth provider: Custom Provider

以 https://build.nvidia.com/moonshotai/kimi-k2.5 模型为例, 在向导中分别提供:

1. API Base URL

API Base URL
│  https://integrate.api.nvidia.com/v1

2. 粘贴获取的 API key

How do you want to provide this API key?
│  ● Paste API key now (Stores the key directly in OpenClaw config)

API Key (leave blank if not required)
nvapi-**********U9w

3. 选择 API 兼容类型

在 OpenClaw（以及类似的 LLM 网关/代理框架）中，模型 API 兼容模式（Compatibility Modes） 的核心作用是协议转换。市面上的大语言模型（LLM）厂商并没有统一的标准，各家的接口参数、消息格式、甚至返回值结构都不一样。这些“模式”就是告诉框架：应该用什么格式把你的 Prompt 组装发给大模型，以及怎么解析大模型吐回来的数据。特别是 OpenClaw 还涉及到工具的调用, 协议不匹配会直接导致 OpenClaw 报错, 比如常见的Message ordering conflict - please try again. If this persists, use /new to start a fresh session.错误就是因为协议不匹配引起的.
OpenClaw 配置向导提供了两种 API 兼容模式, 对于更多的模型厂商, 可以直接去修改 openclaw.json 文件以获得更好的兼容性和功能扩展

 Endpoint compatibility
│  ● OpenAI-compatible (Uses /chat/completions)
│  ○ Anthropic-compatible
│  ○ Unknown (detect automatically)

4. 选择模型 Model ID moonshotai/kimi-k2.5

5. 给 Provider 取个名称 Endpoint ID nvidia-nim

6. Model alias 没有意义, 留空回车完成模型配置

3.2 API 兼容模式对比​

参考上文提供的 openclaw.json 的示例, API 兼容模式配置在 models.providers.<YOUR PROVIDER>.api 属性中, 下表收集了常见的 API 兼容模式, 请根据选用的 provider 和 模型去配置正确的模式:

4. 配置启用 Memory Search (必要)​

在 OpenClaw 这样的大模型 Agent 框架中，如果说前面提到的 session-memory 是机器人的**“短期记忆（RAM 内存）”，那么 Memory Search（记忆搜索） 就是机器人的“长期记忆（硬盘 / 知识库）”**。

Memory Search 的核心作用是跨会话的语义检索与上下文增强（RAG）。它让 AI 能够“记住”几天前、几个月前甚至几年前你们聊过的信息，或者从海量的文档中瞬间找出相关内容。

在 OpenClaw 中，Memory Search 赋予了 Agent 真正的“成长性”和“企业级知识储备”。它让大模型不再是一个每次都需要重新调教的通用工具，而是一个能随着你不断使用、不断积累经验，越来越懂你业务的专属 AI 助手。

Memory Search 并不是像传统数据库那样用 WHERE text LIKE '%关键字%' 去做死板的字面匹配，它使用的是向量检索（Vector Search）。我们需要为 Memory Search 提供一个 Embedding 模型.

4.1. Ollama 配置示例​

如果你有一个带显卡的PC, 可以选择部署一个 Ollama 环境, 参见 Ollama 安装
然后下载一个轻量化的 Embedding 模型(比如 nomic-embed-text), 用于开启 Memory Search.

1. 下载模型

ollama pull nomic-embed-text

2. 配置启用 Memory Search, 假设 Ollama 部署在 OpenClaw 本机:

openclaw config set agents.defaults.memorySearch.enabled true
openclaw config set agents.defaults.memorySearch.provider "ollama"
openclaw config set agents.defaults.memorySearch.remote.baseUrl "http://127.0.0.1:11434"
openclaw config set agents.defaults.memorySearch.remote.apiKey "ollama"
openclaw config set agents.defaults.memorySearch.model "nomic-embed-text"

3. 查看并重建 Memory 索引

openclaw memory status --deep # 查看
openclaw memory index # 索引
openclaw memory status --deep # 再查看

当然也可以直接使用厂家的商业 Embedding 模型, 默认方式相同, 请自行选用

5. 解锁命令执行等所有权限​

OpenClaw v2026.3.13 版本的 profile 默认是 coding, 不具备命令执行权限, 通过把 profile 设置为 full, 以解锁所有权限:

openclaw config set tools.profile full
openclaw gateway restart

6. 使用方式​

6.1. 通过 WebChat. 比如: http://127.0.0.1:18789/​

6.2. 通过你绑定的 Channel. 比如: 飞书, What's App 等​

7. 在 WSL 中基于OpenClaw Browser Relay启用浏览器操作​

在 Windows Subsystem for Linux (WSL) 中安装 OpenClaw 没有像在 MacOS 和 Windows 上安装那么方便的操纵浏览器, 但也不是没有办法.

比如通过 Chrome 的插件: OpenClaw Browser Relay, 到这儿来安装: https://chromewebstore.google.com/search/OpenClaw%20Browser%20Relay, 然后设置:

1. 安装完成后会弹出设置界面, 默认情况下不用修改端口, 填入 Gateway token 后点击 Save 按钮
   

2. 确保 OpenClaw Browser Relay 插件成功连接到网关:
   

3. 在浏览器中把插件按钮显示出来, 并点击:
   

4. 当插件的状态变为"ON"的时候, OpenClaw就可以操纵这个浏览器 tab了.
   

然后就可以通过 WebChat 或 Channel 直接告诉 OpenClaw 帮你填下活了, 比如: 打开某个网址, 进入某个模块, 抓取某些数据, 有异常的话给 Channel 发个告警, 然后再把这几步做下定时巡检任务.

注: OpenClaw Browser Relay 在 v2026.3.13 版本工作正常, 但升级到 v2026.3.23-2 版本后, 浏览器插件连接网关一直连不上, 还在研究. 报错如下:
Relay not reachable/authenticated at http://127.0.0.1:18792/. Start OpenClaw browser relay and verify token.

8. 环境变量的配置​

使用 .openclaw 目录下的 .env 文件, 可以直接为 OpenClaw 配置所以的环境变量. 比如:

$ cat ~/.openclaw/.env
HTTP_PROXY=http://127.0.0.1:10808
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
FEISHU_APP_SECRET=...

9. 使用 Clawhub 安装 Skill​

想持续提供 OpenClaw 的能力吗? 请安装 Skill.

1. 去 https://clawhub.ai/skills 找到心仪的 Skill
2. 安装 clawhub CLI: npm i -g clawhub
3. 使用clawhub login登录 clawhub, 登录后可以使用clawhub whoami查看登录状态
4. 使用clawhub install <SKILL>安装. 比如: clawhub install weather

10. 升级 OpenClaw​

跟安装一样, 重新执行就行了, 然后在配置向导中一路选择保留配置和数据.

12. 卸载 OpenClaw​

1. 执行如下脚本进行卸载:

openclaw uninstall --all --yes --non-interactive
npm rm -g openclaw

2. 如果无法通过上述指令清除干净, 必要情况下通过查找删除所有目录:

$ which openclaw
/home/zhangsan/.npm-global/bin/openclaw

$ cd /home/zhangsan/.npm-global/bin/
$ ls -la
total 8
drwxr-xr-x 2 zhangsan zhangsan 4096 Mar 12 20:26 .
drwxr-xr-x 4 zhangsan zhangsan 4096 Mar 12 20:13 ..
lrwxrwxrwx 1 zhangsan zhangsan   41 Mar 12 20:26 openclaw -> ../lib/node_modules/openclaw/openclaw.mjs

~/.npm-global/bin$ rm openclaw
~/.npm-global/bin$ rm -rf ../lib/node_modules/openclaw

3. 修改 ~/.bashrc, 删除 OpenClaw bash completions 相关内容

12. Slash Commands​

OpenClaw 的 WebChat 中可以直接执行 bash 指令, 格式是在聊天窗口中直接输入 !<cmd> 或 /bash <cmd>
但默认没有开启, 执行/bash ls -la时会提示: bash is disabled. Set commands.bash=true to enable. Docs: https://docs.openclaw.ai/tools/slash-commands#config

现在展示一步步开启:

1. openclaw config set commands.bash true

$ openclaw config set commands.bash true

🦞 OpenClaw 2026.3.23-2 (7ffe7e4) — I don't sleep, I just enter low-power mode and dream of clean diffs.

Config overwrite: /home/zhangsan/.openclaw/openclaw.json (sha256 19870f67fda3bf3964d110ac38cfac4e87e1363dbe4dba25fa4fdadd9f91ba63 -> 4e9bb164bd13d959ef161810194e112ad97bd037ec0570b57298555d9b68eeb2, backup=/home/zhangsan/.openclaw/openclaw.json.bak)
Updated commands.bash. Restart the gateway to apply.

再试/bash ls -la提示:

elevated is not available right now (runtime=direct).
Failing gates: allowFrom (tools.elevated.allowFrom.webchat)
Fix-it keys:
- tools.elevated.enabled
- tools.elevated.allowFrom.<provider>
- agents.list[].tools.elevated.enabled
- agents.list[].tools.elevated.allowFrom.<provider>
See: openclaw sandbox explain --session agent:main:main

2. openclaw sandbox explain --session agent:main:main

$ openclaw sandbox explain --session agent:main:main

🦞 OpenClaw 2026.3.23-2 (7ffe7e4) — Self-hosted, self-updating, self-aware (just kidding... unless?).

Effective sandbox:
  agentId: main
  sessionKey: agent:main:main
  mainSessionKey: agent:main:main
  runtime: direct
  mode: off scope: agent perSession: false
  workspaceAccess: none workspaceRoot: /home/zhangsan/.openclaw/sandboxes

Sandbox tool policy:
  allow (default): exec, process, read, write, edit, apply_patch, image, sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
  deny  (default): browser, canvas, nodes, cron, gateway, telegram, whatsapp, discord, irc, googlechat, slack, signal, imessage, line

Elevated:
  enabled: true
  channel: webchat
  allowedByConfig: false
  failing gates: allowFrom (tools.elevated.allowFrom.webchat)

Fix-it:
  - tools.sandbox.tools.allow
  - tools.sandbox.tools.deny
  - agents.list[].tools.sandbox.tools.allow
  - agents.list[].tools.sandbox.tools.deny
  - tools.elevated.enabled
  - tools.elevated.allowFrom.webchat

Docs: docs.openclaw.ai/sandbox

3. 根据提示依次执行:

openclaw config set tools.elevated.enabled true
openclaw config set tools.elevated.allowFrom.webchat '["*"]'
openclaw gateway restart

4. 再次尝试执行/bash ls -la, 在弹出的窗口 Allow 操作
   

13. 其它排错调试场景​

1. 在飞书中向机器人发消息时得到的回复是OpenClaw: access not configured.

OpenClaw: access not configured.
Your Feishu user id: ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Pairing code: XXXXXXXX
Ask the bot owner to approve with:
openclaw pairing approve feishu XXXXXXXX

是因为你飞书 Channel 的 DM Policy 是 pairing, 需要 OpenClaw 所有人执行 openclaw pairing approve feishu XXXXXXXX 进行授权, 然后就可以通过飞书指挥 OpenClaw 了\

2. 大量的 Tool not found 回复 大概率就是你的模型 API 类型配置错误, 请检查 openclaw.json 中的这三个属性值配置是否跟模型匹配:

• models.providers.<YOUR PROVIDER>.api - API 兼容模式
• models.providers.<YOUR PROVIDER>.models[].reasoning - 是否支持开启思考
• models.providers.<YOUR PROVIDER>.models[].input[] - 是否配置了支持的输入类型. 如 "text", "image" 等

最后祝养虾愉快!!!

1. 主要步骤:

• 创建新的身份池：先建一个 Workload Identity Pool，它像一个“外层容器”，用来容纳来自 GitHub 的外部身份。
• 配置映射并添加条件：在这个池里建一个 OIDC Provider，把 GitHub 发来的 OIDC claims 映射成 Google 可识别的属性，并加一个准入条件，限制只有你指定的 GitHub 组织/仓库/分支能进来。
• 将新池连接到服务帐户：这一步不是点一个“连接”按钮，而是给目标 Service Account 加一条 IAM policy binding，让来自这个池中、满足条件的 GitHub principal 能以 roles/iam.workloadIdentityUser 身份冒充这个服务账号。

对于“GitHub Actions 操作 GCE”，建议直接走 Workload Identity Federation through a Service Account，不要用长期 JSON key。Google 的 auth Action 文档把它列为推荐路径之一；而且如果要生成 OAuth 2.0 access token 或用 gcloud 操作资源，通常都要提供 service account。直接给 pool/resource 绑定权限的方式虽然可行，但并不是所有资源都支持 principalSet，并且直接 WIF 的 token 生命周期还有更严格限制。

2. 前置条件: 你至少要有这些权限：

• 配置 Workload Identity Pool / Provider：roles/iam.workloadIdentityPoolAdmin
• 创建 Service Account：roles/iam.serviceAccountCreator
• 修改 Service Account 的 IAM 访问策略：roles/iam.serviceAccountAdmin (docs.cloud.google.com) 另外，如果你的项目还没开相关 API，至少要确保 IAM API 和 Compute Engine API 已启用；Compute Engine API 的服务名是 compute.googleapis.com，IAM API 会处理 service account 相关能力。

3. 资源准备: 先假设已有或需要准备这些资源值：

• Github Organization or User, Github 组织或用户名. 比如 myorg
• Github Repository, Github 仓库地址. 比如 myorg/myrepo
• GCP Project ID, Google Cloud 项目ID. 比如 my-gcp-project
• GCP Project Number, Google Cloud 项目编号. 比如 123456789012
• GCP Workload Identity Pool ID, 需要命名并创建. 比如 github-actions
• GCP Workload Identity Provider ID, 需要命名并创建. 比如 github-myorg-myrepo
• GCP Service Account, 现有 GCE 实例关联的 Service Account. 比如自动生成的 123456789012-compute
• GCP Service Account Email, 现有 GCE 实例关联的 Service Account Email. 比如自动生成的 123456789012-compute@developer.gserviceaccount.com

4. 安全优势 使用 OIDC Workload Identity Federation 相比传统 SSH 密钥方式有以下优势：

• 无需长期密钥：不再需要在 GitHub Secrets 中存储 SSH 私钥，认证令牌是短期的，自动过期
• 细粒度权限控制：可以通过 GCP IAM 精细控制部署权限
• 审计追踪：所有认证和操作都会记录在 GCP Cloud Audit Logs 中
• 条件约束：可以限制只允许特定仓库、分支触发部署
• 权限分离：SA 用户仅负责 SSH 登录和文件传输，实际部署以 OS 用户身份执行，遵循最小权限原则

1. Google Cloud 设置​

登录 Google Cloud -> IAM & Admin / Wordload Identity Federation

1.1. 创建和配置 Workload Identity Pool 和 Provider​

1. 如果没有 Workload Identity Pool, 点击Create pool根据需要创建一个 输入 Pool 名称, Pool ID 会自动生成, 也可以修改, 点击 Continue 继续.

对 gcloud cli 熟悉也可以通过 cli 创建. 示例:

gcloud iam workload-identity-pools create "github-actions" \
  --project="${GCP_PROJECT_ID}" \
  --location="global" \
  --display-name="GitHub Actions"

2. 继续创建 Provider, Provider 类型选择 OpenID Connect (OIDC), 输入 Provider 名称, Issuer 填入 GitHub 官方 OIDC issuer https://token.actions.githubusercontent.com, 其它不变

3. 创建 Provider 属性映射, 映射/mapping 是"把 claim 变成可引用属性"

• google.subject -> assertion.sub
• attribute.repository -> assertion.repository
• attribute.repository_owner -> assertion.repository_owner
• attribute.actor -> assertion.actor
• attribute.ref -> assertion.ref

具体字段细节请参考: https://docs.cloud.google.com/iam/docs/workload-identity-federation#mapping

4. 设置 Attribute conditions, condition 是"准入规则", 以限制能通过认证的范围. 这里我们设置只有指定的 Owner 和指定的仓库才能通过认证触发相应动作. 最后点击 Save 完成 Provider Pool 创建 assertion.repository_owner == 'GITHUB_ORG_OR_USER' && attribute.repository == 'GITHUB_ORG_OR_USER/GITHUB_REPO_NAME'

合并上述 #2/#3/#4 步骤的 gcloud cli 示例:

gcloud iam workload-identity-pools providers create-oidc "github-actions-provider" \
  --project="${GCP_PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="github-actions-pool" \
  --display-name="GitHub Actions Provider" \
  --attribute-mapping="googled.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner,attribute.actor=assertion.actor,attribute.ref=assertion.ref" \
  --attribute-condition="assertion.repository_owner == 'GITHUB_ORG_OR_USER'" \
  --issuer-uri="https://token.actions.githubusercontent.com"

1.2. 创建和配置 Github Actions 的 Service Account​

1. 如果你还没有专门给 GitHub Actions 用的 Service Account，先创建一个: IAM & Admin/IAM 和管理 -> Service Accounts/服务账号 -> Create service account/创建服务账号, 创建时只填服务账号名称即可, 权限稍后配置.

2. 为 Service Account 授于角色

• 进入 IAM & Admin → IAM -> Allow tab
• 找到你刚创建的 service account（邮箱类似 gha-gce@PROJECT_ID.iam.gserviceaccount.com）
• 点击铅笔 Edit principal
• 根据需要在 Assign roles 里增加 相应的Role. 在些我需要让这个 SA 可以 SSH 到 Compute Engine 中执行 sudo, 因此给这个SA 授予Compute Viewer和Compute OS Admin Login
• 保存。Google Cloud 的 IAM 策略把角色绑定到 principal 上，项目级角色会影响该项目内资源。

3. 把 Pool “连接”到 Service Account

• 进入 IAM & Admin -> Service accounts
• 找到你刚才创建的 Service Account, 点击进入详细页并切换到Principals with access tab
• 点击Grant access把指定 GitHub repo 的 principal 授权为可以使用该 Service Account:
  • New principals字段中填写principalSet://iam.googleapis.com/projects/<GCP_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<IDENTITY_POOL_ID>/attribute.repository/<GITHUB_ORG_OR_USER>/<GITHUB_REPO_NAME> (这背后的意思是: “允许来自这个 pool 且 attribute.repository == <GITHUB_ORG_OR_USER>/<GITHUB_REPO_NAME> 的主体使用这个 service account。”, 这种 principal identifier 格式是 Google IAM 支持的做法)
  • Role选择Workload Identity User. Workload Identity User 允许工作负载身份代表该 service account 获取 access token / OIDC token
  • 点击Save完成授权

1.3. 检查是否启用 Compute Engine API​

如果你的项目从没用过 Compute / IAM 相关能力，建议顺手检查 API 是否启用。控制台操作:

1. 进入APIs & Services -> 点击 Enabled APIs & services
2. 搜索并启用 Compute Engine API
3. 与 IAM / Service Account 相关 API（如果页面提示缺失，一并启用）

1.4. 授权 GitHub Actions 的 SA 使用 VM 的 SA​

如果 Github Actions 使用的 Service Account 与 GCP 服务器绑定的 Service Account 不是同一个, 则需要授权 GitHub Actions 的 Service Account 可以使用 VM 绑定的 SA,

1. IAM & Admin → Service Accounts, 找到 VM 绑定的 service account, 点击进入详情页
2. 切换到 Principals with access tab, 点击Grant access
3. New principals搜索并选择 Github Actions 使用的 Service account
4. 在Assign roles中添加Service Account User role

1.5. 开启 OS Login​

1. 进入 GCP Comoute Engine控制台并找到需要操作的VM
2. 点击Edit修改该VM, 在Metadata中添加 key enable-oslogin, 设置 value 为TRUE后保存

2. Github Actions 设置​

2.1. 在项目的 .github/workflows 目录下创建 deploy.yml​

一个配置示例:

name: Build and Deploy
on:
  push:
    branches:
      - release
  workflow_dispatch:
# Required for requesting the OIDC JWT token
permissions:
  contents: read
  id-token: write
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_BASE: ${{ secrets.GCP_VM_DEPLOY_BASE }}
      DEPLOY_TAR: /tmp/mywebsite-com-build.tar.gz
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          lfs: true
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'yarn'
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build static files
        run: yarn build
      - name: Compress build output
        run: tar -czf build.tar.gz -C build .
      - name: Authenticate to Google Cloud via OIDC
        id: auth
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
      - name: Set up Cloud SDK
        uses: google-github-actions/setup-gcloud@v2
      - name: Generate release timestamp
        id: release
        run: echo "timestamp=$(TZ=Asia/Shanghai date +%Y%m%d%H%M%S)" >> "$GITHUB_OUTPUT"
      - name: Upload archive to GCP VM
        run: |
          gcloud compute scp build.tar.gz \
            ${{ secrets.GCP_VM_SA_USER }}@${{ secrets.GCP_VM_INSTANCE_NAME }}:$DEPLOY_TAR \
            --zone=${{ secrets.GCP_VM_ZONE }} \
            --project=${{ secrets.GCP_PROJECT_ID }}
      - name: Deploy, switch release, and cleanup
        env:
          RELEASE_TS: ${{ steps.release.outputs.timestamp }}
        run: |
          gcloud compute ssh ${{ secrets.GCP_VM_SA_USER }}@${{ secrets.GCP_VM_INSTANCE_NAME }} \
            --zone=${{ secrets.GCP_VM_ZONE }} \
            --project=${{ secrets.GCP_PROJECT_ID }} \
            --command="sudo chown ${{ secrets.GCP_VM_OS_USER }}:${{ secrets.GCP_VM_OS_USER }} $DEPLOY_TAR && sudo -u ${{ secrets.GCP_VM_OS_USER }} $DEPLOY_BASE/deploy.sh '$DEPLOY_BASE' '$RELEASE_TS' '$DEPLOY_TAR'"

2.2. 在 github 项目 -> Settings -> Secrets and veriables 下创建相应的 secrets​

配合 deploy.yml 示例, 提供如下 secrets:

说明：GCP_VM_SA_USER 是 GCP OS Login 为 Service Account 自动生成的用户名（格式为 sa_<OAuth2 Client ID>），用于 gcloud compute scp/ssh 登录。GCP_VM_OS_USER 是服务器上拥有部署目录权限的实际用户，deploy.sh 会通过 sudo -u 以该用户身份执行。

3. GCP 服务器端一次性配置​

3.1. 创建部署目录结构​

sudo mkdir -p /var/www/mywebsite.com/releases
sudo chown -R <deploy_user>:<deploy_user> /var/www/mywebsite.com

3.2. 部署 deploy.sh 脚本​

创建脚本 $GCP_VM_DEPLOY_BASE/deploy.sh:

#!/usr/bin/env bash
set -euo pipefail

DEPLOY_BASE="$1"
RELEASE_TS="$2"
DEPLOY_TAR="$3"

RELEASE_DIR=${DEPLOY_BASE}/releases/${RELEASE_TS}
CURRENT_LINK=${DEPLOY_BASE}/current

# Create release directory and extract archive
mkdir -p ${RELEASE_DIR}
tar -xzf $DEPLOY_TAR -C ${RELEASE_DIR}
rm -f $DEPLOY_TAR

# Atomically switch the 'current' symlink to the new release
# ln -sfn is atomic on Linux (single rename syscall)
ln -sfn ${RELEASE_DIR} ${CURRENT_LINK}

# Test nginx config
sudo /usr/sbin/nginx -t

# Reload nginx to pick up any potential config changes
sudo systemctl reload nginx

# Clean up old releases, keeping only the current and previous
cd ${DEPLOY_BASE}/releases
ls -1dt */ | tail -n +3 | xargs -r rm -rf

echo '✅ Deployment completed successfully'
echo "📦 Release: ${RELEASE_TS}"
echo "📂 Path: ${RELEASE_DIR}"
ls -la ${CURRENT_LINK}

设置脚本权限：

chmod +x /var/www/mywebsite.com/deploy.sh

3.3. 配置 sudoers​

在/etc/sudoers.d目录下为 deploy user 创建 sudoer配置文件. 比如 zhangsan_sudoers

zhangsan ALL=(root) NOPASSWD: /usr/sbin/nginx -t
zhangsan ALL=(root) NOPASSWD: /usr/sbin/nginx -s reload
zhangsan ALL=(root) NOPASSWD: /usr/bin/systemctl reload nginx

将 suders 文件的权限修改为 440

sudo chmod 440 /etc/sudoers.d/zhangsan_sudoers

---全文完---

1.1. 使用 Remote ADB Server 共享 USB设备​

1.1.1. 安装 ADB​

准备一台 Linux 系统的 PC 机, 推荐 Ubuntu 24.04 LTS, 安装 Android Debug Bridge, 推荐下载最新版https://developer.android.com/tools/releases/platform-tools:

curl -OL https://dl.google.com/android/repository/platform-tools-latest-linux.zip
unzip platform-tools-latest-linux.zip -d ./
mv platform-tools /usr/lib/android-sdk/
ln /usr/lib/android-sdk/platform-tools/adb /usr/bin/adb

1.1.2. 启动 ADB Server​

以 systemd 形式启动 ADB Server 监听在所有网络接口

cat > /etc/systemd/system/adb-server.service <<'EOF'
[Unit]
Description=ADB Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/adb -a -P 5037 nodaemon server
ExecStartPre=/usr/bin/adb kill-server
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now adb-server

1.1.3. 通过 USB 数据线连接手机到 ADB Server 所在的 Linux PC, 并开启手机的 USB Debug​

1.1.4. 在其它 PC 上通过 ADB 指令使用 ADB Server 上的设备​

1. 方式1

export ADB_SERVER_SOCKET=tcp:<ADB Server IP>:5037
adb devices

2. 方式2

adb -H <ADB Server IP> -P 5037 devices

1.2. 通过 scrcpy 投屏到电脑​

1. 下载最新的 scrcpy 3.3.3: https://github.com/Genymobile/scrcpy/releases

Linux 也可以从源码编译安装, 参考: https://github.com/Genymobile/scrcpy/blob/master/doc/linux.md

# for Debian/Ubuntu
sudo apt install ffmpeg libsdl2-2.0-0 adb wget \
                 gcc git pkg-config meson ninja-build libsdl2-dev \
                 libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev \
                 libswresample-dev libusb-1.0-0 libusb-1.0-0-dev

git clone https://github.com/Genymobile/scrcpy
cd scrcpy
./install_release.sh

2. 执行 scrcpy 并把 --tunnel-host 参数指向 ADB Server, 确保能访问 ADB Server 上的 27183 到 27199 端口, Android 手机的投屏将会显示在 scrcpy 运行的PC上

scrcpy -s <设备 ID>--tunnel-host <ADB Server IP> --tunnel-port=27183

1. 参数说明
   1. -s 参数在只有一台设备时可以省略
   2. --tunnel-host 参数指向连接手机的 ADB Server
   3. --tunnel-port 参数可以省略, 默认值是 27183
2. scrcpy 启动时，将会:
   1. 向设备 /data/local/tmp 推送 scrcpy-server. 等同指令:

adb -s <设备 ID> push scrcpy-server /data/local/tmp/scrcpy-server.jar

2. 在设备上启动 scrcpy-server, 等同指令:

adb -s <设备 ID> shell CLASSPATH=/data/local/tmp/scrcpy-server.jar app_process / com.genymobile.scrcpy.Server 3.3.3 scid=23d1ac65 log_level=info tunnel_forward=true

3. scrcpy-server 会在设备中创建unix socket, 用于 scrcpy-server与 adbd 之间的 音频/视频/控制 数据的转发:

$ cat /proc/net/unix | grep scrcpy
0000000000000000: 00000003 00000000 00000000 0001 03 1750017 @scrcpy_0801e049
0000000000000000: 00000003 00000000 00000000 0001 03 1748184 @scrcpy_0801e049
0000000000000000: 00000003 00000000 00000000 0001 03 1748188 @scrcpy_0801e049

4. 启动 scrcpy 连接 ADB 转发隧道, 获取视频流并展示在 scrcpy 客户端 PC, 并接收用户指令转发给 adb, 经 adbd 转发给设备

2. 基于 Linux gnome 创建一个手机屏幕监控​

2.1. 写脚本​

#!/usr/bin/env bash
################################################################################
# auto_scrcpy.sh - Android设备自动投屏监控脚本
#
# 功能说明：
#   - 自动检测ADB设备插拔，动态启动/停止scrcpy投屏
#   - 多设备横向排列显示，避免窗口重叠
#   - 投屏窗口意外关闭时自动重启
#   - Ctrl+C退出时自动清理所有进程，无残留
#
# 使用方法：
#   chmod +x auto_scrcpy.sh
#   ./auto_scrcpy.sh
#   (按 Ctrl+C 停止)
#
# 环境要求：
#   - 已安装 adb 和 scrcpy
#   - Android设备开启USB调试并连接
#
# 配置参数：
#   X_OFFSET=40           # 窗口水平间距(px)
#   Y_OFFSET=60           # 窗口垂直起始位置(px)
#   WINDOW_WIDTH=428      # 窗口宽度(px)
#   RECHECK_INTERVAL=2    # 设备检测间隔(秒)
#
################################################################################

X_OFFSET=40
Y_OFFSET=60
WINDOW_WIDTH=428
RECHECK_INTERVAL=2

declare -A MON_PID        # 监控器进程 PID: MON_PID[$serial]=pid

calc_x() {
    local idx=$1
    echo $(( X_OFFSET*(idx+1) + WINDOW_WIDTH*idx ))
}

# 检查进程是否存活
is_process_alive() {
    local pid=$1
    kill -0 "$pid" 2>/dev/null
    return $?
}

# 获取设备在当前列表中的索引
get_device_index() {
    local serial=$1
    local -n arr=$2
    for i in "${!arr[@]}"; do
        if [ "${arr[$i]}" == "$serial" ]; then
            echo $i
            return
        fi
    done
    echo -1
}

# 启动单个设备的监控器（后台）
start_monitor_for() {
    local serial=$1
    local idx=$2

    # 检查是否已经有存活的监控器
    if [ -n "${MON_PID[$serial]}" ]; then
        if is_process_alive "${MON_PID[$serial]}"; then
            echo "[MAIN] monitor for $serial already running (pid ${MON_PID[$serial]})"
            return
        else
            echo "[MAIN] cleaning stale monitor pid ${MON_PID[$serial]} for $serial"
            unset MON_PID["$serial"]
        fi
    fi

    # 先计算好X坐标
    local x_pos=$(calc_x $idx)

    # 监控器脚本体
    (
        setsid bash -c -- "
            while true; do
                X=$x_pos
                Y=$Y_OFFSET
                echo \"[MONITOR][$serial] start scrcpy at \$X,\$Y (index=$idx)\"
                scrcpy -s \"$serial\" --window-x=\$X --window-y=\$Y &
                child=\$!
                echo \$child > /tmp/auto_scrcpy_${serial}.pid
                wait \$child
                echo \"[MONITOR][$serial] scrcpy (\$child) exited, restart after 1s\"
                rm -f /tmp/auto_scrcpy_${serial}.pid
                sleep 1
            done
        "
    ) &
    local mpid=$!
    MON_PID["$serial"]=$mpid
    echo "[MAIN] started monitor for $serial (pid $mpid, X=$x_pos)"
}

# 停止单个设备监控
stop_monitor_for() {
    local serial=$1
    local mpid=${MON_PID[$serial]}
    if [ -z "$mpid" ]; then
        return
    fi

    echo "[MAIN] stopping monitor for $serial (monitor pid $mpid)"

    # 1) 杀 scrcpy 子进程
    local pidfile="/tmp/auto_scrcpy_${serial}.pid"
    if [ -f "$pidfile" ]; then
        childpid=$(cat "$pidfile" 2>/dev/null)
        if [ -n "$childpid" ] && is_process_alive "$childpid"; then
            echo "[MAIN] killing scrcpy pid $childpid for $serial"
            kill $childpid 2>/dev/null || true
            sleep 0.2
            kill -9 $childpid 2>/dev/null || true
        fi
        rm -f "$pidfile"
    fi

    # 2) 杀 monitor 的所有子进程（包括孤儿进程）
    pchildren=$(pgrep -P $mpid 2>/dev/null || true)
    if [ -n "$pchildren" ]; then
        echo "[MAIN] killing child processes of monitor $mpid: $pchildren"
        for c in $pchildren; do
            kill $c 2>/dev/null || true
            sleep 0.05
            kill -9 $c 2>/dev/null || true
        done
    fi

    # 3) 杀 monitor 本身（使用进程组杀死，确保 setsid 创建的会话也被清理）
    if is_process_alive "$mpid"; then
        # 获取进程组ID并杀死整个组
        pgid=$(ps -o pgid= -p $mpid 2>/dev/null | tr -d ' ')
        if [ -n "$pgid" ]; then
            echo "[MAIN] killing process group $pgid for monitor $mpid"
            kill -- -$pgid 2>/dev/null || true
            sleep 0.2
            kill -9 -- -$pgid 2>/dev/null || true
        fi
        # 再单独杀 monitor 进程
        kill $mpid 2>/dev/null || true
        sleep 0.1
        kill -9 $mpid 2>/dev/null || true
    fi

    unset MON_PID["$serial"]
    rm -f /tmp/auto_scrcpy_${serial}.pid
}

# 彻底停止并清理所有
stop_all() {
    echo "[MAIN] stopping all monitors..."
    for s in "${!MON_PID[@]}"; do
        stop_monitor_for "$s"
    done

    # 额外清理：查找所有可能残留的 scrcpy 进程
    echo "[MAIN] cleaning up any remaining scrcpy processes..."
    pkill -f "scrcpy -s" 2>/dev/null || true

    # 清理所有临时文件
    rm -f /tmp/auto_scrcpy_*.pid

    MON_PID=()
}

# 读取设备列表并倒序
get_device_array() {
    local -n out=$1
    mapfile -t out < <(adb devices | awk 'NR>1 && $2=="device"{print $1}' | tac)
}

# 捕获退出信号，确保清理所有进程
cleanup_on_exit() {
    echo ""
    echo "[MAIN] received exit signal, cleaning up..."
    stop_all
    echo "[MAIN] cleanup complete, exiting"
    exit 0
}

# 注册信号处理
trap cleanup_on_exit SIGINT SIGTERM EXIT

# 主循环
declare -a last_devices=()

echo "[MAIN] auto_scrcpy monitor started"
echo "[MAIN] press Ctrl+C to stop"

while true; do
    sleep $RECHECK_INTERVAL
    declare -a cur_devices=()
    get_device_array cur_devices

    # 构建设备集合
    declare -A set_last=()
    declare -A set_cur=()
    for d in "${last_devices[@]}"; do set_last["$d"]=1; done
    for d in "${cur_devices[@]}"; do set_cur["$d"]=1; done

    # 处理移除的设备
    for d in "${last_devices[@]}"; do
        if [ -z "${set_cur[$d]}" ]; then
            echo "[EVENT] device removed: $d"
            stop_monitor_for "$d"
        fi
    done

    # 处理新增的设备
    for d in "${cur_devices[@]}"; do
        if [ -z "${set_last[$d]}" ]; then
            echo "[EVENT] device added: $d"
            idx=$(get_device_index "$d" cur_devices)
            if [ $idx -ge 0 ]; then
                start_monitor_for "$d" "$idx"
                sleep 0.2
            fi
        fi
    done

    # 更新设备列表
    last_devices=("${cur_devices[@]}")
done

chmod 755 /opt/screen-manager/auto_scrcpy.sh

2.2. 创建桌面登录后启动项​

cat > ~/.config/autostart/scrcpy-manager.desktop <<EOF
[Desktop Entry]
Type=Application
Name=SCRCPY Manager
Exec=/opt/screen-manager/auto_scrcpy.sh
X-GNOME-Autostart-enabled=true
EOF

3. 基于 SSH 的加密端口转发共享屏幕​

参考: https://github.com/Genymobile/scrcpy/blob/master/doc/tunnels.md

先来了解一下 scrcpy 基于 adb 的数据转发方式:

======================== CONTROL FLOW ========================
      PC (adb client)
          |  TCP connect to PC:5037
          v
      PC (adb server :5037)
          |  USB ADB protocol
          v
      手机 (adbd)
          |  ADB internal socket
          v
      手机 (scrcpy-server)
==============================================================

======================== VIDEO FLOW ==========================
      手机 (scrcpy-server)
          |  localabstract:scrcpy  (video source)
          v
      手机 (adbd)
          |  via USB (adb reverse)
          v
      PC (adb server listens on :27183)
          | TCP forwarding (your network)
          v
      PC (scrcpy client: connects to 27183)
==============================================================

3.1. 环境​

1. PC1 环境: 启动了 adb server: adb start-server, USB连接了手机
2. PC2 环境: ADB client, scrcpy

3.2. 步骤​

3.2.1. 隧道方式1:​

1. 在 PC2 上执行 ssh, 建立到 PC1的 隧道:

ssh -CN -L5037:localhost:5037 -R27183:localhost:27183 root@<PC1 IP>

作用:

• 在本地打开一个 5037 → 远程 5037 的正向转发
• 在远程打开一个 27183 → 本地 27183 的反向转发

2. 在 PC2 上启动客户端, 可直接投屏呈现手机屏幕:

scrcpy

3.2.2. 隧道方式2：​

1. 在 PC2 上执行

ssh -CN -L5037:localhost:5037 -L27183:localhost:27183 root@<PC1 IP>

作用:

• 在本地打开一个 5037 → 远程 5037 的正向转发
• 在本地打开一个 27183 → 远程 27183 的正向转发

2. 在 PC2 上 添加 --force-adb-forward 参数启动 scrcpy 客户端, 可直接投屏呈现手机屏幕:

scrcpy --force-adb-forward

4. 通过 Sonic Server 管理手机和 Web 投屏​

4.1. 开发编译环境搭建​

4.1.1. Sonic Server​

4.1.1.1. Install JDK and Maven​

sudo apt install openjdk-17-jdk -y
java --version
sudo apt install maven -y
mvn --version

4.1.1.2. 调试运行​

下载源码, 进入源码根目录

git clone git@github.com:ylhyh/sonic-server.git
cd sonic-server

开发环境启动 eureka

cd sonic-server-eureka
mvn spring-boot:run -DSONIC_VERSION=2.7.3

开发环境启动 controller

cd sonic-server-controller
# 配置数据库
export MYSQL_HOST=172.16.126.26
export MYSQL_DATABASE=sonic
export MYSQL_PORT=3306
export MYSQL_USERNAME=sonic
export MYSQL_PASSWORD=xxxxxx

mvn spring-boot:run -DSONIC_VERSION=2.7.3

开发环境启动 gateway

cd sonic-server-gateway
mvn spring-boot:run -DSONIC_VERSION=2.7.3

4.1.1.3. 编译打包安装​

mvn clean install -Dplatform=linux-x86_64 -DskipTests -DSONIC_VERSION=2.7.3

4.1.1.4. 构建 Docker 镜像​

cd sonic-server
docker build -t ylhyh/sonic-server-folder:v2.7.3 -f sonic-server-folder/src/main/docker/Dockerfile .
docker build -t ylhyh/sonic-server-gateway:v2.7.3 -f sonic-server-gateway/src/main/docker/Dockerfile .
docker build -t ylhyh/sonic-server-eureka:v2.7.3 -f sonic-server-eureka/src/main/docker/Dockerfile .
docker build -t ylhyh/sonic-server-controller:v2.7.3 -f sonic-server-controller/src/main/docker/Dockerfile .

4.1.2. Sonic Web​

4.1.2.1. 安装 nvm npm​

安装 npm 18

nvm install 18

4.1.2.2.调试运行​

git clone git@github.com:ylhyh/sonic-client-web.git
cd sonic-client-web
nvm use 18
nvm alias default 18
npm install
npm run dev

4.1.2.3. 编译打包​

cd sonic-client-web
npm run build

4.1.2.4. 构建 Docker 镜像​

cd sonic-client-web
docker build -t ylhyh/sonic-client-web:v2.7.3 .

4.1.3. Sonic Agent​

4.1.3.1. 调试运行​

git clone git@github.com:ylhyh/sonic-agent.git
cd sonic-agent
mvn spring-boot:run -DSONIC_VERSION=2.7.3

4.1.3.2. 编译 jar 包并运行​

mvn clean package -Dplatform=linux-x86_64 -DskipTests -DSONIC_VERSION=2.7.3
java -Dfile.encoding=utf-8 -jar sonic-agent-linux-x86_64.jar

4.2. 部署​

4.2.1. 服务端部署​

参考: https://github.com/ylhyh/sonic-server/blob/main/k8s-all-in-one.md

4.2.2. Agent 部署​

1. 配置 sonic-agent service

cat > /etc/systemd/system/sonic-agent.service <<'EOF'
[Unit]
Description=Sonic Agent Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

# 使用 root 用户（设备管理需要）
User=root
Group=root
WorkingDirectory=/opt/sonic-agent
ExecStart=/usr/bin/java -Dfile.encoding=utf-8 -Xms512m -Xmx1024m -jar /opt/sonic-agent/sonic-agent-linux-x86_64.jar

# 重启策略
Restart=on-failure
RestartSec=10
StartLimitInterval=300
StartLimitBurst=5

# 资源限制
LimitNOFILE=65536

# 超时
TimeoutStartSec=90

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now sonic-agent

4.2.3. Android 设备 -> 在 Agent 上 配置 ADB Server​

4.2.4. iOS 设备 -> 在 Agent 上配置 usbmuxd​

1. 安装 usbmuxd

sudo apt install usbmuxd libimobiledevice-utils -y

2. 在 Agent 所在 PC 上通过 USB 连接 iOS 手机, 在手机弹窗中选择信任该电脑
3. 运行 agent 包中的 sonic-ios-bridge (sib) 查看 USB 中的 iOS 设备

/opt/sonic-agent/plugins/sonic-ios-bridge devices

iOS手机的投屏需要通过 macOS + 开发者账号在手机中安装 WebDriverAgent

5. 其它投屏玩法: 通过 X11 转发手机屏幕​

前提: 有 ADB Server 的 ssh 权限

# 在客户端上通过 SSH X11转发连接
ssh -X root@172.16.136.98
# SSH到 ADB Server上执行
scrcpy

6. 附录​

6.1. Scrcpy 使用小技巧​

1. 打开手机摄像头录制视频到文件

 scrcpy --video-source=camera --video-codec=h265 --camera-size=1920x1080 --record=file.mp4