# 使用说明 · Gerdr

> Gerdr 怎么装、怎么用、能做什么：安装 Claude Code / Codex 的图形界面，同时管一群 agent，自己做面板，手机上远程接着管。

目录

- [01安装](#install)
- [02上手](#start)
- [03能做什么](#features)
- [04自定义面板](#panels)
- [05手机和远程](#remote)
- [06快捷键](#keys)
- [07更多](#more)

DOCS / 使用指南

# 使用说明

Gerdr 是 Claude Code / Codex 的图形界面：一个窗口同时管一群 agent，谁在干活、谁在等你一眼就知道，出门了用手机接着管。免费、开源。

这些文档，其实可以不看

你只需要把 Gerdr 装上，装也可以交给 AI。装好之后，想配什么、想用什么功能， **直接在 Gerdr 里问 agent**：它知道 Gerdr 的每一项设置和功能，会直接帮你改好。

1装上

[自己下载安装](#install)

或者把这段话发给你的 Claude Code / Codex，让它帮你装：

帮我在这台电脑上装好 Gerdr（https://github.com/gerdr-dev/gerdr）：看它 README 的安装说明，挑适合我系统的安装包下载、装好并打开。Claude Code 或 Codex 没装、没登录的话也帮我装上，登录那一步告诉我怎么做。

复制这段话

2剩下的，直接问

在 Gerdr 里跟任何一个 agent 说，比如：

换成深色主题装上额度条插件给这个项目做一个周报面板再加一个 Claude 账号把前缀键改成 ctrl+a

01

## 安装

01

先装好你要用的 agent

Gerdr 不自带模型，用的是你电脑上的 Claude Code、Codex。装好之后各登录一次：

```
curl -fsSL https://claude.ai/install.sh | bash   # Claude Code，装完跑一次 claude 登录
npm i -g @openai/codex                           # Codex，装完跑 codex login
```

只想用 GPT、DeepSeek 等模型的 API 也行：Gerdr 自带一个 Gerdr Agent，在设置里填上接口地址和 key 就能用。

02

下载 Gerdr

全部在 [GitHub Releases](https://github.com/gerdr-dev/gerdr/releases/latest) 最新版里：

- **macOS：** Apple 芯片（M1 及以后）下 `Gerdr-x.y.z-mac-arm64.dmg`，Intel 下 `mac-x64.dmg`，拖进「应用程序」。第一次打开提示「无法验证开发者」的话，在 Finder 里右键 → 打开。
- **Windows：** 下 `windows-x64-setup.exe`。安装包没签名，SmartScreen 拦的话点「更多信息 → 仍要运行」。
- **安卓：** 下 `android.apk`。它连的是你自己电脑上的 Gerdr，要先配好 [远程访问](#remote)。
- **浏览器：** 装了命令行以后，任何浏览器都能打开（见下一步）。

03

打开

桌面 App 直接打开就行。也可以用命令行起服务，在浏览器里用：

```
gerdr            # 起服务，打印一个带令牌的链接
gerdr --open     # 起服务并打开浏览器
gerdr url        # 再拿一次登录链接
```

App 和命令行可以同时用，看到的是同一份会话。mac 上在「设置 → 通用」打开「后台常驻」，⌘Q 退出 App 以后 agent 也照跑。

02

## 上手

- **开一个会话：** 选 agent、选目录，开始。下面会列出这个目录里以前的会话（包括在终端里开过的 Claude Code / Codex），点一下接着聊。
- **说话：** 回车发送，Shift+回车换行；输入 / 出斜杠命令；图片可以直接粘贴或拖进来。
- **中途插话、打断：** agent 干活时照样发消息，会插进正在跑的那一轮；Esc 打断。
- **审批和提问是卡片：** 批命令、批改文件、回答选择题，点一下就行。
- **回退：** 鼠标移到自己说过的话上点 ↺，回到这句之前，原话放回输入框，改了再发。只退对话，不恢复文件。
- **分屏：** 按 `ctrl+b` 松开再按 `v` 左右分屏、 `-` 上下分屏，每一格放一个 agent。哪个在等你，侧栏和格子上都有标记，按 `ctrl+b`  `o` 直接跳过去。
- **终端：** `ctrl+b`  `t` 在旁边开一个，跟着当前目录；刷新页面、换到手机上都还在。

03

## 能做什么

一个窗口，管一群 agent

分屏、tab、工作空间，开十几个也不乱。谁在干活、谁在等你一眼就知道，一个键跳过去。用过 herdr 的话，快捷键一样，布局能直接导进来。

agent 之间互相派活

agent 能自己开新会话、交代任务、等回复、读结果。比如 Claude 改页面，同时让 Codex 去画图，画好了自动回报。

图、视频、PDF 直接看

agent 给的图片、视频、PDF 在对话里就能看，点一下文件路径就打开，不用切出去找。

不止 Claude 和 Codex

同一个 agent 可以挂多个账号并排用，额度用完换一个接着聊；能接任意 ACP agent（Gemini CLI、OpenCode……），也能直接调 GPT / DeepSeek / Claude 的 API。

[自定义面板\
\
每个项目除了写代码，还能有自己的面板：看板、日报、数据台……面板是一整套页面加上它自己的助手，让 agent 照你的想法搭出来，或者装别人做好的。\
详细看看 →](#panels) [手机上接着管\
\
出门了用手机打开同一个 Gerdr：看进度、插话、点审批。安卓 App 在家时走局域网直连，还能收后台通知。\
详细看看 →](#remote)

界面让 agent 改

Gerdr 的界面是源码，想加按钮、快捷键、显示什么，直接跟 agent 说，保存就生效，不用发版。改坏了有改不坏的急救面板。

[插件、skill、MCP\
\
插件商店一键装（额度条、今日花费、常用短语、Slack 接入……）；skill 和 MCP 可以全局配，也可以只给某个项目。\
详细看看 →](/zh/addons.md)

外面的事 agent 也知道

MR 评论、流水线结束、聊天消息都记成「事件」，面板和会话可以订阅，回复能原路发回去。

多台电脑一起管

在这台电脑上用另一台的 Gerdr：在那边开会话、看终端、读文件，把对话挪过去接着聊。

04

## 自定义面板

每个项目左边的窄条上，除了 **Code**（写代码的工作区），还可以放几个 **面板**。一个面板就是一个小应用：左边是它的页面，右边是它自己的助手。页面上的按钮会把任务交给助手去做，比如「把这周的进度写成周报」。

一个面板里有什么

- **页面：** 普通的 React 页面，没有打包环节，改了立刻刷新；手机上也能用。
- **本地函数：** 在你电脑上跑的代码，读文件、调接口、开新的 agent 会话都行，页面上的按钮调它们。
- **助手的做法：** 写在面板的 skill 里，用你自己的话说清楚活该怎么干，助手照着做。
- **定时和触发：** 每天几点跑一次，或者 MR 来了评论、聊天里有人 @ 你时自动接着干。
- **自己的数据和设置：** 存在面板目录里，更新面板也不会动它们。

### 三种方式得到一个面板

01

让助手从空白开始搭

点窄条上面板按钮下面的 **+** →「新建空白面板」，然后直接跟右边的助手说你要什么，例如：

做一个看板，列出这个项目所有在跑的 agent 和它们在干什么，卡住的标红，点一下就跳过去。

它写页面、写函数，你在左边马上看到效果，不满意接着说。

02

装别人做好的

同一个 **+** 里有推荐列表，点一下就装；也可以粘贴任意 GitHub 仓库地址。别人发布的面板在 GitHub 上都带 [gerdr-panel](https://github.com/topics/gerdr-panel) 标签。装好的面板能更新，你自己的改动和数据留着。

03

让 agent 用命令行装

agent 能做的和你在界面上能做的一样，跟它说一声就行。它用的是这些命令：

```
gerdr panel install owner/repo     # 装一个发布在 GitHub 上的面板
gerdr panel new 周报                # 新建空白面板
gerdr panel update                 # 更新
gerdr panel icon 周报 kanban        # 换图标
```

例子：Superagent 看板

一个替你派活的面板：把任务写成卡片，它开 agent 去做、盯进度，做完、卡住或者需要你拍板时告诉你。代码在 [gerdr-dev/gerdr-panel-superagent](https://github.com/gerdr-dev/gerdr-panel-superagent)，在推荐列表里一键装。

05

## 手机和远程

从外面访问走云端中继：加密一直到你自己的电脑，中继只转密文。新设备第一次用 **配对码** 进来（只有坐在电脑前的人能出），之后加一把 **passkey**，以后换设备也不用回电脑前。

- **配对：** 设置 →「远程访问」→ 出一个配对码，手机扫码就进来了。码 5 分钟内有效，只能用一次。
- **passkey：** 在手机打开的 Gerdr 里，设置 →「远程访问」→ 加一把 passkey。
- **踢掉设备：** 设置里点「踢掉」，或者 `gerdr remote revoke`。
- **安卓 App：** 和网页同一套界面，在家时局域网直连更快，还能收后台通知。

第一次要先把这台电脑接上中继，步骤见 README 的 [「远程访问」](https://github.com/gerdr-dev/gerdr/blob/main/README.zh-CN.md#远程访问手机--别的电脑)。不想用中继，看下面的「直接访问」。

### 直接访问：用 Tailscale 或 frp，不走中继

Gerdr 只负责在一个端口（默认 7878）上用你域名的证书对外，配对码、passkey 的规则和中继一样；手机怎么连到这台电脑，交给你自己的网络。证书照样要（passkey 只在 HTTPS 下能用），但签证书走 DNS，不需要公网连得到你的电脑。

#### 用 Tailscale（什么都不暴露到公网）

01

两边都装上 Tailscale

电脑和手机都装 Tailscale，登进同一个账号。

02

在 Gerdr 里开直接访问

设置 →「远程访问」→「直接访问」：填你的域名（比如 `gerdr.example.com`），「地址里的端口」留空，连接。然后在下面「证书」里选你的 DNS 服务商、填 API 凭据，证书会自己签、自己续。

不想点界面，也可以在电脑的终端里跑一条命令，效果和上面完全一样（写好配置，正在跑的 Gerdr 立刻生效；让 agent 帮你配时它也用这个）：

```
gerdr remote direct gerdr.example.com \
  --dns cloudflare \
  --env CLOUDFLARE_DNS_API_TOKEN=你的令牌
```

03

加一条 DNS 记录

A 记录： `gerdr.example.com → 100.x.y.z`，也就是这台电脑的 Tailscale 地址（设置页里会显示）。只有你 Tailscale 里的设备连得到这个地址。

04

手机上打开

手机开着 Tailscale，打开 `https://gerdr.example.com:7878`，扫配对码进来。安卓 App 里填同一个地址。

为什么不用别的设置就能连上：域名本身指向的就是 Tailscale 里的地址，而手机上的 Tailscale 是系统级 VPN，浏览器和 App 发出去的连接都会经它到你的电脑。反过来，手机上 Tailscale 关着时这个地址就打不开（安卓 App 在家里还能走局域网）。地址里带 `:7878`，是因为 macOS 不让普通程序在具体地址上占 443 端口。

#### 用 frp 或路由器端口转发

「直接访问」里「地址里的端口」填 `443`（用命令的话，在上面那条命令后面加 `--url-port 443`），A 记录指向 frps 那台机器（或你的公网 IP），地址就是 `https://gerdr.example.com`。frps 要有 `vhostHTTPSPort = 443`，frpc 里加：

```
[[proxies]]
name = "gerdr"
# 原样转 TLS，别用 https2http 插件
type = "https"
customDomains = ["gerdr.example.com"]
localIP = "127.0.0.1"
localPort = 7878
# 可选：让 Gerdr 看到真实来源 IP
transport.proxyProtocolVersion = "v2"
```

- **防火墙：** macOS 第一次可能问是否允许 Gerdr 接受传入连接，要点允许，不然手机连不进来，也没有任何报错。
- **安卓 App 的 passkey：** 地址带端口时 App 里不能直接刷 passkey（安卓只去 443 核对 App），登录会转到浏览器批准；也可以在电脑上「设置 → 远程访问 → 批准 App 登录」输码。

06

## 快捷键

和 tmux / herdr 一样：先按 `ctrl+b`，松开，再按下表里的键。开着中文输入法也能用；全部可以在「设置 → 快捷键」里改。

|     |     |
| --- | --- |
| v / - | 左右 / 上下分屏 |
| h j k l 或方向键 | 切换格子 |
| z | 放大 / 还原当前格子 |
| x | 关掉当前格子 |
| o | 跳到在等你的会话 |
| u / d | 上一个 / 下一个要你处理的会话 |
| c / n / p | 新 tab / 下一个 / 上一个 |
| 1 … 9 | 跳到第几个 tab |
| shift+n / w | 新工作空间 / 切工作空间 |
| g | 会话列表 |
| t | 开终端 |
| : 或 ⌘K | 命令面板 |
| ? | 全部快捷键 |

07

## 更多

- **完整说明：** [GitHub 上的 README](https://github.com/gerdr-dev/gerdr/blob/main/README.zh-CN.md)，包括配置项、环境变量、从源码构建。
- **HTTP 接口：** 脚本、手环这类程序想看会话、发消息、点审批，见 [docs/API.md](https://github.com/gerdr-dev/gerdr/blob/main/docs/API.md)。
- **插件：** [插件商店里有什么、怎么自己写一个](/zh/addons.md)。
- **每个版本改了什么：** [更新记录](/zh/changelog.md)。
- **遇到问题：** 在 [GitHub Issues](https://github.com/gerdr-dev/gerdr/issues) 提。

> 全站页面清单：[/llms.txt](/llms.txt)
