要点
- 在操作 OpenCode 之前，先用 curl 验证接口，以便确定故障是出在配置还是 API 上。
- 自定义提供商需要三个要素：Base URL、API 密钥和模型 ID，此处为 uncensored。
- 将上下文限制设置为 100,000 token，以便 Agent 围绕实际窗口进行规划。
- 支持流式输出和函数调用，这是 Agent 循环所需的功能。
开始前的准备工作
OpenCode 是一个在终端中运行的开源编码 Agent。它可以连接多个模型提供商，并且如果接口遵循 OpenAI 聊天格式，它允许你添加自己的提供商。本 API 符合该格式，因此设置只需填写几个字段。
首先收集这三个值：
- Base URL：
https://api.kimicode.top/v1 - 模型 ID：
uncensored - API 密钥： 在 API 密钥页面 创建一个。新账户可以一键领取 $0.50 的试用额度，这对于下面的测试来说已经足够了。试用密钥允许 2 个并发请求和每分钟 60 个请求。
将密钥保存在环境变量中，而不是将其粘贴到你要提交的文件中：
export KIMICODE_API_KEY="your-key-here"步骤 1：使用 curl 测试接口
在配置任何工具之前执行此操作。如果 curl 成功但 OpenCode 失败，你知道问题出在配置上。如果 curl 失败，你只需修复密钥或 URL 一处，而不是两处。
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}],
"max_tokens": 40
}'你应该得到一个包含 choices 数组和 usage 块的 JSON 对象。401 错误表示密钥错误或缺少 Bearer 前缀。404 错误通常表示 URL 输入错误或已包含 /chat/completions。
编码 Agent 会流式输出答案并调用工具，因此也要检查这两项：
curl -N https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to five."}]
}'你会看到一系列 data: 行，每行包含一个 JSON 增量，最后以用量数据和结束标记结尾。-N 标志会关闭 curl 的缓冲，使数据块在到达时立即显示。
步骤 2：向 OpenCode 添加自定义提供商
OpenCode 会从你的项目文件夹或其全局配置目录中读取 JSON 配置文件 opencode.json。自定义 OpenAI 风格的服务商通过 AI SDK 的 OpenAI 兼容包进行声明，需要配置基础 URL 和模型列表。以下布局遵循 OpenCode 在撰写本文时的公开文档。字段名称在不同版本之间可能会发生变化，如果某项被拒绝，请将其与当前 OpenCode 文档的服务商部分进行比较。
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kimicode": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kimicode API",
"options": {
"baseURL": "https://api.kimicode.top/v1",
"apiKey": "{env:KIMICODE_API_KEY}"
},
"models": {
"uncensored": {
"name": "Uncensored",
"limit": {
"context": 100000,
"output": 8192
}
}
}
}
},
"model": "kimicode/uncensored"
}models 下的键是发送给服务器的确切模型 ID，因此必须为 uncensored。最后一行将服务商和模型设为默认值，格式为服务商名称、斜杠，然后是模型 ID。
{env:KIMICODE_API_KEY} 形式指示 OpenCode 从你的 shell 中读取该变量。如果你的版本通过其自己的登录命令处理凭证，请使用该方式，并将密钥从文件中移除。无论哪种方式，都不要提交真实的密钥。
项目配置或全局配置
你可以将提供商块保留在两个位置。项目根目录中的文件仅适用于该仓库，适合共享一个设置的团队。用户配置目录中的文件适用于所有位置，适合个人默认设置。如果两者都存在，项目文件会添加或覆盖全局文件。
建议在全局文件中进行服务商定义，并使用环境变量来存储密钥。这样每个仓库都可以使用该接口，且敏感信息不会与你的源代码放在一起。如果多人在一个项目中工作，请只提交不包含密钥的服务商块，并让每个人设置自己的变量。这也使得轮换密钥变得简单：修改变量，重启终端，配置文件保持不变。
步骤 3：选择模型并运行任务
在项目文件夹中启动 OpenCode 并打开模型选择器。你的自定义提供商应出现在列表中，显示为你设置的显示名称。选择它，然后给 Agent 一个小的、可检查的任务，例如解释函数或为短文件编写单元测试。
从小处着手有两个原因。首先，你可以查看工具调用是否有效：当 OpenCode 要求模型读取或编辑文件时，它是通过工具调用接口完成的。其次，编码代理每轮会发送大量文本，包括文件内容和历史记录，因此长会话会快速消耗 token。下一节将对这些数字进行量化。
如果模型未显示，请检查文件是否为有效的 JSON，文件是否位于 OpenCode 查找配置的位置，以及提供商名称是否与你在 model 字段中输入的一致。
直接测试函数调用和 JSON 模式
OpenCode 依赖工具调用来读取文件、运行命令和编辑代码，因此在归咎于代理之前，值得确认接口是否处理工具定义。此请求提供一个工具并提出需要该工具的问题。
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a text file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'良好的响应包含一个 tool_calls 条目，命名 read_file 以及 JSON 参数字符串。Agent 运行工具，然后将结果作为 role 设置为 tool 的消息发送回去，模型从那里继续。如果你只看到纯文本，请尝试更直接的提示词，因为模型是否决定调用工具是其行为的一部分。
JSON 模式是一个单独的开关。添加 "response_format": {"type": "json_object"} 请求有效的 JSON 输出，当其他脚本需要解析返回内容时会有所帮助。在提示词中也提及 JSON，以便模型了解你期望的格式。
上下文大小与会话成本
上下文窗口为 100,000 个 token，提示词和补全内容合计计算。将 limit.context 设置为 100000 可以让代理知道实际上限，以便在服务器拒绝请求之前截断或总结历史记录。补全内容可以使用剩余的任何空间，max_tokens 是可选的。
计费为每 1M 输入 token $0.15，每 1M 输出 token $0.50。代理是输入密集的，因为每轮都会重新发送对话。以下是中等会话的工作示例：
- 40 轮，每轮发送约 30,000 输入 token：1,200,000 输入 token，即 1.2 x $0.15 = $0.18。
- 每轮返回约 800 输出 token：32,000 输出 token，即 0.032 x $0.50 = $0.016。
- 总计：$0.196，即整个会话大约二十美分。
你的数值会有所不同。请查看响应中的 usage 值，或观察 X-Balance-USD 头信息，它在每次响应中报告你的剩余余额。额度是预付的，永不过期，失败或被拒绝的请求不收费。详细信息见 定价页面。
对编码 Agent 的合理预期
这是一个通用文本模型，针对合法成人使用进行优化，不进行内容审查。它不是专门为代码构建的模型，本页面没有基准声明。它是否可靠地编辑你的仓库，你应该在自己的任务上测试，开启版本控制，然后再让它处理任何重要内容。
它处理 Agent 所需的底层机制：带有流式 tool_calls 的工具调用，作为 role: "tool" 消息发送的工具结果，以及通过 response_format 实现的 JSON 模式。它仅支持文本，不支持图像，因此附加截图的功能将无法工作。
两个限制对代理很重要。完整密钥允许 8 个并发请求和每分钟 300 个请求。子代理或并行工具运行如果同时触发许多调用，可能会达到并发上限，并且流式请求会保持其槽位直到流结束。发生这种情况时，你会得到代码为 concurrency 的 HTTP 429。代码 rate_limited 表示每分钟请求过多。在临时过载时，你也可能会看到带有 Retry-After: 5 的 429。请降低并发量或等待后重试。
故障排除
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 401 未授权 | 密钥为空或错误；启动 OpenCode 的 shell 中未设置环境变量 | 在同一个终端中运行 echo $KIMICODE_API_KEY，然后重启 OpenCode |
| 404 未找到 | 基础 URL 包含/chat/completions或缺少/v1 | 精确使用 https://api.kimicode.top/v1 |
| 未找到模型 | 模型标识符与 uncensored 不同 | 将 models 中的标识符与 GET /v1/models 返回的 ID 匹配 |
429 错误与 concurrency 相关 | 同时请求过多 | 减少并行的工具调用，或等待流式输出完成 |
| 请求过大 | 请求体超过 8 MB 或历史记录接近上下文窗口限制 | 开始新会话或总结历史记录 |
对于此处未涵盖的内容，文档页面提供了完整的请求参考，集成指南则从其他类 OpenAI 客户端的角度介绍了同一接口。
