托管工具调用的是公网 HTTPS 端点,因此无法把 localhost 上的端点保存到工具上。modelriver tools 在你开发期间弥补了这一差距:它接收你的请求的工具调用,并转发到你的机器。
需要 @modelriver/cli 2.0 或更高版本(Node.js 22.12 或更高版本)。
用法
modelriver tools --forward-to http://localhost:3000CLI 会与你的 API 密钥所属的项目建立一个会话,并打印其 id(cts_…)。保持它运行,然后任选其一:
- 在 Playground(Async mode)中打开 Send tool calls to my CLI,或
- 在你后端发出的
POST /v1/ai/async请求中加入"tool_route": {"cli_session": "cts_…"}。
每次调用都会被 POST 到你机器上与工具已保存端点相同的路径:保存为 https://api.example.com/tools/orders 的工具,会在 http://localhost:3000/tools/orders 被调用。
选项
| 选项 | 说明 |
|---|---|
--forward-to <url> | 你的工具服务器运行的位置。必须在本机:localhost、127.0.0.1 或 ::1。http 和 https 均可 |
--print | 同时打印每次调用的参数和你的端点的结果。默认关闭 |
--new-session | 开启一个新会话,而不是重新加入本机保存的会话 |
-k, --api-key <key> | 使用该 API 密钥,而不是已保存的密钥 |
--api-url <url> | 使用该 ModelRiver API,而不是 https://api.modelriver.com |
-v, --verbose | 显示连接详情 |
你的端点会收到什么
与线上调用发送的请求相同:相同的 JSON 请求体(逐字节一致)和相同的 x-modelriver-* 请求头,并用项目的工具签名密钥签名。请像在生产环境中那样验证它。请求体的 request 中带有 "via": "cli"。
你的端点照常应答(端点契约)。CLI 会把状态和响应体送回 ModelRiver,在那里按与任何调用相同的规则、大小限制和超时来读取应答。通过 CLI 的调用不会重试。
对会更改内容的工具的调用仍会先等待审批(在 Playground 中由你自己审批),然后通过 CLI 发送一次。如果那时会话已经结束,这次调用不会执行,模型会被告知该工具不可用。
重启 CLI
会话保存在你的机器上的 ~/.modelriver/tool-sessions.json 中,只有你可以读取。当你用相同的 API 密钥和 --forward-to 再次启动 modelriver tools 时(包括它被强制终止之后),它会重新加入该会话,而不是开启新会话:
- 已经指定该会话的请求可以继续使用,等待审批的调用在获批后会到达重启后的 CLI。
- 会话 id 只在会话开启时完整打印一次。重启后它以掩码形式显示(
cts_…1234)。 - 上一次运行已经发送到你的服务器的调用,绝不会再次发送给它。ModelRiver 也不会把同一个调用发送第二次:CLI 停止时正在进行的调用会超时,对于会更改内容的工具,其结果会被记录为未知。
- 如果保存的会话已无法加入(已过期或已被移除),CLI 会说明这一点并开启一个新会话,使用新的 id。如果该组织未开启托管工具,CLI 会给出相应提示并停止,同时保留已保存的会话以便日后使用。
- 用相同的 API 密钥和
--forward-to启动的第二个modelriver tools会接管该会话,第一个随即停止。需要独立的会话时请传入--new-session。
在终端中审批调用
对会更改内容的工具的调用会等待其终端用户。测试用你的 API 密钥发出的请求时,你可以在第二个终端中以该用户的身份作答,就像你的后端那样:
modelriver tools show tc_3f2a9c1d5b7e4a6f8c0d1e2bmodelriver tools approve tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812modelriver tools reject tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812show会打印审批提示、终端用户看到的参数以及等待结束的时间(GET /v1/ai/tool-calls/:call_id)。approve和reject会发送决定(POST /v1/ai/tool-calls/:call_id/approve或/reject)。--end-user必填,且必须是发出请求时使用的end_user.id。- Playground 运行中的调用要在 Playground 中决定。对这些调用,上述命令会返回
tool_call_not_found。 - 每条命令成功时以
0退出,失败时以1退出。
要一次完成发送请求并跟进,请使用带 --end-user 和 --cli-session 的 modelriver websocket:它会打印每个等待中的调用以及用于决定它的命令。
安全
- CLI 只会转发到你自己的机器。任何其他地址都会被拒绝,且不会跟随重定向。
- 会话属于 API 密钥所在的项目以及该密钥的所有者,24 小时后过期。请求只能指定自己项目的会话,Playground 只会提供用你创建的 API 密钥开启的会话。
- 每人每个项目最多可同时连接 5 个会话。开启新会话会占用已不再连接的会话的名额。
tools不会使用当前文件夹中.modelriverrc里的 API 密钥:克隆的仓库可能植入另一个账户的密钥,该账户就能把调用发送到你的机器。请使用MODELRIVER_API_KEY、-k或modelriver login。- 当 CLI 没有运行时,指定了它的会话的请求会被拒绝,如果它中途停止,后续的调用会立即失败。调用绝不会改为发送到保存的端点。
- 你的生产端点应拒绝带有
"via": "cli"的调用:会话会收到完整的签名调用。 - 除非传入
--print,否则不会打印参数和结果。 - 部署前请移除
tool_route:生产请求绝不应指定 CLI 会话。