feat: 新增博客文章「用 Tailscale + Terminus 在 iPad 上远程操控 Claude Code」

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: xkcoding

src/data/blog/2026-02-17.remote-claude-code-with-tailscale-terminus.md

@@ -0,0 +1,216 @@
+---
+title: "用 Tailscale + Terminus 在 iPad 上远程操控 Claude Code"
+author: xkcoding
+pubDatetime: 2026-02-17T00:00:00.000Z
+slug: remote-claude-code-with-tailscale-terminus
+featured: true
+draft: false
+ogImage: https://cdn.xkcoding.com/blog/2026-02-16-remote-claude-code-tailscale-cover-16x9.webp?x-oss-process=style/tag_compress
+tags:
+  - ai
+  - claude-code
+  - tailscale
+description: "Claude Code 驱动的工作流用得越深，越离不开那台 Mac。上下文、笔记、项目全在上面，出门就接不上。本文对比了 frp、Cloudflare Tunnel、Happy Coder、Tailscale 几种远程方案，最后用 Tailscale 组网加 Terminus 做移动端 SSH，iPad 和手机随时能连回 Mac 用 Claude Code。也记录了搭建 Tailscale 过程中踩的坑：GUI 版锁屏断连、国内 DNS 污染、SSH 读不到 macOS 钥匙串，以及自己的排查思路。"
+---
+
+## 写在前面
+
+我的第二大脑是 Obsidian + Claude Code 搭的 [Claudesidian](https://github.com/heyitsnoah/claudesidian) 方案。它在 Obsidian 里预设了一套 PARA 结构的知识库，然后通过 Slash Command 和 MCP 让 Claude Code 来驱动整个工作流：日常写笔记、整理收藏、做 daily review，甚至研究一个新话题，都是在跟 Claude Code 对话中完成的。它不只是个工具，更像一个长期协作伙伴。
+
+问题是，我不可能随时坐在电脑前。春节假期躺沙发上突然冒出个想法，陪娃逛街时脑子里闪过一个 bug 的解法。偏偏这种碎片化的瞬间，最想随手跟 AI 聊两句。
+
+折腾了一番，我使用 Tailscale 组网 + Terminus 做移动终端，现在在 iPad 上打开 Terminus 就能直接跟 Mac 上的 Claude Code 对话。
+
+![工作流从 Mac 延伸到移动端](https://cdn.xkcoding.com/blog/2026-02-16-illustration-overview-architecture.webp?x-oss-process=style/tag_compress)
+
+## 为什么选 Tailscale
+
+想要从外面连回家里的 Mac，核心问题是组网。常见方案有几种：
+
+- **frp / ngrok**：需要一台有公网 IP 的服务器做中转，不是每个人都有
+- **Cloudflare Tunnel**：免费，不需要公网 IP，但需要一个托管在 Cloudflare 的域名。SSH 场景下客户端也得装 `cloudflared` 做代理，配置链路比较长（建 Tunnel、配公共主机名、改本地 SSH config、加 Access 策略），更适合暴露 Web 服务
+- **[Happy Coder](https://happy.engineering/)**：专门为 Claude Code 设计的移动端方案，扫码配对就能用。它通过中继服务器转发加密消息，你的代码和对话会经过第三方服务。如果你只需要在手机上操控 Claude Code，这是最轻量的选择
+- **Tailscale**：注册一个账号（支持 GitHub 登录），各设备装上客户端，自动组成虚拟局域网，设备之间点对点直连，不经过第三方
+
+我选 Tailscale，原因很简单：零配置门槛，装上就能用。我平时有在家折腾 homelab，用闲置硬件搭了一套自己的开发和存储环境，这些设备本来就跑在 Tailscale 网络里，iPad 和手机加进来只是顺手的事。
+
+没了解过 Tailscale 的同学，这里简单说一下它的原理：它基于 WireGuard 协议，在你的设备之间建立点对点的加密隧道。大部分情况下设备之间直连，不经过中转服务器，延迟很低。每台设备会分配一个固定的 `100.x.x.x` 内网 IP，你用这个 IP 就能像在同一个局域网一样互相访问。
+
+![四种远程方案对比](https://cdn.xkcoding.com/blog/2026-02-16-illustration-solution-comparison.webp?x-oss-process=style/tag_compress)
+
+## 前置准备
+
+### Mac 保持在线
+
+整个方案的前提是 Mac 不能休眠断网。接上电源，然后打开「系统设置」→「显示器」→「高级」，开启"当显示器关闭时，防止自动休眠"；再到「电池」→「选项」，把"唤醒以供网络访问"设为"始终"。
+
+### Mac 开启远程登录
+
+「系统设置」→「通用」→「共享」→ 打开"远程登录"。这一步开启的就是 SSH 服务。
+
+### 移动端安装 Terminus
+
+[Terminus](https://termius.com/) 是一个跨平台的 SSH 客户端，支持 iOS、iPadOS 和 Android，免费版功能足够用了。
+
+> [!TIP]
+> iPad 强烈建议配一个键盘外设，体验会好很多。
+
+## Mac 端 Tailscale 配置
+
+### 安装 Tailscale
+
+Tailscale 在 Mac 上有两种安装方式：App Store 的图形界面版本，和 Homebrew 的命令行守护进程版本。
+
+我一开始装的是 GUI 版，用着没问题，但合上盖子或者锁屏关闭显示器之后，iPad 就连不上了。换成 Homebrew 版就没这个问题，它作为系统守护进程运行，锁屏也不会断。
+
+```bash
+brew install tailscale
+sudo brew services start tailscale
+sudo tailscale up
+```
+
+运行 `tailscale up` 后终端会打印一个认证链接，复制到浏览器打开完成登录就行。
+
+如果一切顺利，到这里就结束了。但我遇到了两个坑。
+
+### 踩坑 1：GUI 版残留导致命令失效
+
+如果你之前装过 GUI 版，`/usr/local/bin/tailscale` 可能还指向旧的应用路径，执行时会报 `No such file or directory`。
+
+```bash
+# 删掉失效的旧链接
+sudo rm /usr/local/bin/tailscale
+
+# 让 Homebrew 接管
+brew link --overwrite tailscale
+```
+
+确认一下新路径：
+
+```bash
+which tailscale
+# Apple Silicon: /opt/homebrew/bin/tailscale
+# Intel Mac: /usr/local/bin/tailscale
+```
+
+如果看到 `/opt/homebrew/bin/tailscale` 或 `/usr/local/bin/tailscale`，说明链接修复成功。
+
+### 踩坑 2：DNS 污染导致连不上服务器
+
+> [!NOTE]
+> 这个问题卡了我最久。国内使用代理工具的用户大概率会遇到，网络环境没问题的可以跳过这段。
+
+`tailscale up` 之后一直卡着没反应，手动启动守护进程看日志，发现：
+
+```
+logtail: dial "log.tailscale.com:443" failed: dial tcp 11.0.0.1:443: i/o timeout
+```
+
+`log.tailscale.com` 被解析到了 `11.0.0.1`，这是典型的 DNS 污染。解法是让 Tailscale 走代理启动。
+
+先手动验证代理能不能通：
+
+```bash
+# 杀掉残留进程
+sudo pkill tailscaled
+
+# 带代理启动守护进程（替换成你自己的代理端口）
+sudo env http_proxy=http://127.0.0.1:10080 \
+         https_proxy=http://127.0.0.1:10080 \
+         all_proxy=socks5://127.0.0.1:10081 \
+         /opt/homebrew/bin/tailscaled
+```
+
+如果日志正常滚动没报错，开一个新终端窗口执行 `tailscale up` 完成登录。
+
+验证通过后，把代理配置写进 Homebrew 的服务配置文件里，这样重启也能自动生效：
+
+```bash
+sudo nano /opt/homebrew/Cellar/tailscale/$(tailscale version | head -1)/homebrew.mxcl.tailscale.plist
+```
+
+在 `<dict>` 内添加：
+
+```xml
+<key>EnvironmentVariables</key>
+<dict>
+    <key>http_proxy</key>
+    <string>http://127.0.0.1:10080</string>
+    <key>https_proxy</key>
+    <string>http://127.0.0.1:10080</string>
+    <key>all_proxy</key>
+    <string>socks5://127.0.0.1:10081</string>
+</dict>
+```
+
+保存后重启服务：
+
+```bash
+sudo brew services restart tailscale
+```
+
+运行 `tailscale status`，如果能看到你的设备列表，说明配置生效了。
+
+### 补充：macOS Screen Time 可能拦截网络
+
+> [!NOTE]
+> 这个坑我没遇到，但排查过程中发现有人踩过。macOS 的「屏幕使用时间」里「内容与隐私」默认是关闭的，大部分人不会遇到。但如果你开启过网页内容限制（或者家里小孩用过你的电脑），它会在系统底层拦截网络流量，导致 Tailscale 怎么配都连不上。
+>
+> 如果你排查了代理和 DNS 都没问题，检查一下「系统设置」→「屏幕使用时间」→「内容与隐私」，把「访问网页内容」设为"无限制"，或者直接关掉「内容与隐私」的总开关。改完之后 `sudo brew services restart tailscale`，再用 `tailscale status` 确认一下。
+
+## 移动端连接 Claude Code
+
+Tailscale 配好之后，iPad 和手机上装好 Tailscale 客户端并登录同一个账号，就能拿到 Mac 的 Tailscale IP（`100.x.x.x`）。
+
+在 Terminus 里新建一个 Host，地址填 Mac 的 Tailscale IP，用户名填 Mac 的登录用户名，连接方式选 SSH。连上之后就是一个标准的终端环境，直接敲 `claude` 就能启动 Claude Code。
+
+但第一次连大概率会遇到这个提示：
+
+```
+run in another terminal: security unlock-keychain
+```
+
+这是因为 Claude Code 把登录凭证存在 macOS 的钥匙串（Keychain）里。你坐在 Mac 前面用的时候，系统会自动解锁钥匙串；但通过 SSH 远程连接时，macOS 出于安全考虑不会自动解锁，Claude Code 读不到凭证就会报错。
+
+手动解锁：
+
+```bash
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+```
+
+输入 Mac 的登录密码就行。
+
+每次 SSH 连接都手动敲这行命令有点烦，在 `.zshrc` 里加一段自动判断：
+
+```bash
+if [ -n "$SSH_CONNECTION" ]; then
+  echo "🔓 unlocking Keychain for Claude Code..."
+  security unlock-keychain ~/Library/Keychains/login.keychain-db
+fi
+```
+
+这样每次通过 SSH 登录时会自动触发解锁，只需要输一次密码。看似每次都要输密码，但实际用下来完全可以接受。
+
+到这里，整个链路就通了。Mac 锁屏挂着，iPad 或手机随时打开 Terminus 就能接入 Claude Code。
+
+## 日常使用效果
+
+用手机备忘录也能记想法，但事后还得手动整理到 Obsidian 里，自己补上下文、打标签、关联已有笔记。Obsidian 虽然有移动端，但我的工作流是 Claude Code 驱动的，笔记的创建、归档、关联都是 Claude 在做，直接用 Obsidian App 反而对不上。
+
+用 Terminus 连上 Claude Code 之后，移动端也能用完整的工作流。记录灵感、改点代码，都能直接上手。
+
+**捕捉灵感**：假期窝在沙发上突然想到一个点子，拿起 iPad 跟 Claude 说两句，它知道我的笔记结构，会自动归档到对应目录、补上 frontmatter。陪娃在外面逛也一样，掏出手机打开 Terminus 快速记一笔。手机上打长命令确实不太舒服，但记个灵感够用了。
+
+**出门也能改代码**：刚发完一篇博客发现导出格式有个小问题，手边没电脑，iPad 上跟 Claude Code 描述一下，它自己找到导出脚本改好。不用看代码，不用等回家。
+
+**灵感趁热落地**：跟朋友聊天聊到一个好用的工作流，当场让 Claude 起一个新 Skill 的骨架，回家再细调。想法热乎的时候直接落地，比事后回忆靠谱得多。
+
+![随时随地接入 Claude Code](https://cdn.xkcoding.com/blog/2026-02-16-illustration-daily-usage.webp?x-oss-process=style/tag_compress)
+
+## 最后
+
+这套方案用起来比预想的简单，搭完之后基本没折腾过。Tailscale 组网的能力也不止于此，有需要的时候可以把更多设备加进来。
+
+搭建过程踩的坑，基本都是把报错丢给 AI 一轮轮排查解决的。给足上下文，试错成本很低。
+
+希望这篇文章对你有帮助，有更好的方案欢迎留言讨论。