1. 多设备写代码会话上下文总是断在半路你在公司台式机上让 AI 帮忙重构了一个模块晚上回家打开笔记本想接着调结果发现对话历史全没了只能重新贴一遍报错、重新解释项目结构。这种场景对经常在工位、家里、甚至备用机之间切换的开发者来说太常见了。opencode 本身是终端里的 AI 编码助手会话默认存在本地换台机器就等于从零开始。我试过最原始的办法手动把会话 JSON 复制到网盘到另一台机器再粘回去。能用但每次都要找文件路径、改文件名、确认版本几次之后就懒得同步了。真正需要的是一个能自动把会话导出到远端、再在另一台设备拉回来的机制。这就是 opencode 会话同步 skill 要解决的问题把会话当成可迁移的资产而不是锁死在单机上的临时状态。Gist 在这里是个很合适的存储层。它轻量、有版本记录、默认私有而且 GitHub 和 Gitee 都提供 API不需要自己搭服务。配合 TaoToken 的统一 Key 和 API 通道你可以在不同设备上用同一套凭证访问模型会话同步和模型调用两条链路都统一起来不用每台机器单独配一遍。这篇会从 skill 的目录结构讲起给出可复制的配置片段然后走一遍完整的跨设备同步验证在 A 机器上传会话在 B 机器拉取并恢复。中间会对照几个真实报错比如缺少 Token、Gist ID 未配置、平台选错。目标很明确你跟着做完能在一台机器上备份会话在另一台上把它接回来。适合谁看如果你同时用两台以上设备写代码或者经常需要在不同项目间切换、希望保留 AI 对话的上下文这套流程能省掉大量重复解释的成本。不需要你懂 Gist 的底层 API只要会配环境变量、会跑 shell 命令就行。2. TaoToken 前置统一 Key 与 API 通道在配同步 skill 之前先把模型访问这条链路理清楚。opencode 要调用大模型需要 Base URL、API Key、Model ID 三样东西。如果你每台设备都单独申请 Key、单独填配置换机器时不仅要同步会话还要同步凭证麻烦翻倍。TaoToken 的作用是把这三样统一成一套所有设备指向同一个 API 入口。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 就是你所有设备共用的凭证不要提交到 Git 仓库里。拿到之后Base URL 用 https://taotoken.net/api 注意末尾不带斜杠。Model ID 根据你要用的模型填比如 claude-sonnet-4-20250514 这类标识具体以控制台里列出的为准。opencode 的模型配置通常写在项目根目录或全局配置里。以项目级配置为例在 opencode.json 或对应的 settings 文件中填入{ provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 } } }如果你用的是环境变量方式可以这样写export TAOTOKEN_API_KEYsk-你的TaoToken密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-20250514Windows PowerShell 对应$env:TAOTOKEN_API_KEY sk-你的TaoToken密钥 $env:TAOTOKEN_BASE_URL https://taotoken.net/api $env:TAOTOKEN_MODEL claude-sonnet-4-20250514这里有个容易踩的坑Base URL 写成 https://taotoken.net/api/ 带斜杠某些客户端会拼出双斜杠导致 404。统一去掉末尾斜杠。另外 Key 不要硬编码在会提交的文件里用环境变量或者本地未跟踪的配置文件。配好之后先单独验证模型通道能不能通。在终端里跑一个最小请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL, messages: [{role: user, content: ping}] }如果返回里有 choices 字段和内容说明 Key、Base URL、Model ID 三件套是对的。这一步过了再去配会话同步 skill否则同步回来的会话也没法继续跑。模型通道和同步通道是两条独立的链路先确保模型这条通排障时才能分清是同步问题还是鉴权问题。TaoToken 的接入文档在 https://taotoken.net/doc 里面有各客户端的配置示例遇到字段名对不上可以对照查。控制台在 https://taotoken.net/console 可以看调用记录和额度。如果你打算长期在多设备上跑编码 AgentCoding Plan 页面 https://taotoken.net/coding-plan 有套餐说明按需选就行。3. 可复制的 skill 配置与 Gist 读写片段会话同步 skill 的本质是一个目录里面放说明文档和同步脚本。opencode 会读取 skill 目录下的 SKILL.md 来理解这个技能能做什么脚本负责实际的 Gist 读写。先建目录结构mkdir -p ~/.config/opencode/skills/session-sync/scripts全局安装的话放在 ~/.config/opencode/skills/ 下项目级安装放在项目根目录的 .opencode/skills/ 下。两种方式二选一全局装所有项目都能用项目级装只对当前项目生效。目录结构如下session-sync/ ├── SKILL.md ├── README.md └── scripts/ ├── sync.sh └── sync.ps1SKILL.md 是给 Agent 看的技能说明写清楚这个 skill 的用途和调用方式--- name: session-sync description: 将 opencode 会话导出到 Gist或从 Gist 拉取会话并导入本地 --- # Session Sync ## 功能 - 上传会话将当前或指定的 opencode 会话导出为 JSON上传到 Gist - 恢复会话从 Gist 下载会话 JSON 并导入到当前项目 - 自动管理 Gist ID每个项目独立记录自己的 Gist 映射 ## 使用 在 opencode 会话窗口发送「同步会话」或「上传会话」触发上传。 发送「恢复会话」触发拉取。接下来是核心的配置片段。Gist 的读写需要 Token 和 Gist ID 两个东西。Token 是访问 Gist API 的凭证Gist ID 是你要同步到哪个 Gist 的标识。推荐用环境变量管理 Token用项目根目录的映射文件管理 Gist ID。环境变量配置Linux/macOS 写进 ~/.bashrc 或 ~/.zshrcexport GITEE_TOKEN你的Gitee令牌 export GITHUB_TOKEN你的GitHub令牌 export OPENCODE_SYNC_PLATFORMgithubWindows PowerShell 通过系统环境变量或当前会话设置$env:GITHUB_TOKEN 你的GitHub令牌 $env:OPENCODE_SYNC_PLATFORM githubGist ID 用项目根目录的 .session-gist.json 记录这样每个项目独立互不干扰{ gist_id: abc123def456, platform: github }这个文件建议加进 .gitignore因为它记录的是你个人的 Gist 映射不该提交到项目仓库。获取 Gist ID 的方式在 GitHub 或 Gitee 上创建一个新 Gist可以是空的创建后从 URL 里复制 ID。比如 URL 是 https://gist.github.com/username/abc123def456 那 Gist ID 就是 abc123def456。Token 的权限只需要 gist 一项。GitHub 在 Settings → Developer settings → Personal access tokens → Tokens (classic) 里生成勾选 gist 权限。Gitee 在设置 → 私人令牌里生成同样只勾 gist 相关权限。权限给多了没必要给少了会报 403。sync.sh 的核心逻辑是读环境变量、读映射文件、调 Gist API。上传部分大致是这样#!/usr/bin/env bash set -euo pipefail PLATFORM${OPENCODE_SYNC_PLATFORM:-gitee} GIST_FILE.session-gist.json if [ ! -f $GIST_FILE ]; then echo 错误未找到 $GIST_FILE请先配置 Gist ID exit 1 fi GIST_ID$(python3 -c import json;print(json.load(open($GIST_FILE))[gist_id])) if [ $PLATFORM github ]; then TOKEN${GITHUB_TOKEN:-} APIhttps://api.github.com/gists/$GIST_ID else TOKEN${GITEE_TOKEN:-} APIhttps://gitee.com/api/v5/gists/$GIST_ID fi if [ -z $TOKEN ]; then echo 错误缺少 Token请设置 GITHUB_TOKEN 或 GITEE_TOKEN exit 1 fi SESSION_FILE$1 FILENAME$(basename $(pwd))-$(basename $SESSION_FILE) PAYLOAD$(python3 -c import json,sys contentopen($SESSION_FILE).read() print(json.dumps({files:{$FILENAME:{content:content}}})) ) curl -s -X PATCH $API \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d $PAYLOAD这段脚本做了几件事检查映射文件是否存在、读取 Gist ID、根据平台选 API 地址、检查 Token、把会话文件内容包成 Gist API 需要的 JSON 格式、发 PATCH 请求更新 Gist。文件名用「项目名-会话名」的格式避免不同项目的会话在同一个 Gist 里重名覆盖。拉取部分逻辑类似把 PATCH 换成 GET拿到响应后解析出文件内容写回本地会话目录。sync.ps1 是 Windows 的对应实现逻辑一致只是用 PowerShell 的 Invoke-RestMethod 替代 curl。配置完成后把 skill 目录复制到全局或项目级位置cp -r session-sync ~/.config/opencode/skills/session-sync或者项目级cp -r session-sync ./.opencode/skills/session-sync到这里配置就齐了。三件套是TaoToken 的 Base URL Key Model ID 负责模型调用Gist Token Gist ID 负责会话存储两者独立配置、独立排障。4. 验证请求从 A 机上传到 B 机恢复配置写完不算完得实际跑一遍跨设备同步确认会话真的能迁移。下面用两台机器的场景走完整流程。在 A 机器上先确认环境变量生效echo $GITHUB_TOKEN echo $OPENCODE_SYNC_PLATFORM cat .session-gist.json三个都有值说明前置配置没问题。然后进入 opencode 会话窗口随便聊几轮让会话里有实际内容比如让它读一个文件、解释一段代码。会话产生后找到会话 JSON 的存储位置。opencode 的会话通常存在项目目录下的 .opencode/sessions/ 或用户配置目录里具体路径可以在 opencode 的配置里查或者用 find 找最近的 json 文件find . -name *.json -path *session* -mmin -10找到会话文件后触发上传。在 opencode 会话窗口发送「上传会话」或「同步会话」skill 会调用 sync.sh 把文件推到 Gist。也可以手动跑脚本验证bash ~/.config/opencode/skills/session-sync/scripts/sync.sh .opencode/sessions/xxx.json成功的话curl 返回的 JSON 里会有 files 字段里面包含你上传的文件名和内容。去 Gist 页面刷新能看到新文件出现。这一步确认了上传链路通。现在切到 B 机器。先把同样的环境变量配好GITHUB_TOKEN 用同一个OPENCODE_SYNC_PLATFORM 设为 github。把 A 机器项目里的 .session-gist.json 复制到 B 机器的对应项目根目录或者手动创建一个内容相同的。然后拉取curl -s https://api.github.com/gists/$GIST_ID \ -H Authorization: Bearer $GITHUB_TOKEN | python3 -m json.tool返回里应该能看到 A 机器上传的那个文件。确认存在后在 B 机器的 opencode 会话窗口发送「恢复会话」skill 会下载文件内容并写入本地会话目录。恢复完成后opencode 的会话列表里应该出现从 A 机器同步过来的会话点进去能看到之前的对话历史。验证是否真的接上了在恢复的会话里继续提问比如「接着上面的重构把剩下的函数也改了」。如果模型能基于之前的上下文回答说明会话内容完整迁移不是只同步了个空壳。这一步是整个流程的验收点。再验证一下模型通道在 B 机器上也通。用第 2 节的 curl 命令跑一次确认 TaoToken 的 Key 和 Base URL 在 B 机器上同样有效。两条链路都通跨设备工作流才算闭环。如果 B 机器上恢复后会话打不开先检查文件是否写到了正确的会话目录再检查文件权限。有时候是路径不对文件下载下来了但 opencode 没扫到。对照 A 机器的目录结构确认 B 机器的目录一致。5. 常见报错排查401、缺少 Token、Gist ID 未配置同步流程跑不通时报错信息通常指向几个固定位置。下面按真实遇到的顺序列出来对照着查。错误缺少 Token。请设置 GITHUB_TOKEN 或 GITEE_TOKEN 环境变量。这是最常见的。脚本读不到 Token直接退出。原因通常是环境变量没导出或者导出在了另一个 shell 会话里。检查方法echo $GITHUB_TOKEN如果输出为空说明当前 shell 没有这个变量。Linux/macOS 下确认写进了 ~/.bashrc 或 ~/.zshrc 并且执行了 source或者新开终端。Windows 下确认是在系统环境变量里设的还是只在当前 PowerShell 会话里设的。只在当前会话设的关掉窗口就没了。另外注意变量名拼写GITHUB_TOKEN 和 GITEE_TOKEN 是两个不同的变量平台选 github 却只设了 GITEE_TOKEN一样会报缺少 Token。错误401 Unauthorized。Token 存在但无效。可能是 Token 过期、被撤销、或者权限不够。GitHub 的 classic token 如果没勾 gist 权限调 Gist API 会返回 401 或 403。去 Token 设置页面确认 gist 权限已勾选必要时重新生成一个。Gitee 的令牌同理确认勾了 gist 相关权限。还有一种情况是 Token 复制时带了空格或换行用 echo 检查一下长度和首尾字符。错误项目 xxx 未配置 Gist ID。脚本找不到 .session-gist.json或者文件里没有 gist_id 字段。检查项目根目录下有没有这个文件ls -la .session-gist.json cat .session-gist.json文件存在但内容格式不对也会报这个。确保是合法的 JSONgist_id 和 platform 两个字段都有值。如果是从别的项目复制过来的记得改 gist_id否则会同步到错误的 Gist 上把别的项目的会话覆盖掉。错误local proxy failed 或连接超时。这类报错通常和网络链路有关。先确认 Base URL 写对了https://taotoken.net/api 不带末尾斜杠。如果模型调用报这个检查 TaoToken 的 Key 是否有效、额度是否充足。如果 Gist 调用报这个检查 api.github.com 或 gitee.com 的 API 地址是否能通。注意不要在任何配置里引入代理相关的设置保持直连。错误reading choices 失败或返回体里没有 choices。模型通道的问题不是同步的问题。检查请求体里的 model 字段是否和控制台里列出的 Model ID 完全一致大小写和版本号都不能差。Base URL 和 Key 再核对一遍。用第 2 节的 curl 最小请求单独测排除是 opencode 配置的问题还是凭证的问题。错误OAuth 相关报错。如果你用的是 OAuth 方式登录而不是 API Key注意 opencode 的 OAuth 流程和 Gist 的 Token 是两套东西。OAuth 管的是模型访问授权Gist Token 管的是存储访问。两者不要混用。模型访问统一走 TaoToken 的 API Key简单直接不涉及 OAuth 回调。排查顺序建议先确认模型通道通curl 测 TaoToken再确认 Gist 通道通curl 测 Gist API最后确认 skill 脚本能读到环境变量和映射文件。三层分开测比一上来就怀疑 skill 本身高效得多。6. 把会话当成可迁移资产跨设备同步这件事核心不是技术多复杂而是把会话从「本地临时文件」变成「可迁移资产」。Gist 提供存储skill 提供读写TaoToken 提供统一的模型通道三者拼起来就是一套轻量的多设备工作流。实际用下来有几个习惯能减少麻烦。每个项目单独一个 Gist不要所有项目共用一个否则会话文件混在一起恢复时容易拉错。.session-gist.json 一定加进 .gitignore这是个人配置不该进仓库。Token 用环境变量管理不要写死在脚本里换机器时只配一次。如果你经常在多个项目间切换可以给每个项目建一个 GistGist ID 记在各自项目的映射文件里。这样在 A 机器上改项目 X 的会话推到 X 的 GistB 机器上拉 X 的 Gist不会串到项目 Y。项目隔离做干净后面维护成本低很多。模型通道这边TaoToken 的 Key 和 Base URL 在所有设备上保持一致省去每台机器单独配凭证的步骤。接入文档在 https://taotoken.net/doc 配置示例可以直接对照。需要看调用记录和额度就去 https://taotoken.net/console 。长期跑编码 Agent 的话Coding Plan 页面 https://taotoken.net/coding-plan 有套餐说明按使用量选。最后一步验证做完你手上就有了一套能用的跨设备会话同步流程。下次换机器不用再重新解释项目背景会话接上就能继续。