Janus:把 OpenCode 包装成统一的 Agent 网关
一个开源的 AI Agent 网关:统一协议、统一会话、统一模型与权限,但不重造 Agent 运行时。
我们面对的现实
2026 年的 coding agent 已经很多:OpenCode、Claude Code、Codex CLI、Gemini CLI……它们各自很强,但一旦你要把它们接进自己的系统,问题就来了:
- 每个 agent 只说自己的协议(Claude Code 说 Anthropic Messages,Codex 说 OpenAI Responses,OpenCode 是自有
/api/*); - 模型、鉴权、会话、权限、观测,全都散落在各个工具里;
- 想在它们之间切换、统一计费、统一审计,几乎要重写一遍 glue。
Janus 想解决的就是这一层。
Janus 是什么
一句话:
Agent 负责「怎么做」,Janus 负责「谁可以怎么用」。
Janus 是一个 OpenAI / Anthropic 兼容的网关 + 控制平面:把只有 /api/* 的 OpenCode server 包装成标准 /v1/*,让各类 OpenAI / Anthropic 客户端(Trae、CodeBuddy、Cursor、Claude Code、OpenAI SDK、LangChain…)直接可用;同时把会话、工具、权限、用量统一管起来。
它不重造 Agent runtime、Tool runtime、MCP runtime、Session runtime —— 这些交给 OpenCode 等现成的 agent,Janus 只做控制平面该做的事。
一次请求经过了什么
Janus 不是简单的 HTTP 转发器,而是把“无状态 API 请求”接到“有状态的 OpenCode Agent 会话”上:
1 | OpenAI / Anthropic 客户端 |
客户端每轮通常会重新发送完整的 messages。Janus 按会话键和严格的历史前缀匹配找到对应的 OpenCode session,只把新增内容发给上游;找不到前缀时才新建会话,避免不同话题互相污染。Responses API 用 previous_response_id 续接,Anthropic 客户端则可用 x-claude-code-session-id 固定会话。
源码与安装
项目地址:https://github.com/qist/janus(MIT 许可)
方式一:下载预编译包(推荐)
到 Releases 下载对应平台与架构的包(Linux / macOS / Windows,amd64 / arm64 / arm / 386):
1 | VERSION=v0.3.15 |
桌面用户直接用 macOS / Windows 包:macOS 拆好了 darwin/amd64 与 darwin/arm64(Intel / Apple Silicon);Windows 的 zip 解压即用,数据目录也各自遵循了平台惯例(macOS ~/Library/Application Support/janus,Windows %LOCALAPPDATA%\janus)。
方式二:源码编译
1 | git clone https://github.com/qist/janus.git |
依赖:Go 1.26+;上游需要已安装 OpenCode(未装时 Janus 会在日志里提示安装命令)。
方式三:Docker / systemd
1 | # Docker(distroless 非 root 静态镜像) |
运行
1 | # 0. 先装 OpenCode(Janus 的上游 agent;未装时 Janus 会在日志里提示) |
OpenCode 不用你手动启动:Janus 启动时会自动发现已在跑的
opencode serve,没有就自己拉一个(默认开启,可用OPENCODE_AUTOSTART=false关闭;随机端口 + 随机密码)。你只要把它装好即可 —— 所以也没有「填端口/密码」这一步。
客户端把 Base URL 指到 http://127.0.0.1:2810/v1、API Key 填 BRIDGE_API_KEY 即可,零改动;Claude Code / Anthropic 客户端则把 ANTHROPIC_BASE_URL 指到 http://127.0.0.1:2810。
已实现端点:/v1/models(含 /v1/models/{id} 详情)、/v1/chat/completions(流式+非流式)、/v1/completions、/v1/responses(含 previous_response_id 续链)、/v1/messages 与 /v1/messages/count_tokens(Anthropic)、/anthropic/v1/models、/v1/usage、/v1/requests、/v1/settings、/metrics、/ui、/healthz。
三种执行模式(执行边界很清楚)
这里的模式是 BRIDGE_AGENT + BRIDGE_TOOL_CALLING 组成的语义组合,不是单独的环境变量;按部署形态选一种:
| 模式 | 工具在哪执行 | 适合 |
|---|---|---|
native |
服务端(Janus 主机、会话目录) | 本机自用,链路最短 |
remote-tools |
客户端(走内置 MCP 工具桥) | 集中部署、代码在本地 |
none |
无工具(纯推理) | Chat / Review / 规划 |
remote-tools 里,MCP 只存在于 Janus ↔ agent 之间,对客户端始终是标准的 tool_calls / tool_use —— 客户端不用懂 MCP。
自用配置(可直接抄)
这是我们自己在用的一份 janus.env(已脱敏,路径请改成你自己的):
1 | # 监听与鉴权 |
切 native 模式:
BRIDGE_AGENT=build+BRIDGE_TOOL_CALLING=false。
切 none 模式:BRIDGE_AGENT=orchestrator+BRIDGE_TOOL_CALLING=false。OPENCODE_REUSE_EXTERNAL=false让 Janus 总是自己拉起 OpenCode —— 这是「自动注入 agent 配置」生效的前提。
一个叫 janus 的虚拟模型
痛点很具体:很多 IDE 用自定义模型名时没法设置思考档位(low/high/max),换模型还得改配置文件。
于是加了:
- 一个**虚拟模型
janus**:映射到/ui面板里选定的默认模型; - 面板「模型」页每行「设为 janus」;「思考档位」列是点选按钮组(点一下即设、当前高亮);
- 客户端/IDE 里模型名固定填
janus,换模型/换档位在面板点一下,不用改 env、不用改客户端。
关键是切换时机:面板改完,下一条请求就原地切换(Janus 调 POST /api/session/{id}/model),不重开会话、上下文保留——不需要等会话结束,也不用新开会话。
解析优先级:面板选择(存 DB) > BRIDGE_DEFAULT_MODEL > 上游默认。default / auto / 留空仍是默认别名:优先使用 BRIDGE_DEFAULT_MODEL,未设置时跟随上游默认;真实 provider/id 仍原样透传。两套语义都保留,互不干扰。
Claude Code:快速接入
Janus 同时实现了 Anthropic Messages API,Claude Code / Anthropic SDK 直接指向它:
1 | export ANTHROPIC_BASE_URL=http://127.0.0.1:2810 |
Claude Code 只会用 claude-opus* / claude-sonnet* / claude-haiku* 这几个档位名,所以不用逐个映射模型:
- 多数用户只需一个开关:
BRIDGE_DEFAULT_MODEL=opencode-go/gpt-6-luna,所有档位都走它; - 想分档位(opus 用强模型、haiku 用便宜快的)用
BRIDGE_MODEL_MAP,且只需映射 3 个档位(支持*前缀通配):
1 | BRIDGE_MODEL_MAP=claude-opus*=opencode-go/deepseek-v4-pro,claude-sonnet*=opencode-go/deepseek-v4.1-flash,claude-haiku*=opencode-go/glm-5.3-flash |
janus modelsCLI 列出上游全部模型(价格 / 上下文 / 能力),末尾直接给出三个档位的映射结果,复制即用。- Claude Code 声明的
web_search由 Janus 服务端执行(调上游/api/websearch),不会甩回客户端;OpenAI Responses 的{"type":"web_search"}同一实现。 x-claude-code-session-id头自动作为会话锚点,不同 CC 会话天然隔离。
跨设备共享(scope)
客户端大多不给「会话 id」(Trae / Copilot / CodeBuddy 都不给)。开启 BRIDGE_SCOPE_KEY=true 后,Janus 按 scope = IDE + 项目 定位会话:
- 同 IDE + 同项目(跨设备)→ 同一会话;不同项目 / 不同 IDE → 隔离;
- 项目识别取各客户端 firstUser 的权威字段(Trae 的
Primary working directory、CodeBuddy 的Workspace Folder、Copilot 的following folders),也可用BRIDGE_PROJECT/BRIDGE_PROJECT_MAP显式指定; - 共享会话独立 TTL(
BRIDGE_SHARED_SESSION_TTL,默认24h),普通会话仍 30m——跨设备共享想留更久没冲突。
远程部署时客户端项目路径在 Janus 主机上不存在,会自动落到 BRIDGE_WORKSPACES_DIR/<scope> 的中性空目录,避免 agent 误认项目、也避免上游 500。
稳定性:本周补上的几块硬骨头
跑得久才会暴露的问题,这几天集中修了一轮:
- 流式空闲超时(
BRIDGE_STREAM_IDLE_TIMEOUT,默认120s):此前流式路径没有服务端超时,上游 agent 卡住时客户端会一直挂到自己断开(实测挂过约 15 分钟)。现在超过这么久没有真实数据(正文/推理 delta、工具调用、上游事件)就中断并收尾——心跳不算数据,一直有输出的长回答不受影响。 - 工具调用等待分两档:只读/编辑类工具(Read/Grep/Glob…)秒回,卡住基本是客户端卡死;走
BRIDGE_TOOL_CALL_WAIT_FAST(默认90s)快速判失败把错误还给模型继续,不再干等 5 分钟撞上 IDE 自身超时。 - 工具桥 id 对不上:有的客户端用自己生成的
tool_call_id,现在按「精确 id → 工具名 → 顺序」三级对齐,且只匹配当前这一轮。 - 「下一轮工具目录为空」:不再每轮注销 MCP,改为会话存活期内保持注册。
- 出站 User-Agent:默认
janus/<version>替代 Go 默认的Go-http-client/1.1(容易被网关/风控当脚本拦掉),可用BRIDGE_USER_AGENT覆盖。
部署前先划清安全边界
Janus 背后接的是能读写文件、执行命令的 Agent,不是普通的模型转发器:
- 默认监听
127.0.0.1;需要远程访问时,优先用 SSH 隧道、VPN 或 Tailscale,不要直接裸露公网。 - 监听
0.0.0.0时必须设置强BRIDGE_API_KEY;Janus 本身不提供 TLS,公网部署要套 HTTPS 反向代理。 native模式的工具以 Janus 进程用户身份在服务端执行;remote-tools虽然把工具放到客户端,内置 MCP 端点仍建议用BRIDGE_MCP_ALLOW限制来源。BRIDGE_PERMISSION_REPLY=once是较保守的默认值;always会把授权写入 OpenCode 的持久权限。
可观测:不用开官方 console
启动后打开 http://127.0.0.1:2810/ui 即可进入内置面板;页面本身是静态页,数据请求仍按 API Key 鉴权。/v1/requests + /ui 提供逐条请求的缓存命中率、思考 token、耗时、费用,支持搜索/排序/分组汇总。面板拆成了 用量 / 最近请求 / 模型 / 运行 几个标签页。
用量/余额需要读取 OpenCode 本地凭据库并访问 console;这部分不可用时不影响对话功能。
Token 统计同时给出 OpenAI 的 prompt_tokens_details.cached_tokens 与 DeepSeek 风格的 prompt_cache_hit_tokens / prompt_cache_miss_tokens。/v1/usage 还合并了 console 的余额/按天消耗与 Go 套餐三窗口限额(5h 滚动 / 周 / 月)。
一周的节奏
v0.1.0(10-03)到 v0.3.15(10-06),四天:
| 日期 | 版本 | 关键词 |
|---|---|---|
| 10-03 | v0.1.0 | OpenAI 兼容壳、会话分桶、自动发现 |
| 10-04 | v0.2.0 | Anthropic API、Responses 续链、SQLite 持久化 |
| 10-05 | v0.3.0–0.3.3 | 自动拉起上游、用量面板、orchestrator 自动注入 |
| 10-06 | v0.3.4–0.3.15 | 虚拟模型 janus、scope 跨设备共享、跨平台发布、稳定性收尾 |
结语
如果你也在把各种 coding agent 往自己的系统里接,欢迎试试 Janus:它不替你造 agent,只把 agent 管好。
(本文对应版本:v0.3.15,2026-10-06。)