内容
发[](https://github.com/openclaw/turnwire/actions/workflows/ci.yml)
[](LICENSE器是一种经过审计的纯文本MCP中调用者通过一个`talk`工具发送文本，配置的语言模型生成文本，然后转发器记录这两个消息后再返回回复器仅暴露一个能力：text
talk(text, request_id?, conversation_id?) -> reply receipt
```
它不暴露shell命令、浏览器控制、MCP资源、MCP提示或模型工具。对话ID关联消息，但在版本1中不添加模型侧的内存。
## 架构
```text
MCP客户端或代理
│ MCP请求和响应
▼
操作员选择的传输
│ 在跨主机时外部认证
▼
转发器服务 ──► 聊天完成或响应文本模型
│
└── 仅追加的audit.jsonl
```
转发器通过标准输入和标准输出提供MCP服务。它不打开网络监听器、认证调用者或建立隧道。当客户端和转发器在不同主机上运行时，请在适合您环境的认证传输后面放置转发器。
## 快速入门
要求：
- macOS或Linux。Windows构建，但运行时审计存储故意关闭，直到实现仅所有者DACL强制执行。
- macOS构建必须启用cgo，以便可以检查本机ACL；禁用cgo的二进制文件编译，但在运行时关闭。
- Go 1.25或更高版本。
- 非流式聊天完成或响应兼容端点。默认情况下，llama](https://ollama.com/)在环回上提供公共[`gpt-oss:20b`](https://ollama.com/library/gpt-oss)模型。
```bash
mkdir -p ./bin
go build -o ./bin/turnwire ./cmd/turnwire
ollama pull gpt-oss:20b
./bin/turnwire init
./bin/turnwire doctor --probe
```
要使用OpenAI GPT模型，请设置`OPENAI_API_KEY`并初始化OpenAI预设。它使用响应API，禁用提供者侧的响应存储，并默认为`gpt-5.5`。GPT-4也支持`--model gpt-5.4`bash
./bin/turnwire init --provider openai
./bin/turnwire doctor --probe
```
对于GPT-5.4：
```bash
./bin/turnwire init --provider openai --model gpt-5.4
./bin/turnwire doctor --probe
```
`init`写入一个限制性的每用户JSON配置文件，并创建审计目录。它从不写入API密钥。为使用通用JSON MCP服务器形状的客户端配置MCP客户端，以`serve`参数启动绝对二进制路径。对于客户端：
```json
{
"mcpServers": {
"turnwire": {
"command": "/绝对路径/to/turnwire/bin/turnwire",
"args": ["serve"]
}
}
}
```
确切的外部配置格式取决于客户端。
进程仅将MCP JSON-RPC写入标准输出。诊断信息发送到标准错误流；消息内容发送到审计日志。为了保持非调用SDK队列的有界性，每个标准输入/输出会话在16个入站通知或响应后关闭；重新连接以启动新的会话。
### 可选：OpenAI安全MCP隧道
[OpenAI安全MCP隧道](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)是一种可选的公共传输集成。其公共[`tunnel-client`](https://github.com/openai/tunnel-client)可以启动转发器作为本地标准输入/输出MCP服务器：
```bash
tunnel-client init \
--sample sample_mcp_stdio_local \
--profile turnwire \
--tunnel-id TUNNEL_ID \
--mcp-command "/绝对路径/to/turnwire/bin/turnwire serve"
tunnel-client doctor --profile turnwire --explain
tunnel-client run --profile turnwire
```
遵循公共指南进行隧道创建、权限和工作区关联。隧道不是转发器的一部分，可以使用其他身份验证传输代替。
## 命令行界面
```text
turnwire init [选项] 创建配置和审计存储
turnwire serve 通过标准输入/输出提供MCP服务
turnwire doctor [--probe] 验证配置、存储和模型访问
turnwire log list 列出已记录的交换
turnwire log show ID 显示一个交换
turnwire log verify 验证完整的审计哈希链
turnwire version 打印构建信息
```
人类可读的日志命令转义终端控件。`log list`仅保留交换元数据，而`log list --json`包括确切的已记录UTF-8正文。两种模式都强制执行16 MiB的内存预算，用于选定的最新记录；较旧的历史记录在不保留的情况下进行验证。如果选定的窗口超过预算，请减少`--limit`或使用`--conversation`进行筛选。JSON记录在完整审计链验证后一次发出一条。
## 配置
默认配置是仅本地的：
```json
{
"version": 1,
"provider": {
"api": "chat_completions",
"endpoint": "http://127.0.0.1:11434/v1/chat/completions",
"model": "gpt-oss:20b"
},
"limits": {
"max_input_bytes": 16384,
"max_output_bytes": 16384,
"max_audit_bytes": 268435456,
"timeout": "120s",
"max_concurrent": 1
}
}
```
远程提供者需要HTTPS和显式的`allow_remote`选择。如果提供者需要承载令牌，请将`api_key_env`设置为环境变量的名称；请勿将值放在配置文件或命令行标志中。参见[配置](docs/configuration.md)。
## 审计行为
每个接受的请求在模型执行前都会被写入并同步。每个回复在成功返回前都会被写入并同步。此顺序取决于操作系统、文件系统和存储设备是否遵循其文档化的`fsync`语义；这不是针对有故障或恶意的存储的保证。
条目包含确切的UTF-8内容、SHA-256内容摘要、单调序列和到前一条目的哈希链接。如果验证检测到格式错误或修改的链，服务会拒绝启动，并且排他文件锁防止合作的转发器进程写入相同的日志。
审计路径通过验证的目录描述符打开。失败或不确定的追加或同步会使该活动句柄失效：在关闭和成功同步、验证重新打开之前，不允许回复查找或日志读取。独立的日志命令需要排他恢复锁，因此在转发器写入器活动时拒绝读取。请求ID在重新启动后仍然可通过扫描已验证的日志使用。活动紧凑的幂等性元数据保留在；已完成回复正文按需从其索引读取和验证。
编码日志默认容量为256 Mi条目在写入前会根据确切的序列化大小进行接收；配额耗尽是一种干净的错误，不会破坏验证或日志检查。转发器不会自动删除或审计历史记录。在服务停止时，请在自己的保留策略下存档或替换日志。要在耗尽后恢复，请保留旧目录及其最终审计头，然后在重新启动前将`audit_dir`指向新的绝对所有者专用目录（或存档旧目录并重新创建配置的路径）。
`doctor --probe`是唯一的运行时例外：它向提供者发送固定的、非用户提供的健康检查文本，丢弃模型文本，并且不记录中继交换。
本地哈希链可以检测到许多修改，但不能防止主机管理员替换或截断整个日志。如果该威胁对您的部署很重要，请独立检查或签名审计头。
## 开发
```bash
go test -race ./...
go vet ./...
go build ./cmd/turnwire
```
普通的Go构建从Go工具链嵌入的模块和VCS元数据中填充`turnwire version --json`，包括工作树是否被修改。当VCS状态不可用时，JSON省略`modified`，而不是声称源树是干净的。发布构建可以使用链接器标志提供权威值。保持Go的VCS标记启用，以便_dirty发布检查保留可见；发布自动化也应需要干净的树。使用源修订时间而不是墙上时钟构建时间，保持相同发布输入的出处字段稳定：
```bash
VERSION=v1.2.3
REVISION="$(git rev-parse HEAD)"
REVISION_TIME="$(git show -s --format=%cI HEAD)"
go build -trimpath \
-ldflags="-X github.com/openclaw/turnwire/internal/buildinfo.Version=${VERSION} -X github.com/openclaw/turnwire/internal/buildinfo.Commit=${REVISION} -X github.com/openclaw/turnwire/internal/buildinfo.BuildTime=${REVISION_TIME}" \
-o ./bin/turnwire ./cmd/turnwire
```
在扩大协议范围之前，请阅读[威胁模型](docs/threat-model.md)。文件访问、工具执行、附件传输和非请求的网络功能在版本1中故意不在范围内。
## 许可证
转发器可在 [MIT 许可证](LICENSE) 下使用。
