WaveTerm：让 AI 编程助手住进你的终端

WaveTerm：让 AI 编程助手住进你的终端

如果你同时在用 Claude Code、Codex、OpenCode 等 AI 编程智能体，一定会遇到一个问题：开了一堆终端窗口，哪个在等输入、哪个跑完了、哪个卡住了，根本分不清。

WaveTerm（Wave Terminal）就是为解决这个问题而生的。它是一个开源的、AI 原生终端，可以在 macOS、Linux 和 Windows 上运行，天然支持多智能体并行工作流。

安装

Windows

从 GitHub Releases 页面下载安装包：

https://github.com/wavetermdev/waveterm/releases

下载 .exe 安装包，双击安装即可。

macOS

brew install --cask waveterm

Linux

# Debian/Ubuntu
sudo dpkg -i waveterm_*.deb

# Fedora
sudo rpm -i waveterm_*.rpm

Windows 用户必做：设置 Git Bash

Windows 上 WaveTerm 默认使用 PowerShell。如果你习惯 Git Bash（大部分 AI 智能体的脚本都基于 bash），需要手动配置：

wsh setconfig term:gitbashpath="C:\Program Files\Git\bin\bash.exe"

这个命令告诉 WaveTerm 用 Git Bash 替代默认 Shell。如果你的 Git 安装路径不同，改成对应的路径即可。

验证是否生效：重启 WaveTerm，在终端里输入 echo $SHELL，如果输出包含 bash 就说明配置成功。

wsh 命令速查

wsh 是 WaveTerm 的核心命令行工具，能让你的终端命令和 Wave 的图形界面互相通信。以下是常用命令：

配置管理

# 设置配置项
wsh setconfig <key>="<value>"

# 编辑配置文件（用内置编辑器打开）
wsh editconfig

# 查看当前主题
wsh setconfig term:theme

常用配置项：

配置键 说明 示例
term:gitbashpath Windows Git Bash 路径 "C:\\Program Files\\Git\\bin\\bash.exe"
term:theme 终端主题 dracula, default-dark
waveai:defaultmode AI 默认模式 "my-proxy"
waveai:showcloudmodes 是否显示云端模式 false

文件操作

# 在编辑器中打开文件
wsh edit <filepath>

# 查看文件信息
wsh file info <filepath>

# 读写文件
wsh file cat <filepath>
wsh file write <filepath> "内容"

# 远程文件操作（在远程机器上访问本地文件）
wsh file cat wsh://local/~/config/app.json

界面控制

# 设置当前 block 的背景图
wsh setbg <image_url_or_path>

# 设置 Tab 徽章（Badge）
wsh badge <icon> --color '<color>' --priority <num> [--beep]

# 清除徽章
wsh badge clear

# 发送系统通知
wsh notify "任务完成！"

Block 管理

# 在新 block 中运行命令（完成后自动关闭）
wsh run <command>

# 删除当前 block
wsh deleteblock

# 列出所有 blocks
wsh blocks list

连接管理

# SSH 连接
wsh ssh user@hostname

# WSL 连接（Windows）
wsh wsl

# 查看连接状态
wsh conn status

其他实用命令

# 设置/获取变量
wsh setvar <key> "<value>"
wsh getvar <key>

# 获取 Wave 安装路径
wsh wavepath

# 重新安装 wsh 扩展
wsh reinstall

结合 Claude Code 使用

这是 WaveTerm 最强大的场景。当你在 WaveTerm 中并行跑多个 Claude Code 会话时，WaveTerm 的 Badge 系统可以让你一眼看出哪个会话需要关注。

配置 Tab Badge

编辑 ~/.claude/settings.json，添加 hooks：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "wsh badge bell-exclamation --color '#e0b956' --priority 20 --beep"
          }
        ]
      },
      {
        "matcher": "elicitation_dialog",
        "hooks": [
          {
            "type": "command",
            "command": "wsh badge message-question --color '#e0b956' --priority 20 --beep"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wsh badge check --color '#58c142' --priority 10"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          {
            "type": "command",
            "command": "wsh badge message-question --color '#e0b956' --priority 20 --beep"
          }
        ]
      }
    ]
  }
}

配置完成后效果：

事件 Badge 图标 颜色 优先级 含义
需要权限审批 bell-exclamation 金色 20 Claude Code 在等你批准操作
询问用户 message-question 金色 20 Claude Code 在等你回答问题
会话完成 check 绿色 10 任务跑完了

当你在 WaveTerm 中开了 5 个 Claude Code Tab，一眼就能看到：

  • 金色感叹号 = 快去看看，卡住了
  • 绿色勾 = 已完成，有空再看
  • 什么都没有 = 还在跑，不用管

Badge 在你点击进入 Tab 后自动清除，纯粹的"提醒"信号。

自定义更多 Badge

你可以为任何 Claude Code 工具添加 Badge 提示：

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "wsh badge spinner --color '#00FFDB' --priority 5"
    }
  ]
}

可用的图标名来自 Font Awesome（去掉 fa- 前缀），颜色支持任何 CSS 颜色值。

结合 OpenAI Codex 使用

OpenAI Codex 同样是终端内运行的 AI 智能体，在 WaveTerm 中使用时可以：

# 在 WaveTerm 中直接启动 Codex
codex "帮我重构这个函数"

如果你同时跑 Claude Code 和 Codex，建议在 WaveTerm 中分不同 Tab 组织：

  • Tab 1: Claude Code（前端开发）
  • Tab 2: Codex（后端开发）
  • Tab 3: 测试/构建

每个 Tab 独立运行，互不干扰。

结合 OpenCode 使用

OpenCode 是另一个流行的终端 AI 工具，同样可以在 WaveTerm 中运行：

# 启动 OpenCode
opencode

# 或指定模型
opencode run "分析这段代码的性能问题" --model zhipuai-coding-plan/glm-4.7

多智能体并行工作流实战

场景：同时用 3 个智能体开发一个功能

  1. Tab 1 — Claude Code 做前端 UI
claude "实现用户登录页面，使用 React + TailwindCSS"
  1. Tab 2 — Codex 写后端 API
codex "创建 POST /api/login 接口，JWT 认证"
  1. Tab 3 — OpenCode 做代码审查
opencode run "审查 src/auth/ 目录下的所有文件，输出安全风险报告"

在 WaveTerm 中，三个 Tab 并行运行。Badge 系统让你随时知道谁在等你、谁完成了。点击有金色 Badge 的 Tab 处理完，继续做别的事。

高级技巧

远程开发：用 wsh ssh 连接远程服务器，在远程机器上运行 AI 智能体，同时 Badge 依然在本地显示。

# 连接远程服务器
wsh ssh user@your-server

# 在远程服务器上运行 Claude Code
claude "部署这个应用到 Kubernetes"

文件桥接：在远程机器上访问本地文件：

# 远程机器上读取本地配置
wsh file cat wsh://local/~/project/config.yaml

自动通知：长时间任务完成后通知你：

# 在智能体命令后面追加通知
claude "跑完整测试套件" && wsh notify "测试完成！"

常见问题

Q: Windows 上打开 WaveTerm 闪退？

检查 Git Bash 路径是否正确：

wsh setconfig term:gitbashpath="C:\Program Files\Git\bin\bash.exe"

Q: Claude Code Badge 不显示？

确认 ~/.claude/settings.json 中的 hooks 格式正确，然后重启 Claude Code 会话。

Q: 主题怎么换？

# 切换 Dracula 主题
wsh setconfig term:theme dracula

# 恢复默认
wsh setconfig term:theme default-dark

Q: 如何配置 AI 模型？

# 使用自定义 OpenAI 兼容 API
wsh setconfig waveai:defaultmode="my-proxy"

# 隐藏官方云端模式（只用自建 API）
wsh setconfig waveai:showcloudmodes=false

然后用 wsh editconfig 打开配置文件，编辑 API 地址和密钥。

总结

WaveTerm 的核心价值：

  • 多智能体并行：一个窗口管理 Claude Code、Codex、OpenCode 等多个 AI 助手
  • Badge 通知系统：一眼看出哪个智能体在等你，不用逐个切换检查
  • wsh 命令体系：打通终端命令和图形界面，文件桥接、远程操作一体化
  • 开源免费：跨平台，支持 macOS、Linux、Windows

如果你每天都在和多个 AI 编程助手打交道，WaveTerm 值得一试。

项目地址：https://github.com/wavetermdev/waveterm
官方文档：https://docs.waveterm.dev

Views: 1