使用说明
Gerdr 是 Claude Code / Codex 的图形界面:一个窗口同时管一群 agent,谁在干活、谁在等你一眼就知道,出门了用手机接着管。免费、开源。
你只需要把 Gerdr 装上,装也可以交给 AI。装好之后,想配什么、想用什么功能,直接在 Gerdr 里问 agent:它知道 Gerdr 的每一项设置和功能,会直接帮你改好。
帮我在这台电脑上装好 Gerdr(https://github.com/gerdr-dev/gerdr):看它 README 的安装说明,挑适合我系统的安装包下载、装好并打开。Claude Code 或 Codex 没装、没登录的话也帮我装上,登录那一步告诉我怎么做。
安装
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 就能用。
全部在 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,要先配好远程访问。 - 浏览器:装了命令行以后,任何浏览器都能打开(见下一步)。
桌面 App 直接打开就行。也可以用命令行起服务,在浏览器里用:
gerdr # 起服务,打印一个带令牌的链接 gerdr --open # 起服务并打开浏览器 gerdr url # 再拿一次登录链接
App 和命令行可以同时用,看到的是同一份会话。mac 上在「设置 → 通用」打开「后台常驻」,⌘Q 退出 App 以后 agent 也照跑。
上手
- 开一个会话:选 agent、选目录,开始。下面会列出这个目录里以前的会话(包括在终端里开过的 Claude Code / Codex),点一下接着聊。
- 说话:回车发送,Shift+回车换行;输入 / 出斜杠命令;图片可以直接粘贴或拖进来。
- 中途插话、打断:agent 干活时照样发消息,会插进正在跑的那一轮;Esc 打断。
- 审批和提问是卡片:批命令、批改文件、回答选择题,点一下就行。
- 回退:鼠标移到自己说过的话上点 ↺,回到这句之前,原话放回输入框,改了再发。只退对话,不恢复文件。
- 分屏:按 ctrl+b 松开再按 v 左右分屏、- 上下分屏,每一格放一个 agent。哪个在等你,侧栏和格子上都有标记,按 ctrl+b o 直接跳过去。
- 终端:ctrl+b t 在旁边开一个,跟着当前目录;刷新页面、换到手机上都还在。
能做什么
分屏、tab、工作空间,开十几个也不乱。谁在干活、谁在等你一眼就知道,一个键跳过去。用过 herdr 的话,快捷键一样,布局能直接导进来。
agent 能自己开新会话、交代任务、等回复、读结果。比如 Claude 改页面,同时让 Codex 去画图,画好了自动回报。
agent 给的图片、视频、PDF 在对话里就能看,点一下文件路径就打开,不用切出去找。
同一个 agent 可以挂多个账号并排用,额度用完换一个接着聊;能接任意 ACP agent(Gemini CLI、OpenCode……),也能直接调 GPT / DeepSeek / Claude 的 API。
每个项目除了写代码,还能有自己的面板:看板、日报、数据台……面板是一整套页面加上它自己的助手,让 agent 照你的想法搭出来,或者装别人做好的。
详细看看 →出门了用手机打开同一个 Gerdr:看进度、插话、点审批。安卓 App 在家时走局域网直连,还能收后台通知。
详细看看 →Gerdr 的界面是源码,想加按钮、快捷键、显示什么,直接跟 agent 说,保存就生效,不用发版。改坏了有改不坏的急救面板。
插件商店一键装(额度条、今日花费、常用短语、Slack 接入……);skill 和 MCP 可以全局配,也可以只给某个项目。
详细看看 →MR 评论、流水线结束、聊天消息都记成「事件」,面板和会话可以订阅,回复能原路发回去。
在这台电脑上用另一台的 Gerdr:在那边开会话、看终端、读文件,把对话挪过去接着聊。
自定义面板
每个项目左边的窄条上,除了 Code(写代码的工作区),还可以放几个面板。一个面板就是一个小应用:左边是它的页面,右边是它自己的助手。页面上的按钮会把任务交给助手去做,比如「把这周的进度写成周报」。
- 页面:普通的 React 页面,没有打包环节,改了立刻刷新;手机上也能用。
- 本地函数:在你电脑上跑的代码,读文件、调接口、开新的 agent 会话都行,页面上的按钮调它们。
- 助手的做法:写在面板的 skill 里,用你自己的话说清楚活该怎么干,助手照着做。
- 定时和触发:每天几点跑一次,或者 MR 来了评论、聊天里有人 @ 你时自动接着干。
- 自己的数据和设置:存在面板目录里,更新面板也不会动它们。
三种方式得到一个面板
点窄条上面板按钮下面的 + →「新建空白面板」,然后直接跟右边的助手说你要什么,例如:
它写页面、写函数,你在左边马上看到效果,不满意接着说。
同一个 + 里有推荐列表,点一下就装;也可以粘贴任意 GitHub 仓库地址。别人发布的面板在 GitHub 上都带 gerdr-panel 标签。装好的面板能更新,你自己的改动和数据留着。
agent 能做的和你在界面上能做的一样,跟它说一声就行。它用的是这些命令:
gerdr panel install owner/repo # 装一个发布在 GitHub 上的面板 gerdr panel new 周报 # 新建空白面板 gerdr panel update # 更新 gerdr panel icon 周报 kanban # 换图标
一个替你派活的面板:把任务写成卡片,它开 agent 去做、盯进度,做完、卡住或者需要你拍板时告诉你。代码在 gerdr-dev/gerdr-panel-superagent,在推荐列表里一键装。
手机和远程
从外面访问走云端中继:加密一直到你自己的电脑,中继只转密文。新设备第一次用配对码进来(只有坐在电脑前的人能出),之后加一把 passkey,以后换设备也不用回电脑前。
- 配对:设置 →「远程访问」→ 出一个配对码,手机扫码就进来了。码 5 分钟内有效,只能用一次。
- passkey:在手机打开的 Gerdr 里,设置 →「远程访问」→ 加一把 passkey。
- 踢掉设备:设置里点「踢掉」,或者
gerdr remote revoke。 - 安卓 App:和网页同一套界面,在家时局域网直连更快,还能收后台通知。
第一次要先把这台电脑接上中继,步骤见 README 的「远程访问」。不想用中继,看下面的「直接访问」。
直接访问:用 Tailscale 或 frp,不走中继
Gerdr 只负责在一个端口(默认 7878)上用你域名的证书对外,配对码、passkey 的规则和中继一样;手机怎么连到这台电脑,交给你自己的网络。证书照样要(passkey 只在 HTTPS 下能用),但签证书走 DNS,不需要公网连得到你的电脑。
用 Tailscale(什么都不暴露到公网)
电脑和手机都装 Tailscale,登进同一个账号。
设置 →「远程访问」→「直接访问」:填你的域名(比如 gerdr.example.com),「地址里的端口」留空,连接。然后在下面「证书」里选你的 DNS 服务商、填 API 凭据,证书会自己签、自己续。
不想点界面,也可以在电脑的终端里跑一条命令,效果和上面完全一样(写好配置,正在跑的 Gerdr 立刻生效;让 agent 帮你配时它也用这个):
gerdr remote direct gerdr.example.com \ --dns cloudflare \ --env CLOUDFLARE_DNS_API_TOKEN=你的令牌
A 记录:gerdr.example.com → 100.x.y.z,也就是这台电脑的 Tailscale 地址(设置页里会显示)。只有你 Tailscale 里的设备连得到这个地址。
手机开着 Tailscale,打开 https://gerdr.example.com:7878,扫配对码进来。安卓 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 登录」输码。
快捷键
和 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 | 命令面板 |
| ? | 全部快捷键 |
更多
- 完整说明:GitHub 上的 README,包括配置项、环境变量、从源码构建。
- HTTP 接口:脚本、手环这类程序想看会话、发消息、点审批,见 docs/API.md。
- 插件:插件商店里有什么、怎么自己写一个。
- 每个版本改了什么:更新记录。
- 遇到问题:在 GitHub Issues 提。