# @cabane/companion 中文文档

规范地址：https://npmcn.com/package/%40cabane/companion/

版本：0\.6\.232
npm 元数据更新时间：2026-11-08T21:34:19.670Z
中文译文更新时间：2026-11-08T22:54:27.715Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cabane/companion
原文对照：https://npmcn.com/package/%40cabane/companion/?lang=original
项目主页：https://cabane.ai/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：10 个
- 首次发布：2026-08-01T18:48:41.216Z
- 最新版本发布：2026-11-08T21:34:19.481Z
- 近 30 天下载量：14274（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：226（近 12 个月 226 个）

## 中文简介

Cabane Companion（无头）：将您的机器上的代理连接到您的Cabane工作区，作为响应器-针对您自己的代码库，文件和MCP服务器驱动工作，而无需将任何内容放在Cabane中。

## 安装

```sh
npm install @cabane/companion
```

也可以使用：`pnpm add @cabane/companion`、`yarn add @cabane/companion`、`bun add @cabane/companion`

## README

# 卡贝恩

Cabane公司负责你的Cabane特工 使用你选择的装置 它从 Cabane 接收他们的作品, 启动一个控制装置 和回回流。 该电机呼叫其配置的模型提供者;代理商使用其环境可用的本地文件,工具和证书.

用这个 **克劳德代码**, (中文(简体) ), **代码** 或者说 **打开代码**。软件包包括 Claude Code 和 Codex 执行二进制,但设置不运行销售商 CLI 安装器,也不将您签入。 OpenCode需要自己的运行中的服务器.

开始 [卡巴内公司](https://cabane.ai/docs/cabane-companion),则 [宏设置](https://cabane.ai/docs/mac-setup), (中文(简体) ), [窗口设置](https://cabane.ai/docs/windows-setup) 或者说 [服务器和 VPS 设置](https://cabane.ai/docs/server-and-vps-setup)。 。 。 . [FAQ 和帮助](https://cabane.ai/docs/faq-and-help) 盖入入入入入入出出事. 此 README 是设备边参考:命令,配置和当地状态.

配对提供设备代号 而不是你的卡班密码或全账代号 设备代号是用于此设备的任务和活性;被指派的代理接收工作空间所限的证书. 这个 [信任指南](https://cabane.ai/docs/cabane-companion) 解释层层,记录和访问.

## 安装

在装置上,在一个终端。 其中一个:

```sh
curl -fsSL https://cabane.ai/install.sh | bash
```

脚本会带自己的节点( 检查和检查, 输入) `~/.cabane`),不需要苏道. 或,随着22号节点或更新已经在那里(Windows上唯一的路径):

```sh
npm i -g @cabane/companion && cabane setup
```

`cabane setup` 在未发光设备上打印代码和链接:

```
Pair this device
Enter this code in Cabane, or press Return to open the page:

  WXYZ-2345
  https://app.cabane.ai/pair/enter-code

⠋ Waiting for you to confirm in Cabane… (the code is good for 15 minutes)
```

在 Cabane 中输入代码, 作为您自己签名 : 从您的设置 —— 设备 —— 添加一个设备, 从工作空间的设置 —— 设备 —— 设置一个新的设备, 或者在链接打开的页面上 。 Cabane 显示要哪个设备; 确认它配对到您的账户, 而不是其他设备 。 一个工作空间的对话框然后将设备添加到该工作空间;从其他任何地方,将其添加到该工作空间的设置~设备的工作空间. 从一个工作区对齐 一旦一个带子可以使用 你就会在设备上设置默认代理.

没有终端,设置出相同的行并等待一次,所以容器的日志会携带代码. 一个已过期的代码被新代码所取代,最多可有3个; Ctrl-C stops cleanly. 链接位于服务器上设备对:通过 `--server <url>` 为了你自己的 Cabane.

从交互式终端开始,然后在后台启动伴奏,等待其首次登入并报告设备状态. 没有交互终端,设置将保留在运行中的伴奏上.

如果无法使用, 交互式设置会询问您要设置哪个 。 跟踪完整的CLI安装和登录步骤 [宏设置](https://cabane.ai/docs/mac-setup#2-sign-in), (中文(简体) ), [窗口设置](https://cabane.ai/docs/windows-setup#2-sign-in) 或者说 [服务器和 VPS 设置](https://cabane.ai/docs/server-and-vps-setup#2-sign-in-without-a-browser),然后检查 `cabane status`。 。 。 .

```
✓ Paired as "maya-mbp".
  Cabane is running in the background. This device is ready — checked in 2s ago.

  Harnesses on this device
  ✓ Claude Code   connected — signed in (2.1.289)
    Codex         needs sign-in — run  codex login
    OpenCode      off — not running

  Status  cabane status     Stop  cabane stop     Log  cabane logs
  Start at login and keep Cabane updating itself:  cabane service install

  In Cabane: https://app.cabane.ai/settings/devices
```

设置从不安装服务 。 在macOS或Linux上运行 `cabane service install` 当您想要从登录开始并不断更新时;关闭的块名。 原生Windows使用背景过程,没有服务安装器.

若为 `cabane` 之后找不到,打开一个新的终端,或者运行 `source` 行设置已打印.

这个 [服务器指南](https://cabane.ai/docs/server-and-vps-setup) 提供本地构建的 Dockerfile 和 Compose 示例。 它的多克文件安装了Company和所有三个命令行工具;您在容器内签名。 遵循指南对接并启动多克环境.

## 图标

| 命令 | 它会做什么 |
| --- | --- |
| `setup` | 被解开:打印出一个代码进入Cabane,等待确认,然后检测被套并开始. Paired:一个可重新运行的核对表,它报告控制并开始一些没有运行的东西. |
| `start [--foreground]` | 发起无上菩提. 从交互式终端,在背景中运行;非交互式使用可能保持连接. 解开,它的名字 `setup`。 。 。 . `--foreground` 为你的上司留有联系. |
| `stop` | 止住同道清净. 结束任何进展. |
| `status` | 版本和安装, 配对设备的卡巴内名称, 它的状态在卡巴内的话, 当它最后一次检查时, 每个绳子的状态, 特工在那里工作, 宣布秘密名称, 和本地覆盖. |
| `update [--auto on|off]` | 现在就安装 Cabane 版本名称; 使用 `--auto`,确定同伴是否保持最新状态. |
| `service install|uninstall|status` | 运行为系统化的用户服务或启动代理,在登录时启动,如果停止则重新启动;删除;显示状态. |
| `logs [-n N] [-f]` | 最近的日志行,或跟随. |
| `transcript [file] [--last] [-f]` | 回读一个完整的代理回合,包括工具呼叫和结果. |
| `logout [--purge]` | 删除设备符和缓存代理证书 。 没有移除 Cabane 的装置. |

任何关于设备的其他事情都发生在卡巴内,在设备的页面上.

## 继续运行

对于直接安装,重启或坠机 离开伴星停止到下一个 `cabane start` 除非你已经安装了服务。 在服务下, 如果它停止并开始用户会话( 在 macOS 上登录; 允许 Linux 上的内存在登录后操作) , 它会重新启动, 并遵循 Cabane 的版本名称: 它安装新版本 `~/.cabane/versions`,检查它开始,然后转换到它,它可以在转弯时重新启动伴奏。 无法启动的版本被后卫滚回. `cabane update --auto off` 停止更新; 没有服务, `cabane update` 安装和下一个 `cabane start` 运行它.

在本地窗口上, 请检查背景进程 `cabane status` 运行 `cabane start` 窗口重新启动后。 如果您在 Docker 外安装了 OpenCode, 请保持其服务器单独运行; Companion 的服务不监督它.

对于多克克来说,保持自动Companyion更新,并重建本地图像来更新Companyion并使用工具. 跟着 [服务器指南的更新步骤](https://cabane.ai/docs/server-and-vps-setup#keep-the-container-running-and-update)。 。 。 .

其他主管:运行 `cabane start --foreground` 与 `CABANE_COMPANION_SUPERVISED=1` 设定,使用绝对路径 `~/.cabane/node/bin/node` 财务报告和审定财务报表 `~/.cabane/current/dist/bin.js`,它不会移动 在更新.

为了直接安装,在 **旋转令牌** 在 Cabane 中,在设备上应用替换:

1.  运行 `cabane stop`。 。 。 .
2.  单位 `~/.cabane/config.json`,替换 `deviceToken` cabane显示的替换符.
3.  运行 `cabane start`。 。 。 .

对于多克,跟随 [旋转一个 Docker 设备的令牌](https://cabane.ai/docs/server-and-vps-setup#rotate-a-docker-devices-token)。 。 。 .

## 这个设备上有什么

全部放进去 `~/.cabane/`,模式 600,没有数据库。 卡班是真相的来源 特工们如何运作.

```
~/.cabane/
├── config.json       # pairing, local overrides
├── work/             # a directory per agent and conversation, for agents with no folder of their own
├── credentials.json  # per-agent workspace-bound credentials, delivered once
├── secrets.json      # { NAME: "value" } for ${NAME} placeholders
├── transcripts/      # one JSONL per turn, newest ~200 kept, local only
├── outbox/           # a reply survives a transient API outage
└── companion.log
```

### 秘诀

在 Cabane 名称中配置的 MCP 服务器证书为 `${NAME}`;该值永远不会离开设备。 同伴解决它从 `secrets.json` 在发送,决不从你的外壳环境, 和一个没有被宣布的名字 响亮地失败转弯。 它在心跳上报告所宣布的名字(从不表示值),因此卡巴内可以在转弯前发出警告.

没有键盘链或浏览器的设备,如服务器或容器,可以从 `secrets.json` 还有: `CLAUDE_CODE_OAUTH_TOKEN` 或者说 `ANTHROPIC_API_KEY` 克劳德代码, `CODEX_API_KEY` 用于 Codex. 只有转弯的自带 得到它的登录. `GH_TOKEN` 到达每一个转弯,因为 `gh` 并给HTTPS.

### 本地覆盖

`config.json` 可以携带,每个代理人(由id键, `@username` 或者说 `workspace-slug/username`或整个设备:

-   `cwd`: 胜过代理 **开始于** cabane 设置了文件夹 .
-   `prepareHook`: 在每个回合前解决工作目录的命令; 胜过两者。 一个设备级的钩子适用于每一个不命名自己的代理人. 钩子被勾住 `CABANE_DEFAULT_CWD`,下面的目录, 对于一个只增加它的钩子.
-   `root`:当没有别人说的时候,特工们就在那里工作. 每个经纪人每一次谈话都有一个目录, `<root>/<workspace>/<agent>/<conversation>/`,在第一个转弯, 从来没有被同伴取走。 默认 `~/.cabane/work`绝对值,或 `~/…`在卡巴内没有文件夹的代理人,没有 `cwd` 没有钩子站在那里; 文件夹或 `cwd` 这不是一个已有的目录,而是通过日志中的行来传递.
-   `harnesses`: 诸如 `["claude-code"]`;缺席意味着全部三个.
-   `claudeCode.autoMemory`: Claude Code的本地内存目录默认在Companyion中被关闭,因为注释属于其他人可以读取它们的工作空间. `true` 把它拿回来.

错误的块失败 `cabane start` 与球场命名。 A 类 `runners` 块,一行 `sandbox`,或一个 `prepareHook`是因为 `validateCached` 或者说 `failureReporter` 从一个更古老版本的"伴奏"被忽略,在日志中有一行取名.

每个转弯的外壳 `CABANE_CONVERSATION_ID` 财务报告和审定财务报表 `CABANE_AGENT_ID`,所以一个代理运行的脚本可以知道它为哪个对话和代理工作.

### 每转一转

`runner.command` 在每个回合前都发出命令: `"runner": { "command": ["/usr/local/bin/enter-sandbox", "--fresh"] }` 以 `enter-sandbox --fresh <the Companion's own run-turn command>`。使用它来运行每个回合在自己的容器或VM中运行,而同伴则留在外面。 您的命令必须运行它的其他论点, 与环境 和辛丁它得到了.

一个被包裹的转弯 得到设备的秘密 在它的stdin而不是阅读 `secrets.json`,不会从同伴自己的环境中继承任何签名,也不会被外部的流程组显示:无论转折留下什么,您的命令都会结束.

您的命令可以依赖并且可以设置 :

| 变量 |  |
| --- | --- |
| `CABANE_DISPATCH` | 读取: 发送为 JSON, 包括 `conversationId` 财务报告和审定财务报表 `agentId`。 。 。 . |
| `CABANE_RUNNER_SPEC` | 读取: 回合设置为 JSON, 包括 `agentUsername`。 。 。 . |
| `CABANE_TURN_ID` | 读取:转会为id. |
| `CABANE_COMPANION_HOME` | 读取,当伴者开始 一个: 家园,它的 `.cabane` 目录在下面. |
| `CABANE_WORK_ROOT` | 设置:转弯工作目录下方的根,取而代之 `root`。 。 。 . |
| `CABANE_TRANSCRIPT_DIR` | 设定:转弯处会写出笔录. 下方为一级目录 `~/.cabane/transcripts/` 列表中 `cabane transcript`。 。 。 . |
| `CABANE_WORK_ROOT_DEDICATED` | 设定为 `1` 当根已经是一个谈话和代理的:转弯直接站在里面,下面没有每个对话目录. |

这些名字是一份合同:更改一个会打破你的指令,所以没有在发行时的注释,就不会改变.

### 将供应商证书保存在沙盒外

操作员管理的沙盒可以使用主机侧 `@cabane/companion/credential-broker` 模块。 这是对一个可信任的主机适配器的嵌入API,而不是通过在本地主机上收听而变得安全的代理. 适配器必须认证被接受的套接字为活沙箱实例,并在中止该实例时撤销其赠款。 共享的 UID 、 复制的占位符、 套接字文件名或 HTTP 标题不是实例身份 。 身份不明、模棱两可或改变必须归还 `null` 从 `resolveIdentity(socket)`。 。 。 .

在每个沙盒UID映射之外,在主机身份下运行经纪人及其证书文件. 在整个服务寿命期间,包括停机,都有一个专属的流程锁:每个账户文件必须有一个完全的更新所有者。 账户文件的父文件必须是该身份所拥有, 模式 `0700`; 文件必须是常规的,单链接 `0600` 文档。 在导入或更改登录状态前停止服务 . `fileCredentialStore(path)` 财务报告和审定财务报表 `openBrokerCredentials(store)` 读取该状态;在使用账户的每一笔赠款之间分享所得所有者。 更新写入并同步替换后再发布 。 一个失败的持久性写入拒绝进一步使用,直到操作员恢复所存储的账户.

账户格式为 `{ mode, accessToken, refreshToken?, idToken?, expiresAt?, accountId? }`。 。 。 . `mode` 实值 `claude-setup`, (中文(简体) ), `claude-oauth`, (中文(简体) ), `codex-oauth` 或者说 `github`。 OAuth 模式需要刷新令牌并用 epoch 毫秒表示过期。 一个设置的标志 永远不会更新。 正常克洛德·奥特在经纪人内部更新到到期前,或者在上游的一个401; Codex续作将新的占位符返回给客户. 交换失败后,所有者拒绝更新后退窗口,30秒将翻倍到15分钟,而不是在每次请求时在上游重试;成功更新即可清除. 永远不要在沙盒内放置真实的账户文件,一个证书存储绑定,或者一个备用的吊带登录. 真实的 OAuth 兼容性必须与已安装的带和登录模式进行校验;一个成功的设置托肯转会无法证明 OAuth 更新 .

创建经纪人 `createCredentialBroker({ resolveIdentity, audit? })`。 。 `server` 处理模型和 git 路由; 仅将其绑定为主机回路。 Git 的 HTTP 代理请求只被接受 `http://github.com/` ,然后转发到固定的HTTPS GitHub上游. 任意代理目的地和CONNECT地道被拒绝. 内容 `githubServer` 处理 gh 的 `http_unix_socket` 传输; 认证套接字的对等点 。 也没有暴露管理端点。 打电话 `grant({ identity, credentials, expiresAt })` 仅来自信任的主机适配器. `credentials` 地图 `claude`, (中文(简体) ), `codex` 财务报告和审定财务报表 `github` 给相应的证书拥有者。 回来的 `token` 有可支配性; `revoke()` 中止活动请求并删除其别名。 解散电话 `revokeIdentity(identity)`; 服务关闭呼叫 `revokeAll()` 并关闭两个服务器。 重启会创造新的赠款,所以旧的占地者停止工作.

在 GitHub 侧面覆盖 GitHub 令牌; 经纪人没有强制执行寄存器、 分支、 PR- 动作或 GraphQL- 形状政策 .

设定 `runner.brokeredCredentials: true` 旁边 `runner.command` 在伴奏的设定中。 这在包装器收到前,将供应商和GitHub证书变量从发射装置的环境、秘密储存有效载荷和装置授予有效载荷中移除。 包装用品 `brokerClientConfiguration({ baseUrl, placeholder, githubSocket, codexConfig })`环境和生成的配置到被隔离的家庭,并写 `await grant.codexAuth()` 仅作为其占位符代码x `auth.json`。帮助者在选择经纪人提供者和 HTTP 响应传输时保留所提供的 Codex 设置。 将它的git配置包含在沙盒的全局配置中,并使用它的gh配置在那里. 对于一个 GitHub 启用的盒子, 提供 `githubSocket`。帮助设置 `GH_TOKEN` 保留 `github.com` 在git的扩展远程 所以gh可以解析一个有轨分支, 不设置 `GH_REPO`。生成的 git 配置将 HTTPS URL 重写到只包含一个占位符的 HTTP GitHub URL, 并使用 Git 的 per 源代码通过回路经纪发送源代码 `http.proxy`; 经纪人的上游跳仍然为HTTPS. 安装整个生成的配置,替换之前生成的文件,而不是保留更古老的重写. 不要绕过此代理 `NO_PROXY` 或一个 per- 远端代理 覆盖 。 对于只使用模型的框,请省略 `githubSocket` 或通过 `null`;没有 GitHub 环境被排放,而且 git/gh 配置字符串都是空的, 因此适配器可以清除任何先前生成的路由 。 包装器必须删除旧的证书挂载和替代认证帮助器; 此切换无法检查或保证操作员的文件系统挂载 .

固定的上游主机是 `api.anthropic.com`, (中文(简体) ), `chatgpt.com`, (中文(简体) ), `api.github.com` 财务报告和审定财务报表 `github.com`. 路径和请求机构在没有工作流程政策的情况下通过,但已知的证书识别、证书登记或披露终点除外: Claude CLI API 密钥创建和 OAuth 令牌交换, ChatGPT会话/token 披露,以及 GitHub app 通称转换,安装/应用令牌端点, 遗留授权, SSH 用户/部署令牌注册, 跑者注册/移除/JIT证书和 OAuth/device 令牌端点. 这些回声过滤器无法事先知道新的秘密, 或登记盒式选择的证书, 当提供者添加证书返回或证书登记路线时,必须重新审查这一拒绝列表;它不是防止未知终点或任意编码的保证。 重定向被拒绝,并被过滤为已知的证书回声. 免证书注射仅限于Codex指定的 `/backend-api/ps/mcp` 路线。 包括流在内的每个上游交易所,默认以10分钟为上限(`requestTimeoutMs` 打开 `createCredentialBroker`在64个小米B处要求尸体.

任意的房间秘密和其他MCP证书仍然遵循他们现有的交货合同. 此 API 不保护 SSH 密钥, 也不向任意的 HTTP 目的地提供一般的秘密注入 。 克洛德的特性旗在他们直接请求使用占位符时会回落到默认状态. 在允许沙盒部署之前,核查实际的套接字所有权、PID/namespace再利用、服务UID分离、给予撤销、同时更新和重新启动、所需的客户操作以及从真正的沙盒内提取金丝雀的尝试。 成功的单元测试或包安装不能确定主机边界.

### 权限

Companyion通过钩子批准克洛德代码的工具,并批准OpenCode许可请求;没有回合等待工具批准对话框. 对于 Codex 它会禁用批准, 当您的配置设置顶级时 `sandbox_mode`,不通过沙盒旗;没有这种设置 `danger-full-access`。选择代理运行地点 [代理访问](https://cabane.ai/docs/agent-access),然后通过 [磁带沙盒](https://cabane.ai/docs/harness-sandboxes)。 。 。 .

## 调试转弯

Cabane显示了对话;设备也保存了详细的本地记录. 每一回都写满了溪流 `~/.cabane/transcripts/`:工具列表,每个工具调用及其结果,文本,结果. 一个失败的转动的日志行名 .

```sh
cabane transcript --last   # render the most recent turn
cabane transcript          # list recent turns
cabane transcript -f       # live-watch turns as they land
cabane logs -f             # follow the log
```

`cabane start --log-level debug` 或者说 `"logLevel": "debug"` 内 `config.json` 更多; `--log-format json` 为机器可读行.

## 还没有

原生Windows没有安装服务,也没有自我更新. 卡巴内没有每个工具的许可。 控制剂通过环境 和它自己的环境进入.

## 常见问题

### @cabane/companion 是什么？

Cabane Companion（无头）：将您的机器上的代理连接到您的Cabane工作区，作为响应器-针对您自己的代码库，文件和MCP服务器驱动工作，而无需将任何内容放在Cabane中。

### 如何安装 @cabane/companion？

在项目目录运行 npm install @cabane/companion，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cabane、cabane-companion，可以用 npx cabane 直接运行。

### @cabane/companion 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cabane\_\_companion 是否存在。

### @cabane/companion 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cabane/companion 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cabane/companion 可以商用吗？

@cabane/companion 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @cabane/companion 的下载量有多少？

根据 npm 官方下载统计，@cabane/companion 在 2026/10/09 – 2026/11/07 这 30 天内被下载 14,274 次，日均约 476 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cabane/companion 还在维护吗？

最新版本 0\.6\.232 发布于 2026/11/09（今天）；至今共发布 226 个版本，其中过去 12 个月发布了 226 个；首次发布于 2026/08/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。