OpenCode Server 模式接口

OpenDesk 当前实现了一个 opencode 兼容的 headless HTTP server 模式，用于让 opencode TUI 或兼容客户端连接 OpenDesk 的任务、模型、权限、MCP 和事件系统。

本文只描述 OpenDesk 当前真实实现的接口。opencode 原项目中存在但 OpenDesk 尚未实现的接口，会明确标注为未实现或占位。

启动方式

CLI 子命令：

opendesk serve --mode opencode --port 4096 --hostname 127.0.0.1

可用参数：

参数	默认值	说明
`--mode <mode>`	`opencode`	支持 `opencode` 与 `acp` 两种模式。`acp` 模式详见通过 ACP 协议使用 OpenDesk。
`--port <port>`	`4096`	HTTP 监听端口。
`--hostname <hostname>`	`127.0.0.1`	HTTP 监听地址。
`--cors <origins>`	未设置	允许的跨域源，逗号分隔。不设置时允许 `*`。
`--password <password>`	环境变量	启用 HTTP Basic Auth。也可用 `OPENCODE_SERVER_PASSWORD`。
`--username <username>`	环境变量或 `opencode`	Basic Auth 用户名。也可用 `OPENCODE_SERVER_USERNAME`。

启动时会初始化 CLI 平台、全局状态、内置 Agent、应用注册表和应用 Worker，然后启动 Hono HTTP server。

健康检查：

curl http://127.0.0.1:4096/global/health

响应：

{
    "healthy": true,
    "version": "0.2.0"
}

认证

如果未设置 password，所有请求直接放行，启动日志会打印警告。

如果设置了 password，所有非 OPTIONS 请求都需要 Basic Auth：

curl -u opencode:your-password http://127.0.0.1:4096/global/health

也支持用 query 参数传递 Basic Auth token：

?auth_token=<base64(username:password)>

认证失败时返回：

{
    "error": "Unauthorized"
}

HTTP 状态码为 401，并带 WWW-Authenticate: Basic realm="opendesk"。

CORS

server 允许的方法：

GET, POST, PUT, PATCH, DELETE, OPTIONS

允许的请求头：

Content-Type, Authorization, x-opencode-directory, x-opencode-sync

暴露的响应头：

x-opencode-sync, x-next-cursor, link

Workspace 路由

大多数实例级接口会解析当前工作目录。

优先级：

query 参数 directory
请求头 x-opencode-directory
平台当前有效工作空间
process.cwd() 兜底

directory 会先 URL decode，再 path.resolve()。

opencode workspace ID 和文件系统目录是分开的。OpenDesk 会读取：

query 参数 workspace
请求头 x-opencode-workspace

该值只作为 opencode workspace ID 透传到 session 信息中，不参与路径解析。

示例：

curl 'http://127.0.0.1:4096/path?directory=/repo/demo&workspace=wrk_123'

ID 映射

OpenDesk 内部任务 ID 使用 task_ 前缀，opencode session ID 使用 ses_ 前缀。server 路由会自动互转：

外部 ID	内部 ID
`ses_abc`	`task_abc`
`task_abc`	`task_abc`

其他 ID 前缀：

前缀	用途
`msg_`	message
`prt_`	message part
`evt_`	event
`per_`	permission request
`que_`	question request

错误格式

通用错误通常返回：

{
    "error": "message"
}

部分 opencode 兼容接口返回 opencode 风格错误对象，例如：

{
    "_tag": "PermissionNotFoundError",
    "requestID": "per_missing",
    "message": "Permission request not found: per_missing"
}

SSE 事件

OpenDesk 当前实现两个 SSE 事件流：

路径	说明
`GET /event`	实例事件流。
`GET /global/event`	全局事件流，opencode TUI 主要连接这个端点。

两个端点都使用 SSE event name message。

连接成功后立即发送 server.connected，之后每 10 秒发送 server.heartbeat。

/event 的 data 是 BusEvent：

{
    "id": "evt_connected_lx...",
    "type": "server.connected",
    "properties": {}
}

/global/event 的 data 是 GlobalBusEvent：

{
    "directory": "/repo/demo",
    "project": "proj_demo",
    "payload": {
        "id": "evt_connected_lx...",
        "type": "server.connected",
        "properties": {}
    }
}

常见事件类型包括：

类型	触发场景
`server.connected`	SSE 建连。
`server.heartbeat`	心跳。
`session.created`	创建 session。
`session.deleted`	删除 session。
`session.status`	session busy/idle 状态变化。
`session.aborted`	中止 session。
`message.updated`	message 元信息变化。
`message.part.updated`	流式 part 更新。
`permission.asked`	工具调用需要权限确认。
`permission.replied`	权限请求已回复。
`question.asked`	Agent 需要用户回答问题。
`question.replied`	问题已回答。
`question.rejected`	问题被拒绝。
`server.instance.disposed`	调用 dispose。

Global 接口

GET /global/health

返回 server 健康状态和版本。

{
    "healthy": true,
    "version": "0.2.0"
}

GET /global/event

全局 SSE 事件流。格式见“SSE 事件”。

GET /global/config

返回 opencode 兼容配置，等价于 GET /config。

响应示例：

{
    "model": "openai/gpt4o",
    "provider": {
        "openai": {
            "api": "openai",
            "options": {
                "apiKey": "sk-...",
                "baseURL": "https://api.openai.com/v1",
                "noProxy": false
            }
        }
    },
    "permission": {
        "read": "allow"
    }
}

PATCH /global/config

更新配置，逻辑等价于 PATCH /config。

支持两类 payload：

{
    "model": "openai/gpt4o",
    "provider": {
        "openai": {
            "options": {
                "apiKey": "sk-...",
                "baseURL": "https://api.openai.com/v1",
                "noProxy": false
            },
            "enabled": false
        }
    }
}

或 OpenDesk 原生字段：

{
    "default_model": "gpt4o",
    "applications": {
        "search": {
            "defaultWebSearch": "bing"
        }
    }
}

发送 {} 或 { "config": {} } 会触发从磁盘重新加载 setting.json，刷新 skills 和当前任务上下文。

provider 的启用状态通过 OpenDesk 原生 providers[].enabled 保存。enabled: false 的 provider 不会出现在 /config、/config/providers、/provider 和 /provider/auth 中；未设置或 true 表示启用。

POST /global/dispose

发布 server.instance.disposed 事件，返回：

true

未实现

opencode 的 POST /global/upgrade 当前没有在 OpenDesk server 中注册。

Config 接口

GET /config

返回 opencode 兼容配置。

生成规则：

OpenDesk 字段	opencode 响应
`providers[].name`	`provider.<name>`
`providers[].api_key`	`provider.<name>.options.apiKey`
`providers[].base_url`	`provider.<name>.options.baseURL`
`providers[].no_proxy`	`provider.<name>.options.noProxy`
`providers[].enabled`	`false` 时该 provider 不输出；未设置或 `true` 时输出。
`default_model`	`model`，格式为 `<provider_name>/<alias>`
`permission`	原样输出

如果需要禁用某个 provider，请在 setting.json 的对应 providers[] 项里设置 "enabled": false。如果默认模型属于已禁用 provider，model 和默认 provider 映射都不会输出。

PATCH /config

更新配置。行为与 PATCH /global/config 一致。

opencode 风格 provider patch 会更新或新增 provider：

{
    "provider": {
        "openai": {
            "options": {
                "apiKey": "new-key",
                "baseURL": "https://new.example/v1",
                "noProxy": true
            },
            "enabled": false
        }
    }
}

model 可以是字符串：

{
    "model": "openai/gpt-4o"
}

也可以是对象：

{
    "model": {
        "providerID": "openai",
        "modelID": "gpt-4o"
    }
}

OpenDesk 会把它解析为本地 models[].alias。如果能根据 provider 和 model 名称匹配到本地模型，使用对应 alias；否则退回使用 model id。

GET /config/providers

返回配置中的 provider 列表和默认模型映射。

{
    "providers": [
        {
            "id": "openai",
            "name": "openai",
            "source": "config",
            "env": [],
            "options": {
                "baseURL": "https://api.openai.com/v1"
            },
            "models": {
                "gpt4o": {
                    "id": "gpt4o",
                    "providerID": "openai",
                    "name": "gpt-4o",
                    "status": "active"
                }
            }
        }
    ],
    "default": {
        "openai": "gpt4o"
    }
}

model 对象还包含 capabilities、cost、limit、headers 等字段。context_length 未配置时，limit.context 默认为 128000，limit.output 固定为 16384。

providers[].enabled === false 的 provider 会从该接口返回中过滤掉。可以先修改磁盘上的 setting.json，再调用 PATCH /config 或 PATCH /global/config 并发送 {} 或 { "config": {} } 触发 reload，随后请求 /config/providers 验证过滤结果。

Provider 接口

GET /provider

列出可用 provider。

{
    "all": [],
    "default": {},
    "connected": []
}

字段	说明
`all`	provider 列表，格式同 `/config/providers` 中的 provider 对象。
`default`	provider 到默认模型 alias 的映射。
`connected`	`api_key` 非空的 provider 名称列表。

GET /provider/auth

返回每个 provider 支持的认证方式。当前全部是 API Key：

{
    "openai": [
        {
            "type": "api_key",
            "description": "API Key authentication"
        }
    ]
}

未实现

以下 opencode OAuth 接口当前没有在 OpenDesk server 中注册：

接口	状态
`POST /provider/:providerID/oauth/authorize`	未实现
`POST /provider/:providerID/oauth/callback`	未实现

Instance 和 Bootstrap 接口

GET /path

返回路径信息。

{
    "directory": "/repo/demo",
    "home": "/home/user",
    "state": "",
    "config": "",
    "worktree": "/repo/demo"
}

GET /command

列出 Agent 支持的模式，返回数组：

[
    {
        "id": "main:standard",
        "name": "standard",
        "description": "..."
    }
]

GET /agent

列出所有 Agent：

[
    {
        "name": "main",
        "type": "main",
        "modes": [
            {
                "id": "standard",
                "description": "..."
            }
        ]
    }
]

GET /skill

列出用户可调用的 skills：

[
    {
        "name": "skill-name",
        "description": "description",
        "location": "bundle-or-directory",
        "content": "markdown body"
    }
]

返回内容包含已安装 skills、skillmgr.external_paths 扫描到的外部 skills，以及其它应用注册的用户可调用内置 skills。external_paths 会递归扫描包含 SKILL.md 的目录；外部 skill 的 location 是实际 skill 目录。修改磁盘配置后，可以通过 PATCH /config 或 PATCH /global/config 发送 {} / { "config": {} } 触发 reload，再请求该接口验证新增或移除的外部 skill。

POST /instance/dispose

当前只返回：

true

GET /project/current

返回当前项目信息：

{
    "id": "proj_demo",
    "name": "demo",
    "path": "/repo/demo",
    "directory": "/repo/demo"
}

Bootstrap stub

这些接口主要用于让 opencode TUI 启动过程不崩溃，当前返回占位数据：

接口	当前响应
`GET /vcs`	`{ "sha": "", "branch": "", "dirty": false, "root": "<directory>" }`
`GET /lsp`	`[]`
`GET /formatter`	`[]`
`GET /find`	`[]`
`GET /find/file`	`[]`
`GET /find/symbol`	`[]`
`GET /experimental/console`	`{ "consoleManagedProviders": [], "switchableOrgCount": 0 }`
`GET /experimental/resource`	`{}`
`GET /experimental/worktree`	`[]`
`GET /experimental/workspace`	`[]`
`GET /experimental/workspace/status`	`[]`
`POST /experimental/workspace/sync-list`	`[]`

GET /experimental/session

返回全局 session 列表，结构接近 GET /session。支持 query：

参数	说明
`roots=true`	只返回根 session。
`start=<timestamp>`	只返回创建时间大于等于该毫秒时间戳的 session。
`search=<text>`	按标题模糊过滤。
`limit=<n>`	返回最后 n 条。
`scope=project`	不按当前 directory 过滤。

Session 接口

Session 对象

OpenDesk 返回的 session 基本结构：

{
    "id": "ses_abc",
    "slug": "abc",
    "projectID": "proj_demo",
    "workspaceID": "wrk_123",
    "directory": "/repo/demo",
    "path": "",
    "title": "Task title",
    "version": "1",
    "agent": "explore",
    "time": {
        "created": 1710000000000,
        "updated": 1710000000000
    },
    "tokens": {
        "input": 0,
        "output": 0,
        "reasoning": 0,
        "cache": {
            "read": 0,
            "write": 0
        }
    },
    "cost": 0
}

如果是 fork 出来的子任务，会额外包含 parentID。

GET /session

列出 session。

支持 query：

参数	说明
`search=<text>`	按标题过滤。
`limit=<n>`	只返回最后 n 条。
`roots=true`	只返回没有父任务的 session。
`scope=project`	不按当前 directory 过滤。
`directory=<path>`	指定当前目录。
`workspace=<id>`	透传 workspace ID。

默认会按当前 directory 过滤。

GET /session/status

返回所有 session 状态映射：

{
    "ses_abc": {
        "type": "idle"
    },
    "ses_def": {
        "type": "busy"
    }
}

OpenDesk 内部 running 和 waiting 都映射为 busy，其他状态映射为 idle。

POST /session

创建 session。

请求示例：

{
    "title": "Fix tests",
    "workspaceID": "wrk_123",
    "model": {
        "providerID": "openai",
        "modelID": "gpt-4o"
    }
}

也支持顶层 providerID、modelID，或字符串 model: "openai/gpt-4o"。

创建时会初始化 OpenDesk task harness、权限提示器、ask-user 工具集、MCP workspace 和 system prompt，并发布 session.created 事件。

GET /session/:sessionID

获取 session 详情。不存在返回 404：

{
    "error": "Session not found"
}

PATCH /session/:sessionID

更新 session。当前支持：

字段	说明
`title`	更新任务标题。
`model` / `providerID` / `modelID`	更新该 task 使用的模型别名。

DELETE /session/:sessionID

删除 session，返回 true，并发布 session.deleted。

GET /session/:sessionID/children

返回子 session 列表。

GET /session/:sessionID/message

返回消息列表。

支持 query：

参数	说明
`limit=<n>`	最多返回 n 条。
`before=<messageID>`	返回指定 message 之前的消息。

当 limit 截断结果时，响应头会设置：

X-Next-Cursor: <messageID>
Link: <current-url>&before=<messageID>; rel="next"

消息格式：

{
    "info": {
        "id": "msg_abc",
        "sessionID": "ses_abc",
        "role": "assistant",
        "time": {
            "created": 1710000000000,
            "completed": 1710000000000
        },
        "modelID": "",
        "providerID": "",
        "mode": "default",
        "agent": "explore",
        "path": {
            "cwd": "/repo/demo",
            "root": "/repo/demo"
        },
        "cost": 0
    },
    "parts": []
}

GET /session/:sessionID/message/:messageID

返回单条消息。session 或 message 不存在时分别返回 404。

POST /session/:sessionID/message

同步发送消息，等待 OpenDesk task 完成后返回 assistant message。

请求体文本提取规则：

字段	支持格式
`parts`	字符串数组，或 `{ "type": "text", "text": "..." }` 数组
`prompt`	string 或 text parts
`message`	string 或 text parts

示例：

{
    "messageID": "msg_user_1",
    "model": {
        "providerID": "openai",
        "modelID": "gpt-4o"
    },
    "parts": [
        {
            "type": "text",
            "text": "帮我分析这个目录"
        }
    ]
}

行为：

确保 task harness 已初始化。
如果 task 正在运行，先等待上一轮完成。
根据请求体更新 task model。
发布 session.status busy。
发布用户 message.updated 和 message.part.updated。
调用 task.submitUserMessage(text)。
通过 waitUntilFinished 将流式 chunk 转换为 message.part.updated。
完成后发布 assistant message.updated 和 session.status idle。
返回最终 assistant message。

如果没有文本内容，返回 400：

{
    "error": "No message content"
}

POST /session/:sessionID/prompt_async

异步发送消息，立即返回 204。请求体文本规则同 POST /session/:sessionID/message。

后台仍会发布同样的 session.status、message.updated 和 message.part.updated 事件。

POST /session/:sessionID/abort

调用 task.stop("user") 中止 session，返回 true，并发布 session.aborted。

POST /session/:sessionID/fork

调用内部 task.fork() 创建子 session，并返回新 session 信息。

GET /session/:sessionID/todo

当前返回空数组：

[]

GET /session/:sessionID/diff

当前返回空数组：

[]

DELETE /session/:sessionID/message/:messageID

删除一条消息，返回 true。session 或 message 不存在时返回 404。

占位接口

接口	当前行为
`POST /session/:sessionID/command`	返回 400 `{ "error": "Commands not supported" }`
`POST /session/:sessionID/shell`	返回 400 `{ "error": "Shell not supported" }`

opencode 原生的 summarize、revert、permission response 等更多 session 接口当前没有在 OpenDesk server 中注册。

Message Part 转换

OpenDesk 会把内部消息 part 转换为 opencode part：

OpenDesk part	opencode part
`text`	`{ type: "text", text }`
`tool_call`	`{ type: "tool", callID, tool, state, input, output }`
`reasoning`	`{ type: "reasoning", text }`
`image`	`{ type: "file", mediaType: "image", url }`
`file`	`{ type: "file", file }`
`error`	`{ type: "text", text: "Error: ..." }`

工具状态映射：

OpenDesk 状态	opencode 状态
`pending`	`pending`
`running`	`running`
`success`、`result`	`completed`
`error`、`failed`	`error`
其他	`completed`

流式输出期间，同一 assistant message 中同一类型的 part 会使用稳定 part ID，便于 opencode TUI 做增量更新。

MCP 接口

GET /mcp

返回 MCP server 状态映射：

{
    "filesystem": {
        "status": "connected"
    },
    "github": {
        "status": "failed",
        "error": "boom"
    },
    "fetch": {
        "status": "disabled"
    }
}

状态来源优先是 mcpmgr worker 的 getServers，失败时回退到 applications.mcpmgr.servers 配置。

映射规则：

OpenDesk 状态	opencode 状态
`connected`	`{ "status": "connected" }`
`error`	`{ "status": "failed", "error": "..." }`
其他	`{ "status": "disabled" }`

POST /mcp/:name/connect

按 MCP name 或 id 查找 server，调用 worker 的 connectServer。请求带 directory 时，会作为 stdio workspace 传入。

id 是 OpenDesk 创建 MCP server 时生成的内部唯一标识，格式为 mcp_<毫秒时间戳>_<6位base36随机后缀>，例如 mcp_1765200000000_ab12cd。它不会根据 server 名称或配置内容稳定复用；删除后重新添加会生成新的 id。

成功返回：

true

找不到 server 返回 404：

{
    "_tag": "McpServerNotFoundError",
    "name": "missing",
    "message": "MCP server not found: missing"
}

POST /mcp/:name/disconnect

按 MCP name 或 id 查找 server，调用 worker 的 disconnectServer。成功返回 true。

未实现

opencode 的 MCP add 和 OAuth 接口当前没有实现：

接口	状态
`POST /mcp`	未实现
`POST /mcp/:name/auth`	未实现
`POST /mcp/:name/auth/callback`	未实现
`POST /mcp/:name/auth/authenticate`	未实现
`DELETE /mcp/:name/auth`	未实现

Permission 接口

OpenDesk server 把内部权限请求桥接成 opencode permission request。

GET /permission

返回待处理权限请求数组：

[
    {
        "id": "per_lx...",
        "sessionID": "ses_abc",
        "permission": "read",
        "patterns": ["D:/repo/README.md"],
        "metadata": {
            "toolName": "readFile",
            "input": {
                "file_path": "D:/repo/README.md"
            },
            "requests": [
                {
                    "resourceType": "file",
                    "action": "read",
                    "resourcePath": "D:/repo/README.md"
                }
            ],
            "prefixOptions": []
        },
        "always": ["D:/repo/README.md"],
        "tool": {
            "messageID": "msg_...",
            "callID": "call_..."
        }
    }
]

tool 只有在当前权限请求能关联到 assistant message 和 tool call 时才出现。

权限名推断规则：

工具或资源	permission
`readFile` 或文件 read	`read`
`writeFile`、`editFile`、`searchReplace`、`applyPatch` 或文件 write	`edit`
`globFiles`	`glob`
`grepFiles`	`grep`
`executePowerShell`、`executeBash`、`executeZsh` 或 execute action	`bash`
`webFetch` 或 network	`webfetch`
名称包含 `websearch` 或以 `search` 结尾	`websearch`
`loadSkill`、`callSkill` 或 skill resource	`skill`
`createSubTask`	`task`

POST /permission/:requestID/reply

回复权限请求。请求体支持两种格式：

{
    "reply": "once"
}

或：

{
    "body": {
        "reply": "always"
    }
}

reply 可选值：

值	OpenDesk 行为
`once`	本次允许，不记忆。
`always`	允许并按首个 `always` pattern 记忆为 prefix 规则。
`reject`	拒绝。并会拒绝同 session 的其他待处理权限请求。

成功返回：

true

非法请求体返回 400：

{
    "error": "Invalid permission reply"
}

不存在的 request 返回 404：

{
    "_tag": "PermissionNotFoundError",
    "requestID": "per_missing",
    "message": "Permission request not found: per_missing"
}

权限请求默认超时 300 秒。超时会按 reject 处理并发布 permission.replied。

Question 接口

OpenDesk 的 ask-user 工具会通过 question broker 暴露给 opencode 客户端。

GET /question

返回待处理问题数组：

[
    {
        "id": "que_lx...",
        "sessionID": "ses_abc",
        "questions": [
            {
                "question": "Which mode should be used?",
                "header": "Mode",
                "options": [
                    {
                        "label": "Fast",
                        "description": "Use the faster path"
                    }
                ],
                "multiple": false,
                "custom": true
            }
        ]
    }
]

POST /question/:requestID/reply

回复问题。

{
    "answers": [["Fast"]]
}

answers 是二维字符串数组，第一层顺序对应 questions 顺序，第二层是选择的 label 列表。

成功返回 true。非法请求体返回：

{
    "error": "Invalid question reply"
}

不存在的 request 返回：

{
    "_tag": "QuestionNotFoundError",
    "requestID": "que_missing",
    "message": "Question request not found: que_missing"
}

POST /question/:requestID/reject

拒绝问题，OpenDesk 内部会把 ask-user 结果解析为 cancelled。

成功返回：

true

当前实现范围总览

类别	已实现	占位或未实现
启动	`serve --mode opencode`	`--mode acp`（已独立实现，见 ACP 协议，不属于 opencode 兼容范围）
认证	Basic Auth、`auth_token` query	OAuth
事件	`/event`、`/global/event` SSE	WebSocket 事件
配置	`/config`、`/global/config`、`/config/providers`	opencode 全量配置语义
provider	`/provider`、`/provider/auth`	provider OAuth
session	CRUD、消息同步/异步、abort、fork、children、message list/delete	summarize、revert、session permission response 等
MCP	status、connect、disconnect	add、OAuth
权限	list、reply	无
问题	list、reply、reject	无
bootstrap	path、project、agent、command、skill	VCS/LSP/find/formatter 仅 stub
experimental	console/resource/session/worktree/workspace 部分 stub	tool、pty、sync、file、v2、tui 等未注册

因此，当前 server 模式已经能支撑 opencode TUI 的基础连接、配置读取、session 对话、流式渲染、权限确认、用户问题确认和 MCP 连接状态，但还不是 opencode server 全量 API 的完整替代实现。