SDK
OpenCode JS/TS SDK gir en typesikker klient for samhandling med serveren. Bruk den til å bygge integrasjoner og kontrollere OpenCode programmatisk.
Finn ut mer om hvordan serveren fungerer. For eksempler, sjekk ut prosjektene bygget av fellesskapet.
Installer SDK fra npm:
npm install @opencode-ai/sdkOpprett en forekomst av OpenCode:
import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()Dette starter både en server og en klient
Alternativer
| Alternativ | Type | Beskrivelse | Standard |
|---|---|---|---|
hostname | string | Server vertsnavn | 127.0.0.1 |
port | number | Serverport | 4096 |
signal | AbortSignal | AbortSignal for avbrudd | undefined |
timeout | number | Tidsavbrudd i ms for serverstart | 5000 |
config | Config | Konfigurasjonsobjekt | {} |
Du kan sende et konfigurasjonsobjekt for å tilpasse virkemåten. Forekomsten henter fortsatt din opencode.json, men du kan overstyre eller legge til konfigurasjon inline:
import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-sonnet-5-5",
},
})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()Hvis du allerede har en kjørende forekomst av OpenCode, kan du opprette en klientforekomst for å koble til den:
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({
baseUrl: "http://localhost:4096",
})Alternativer
| Alternativ | Type | Beskrivelse | Standard |
|---|---|---|---|
baseUrl | string | URL av serveren | http://localhost:4096 |
fetch | function | Egendefinert fetch-implementasjon | globalThis.fetch |
parseAs | string | Metode for responsparsing | auto |
responseStyle | string | Returstil: data eller fields | fields |
throwOnError | boolean | Kast feil i stedet for retur | false |
SDK inkluderer TypeScript-definisjoner for alle API-typer. Importer dem direkte:
import type { Session, Message, Part } from "@opencode-ai/sdk"Alle typer er generert fra serverens OpenAPI-spesifikasjon og tilgjengelig i type-filen.
SDK kan gi feil som du kan fange opp og håndtere:
try {
await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
console.error("Failed to get session:", (error as Error).message)
}Du kan be om strukturert JSON-utdata fra modellen ved å spesifisere et format med et JSON-skjema. Modellen vil bruke et StructuredOutput-verktøy for å returnere validert JSON som samsvarer med skjemaet ditt.
const result = await client.session.prompt({
path: { id: sessionId },
body: {
parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Company name" },
founded: { type: "number", description: "Year founded" },
products: {
type: "array",
items: { type: "string" },
description: "Main products",
},
},
required: ["company", "founded"],
},
},
},
})
// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }| Type | Beskrivelse |
|---|---|
text | Standard. Standard tekstrespons (ingen strukturert utdata) |
json_schema | Returnerer validert JSON som samsvarer med det angitte skjemaet |
Når du bruker type: 'json_schema', oppgi:
| Felt | Type | Beskrivelse |
|---|---|---|
type | 'json_schema' | Påkrevd. Spesifiserer JSON-skjemamodus |
schema | object | Påkrevd. JSON Schema-objekt som definerer utdatastrukturen |
retryCount | number | Valgfritt. Antall valideringsforsøk (standard: 2) |
Hvis modellen ikke klarer å produsere gyldig strukturert utdata etter alle forsøk, vil svaret inkludere en StructuredOutputError:
if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Failed to produce structured output:", result.data.info.error.message)
console.error("Attempts:", result.data.info.error.retries)
}- Gi klare beskrivelser i skjemaegenskapene dine for å hjelpe modellen med å forstå hvilke data som skal trekkes ut
- Bruk
requiredfor å spesifisere hvilke felt som må være til stede - Hold skjemaer fokuserte - komplekse nøstede skjemaer kan være vanskeligere for modellen å fylle ut riktig
- Angi passende
retryCount- øk for komplekse skjemaer, reduser for enkle
SDK-en eksponerer alle server-API-er gjennom en typesikker klient.
| Metode | Beskrivelse | Svar |
|---|---|---|
global.health() | Sjekk serverstatus og versjon | { healthy: true, version: string } |
Eksempler
const health = await client.global.health()
console.log(health.data.version)| Metode | Beskrivelse | Svar |
|---|---|---|
app.log() | Skriv en loggoppføring | boolean |
app.agents() | List alle tilgjengelige agenter | Agent[] |
Eksempler
// Write a log entry
await client.app.log({
body: {
service: "my-app",
level: "info",
message: "Operation completed",
},
})
// List available agents
const agents = await client.app.agents()| Metode | Beskrivelse | Svar |
|---|---|---|
project.list() | List alle prosjekter | Project[] |
Eksempler
// List all projects
const projects = await client.project.list()
| Metode | Beskrivelse | Svar |
|---|---|---|
path.get() | Hent gjeldende bane | Path |
Eksempler
// Get current path information
const pathInfo = await client.path.get()| Metode | Beskrivelse | Svar |
|---|---|---|
config.get() | Hent konfigurasjonsinformasjon | Config |
config.providers() | List leverandører og standardmodeller | { providers: Provider[], default: { [key: string]: string } } |
Eksempler
const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()| Metode | Beskrivelse | Merknader |
|---|---|---|
session.list() | List økter | Returnerer Session[] |
session.get({ path }) | Hent økt | Returnerer Session |
session.children({ path }) | List barneøkter | Returnerer Session[] |
session.create({ body }) | Opprett økt | Returnerer Session |
session.delete({ path }) | Slett økt | Returnerer boolean |
session.update({ path, body }) | Oppdater øktegenskaper | Returnerer Session |
session.init({ path, body }) | Analyser appen og lag AGENTS.md | Returnerer boolean |
session.abort({ path }) | Avbryt en kjørende økt | Returnerer boolean |
session.share({ path }) | Del økten | Returnerer Session |
session.unshare({ path }) | Slutt å dele økten | Returnerer Session |
session.summarize({ path, body }) | Oppsummer økten | Returnerer boolean |
session.messages({ path }) | List meldinger i en økt | Returnerer { info: Message, parts: Part[]}[] |
session.message({ path }) | Hent meldingsdetaljer | Returnerer { info: Message, parts: Part[]} |
session.prompt({ path, body }) | Send melding | body.noReply: true returnerer UserMessage (kun kontekst). Standard returnerer AssistantMessage med AI svar. Støtter body.outputFormat for strukturert utdata |
session.command({ path, body }) | Send kommando til økt | Returnerer { info: AssistantMessage, parts: Part[]} |
session.shell({ path, body }) | Kjør en shell-kommando | Returnerer AssistantMessage |
session.revert({ path, body }) | Tilbakestill en melding | Returnerer Session |
session.unrevert({ path }) | Gjenopprett reverserte meldinger | Returnerer Session |
postSessionByIdPermissionsByPermissionId({ path, body }) | Svar på en tillatelsesforespørsel | Returnerer boolean |
Eksempler
// Create and manage sessions
const session = await client.session.create({
body: { title: "My session" },
})
const sessions = await client.session.list()
// Send a prompt message
const result = await client.session.prompt({
path: { id: session.id },
body: {
model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
parts: [{ type: "text", text: "Hello!" }],
},
})
// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
path: { id: session.id },
body: {
noReply: true,
parts: [{ type: "text", text: "You are a helpful assistant." }],
},
})| Metode | Beskrivelse | Svar |
|---|---|---|
find.text({ query }) | Søk etter tekst i filer | En rekke matchobjekter med path, lines, line_number, absolute_offset, submatches |
find.files({ query }) | Finn filer og kataloger etter navn | string[] (baner) |
find.symbols({ query }) | Finn symboler i arbeidsområdet | Symbol[] |
file.read({ query }) | Les en fil | { type: "raw" | "patch", content: string } |
file.status({ query? }) | Hent status for sporede filer | File[] |
find.files støtter noen få valgfrie søkefelt:
type:"file"eller"directory"directory: overstyr prosjektroten for søketlimit: maksimalt antall resultater (1–200)
Eksempler
// Search and read files
const textResults = await client.find.text({
query: { pattern: "function.*opencode" },
})
const files = await client.find.files({
query: { query: "*.ts", type: "file" },
})
const directories = await client.find.files({
query: { query: "packages", type: "directory", limit: 20 },
})
const content = await client.file.read({
query: { path: "src/index.ts" },
})| Metode | Beskrivelse | Svar |
|---|---|---|
tui.appendPrompt({ body }) | Legg til tekst i prompten | boolean |
tui.openHelp() | Åpne hjelpedialogen | boolean |
tui.openSessions() | Åpne øktvelgeren | boolean |
tui.openThemes() | Åpne temavelgeren | boolean |
tui.openModels() | Åpne modellvelgeren | boolean |
tui.submitPrompt() | Send inn gjeldende prompt | boolean |
tui.clearPrompt() | Tøm prompten | boolean |
tui.executeCommand({ body }) | Utfør en kommando | boolean |
tui.showToast({ body }) | Vis toast-varsel | boolean |
Eksempler
// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})| Metode | Beskrivelse | Svar |
|---|---|---|
auth.set({ ... }) | Angi autentiseringsinformasjon | boolean |
Eksempler
await client.auth.set({
path: { id: "anthropic" },
body: { type: "api", key: "your-api-key" },
})| Metode | Beskrivelse | Svar |
|---|---|---|
event.subscribe() | Strøm av server-sendte hendelser | Strøm av server-sendte hendelser |
Eksempler
// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
console.log("Event:", event.type, event.properties)
}