1. 项目概述构建你的本地自动化中枢如果你和我一样日常工作中需要频繁地与AI助手进行交互处理各种任务、查询和自动化流程那么一个稳定、可扩展且能持久化状态的“网关”就变得至关重要。opencode-gateway正是这样一个项目它不是一个简单的转发代理而是一个功能完备的本地自动化中枢。它的核心价值在于将零散的AI交互比如通过OpenCode整合成一个有状态、可调度、支持多通道如Telegram的持续运行服务。简单来说它让你的AI助手从一个“一问一答”的聊天窗口升级为一个24小时待命、记得住上下文、能处理定时任务、并能通过你习惯的通讯工具比如Telegram与你对话的智能伙伴。这个项目最吸引我的地方是它的设计理念日常操作对话化。一旦网关初始化并运行起来你就不再需要记忆一堆特殊的CLI命令。无论是重启服务、检查定时任务状态、切换AI代理Agent还是搜索记忆库你都可以直接用自然语言向你的OpenCode助手提出请求比如“帮我重启一下网关”或者“今天下午三点有什么计划任务”。网关内置的工具集会在后台默默处理这些机械性的操作让你专注于任务本身。接下来我将从设计思路、核心配置、实战部署到深度调优为你完整拆解这个强大的工具。2. 核心设计思路与架构解析2.1 为什么需要“网关”而不仅仅是“插件”很多AI工具链生态中插件Plugin负责提供单一功能比如连接某个API或解析特定格式文件。但opencode-gateway的定位是“网关”Gateway这意味它承担了更核心的枢纽角色。我们可以从几个维度来理解这种设计1. 状态持久化与生命周期管理一个纯粹的插件通常在每次会话中加载、执行、然后卸载其状态是临时的。而网关引入了SQLite数据库作为后端持久化存储会话绑定、运行时日志、邮箱队列、定时任务目录和执行历史。这使得“记忆”得以跨越单次对话存在。例如你可以在一次对话中让AI助手安排一个每周报告的任务即使你关闭了聊天窗口或重启了电脑这个任务依然会通过网关的调度器准时触发。2. 统一的路由与执行引擎网关抽象出了“邮箱”Mailbox和“路由”Route的概念。不同的输入渠道如Telegram私聊、群组、未来可能支持的Slack等的消息可以被路由到同一个逻辑邮箱进行处理。这确保了无论你从哪个终端发送指令处理的上下文Session是统一的。同时它管理着任务的执行队列处理“飞行中消息”Inflight Messages的策略是排队、询问还是中断这是普通插件难以实现的复杂并发控制。3. 托管运行时与资源隔离网关通过serve命令启动时会“预热”Warm插件工作线程。这不仅仅是加载插件而是建立了一个受管理的运行时环境。这个环境拥有独立的工作空间opencode-gateway-workspace可以存放用户配置文件USER.md、行为规则RULES.md、每日笔记和本地技能Skills。这种隔离性保证了网关管理的会话与全局OpenCode配置互不干扰更新和调试更加安全。2.2 核心组件交互流程图为了更直观地理解各组件如何协作我们可以想象这样一个数据流一条用户消息从Telegram传入直至获得AI回复并返回给用户。入口IngressTelegram机器人通过长轮询Long Polling接收到用户消息。路由Routing网关根据配置的mailbox.routes将这条来自特定channeltelegram和target用户或群组ID的消息映射到一个唯一的mailbox_key例如shared:telegram:personal。邮箱与队列Mailbox Queue消息进入与该mailbox_key绑定的持久化队列。如果当前该邮箱正有一个会话在执行网关会根据inflight_messages.default_policy决定对新消息的处理方式询问、排队或中断。会话执行Session Execution网关从队列中取出消息为其创建或绑定一个现有的OpenCode会话。在此会话中网关会自动注入Inject配置好的记忆文件如USER.md,RULES.md内容为AI提供持久的上下文。工具调用Tool Call用户的消息被传递给OpenCode。AI可能会调用网关暴露的工具例如gateway_restart、agent_switch或memory_search。这些工具的执行由网关的Rust后端处理与外部系统如进程管理、数据库交互。响应与交付Response DeliveryAI生成的回复可能包含文本、推理过程、工具调用详情被网关接收。网关会应用响应批处理Batching、会话压缩Compaction等逻辑最后通过Telegram运行时将格式化的消息支持预览/工具视图切换发送回用户。旁路调度器Scheduler独立的Cron调度器线程按秒检查任务列表触发定时任务。这些任务同样会创建网关管理的会话并注入记忆但其输入来源于时间表而非外部消息。这套架构使得网关成为一个高度自治的系统。你的日常操作变成了与AI的自然对话而复杂的路由、排队、状态管理和调度等“脏活累活”都交给了这个可靠的后台中枢。3. 从零开始完整配置与部署指南理论讲完了我们动手把它跑起来。这里我会以最常用的Telegram集成作为主线带你走通从初始化到日常使用的全流程。3.1 环境准备与初始化首先确保你的系统已安装Node.js环境推荐使用Bun以获得更好性能但npm也完全兼容。项目推荐通过bunx或npx直接运行最新版本无需克隆源码这对大多数用户来说是最佳路径。步骤1一键初始化配置打开终端执行初始化命令。这会为你创建OpenCode和网关的必要配置文件。bunx opencode-gatewaylatest init这个命令会检查并执行以下操作定位你的OpenCode配置目录通常是~/.config/opencode/。如果目录下不存在opencode.jsonc或opencode.json它会创建一个基本的opencode.jsonc。关键动作确保opencode.jsonc中的plugin数组里包含了opencode-gatewaylatest。这是网关插件能被加载的前提。创建网关专用的配置文件opencode-gateway.toml。注意关于--managed模式如果你不希望网关改动你现有的、可能用于其他目的的OpenCode全局配置可以使用init --managed。这会在~/.config/opencode-gateway/下创建一个独立的配置树实现完全隔离。这对于测试或同时运行多个网关实例非常有用。在后续所有命令中如果使用了--managed初始化都需要附加--managed标志。步骤2获取并配置Telegram Bot Token网关与Telegram的集成是其核心功能之一。你需要先创建一个Telegram Bot。在Telegram中搜索BotFather并开始对话。发送/newbot指令按照提示设置机器人的名字和用户名。用户名必须以bot结尾。创建成功后BotFather会提供给你一个bot token形如1234567890:ABCdefGHIjklMnOpQRstUvWxyz。务必妥善保管它相当于你机器人的密码。接下来编辑刚刚生成的~/.config/opencode/opencode-gateway.toml文件。找到[channels.telegram]部分进行配置[channels.telegram] enabled true # 方式一直接将token写在配置文件中不推荐尤其是当配置文件可能提交到Git时 # bot_token 你的:bot_token # 方式二推荐通过环境变量读取更安全 bot_token_env TELEGRAM_BOT_TOKEN poll_timeout_seconds 25 # 安全限制必须配置允许列表否则机器人不会响应任何人 allowed_chats [] allowed_users [你的Telegram用户ID数字]关键配置解析enabled: 必须设为true。bot_tokenvsbot_token_env: 强烈建议使用bot_token_env然后在启动服务前通过export TELEGRAM_BOT_TOKEN你的token设置环境变量避免敏感信息泄露。allowed_users: 这是最重要的安全设置。你需要将你自己的Telegram用户ID添加到此数组。如何获取在Telegram中搜索userinfobot这个机器人给它发送任意消息它会立刻回复你的数字ID。将这个数字ID填入数组例如allowed_users [6212645712]。这样只有你和你在allowed_chats中授权的群组才能与机器人交互。3.2 深度配置解析打造个性化网关初始化配置只是起点opencode-gateway.toml的强大之处在于其丰富的可定制性。我们来逐一拆解核心配置块。3.2.1 网关核心行为 ([gateway])[gateway] state_db /home/yourname/.local/share/opencode-gateway/state.db log_level info # 默认为空不记录可设为 error, warn, info, debug [gateway.mailbox] batch_replies true batch_window_ms 1000 [[gateway.mailbox.routes]] channel telegram target 6212645712 # 你的用户ID topic personal_chat mailbox_key shared:telegram:main [gateway.execution] session_wait_timeout_ms 600000 # 10分钟 prompt_progress_timeout_ms 300000 # 5分钟 hard_timeout_ms 0 # 禁用硬超时 abort_settle_timeout_ms 5000 [gateway.inflight_messages] default_policy askbatch_replies: 设为true时网关会在短时间内batch_window_ms毫秒聚合AI产生的多个回复片段合并成一条消息发送。这能显著改善Telegram聊天中的刷屏问题让对话流更顺畅。实测中设为true并配合1000-1500毫秒的窗口体验提升非常明显。mailbox.routes: 这是实现复杂路由的关键。上面的例子将来自Telegram、且目标是你个人ID的消息路由到shared:telegram:main这个邮箱。这意味着如果你未来增加了另一个Telegram群组作为target并指向同一个mailbox_key那么私聊和群聊的消息将共享同一个会话上下文。你可以利用topic字段进一步细分路由逻辑。execution超时设置: 网关对长时间任务非常友好。默认的session_wait_timeout_ms和prompt_progress_timeout_ms长达30分钟适合运行代码生成、数据分析等重型任务。hard_timeout_ms默认为0禁用意味着网关不会强行杀死任务。除非你明确知道任务可能失控否则不建议启用硬超时。inflight_messages.default_policy: 当邮箱正在处理一个任务时新消息来了怎么办ask默认会暂停新消息并在Telegram中给你发送一个交互按钮让你选择“排队”或“中断当前任务”。queue会自动排队等当前任务结束再处理。interrupt则会直接中断当前任务立即开始处理新消息。根据你的工作流习惯选择。3.2.2 记忆系统 ([[memory.entries]])记忆系统是网关的“大脑”它决定了哪些长期或短期信息会自动提供给AI。[[memory.entries]] path USER.md description 用户档案与偏好记忆。保持准确、简洁。记录稳定的偏好、沟通风格、工作习惯、项目惯例、工具限制、审查期望等应影响未来协助的持久事实。当了解到关于用户的持久信息时主动更新它。不要存储一次性任务细节或临时上下文。 inject_content true [[memory.entries]] path RULES.md description 助手的行为规则和固定操作约束。保持简洁、明确、最新。用于关于行为、审查标准、输出风格、安全边界等应持续塑造未来响应的持久期望。当新的长期规则或边界明确时主动更新它。 inject_content true [[memory.entries]] path memory/daily description 以YYYY-MM-DD.md文件存储的每日笔记。使用此目录存放日期化日志、短期发现和特定日期的工作上下文这些内容应保持可搜索但不自动注入。当出现有意义的新日期特定上下文时主动创建或更新当天的文件。 search_only true [[memory.entries]] path /absolute/path/to/my/project/README.md description 核心项目文档 inject_content true header project-context footer /project-contextinject_content true: 文件内容会在会话开始时自动、完整地插入到AI的上下文窗口。适用于USER.md、RULES.md这种需要AI时刻牢记的“宪法”级文件。search_only true: 文件或目录的内容不会自动注入但可以通过memory_search工具进行搜索或通过memory_get工具按需读取。适用于memory/daily这种每日笔记避免无关的旧信息污染宝贵的上下文令牌Token。globs模式: 当path指向一个目录时可以用globs指定哪些文件应该被inject_content。例如globs [**/*.md, meetings/*.txt]。header/footer: 可以为注入的内容添加自定义标记。这有助于AI识别不同来源的记忆片段在复杂的提示工程中非常有用。路径解析: 相对路径如USER.md相对于opencode-gateway-workspace目录解析。你也可以使用绝对路径指向系统任何位置的文档。3.2.3 调度器 ([cron])[cron] enabled true tick_seconds 5 max_concurrent_runs 1 timezone Asia/Shanghaitick_seconds: 调度器检查任务的频率。默认5秒足够精确且不会对系统造成负担。max_concurrent_runs: 限制同时运行的定时任务数量防止资源耗尽。timezone: 指定Cron表达式所基于的时区。如果不设置将使用运行网关的服务器的本地时区。对于部署在云服务器上的应用明确设置时区可以避免混乱。3.3 启动、验证与日常使用步骤3运行健康检查在启动前强烈建议运行doctor命令来验证配置。bunx opencode-gatewaylatest doctor这个命令会输出一份清晰的报告告诉你使用的配置目录是哪个。OpenCode主配置文件是否存在且格式正确。网关配置文件是否存在。opencode-gateway插件是否已正确列入插件列表。Telegram Bot Token的配置方式环境变量或直接配置。即将使用的服务器地址和工作空间路径。任何配置错误在这里都会暴露出来先修复它们能节省大量后续调试时间。步骤4启动网关服务使用推荐的serve命令一键启动bunx opencode-gatewaylatest serve这个命令做了两件重要的事它启动了OpenCode服务器opencode serve。它立即“预热”Warm了网关插件。这意味着Telegram的长轮询监听和Cron调度器会在OpenCode启动后立刻开始工作无需等待第一个用户请求来触发插件加载。启动成功后你应该能在终端看到OpenCode服务器的日志。现在打开你的Telegram找到你创建的Bot发送一条消息比如“/start”或“你好”。如果一切配置正确你应该能收到回复。步骤5开始对话式操作现在体验网关的核心魅力。你可以直接在Telegram里对你的AI助手说“检查一下网关的状态。” - 助手可能会调用agent_status工具来反馈。“帮我搜索一下记忆中关于‘数据库迁移’的笔记。” - 助手会使用memory_search工具。“我们开始一个新的会话吧。” - 助手可以调用channel_new_session工具。“创建一个每周一早上9点提醒我写周报的任务。” - 助手会利用调度工具来创建Cron任务。所有这些操作都通过自然语言完成网关在后台默默处理了工具调用、状态管理和结果返回。这才是真正意义上的“智能助手”。4. 高级特性与实战技巧4.1 工作空间与技能管理网关初始化时会在当前目录下或配置指定的位置创建一个opencode-gateway-workspace目录。这不是一个普通的文件夹而是你的“数字工作台”。USER.md与RULES.md: 这是两个最重要的文件。我建议你花时间认真编写它们。USER.md里定义“我是谁我喜欢什么我讨厌什么”例如你的编程风格、常用的技术栈、对回复长度的偏好等。RULES.md里定义“你应该怎么做绝对不能怎么做”例如“所有生成的代码必须附带注释”、“优先使用Python标准库”、“避免在回复中使用可能被误解的比喻”。AI会严格遵守这些规则这能极大提升交互质量。memory/目录: 这是你的第二大脑。daily/子目录按日期存放日志project.md存放长期项目背景notes/存放各种领域知识。通过合理的search_only和inject_content配置你可以构建一个分层记忆体系。.opencode/skills/: 这里存放工作空间本地技能。与全局OpenCode技能不同这里的技能仅对本网关管理的会话生效。这意味着你可以为特定的项目或工作流开发定制技能而不会影响其他OpenCode实例。网关在技能加载上有一个智能策略全局技能可读但新建或更新的技能默认指向工作空间本地目录。这鼓励了技能的项目化、模块化管理。实操心得高效利用记忆注入不要试图在USER.md里写一本自传。它应该是一份精炼的“用户手册摘要”。我自己的USER.md结构如下## 沟通偏好 - 回复请使用中文。 - 技术讨论请保持严谨提供依据。 - 在提供方案时请同时给出备选方案及其优缺点。 ## 技术背景 - 主要语言Python, Go, JavaScript。 - 熟悉框架FastAPI, React, Vue。 - 基础设施Docker, Kubernetes, AWS EC2 S3。 ## 工作流 - 偏好命令行操作。 - 喜欢详细的步骤解释但最终请给出可直接执行的命令或代码块。 - 代码审查时请重点关注错误处理、资源管理和安全性。这样的结构清晰、易维护且能高效地被AI利用。4.2 Telegram用户体验优化网关的Telegram集成包含许多贴心的UX设计了解它们能极大提升使用体验。可编辑预览与工具视图: 当AI执行复杂任务、调用多个工具时默认的tool_call_view toggle设置会在Telegram中生成一条带有Preview/Tools按钮的消息。Preview视图展示AI的推理过程和最终答案清晰易懂。Tools视图则分页展示每个工具调用的详细输入输出便于调试。这是一个非常专业的设计兼顾了普通用户和开发者的需求。会话压缩反应: 当AI完成一轮复杂对话主动压缩上下文session.compacted以节省Token时网关会自动在对应的Telegram消息上添加一个️夹子表情。这是一个视觉提示告诉你AI刚刚进行了“内存整理”。自动清理交互消息: 对于permission请求权限和question提问这类需要用户点击按钮的临时交互消息网关会在用户响应后的一小段时间内自动删除它们保持聊天界面整洁。配置技巧调整预览行为如果你觉得工具视图不重要或者希望回复更简洁可以修改[channels.telegram.ux]tool_call_view inline # 将工具详情内联在预览消息中不提供切换按钮 # 或者 tool_call_view off # 完全隐藏工具调用详情只显示最终结果 compaction_reaction false # 关闭压缩反应提示根据你的使用场景灵活调整。4.3 故障排查与维护即使再稳定的系统也可能遇到问题。以下是几个常见场景的排查思路。问题1Telegram机器人无响应检查Token与配置: 再次运行doctor确认bot_token或bot_token_env配置正确且enabled true。检查允许列表: 这是最容易被忽略的一点。确保你的Telegram用户ID已正确添加到allowed_users数组中。你可以再次询问userinfobot进行确认。检查网络: 确保运行网关的服务器可以访问Telegram的APIapi.telegram.org。如果服务器在国内可能需要配置网络策略。查看日志: 将gateway.log_level设置为info或debug重启服务观察终端输出是否有关于Telegram连接、轮询或消息处理的错误信息。问题2插件升级后出现奇怪行为正如项目文档中提到的升级有时会留下陈旧的缓存或状态。可以执行以下清理步骤停止正在运行的网关服务。删除状态数据库rm ~/.local/share/opencode-gateway/state.db删除插件缓存rm -rf ~/.cache/opencode/node_modules/opencode-gateway重新运行bunx opencode-gatewaylatest init如果使用--managed模式则加上该标志。再次启动服务。问题3定时任务没有执行确认调度器已启用: 检查opencode-gateway.toml中[cron]部分的enabled true。检查时区: 确认timezone设置是否正确。Cron表达式0 9 * * 1在Asia/Shanghai时区代表北京时间周一早上9点。查看任务目录: 网关会在状态数据库中管理任务。你可以通过AI助手使用相关的调度检查工具来列出所有任务或者通过日志查看调度器的tick记录。检查任务定义: 确保你通过工具创建的任务其Cron表达式格式正确并且没有过期或被禁用。问题4记忆文件没有被注入检查文件路径: 确认path配置是相对路径相对于工作空间还是绝对路径并且文件确实存在。网关会自动创建不存在的文件但内容为空。检查inject_content标志: 确认你希望自动注入的文件设置了inject_content true。对于目录默认是search_only。检查会话类型: 记忆注入仅发生在网关管理的会话中。如果你通过其他方式如直接调用OpenCode API创建的会话则不会注入记忆。查看会话日志: 在debug日志级别下你可以看到网关在会话初始化时注入了哪些记忆条目及其内容摘要。5. 开发模式从源码构建与贡献对于想要深入研究、修改网关功能或贡献代码的开发者项目也提供了完整的本地开发路径。环境搭建首先你需要克隆仓库并安装依赖。项目使用Bun作为主要的JavaScript/TypeScript运行时并使用Rust编写核心的WASM绑定。git clone https://github.com/M4n5ter/opencode-gateway.git cd opencode-gateway bun install构建Rust WASM绑定网关的核心性能与状态管理逻辑由Rust实现并编译为WebAssembly供OpenCode插件调用。bun run build:binding这个命令会调用wasm-bindgen在packages/opencode-plugin/generated/wasm/pkg/目录下生成最终的WASM模块和JavaScript胶水代码。使用本地启动器进行开发为了方便开发测试项目提供了一个Rust编写的本地启动器Launcher。它会使用仓库本地的插件源码而不是从npm安装。# 初始化开发用的独立配置 cargo run -p opencode-gateway-launcher -- init # 启动开发服务器 cargo run -p opencode-gateway-launcher -- serve # 运行健康检查 cargo run -p opencode-gateway-launcher -- doctor在开发过程中你可以修改TypeScript插件代码或Rust绑定代码然后重启启动器来测试更改。这种设计将用户使用的“打包CLI”和开发者的“源码环境”清晰分离。运行测试与代码检查确保你的修改不会破坏现有功能# 检查绑定构建 bun run check:binding # 检查插件TypeScript代码 bun run check:plugin # 运行Rust单元测试 cargo test # 运行Clippy进行代码 lint cargo clippy --all-targets --all-features给开发者的建议理解双线程模型: OpenCode插件运行在独立的Worker线程中与主OpenCode运行时隔离。网关的Rust部分通过WASM与插件线程通信而插件线程再通过OpenCode的API与主运行时交互。设计新功能时需要考虑这种异步通信模式。状态管理: 所有持久化状态都通过Rust后端存入SQLite。插件前端TypeScript应通过定义良好的工具接口Tool来请求状态变更而不是直接操作数据库。错误处理: 无论是Rust后端还是TypeScript前端都需要有完善的错误处理和日志记录方便用户通过doctor和日志进行诊断。