# @codeworksh/cli 中文文档

规范地址：https://npmcn.com/package/%40codeworksh/cli/

版本：0\.9\.0
npm 元数据更新时间：2026-11-15T06:16:02.611Z
中文译文更新时间：2026-11-15T06:17:33.174Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codeworksh/cli
原文对照：https://npmcn.com/package/%40codeworksh/cli/?lang=original
项目主页：https://www.codework.sh/
源码仓库：https://github.com/codeworksh/codework

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

- 包体积（解压后）：822 kB，95 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.14\.1
- 运行依赖：9 个
- 首次发布：2026-09-18T04:02:27.818Z
- 最新版本发布：2026-11-15T06:16:02.232Z
- 近 30 天下载量：16463（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：172（近 12 个月 172 个）

## 中文简介

运行 CodeWork 编码代理吊带的 CLI.

## 安装

```sh
npm install @codeworksh/cli
```

也可以使用：`pnpm add @codeworksh/cli`、`yarn add @codeworksh/cli`、`bun add @codeworksh/cli`

## README

# @ codeworksh/ cli (英语)

在您的 repo 或沙盒中运行编码代理会话 .

## 安装

```bash
pnpm add -g @codeworksh/cli
# or run directly
pnpm dlx @codeworksh/cli <command>
```

安装后,每个命令都是 `codework <command>`。 。 。 .

## 发展

从 `packages/codework`,或 `pnpm cli` 在还原根上:

```bash
pnpm start -- --help
pnpm start -- models
pnpm start -- run "Inspect the failing tests"
```

`start` 运行 `src/index.ts` 与 `--conditions=development` 因此工作空间软件包解析为源。 发表 `codework` 二进制是包装 `dist` 建设.

* * *

## 图标

### `codework run`

快速运行代理会话 .

```bash
# Start a new session
codework run "Inspect and fix the failing tests"

# Create a session with explicit provider and model
codework run --provider openai --model gpt-5.5 --thinking high "Plan database migration"

# Continue an existing session (its main thread)
codework run --session ses_01a070f0 "Now implement the migration script"

# Continue one of its threads
codework run --session ses_01a070f0 --thread thr_01a071c2 "Try it without the cache"

# Run in an isolated sandbox (local, daytona, vercel, memory, sqldb)
codework run --sandbox-driver daytona "Inspect repository"
codework run --sandbox-driver daytona --sandbox-provider-id <remote-id> "Continue in sandbox"
```

#### 旗帜 :

-   `--server <url>` ——连接运行中的RPC服务器,例如. `ws://127.0.0.1:7433/rpc/v1`。 。 。 .
-   `-s, --session <id>` 继续现有的会议.
-   `--thread <id>` - 线索 `--session` 继续:线程标识,或 `main` (默认).
-   `-C, --cwd <path>` 新的会议工作目录.
-   `--sandbox-driver <driver>` - 沙盒驱动程序(`local`, (中文(简体) ), `daytona`, (中文(简体) ), `vercel`, (中文(简体) ), `memory`, (中文(简体) ), `sqldb`) (中文(简体) ). 默认 : `local`。 。 。 .
-   `--sandbox-id <id>` - 重新使用现有的沙箱实例;与驱动/提供方坐标相互排斥.
-   `--sandbox-provider-id <id>` - 提供现有远程沙盒的标识.
-   `--provider <id>` ——型号目录提供者ID.
-   `--model <id>` ——型号标识.
-   `--thinking <level>` ——该模型在回答前使用的合理努力(`off`, (中文(简体) ), `minimal`, (中文(简体) ), `low`, (中文(简体) ), `medium`, (中文(简体) ), `high`, (中文(简体) ), `xhigh`, (中文(简体) ), `max`) (中文(简体) ).

全球旗帜 : `--user-config-dir`, (中文(简体) ), `--home`, (中文(简体) ), `--database`。 。 。 .

* * *

### `codework thread`

会话包含一个或多个线程: `main` 绳子,还有叉子 这些命令会与运行中的服务器交谈( C)`--server`默认值 `http://127.0.0.1:7433`) (中文(简体) ).

```bash
# List a session's threads with their model and usage
codework thread list ses_01a070f0

# Start a new thread through an entry, or just before a prompt to send it again
codework thread fork ses_01a070f0 --at <entry-id>
codework thread fork ses_01a070f0 --thread thr_01a071c2 --before <entry-id>

# Move one thread into another checkout of the project, keeping its position under it;
# the rest of the session stays where it is
codework session relink ses_01a070f0 --thread thr_01a071c2 -C ~/work/api
```

`thread fork` 打印新线索ID,然后用于 `--before` 它漏掉的提示文本. `--json` 打印电线表.

* * *

### `codework serve`

启动一个拥有会话和沙盒的持久服务器 :

```bash
codework serve --host 127.0.0.1 --port 7433
codework run --server ws://127.0.0.1:7433/rpc/v1 "Inspect the failing tests"
codework run --server ws://127.0.0.1:7433/rpc/v1 --session <id> "Now fix them"
codework run --server ws://127.0.0.1:7433/rpc/v1 --sandbox-id <sandbox-id> "Start another session in this sandbox"
```

默认地址是 `127.0.0.1:7433`· ; `--port 0` 选择可用的端口并打印实际的 URL。 设定 `--home`, (中文(简体) ), `--database`,以及 `--user-config-dir` 在服务器上。 模型证书,插件,和工作目录由服务器解决. 远程运行不会启动本地的管子.

事件是活的,而不是重播。 客户端在承认其及时性之前订阅,并在渲染后等待执行完成. 丢失的连接和溢出会失败命令; 断开服务器工作运行 。 Ctrl-C发送 `thread.interrupt`,它会阻止运行引起的线程。 远程运行打印沙盒ID以供再利用 . `thread.interrupt` 返回时 `{ interrupted }` 一旦接受停站; `thread.wait` 是单独的清理屏障 `session.interrupt` 停止每条会话的线索。 一个繁忙的时期报告自己 `session.execution.started` 接下来是其中之一 `succeeded`, (中文(简体) ), `failed`,或 `interrupted` - 失败包含一个类别(`provider-authentication-error`, (中文(简体) ), `model-not-found-error`, (中文(简体) ), `sandbox-mount-error`,) 客户端生成的,中断是包含用户还是服务器关闭. 管理沙盒在明确停止或服务器关闭之前仍可使用;外部沙盒不停止.

V0 端点没有认证;其默认绑定为回放. 插件通过声明来发布自己的事件类型(`Plugin.define({ events: [...] })`名称空格 `plugin.<plugin-id>.*`);饲料携带这些并跳过没有声明的类型. 已申报类型的无效有效载荷因打入编码出错而失效.

* * *

### `codework auth login|status|refresh|logout`

用您的 ChatGPT 账户签名到 OpenAI Codex , 或者用您的 GitHub 账户签名到 GitHub copilot 。 全权证书为: 存储在所选的代码工作之家下, 当运行使用时自动加载 `openai-codex` 或者说 `github-copilot` 型号.

```bash
# Sign in
codework auth login --openai-codex
codework auth login --github-copilot

# Codex without a local callback port (SSH, containers, port 1455 in use)
codework auth login --openai-codex --device

# Inspect credential metadata without printing tokens
codework auth status --openai-codex
codework auth status --github-copilot

# Renew an expired login, or clear one
codework auth refresh --openai-codex
codework auth logout --github-copilot

# Authenticate the home owned by a running RPC server
codework auth login --openai-codex --server ws://127.0.0.1:7433/rpc/v1
```

`--home` 与代码安装的其他部分一起继续认证; `--auth-file` 覆盖证书 直接存档。 两个供应商共用一个 `auth.json`由供应商按键,所以签出一个 离开另一个单独. 与 `--server`, CLI 本地运行交互登录 -- -- 浏览器调用和设备提示都需要此 终端 - 并且只将由此产生的证书发送给 RPC 服务器进行存储.

**OpenAI 代码** 有两个流动。 默认保存 Aikit 的注册 `http://localhost:1455/auth/callback` 重定向, 并返回到请求重定向的 URL , 如果召回没有到达 . `--device` 而不是打印要输入的代码 时间 `auth.openai.com/codex/device` 完全不需要本地端口——在SSH上,在集装箱内,或当另一个集装箱内使用 注册已经持有1455。 该端口被针对 OAuth 客户端注册的重定向所固定,因此无法移动.

**GitHub 副驾驶** 使用 GitHub 设备流程: CLI 打印一个用户代码, 打开 `github.com/login/device`,并等待着. 信物没有过期,所以没有 `--refresh` - 再签401分. `--enterprise <domain>` 登录到 GitHub 企业主机,以及 `--enable-models` 打开账户未配置的目录模型 . 登录记录了计划特定的副驾驶 API 主机,它后来运行使用来代替目录默认.

* * *

### `codework models`

列出目录模型为 `provider/model`每行一个.

```bash
# List all models across all providers
codework models

# List models for a specific provider
codework models --provider openai

# List all supported provider IDs
codework models providers
```

* * *

### `codework models refresh`

模型目录住在 `<home>/models.gen.json` (单位:千美元)`~/.codework` 除非 `--home` 说不然). 每个本地命令在使用前检查,并在使用时间超过15分钟后下载新的(`CODEWORK_MODELS_TTL`,比如说. `"1 hour"`(三); `codework serve` 也可以每分钟重新检查一次,每当文件更改时就重新加载。 下载失败保留了上一个目录 .

```bash
# Download the catalog if it is missing or stale; no network call otherwise
codework models refresh

# Download it now
codework models refresh --force
```

* * *

### `codework plugin add` 编号 : `codework plugin remove`

安装插件并记录在设置文件中, 或者把它取回 。 范围如下: 项目是默认的, `-g` 是全用户的.

```bash
# This project: edits .codework/settings.jsonc, creating .codework/ here if no ancestor has one
codework plugin add @acme/codework-tool-proc@1.2.0

# Every project this user runs: writes ~/.codework/settings.jsonc
codework plugin add @acme/codework-tool-proc@1.2.0 -g

# Remove it, along with any configuration written against it
codework plugin remove @acme/codework-tool-proc
```

工程的发现方式是绳索的找到方式,而Git的发现方式是: 最近的祖先持有a `.codework` 目录。 从 `packages/app`,命令编辑 仓库本身 `.codework/settings.jsonc` 而不是在旁边启动第二个项目。 一个 空 `.codework/` 足够了——标记是目录,所以创建它就是你说的 项目从这里开始。 当没有祖先时, `add` 创建 `.codework/` 在目录中您是 输入并打印路径,因为这决定了以后每个插件的输入位置.

`add` 在写入任何内容前安装并导入模块, 因此一个不是插件的 spec 失败, 且文件不受影响; 它打印的行名为插件 ID 模块实际宣布。 添加一个已配置在另一个拼写下的插件—— a 不同的版本,或者用路径代替软件包——重写已设置的条目而不是 留下第二个装货机,路 `npm install pkg@2` 更新已记录的光谱. 在插件上写入的配置则留在原地 。 编辑保存注释、密钥顺序和格式,并写入 通过临时文件, 中断的运行无法切换您的设置 .

`remove` 将模块条目和任何指定同一插件的配置对象,以何者为准 拼写时,每个拼写都用:它加入的版本不是其身份的一部分 ID 模块宣布删除装入的条目。 解析一个ID读取安装的内容 从来不拿任何东西。 插件也可以保留,但关闭时不移除,使用 `{ "plugin": "acme.tool.proc", "enabled": false }`。 。 。 .

#### 旗帜 :

| 旗帜 | 说明 |
| :-- | :-- |
| `-g`, (中文(简体) ), `--global` | 编辑全用户设置文件而不是此工程的 |
| `--home` | 该全用户文件所在的地方( 默认 ): `CODEWORK_HOME_DIR`,则 `~/.codework`(中文(简体) ) |
| `--user-config-dir` | 编辑 `<dir>/settings.jsonc`; 排名高于上述两项 |

插件条目在设置层间累积,所以在 a 宣布自己的项目。 一个想要继承的插件消失的工程本身就这么说了 文件,与 `{ "plugin": "<id>", "enabled": false }`。 。 。 .

* * *

## 环境变量

| 变量 | 说明 |
| :-- | :-- |
| `CODEWORK_MODELS_FILE` | 将目录绑入您管理的文件; 从未自动刷新 |
| `CODEWORK_MODELS_TTL` | 目录在刷新前可能要多久( 默认) `15 minutes`(中文(简体) ) |
| `OPENAI_API_KEY` | OpenAI 模型的 API 密钥 |
| `ANTHROPIC_API_KEY` | Anthropic 模型的 API 密钥 |
| `OPENROUTER_API_KEY` | OpenRouter 模型的 API 密钥 |
| `GOOGLE_GENERATIVE_AI_API_KEY` | 谷歌模型的 API 密钥 |
| `XAI_API_KEY` | XAI 模型的 API 密钥 |

* * *

## 许可证

麻省理工学院

## 常见问题

### @codeworksh/cli 是什么？

运行 CodeWork 编码代理吊带的 CLI\.

### 如何安装 @codeworksh/cli？

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

### @codeworksh/cli 支持 TypeScript 吗？

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

### @codeworksh/cli 支持 ESM 还是 CommonJS？

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

### @codeworksh/cli 需要什么版本的 Node\.js？

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

### @codeworksh/cli 可以商用吗？

@codeworksh/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @codeworksh/cli 的下载量有多少？

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

### @codeworksh/cli 还在维护吗？

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