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
2
3
4
5
6
7
OpenAI / Anthropic 客户端
│ 标准 /v1/* 请求
▼
Janus:鉴权、模型路由、会话映射、工具桥、流式转换
│ OpenCode HTTP API + SSE
▼
OpenCode Agent:推理与工具编排(工具按模式执行)

客户端每轮通常会重新发送完整的 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
2
3
4
5
VERSION=v0.3.15
curl -LO https://github.com/qist/janus/releases/download/$VERSION/janus_${VERSION}_linux_amd64.tar.gz
tar xzf janus_${VERSION}_linux_amd64.tar.gz
sudo install -m 0755 janus_linux_amd64 /usr/local/bin/janus
janus --version

桌面用户直接用 macOS / Windows 包:macOS 拆好了 darwin/amd64 与 darwin/arm64(Intel / Apple Silicon);Windows 的 zip 解压即用,数据目录也各自遵循了平台惯例(macOS ~/Library/Application Support/janus,Windows %LOCALAPPDATA%\janus)。

方式二:源码编译

1
2
3
4
git clone https://github.com/qist/janus.git
cd janus
make build # 自动注入版本号(git tag / VERSION 文件)
sudo install -m 0755 janus /usr/local/bin/janus

依赖:Go 1.26+;上游需要已安装 OpenCode(未装时 Janus 会在日志里提示安装命令)。

方式三:Docker / systemd

1
2
3
4
5
# Docker(distroless 非 root 静态镜像)
docker build -t janus https://github.com/qist/janus.git

# systemd:仓库自带加固单元
# deploy/janus.service

运行

1
2
3
4
5
6
# 0. 先装 OpenCode(Janus 的上游 agent;未装时 Janus 会在日志里提示)
curl -fsSL https://opencode.ai/v2/install | bash

cp janus.env.example janus.env
$EDITOR janus.env # 最少只需改 BRIDGE_API_KEY;native 模式建议显式指定 BRIDGE_DIRECTORY
./scripts/run.sh # 启动 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 监听与鉴权
BRIDGE_ADDR=127.0.0.1:2810
BRIDGE_API_KEY=change-me-to-a-random-secret

# 会话默认工作目录。remote-tools 通常由客户端提供 X-OpenCode-Directory;
# native 模式建议显式指定,按需取消下一行注释
# BRIDGE_DIRECTORY=/path/to/your/project

# 执行模式:remote-tools(工具在客户端执行)
BRIDGE_AGENT=orchestrator
BRIDGE_TOOL_CALLING=true
BRIDGE_PERMISSION_REPLY=once
BRIDGE_TOOL_CALL_WAIT=5m

# 上游 OpenCode:自动发现;总是自己拉起(以便注入生成的 agent 配置)
OPENCODE_URL=auto
OPENCODE_REUSE_EXTERNAL=false

# 面板 / 限流
BRIDGE_USAGE_ENABLED=true
BRIDGE_RATE_LIMIT=600
BRIDGE_RATE_BURST=120
BRIDGE_LOG_LEVEL=info

切 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
2
3
export ANTHROPIC_BASE_URL=http://127.0.0.1:2810
export ANTHROPIC_AUTH_TOKEN=sk-bridge-dev
export ANTHROPIC_MODEL=claude-sonnet-4-5 # 档位名照常写,由 Janus 映射

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 models CLI 列出上游全部模型(价格 / 上下文 / 能力),末尾直接给出三个档位的映射结果,复制即用。
  • 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。)