OpenChamber 1.7.5 版本解读:会话消息去重修复、JWT 会话认证迁移与 OPENCODE_HOST 支持
OpenChamber 1.7.5 版本解读:会话消息去重修复、JWT 会话认证迁移与 OPENCODE_HOST 支持
导读
本文基于 OpenChamber(基于 OpenCode AI Agent 的 Agentic 开发环境)v1.7.5 的官方变更记录(changelog/1.7.5.md),深入解读该版本在 Web/桌面端与 VS Code 扩展端的核心改进:会话消息偶发重复或丢失的可靠性修复、会话切换开销的优化、UI 侧边栏与移动端阅读体验的打磨,以及 Web 端新增的 OPENCODE_HOST 环境变量支持。同时结合仓库中的官方文档(environment.mdx、opencode-server.mdx)与源码(ui-auth.js、useGlobalSessionsStore.ts)说明底层原理。读完本文,你将了解 v1.7.5 的完整变更内容、各改进背后的实现机制,以及如何利用这些能力排查会话消息异常、配置持久化认证与连接外部 OpenCode 服务器。
App(Web 与桌面端)
新增:Web 端支持 OPENCODE_HOST
v1.7.5 在 Web 端新增了对 OPENCODE_HOST 环境变量的支持(感谢 @colinmollenhour)。该变量用于将 OpenChamber 连接到一个已存在的 OpenCode 服务器,而非让 OpenChamber 自行启动托管服务器。
从官方文档(environment.mdx)可知:
OPENCODE_HOST:Connects OpenChamber to an existing OpenCode server. The value must be anhttporhttpsorigin with an explicit port and no path, query, or hash.OPENCODE_HOSTtakes precedence overOPENCODE_PORT.
即其取值必须是显式包含端口、且不含路径/查询串/哈希的 http 或 https Origin,例如 http://localhost:4096。
同时文档指出 OpenChamber 启动时查找服务器的顺序(opencode-server.mdx):
- 复用自己已经启动的服务器;
- 若配置了外部服务器(如通过
OPENCODE_HOST),则连接外部服务器; - 在默认端口
4096上自动探测已存在的服务器; - 否则自行启动并管理一个服务器。
典型使用方式(配合 OPENCODE_SKIP_START=true 禁止 OpenChamber 启动自己的服务器):
OPENCODE_HOST=http://localhost:4096 OPENCODE_SKIP_START=true openchamber
需要注意:
OPENCODE_HOST的优先级高于OPENCODE_PORT;如果只想改端口,直接设置OPENCODE_PORT即可;- 若
OPENCODE_HOST缺少端口或带路径,OpenChamber 会忽略它并回退为启动自己的服务器。此时应在启动日志中留意<a href="https://link.gitcode.com/i/58c93e11ed8b3372d88036307d25b1c0" target="_blank">config]警告,排查"期望的连接未发生"的情况([opencode-server.mdx); - 官方还提供了相关排查文档:opencode-connection.mdx,其中特别强调
OPENCODE_HOST必须包含端口、不能带路径。
改进:Projects 移入独立侧边栏轨道并收紧布局
v1.7.5 将"项目"列表移入一个专用的侧边栏轨道(dedicated sidebar rail),同时收紧整体布局。这一改动让项目导航与聊天会话区域在视觉与交互上解耦:项目作为独立的常驻入口,不再与会话列表混排,从而在项目众多的工作区中减少视觉噪音、提升定位效率。
改进:降低会话切换开销,让聊天上下文切换更即时
该版本针对"会话切换"做了专项性能优化,使切换会话时聊天上下文的变更更即时。从仓库的会话存储实现(useGlobalSessionsStore.ts)及配套说明(stores/DOCUMENTATION.md)可以看出,会话数据的管理分为"全局冷数据层"与"活跃会话层":
- 全局会话 store 维护所有(active/archived)会话的实体索引与目录索引,完整的快照可以一次性重建索引;
- 直接进行的 create/update/move/archive/delete 变更只更新受影响的层级与目录桶(bucket),元数据更新则保留结构引用不动。
这意味着切换到某个会话时,无需重建整个侧边栏索引,只需在既有结构上做增量更新,从而显著降低切换开销。仓库中还有专门的竞态测试(useGlobalSessionsStore-races.test.ts),覆盖了"过期快照晚到"(stale snapshot arriving after removal/archive)等场景,确保会话列表在快速切换时不出现旧数据回填、条目错乱等问题。
改进:会话认证存储迁移至"签名 JWT + 持久化密钥"
这是 v1.7.5 中安全层面最关键的改动:将会话(session)认证存储从原先的实现迁移为使用持久化密钥签名的 JWT(JSON Web Token)。
从源码(ui-auth.js)可以看到具体机制:
const OPENCHAMBER_DATA_DIR = process.env.OPENCHAMBER_DATA_DIR
? path.resolve(process.env.OPENCHAMBER_DATA_DIR)
: path.join(os.homedir(), '.config', 'openchamber');
const JWT_SECRET_FILE = path.join(OPENCHAMBER_DATA_DIR, 'jwt-secret');
function getOrCreateJwtSecret() {
const envSecret = process.env.OPENCODE_JWT_SECRET;
if (envSecret) {
return new TextEncoder().encode(envSecret);
}
// 优先读取持久化的密钥文件
if (fs.existsSync(JWT_SECRET_FILE)) {
return new TextEncoder().encode(fs.readFileSync(JWT_SECRET_FILE, 'utf8').trim());
}
// 否则生成随机 32 字节密钥并持久化(0600 权限)
const secret = crypto.randomBytes(32).toString('hex');
fs.mkdirSync(OPENCHAMBER_DATA_DIR, { recursive: true });
fs.writeFileSync(JWT_SECRET_FILE, secret, { mode: 0o600 });
return new TextEncoder().encode(secret);
}
要点如下:
- 密钥来源优先级:
OPENCODE_JWT_SECRET环境变量 > 数据目录下的jwt-secret文件 > 自动生成的随机 32 字节十六进制密钥(默认数据目录为~/.config/openchamber,可用OPENCHAMBER_DATA_DIR覆盖); - 持久化:自动生成的密钥以
0600权限写入jwt-secret文件,保证服务重启后会话令牌仍可验证,这是"持久化 secret"的核心; - 环境变量场景:对于长期运行的服务部署,官方文档建议设置
OPENCODE_JWT_SECRET为长随机值(见 environment.mdx),以便多实例共享同一签名密钥; - 副作用:源码显示,当设置了
OPENCODE_JWT_SECRET时,全局登出(global sign-out)操作会被禁用(抛出400错误),因为环境变量密钥无法被安全地轮换/持久化替换(ui-auth.js)。
从会话 cookie 的实现(ui-auth.js)还可看到默认会话参数:oc_ui_session cookie 的默认 TTL 为 12 小时,可信设备会话(trusted device session)TTL 为 7 天,URL 认证令牌 TTL 为 60 秒;Cookie 带有 Path=/、HttpOnly、SameSite=Strict 等安全属性(buildCookie),并在 secure 时附加 Secure。这些参数共同构成"签名 JWT + 安全 Cookie"的认证体系,显著提升了会话令牌的抗篡改能力与长期服务下的稳定性。
改进:移动端消息间距与滚动阴影优化
针对小屏阅读体验(感谢 @Jovines):移动端细化了消息间距(message spacing),并移除了顶部滚动阴影(top scroll shadow)。对于窄屏上的长对话,更克制的间距与更干净的顶部视觉边界能减少视觉干扰,使阅读更连续。
修复:活跃会话中消息偶发重复或消失
这是 v1.7.5 的标题级修复:修复了活跃对话期间消息可能偶发重复或消失的问题。该问题通常与以下因素相关:
- 消息在会话切换、重连(reconnect)或流式更新(streaming/live update)过程中的状态竞争;
- 客户端本地快照与服务器消息列表的先后顺序错位(即"stale snapshot"问题)。
结合仓库实现,OpenChamber 的会话列表层面对此类竞态有系统性的防护:useGlobalSessionsStore 在应用服务器快照时会维护实体索引,并以"直接变更只更新受影响部分"的策略避免整树重建(stores/DOCUMENTATION.md);同时 useGlobalSessionsStore-races.test.ts 覆盖了删除/归档后过期快照晚到的场景,确保列表最终一致性。虽然该测试聚焦会话条目本身,但消息渲染层同样依赖此类"最新状态优先、丢弃过期更新"的机制来避免重复/消失。升级到 1.7.5 后,若此前遇到过会话进行中消息重复或突然消失的情况,可确认该版本已针对此问题做了修复。
修复:移动端待处理权限提示在重连/恢复后不再丢失
在 1.7.5 之前,移动端存在一个痛点:当会话处于**待处理权限提示(pending permission prompt)**状态时,若发生重连(reconnect)或从后台恢复(resume),该提示可能中途丢失,导致权限请求"石沉大海"(感谢 @nelsonPires5)。本版本修复后:
- 待处理的权限/问题卡片(pending permission and question cards)会在重连或恢复后重新出现;
- 会话不再看起来"卡死"(frozen)。
从仓库相关代码(crashRecovery.ts 及配套测试 crashRecovery.test.ts、background-network.test.ts)可以看出,OpenChamber 在浏览器/移动端层面具备面向连接中断的恢复机制,待处理交互状态会被保留并在重连时恢复,这正是该修复的底层支撑。
修复:容器化环境下的应用内更新流程
v1.7.5 修复了容器化(containerized)部署中应用内更新(in-app update)流程的问题。在 Docker 等容器环境中,应用内自更新常因只读文件系统、缺少写权限或路径挂载差异而失败;该版本对此类场景做了针对性处理,使 Web/Mobile 在容器中也能正确完成更新流程。相关部署参考可见 docker-compose.yml 与 Dockerfile。
VS Code 扩展
改进:会话切换性能提升
与 App 端"降低会话切换开销"的优化同步,VS Code 扩展侧也改进了会话切换性能(improved switching performance)。在 VS Code 的窄面板中快速切换多个会话时,延迟更低、上下文渲染更跟手。
修复:活跃对话期间消息重复或消失
VS Code 扩展同样修复了会话进行中消息偶发重复或消失的问题,与 App 端修复同源。如果你在 VS Code 中使用 OpenChamber 面板进行长对话时遇到过消息错乱,1.7.5 已覆盖该场景。
小结与升级建议
| 维度 | v1.7.5 关键变更 | 影响 |
|---|---|---|
| 连接性 | Web 新增 OPENCODE_HOST 环境变量支持 |
可直连既有 OpenCode 服务器,配合 OPENCODE_SKIP_START=true 使用;取值须含端口、无路径 |
| 安全 | 会话认证迁移为"签名 JWT + 持久化密钥" | 服务重启后令牌仍可验证;长期部署建议设置 OPENCODE_JWT_SECRET |
| 性能 | 会话切换开销降低(App 与 VS Code) | 大工作区、多会话场景下切换更即时 |
| 可靠性 | 修复活跃对话中消息重复/消失(App 与 VS Code) | 长对话、快速切换场景下消息展示更稳定 |
| 移动端 | 消息间距与顶部阴影优化;待处理权限提示重连后恢复 | 小屏阅读更舒适,权限流程更可靠 |
| 部署 | 修复容器化环境中的应用内更新 | Docker 部署可正常更新 |
验证与排查建议:
- 检查
OPENCODE_HOST是否生效:启动日志若出现<a href="https://link.gitcode.com/i/8077746d216619bc126d051f8565baeb" target="_blank">config]警告且未连接到你期望的服务器,多半是环境变量缺少端口或包含路径([troubleshooting/opencode-connection.mdx); - 确认认证密钥持久化位置:默认位于
~/.config/openchamber/jwt-secret(受OPENCHAMBER_DATA_DIR影响),如需多实例共享,设置OPENCODE_JWT_SECRET; - 若升级后仍怀疑消息重复/消失,可结合会话列表竞态防护机制(useGlobalSessionsStore-races.test.ts)与服务器日志对比消息序列。
相关文档与源码索引
- 变更记录:changelog/1.7.5.md
- 环境变量参考:environment.mdx(
OPENCODE_HOST、OPENCODE_JWT_SECRET、OPENCHAMBER_DATA_DIR等) - OpenCode 服务器连接指南:opencode-server.mdx
- 连接排查:troubleshooting/opencode-connection.mdx
- 认证实现源码:ui-auth.js(JWT 密钥生成与持久化)、ui-auth.js(Cookie 构建)
- 会话存储与竞态防护:useGlobalSessionsStore.ts、useGlobalSessionsStore-races.test.ts、stores/DOCUMENTATION.md
- 连接恢复机制:crashRecovery.ts、crashRecovery.test.ts
- 容器化部署参考:docker-compose.yml、Dockerfile