# @freestyle-sh/with-opencode 中文文档

规范地址：https://npmcn.com/package/%40freestyle-sh/with-opencode/

版本：0\.0\.14
npm 元数据更新时间：2026-05-02T21:48:24.673Z
中文译文更新时间：2026-11-15T13:25:16.842Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40freestyle-sh/with-opencode
原文对照：https://npmcn.com/package/%40freestyle-sh/with-opencode/?lang=original

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

- 包体积（解压后）：13.3 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-01-29T22:43:44.385Z
- 最新版本发布：2026-04-21T19:25:34.733Z
- 近 30 天下载量：11281（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

[打开代码](https://opencode.ai/) 合并 [自由风格](https://freestyle.sh/) 页:1 在您的 Freestyle VM 中提供一个完全配置的 OpenCode AI 编码助理服务器 .

## 安装

```sh
npm install @freestyle-sh/with-opencode
```

也可以使用：`pnpm add @freestyle-sh/with-opencode`、`yarn add @freestyle-sh/with-opencode`、`bun add @freestyle-sh/with-opencode`

## README

# @ freestyle-sh/ 有打开代码

[打开代码](https://opencode.ai/) 合并 [自由风格](https://freestyle.sh/) 页:1 在您的 Freestyle VM 中提供一个完全配置的 OpenCode AI 编码助理服务器 .

## 安装

```bash
bun add @freestyle-sh/with-opencode freestyle
```

## 使用量

### 基本设置

```typescript
import { freestyle, VmSpec } from "freestyle";
import { VmOpenCode } from "@freestyle-sh/with-opencode";

const { vm } = await freestyle.vms.create({
  spec: new VmSpec({
    with: {
      opencode: new VmOpenCode(),
    },
  }),
});

// Expose the web UI
const { url } = await vm.opencode.routeWeb();
console.log(`OpenCode UI: ${url}`);
```

### 使用 API 客户端

```typescript
const { client } = await vm.opencode.client();

// Use the OpenCode SDK client to interact with the server
const sessions = await client.session.list();
```

### 带有自定义域

```typescript
const { url } = await vm.opencode.routeWeb({
  domain: "my-opencode.example.com",
});

const { client } = await vm.opencode.client({
  domain: "my-opencode-api.example.com",
});
```

### 有认证

```typescript
import { freestyle, VmSpec } from "freestyle";
import { VmOpenCode } from "@freestyle-sh/with-opencode";

const { vm } = await freestyle.vms.create({
  spec: new VmSpec({
    with: {
      opencode: new VmOpenCode({
        server: {
          username: "serveradmin",
          password: "secret-server-pass",
        },
        web: {
          username: "webadmin",
          password: "secret-web-pass",
        },
      }),
    },
  }),
});

// URLs will include credentials automatically
const { url } = await vm.opencode.routeWeb();
const { client } = await vm.opencode.client();
```

## 选项

```typescript
new VmOpenCode({
  server: {
    port: 4096, // Optional: API server port (default: 4096)
    username: "admin", // Optional: Basic auth username (default: "opencode" when password is set)
    password: "secret", // Optional: Basic auth password
  },
  web: {
    port: 4097, // Optional: Web UI port (default: 4097)
    username: "admin", // Optional: Basic auth username (default: "opencode" when password is set)
    password: "secret", // Optional: Basic auth password
  },
  env: {
    ANTHROPIC_API_KEY: "sk-ant-...", // Optional: Environment variables for OpenCode
  },
});
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `server.port` | `number` | `4096` | OpenCode API 服务器的端口 |
| `server.username` | `string` | `"opencode"` | 基本认证用户名( 仅在密码设定时使用) |
| `server.password` | `string` | \- 说吧 | API 服务器的基本认证密码 |
| `web.port` | `number` | `4097` | OpenCode 网络用户界面端口 |
| `web.username` | `string` | `"opencode"` | 基本认证用户名( 仅在密码设定时使用) |
| `web.password` | `string` | \- 说吧 | Web UI 的基本认证密码 |
| `env` | `Record<string, string>` | `{}` | 环境变量传递到 OpenCode 进程 |

## 环境变量

OpenCode要求API密钥与AI提供者互动. 在 Freestyle VM 中运行时,使用 `env` 选项.

> **说明:** 环境变量作为纯文本被存储在VM的启动脚本中. 直接或间接访问VM的用户可以查看这些值. 使用适当范围化的API密钥,并在VM共享或被曝光时旋转.

| 变量 | 说明 |
| --- | --- |
| `ANTHROPIC_API_KEY` | Claude 模型的 API 密钥 |
| `OPENAI_API_KEY` | OpenAI 模型的 API 密钥 |
| `OPENROUTER_API_KEY` | OpenRouter 的 API 密钥 |

见 [打开代码提供者](https://opencode.ai/docs/providers/) 对所有支助提供者及其环境变量.

```typescript
const { vm } = await freestyle.vms.create({
  spec: new VmSpec({
    with: {
      opencode: new VmOpenCode({
        env: {
          ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
        },
      }),
    },
  }),
});
```

## API 密码

### `vm.opencode.routeWeb(options?)`

在公有领域曝光 OpenCode Web UI.

**选项 :**

-   `domain?: string` - 需要使用的自定义域。 如果未指定,则生成一个随机子域.

**回返情况:** `Promise<{ url: string }>` - 如果配置了认证, URL 包括证书 .

```typescript
const { url } = await vm.opencode.routeWeb();
console.log(`OpenCode UI available at: ${url}`);
```

### `vm.opencode.client(options?)`

创建连接到服务器的 OpenCode SDK 客户端. 如果启用认证, 客户端会自动配置证书 .

**选项 :**

-   `domain?: string` - 自定义 API 端点域。 如果未指定,则生成一个随机子域.

**回返情况:** `Promise<{ client: OpencodeClient }>`

```typescript
const { client } = await vm.opencode.client();

// List sessions
const sessions = await client.session.list();

// Create a new session
const session = await client.session.create({ path: "/workspace" });
```

### `vm.opencode.serverPort()`

返回已配置的 API 服务器端口 .

**回返情况:** `number`

### `vm.opencode.webPort()`

返回配置的 Web UI 端口 .

**回返情况:** `number`

## 如何运作

软件包使用系统化服务在VM创建期间安装并运行OpenCode:

1.  通过正式安装脚本安装 OpenCode
2.  启动 OpenCode API 服务器( )`opencode serve`(中文(简体) )
3.  启动 OpenCode 网络 UI ()`opencode web`(中文(简体) )

这两个服务都被配置为自动重启,并在所有接口上收听(0.0.0.0).

## 文档

-   [免费文档](https://docs.freestyle.sh/)
-   [打开代码文档](https://opencode.ai/docs)

## 常见问题

### @freestyle-sh/with-opencode 是什么？

打开代码 合并 自由风格 页:1 在您的 Freestyle VM 中提供一个完全配置的 OpenCode AI 编码助理服务器 \.

### 如何安装 @freestyle-sh/with-opencode？

在项目目录运行 npm install @freestyle-sh/with-opencode，或使用 pnpm add / yarn add / bun add。

### @freestyle-sh/with-opencode 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @freestyle-sh/with-opencode 支持 ESM 还是 CommonJS？

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

### @freestyle-sh/with-opencode 可以商用吗？

@freestyle-sh/with-opencode 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @freestyle-sh/with-opencode 的下载量有多少？

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

### @freestyle-sh/with-opencode 还在维护吗？

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