DOCS / 使用指南

使用说明

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

这些文档,其实可以不看

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

1装上
自己下载安装
或者把这段话发给你的 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 最新版里:

  • macOS:Apple 芯片(M1 及以后)下 Gerdr-x.y.z-mac-arm64.dmg,Intel 下 mac-x64.dmg,拖进「应用程序」。第一次打开提示「无法验证开发者」的话,在 Finder 里右键 → 打开。
  • Windows:下 windows-x64-setup.exe。安装包没签名,SmartScreen 拦的话点「更多信息 → 仍要运行」。
  • 安卓:下 android.apk。它连的是你自己电脑上的 Gerdr,要先配好远程访问。
  • 浏览器:装了命令行以后,任何浏览器都能打开(见下一步)。
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 照你的想法搭出来,或者装别人做好的。

详细看看 →
手机上接着管

出门了用手机打开同一个 Gerdr:看进度、插话、点审批。安卓 App 在家时走局域网直连,还能收后台通知。

详细看看 →
界面让 agent 改

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

插件、skill、MCP

插件商店一键装(额度条、今日花费、常用短语、Slack 接入……);skill 和 MCP 可以全局配,也可以只给某个项目。

详细看看 →
外面的事 agent 也知道

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

多台电脑一起管

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

04

自定义面板

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

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

三种方式得到一个面板

01
让助手从空白开始搭

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

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

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

02
装别人做好的

同一个 + 里有推荐列表,点一下就装;也可以粘贴任意 GitHub 仓库地址。别人发布的面板在 GitHub 上都带 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,在推荐列表里一键装。

05

手机和远程

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

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

第一次要先把这台电脑接上中继,步骤见 README 的「远程访问」。不想用中继,看下面的「直接访问」。

直接访问:用 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

更多

Render diagnostics