Devika配置教程：API Key与模型设置跑通第一个任务

Devika 是一个开源的 AI 软件工程师代理项目，配置它的核心不是改多少代码，而是把 Python 运行环境、模型 API Key 和前后端启动参数对齐。
这篇教程按“先能跑、再调优”的顺序，带你在本地或服务器上完成 Devika 配置，并跑通一个简单任务来确认配置生效。

开始之前需要准备什么

Devika 依赖 Python 运行后端，前端通过浏览器访问。
建议使用 Ubuntu 22.04 或同类 Linux 发行版，Python 版本以项目 requirements.txt 或 README 中写明的范围为准，不要盲目用最新版。

需要提前准备：

• 一个可用的模型服务 API Key，并确认它有调用权限；
• Git 和 Python 包管理工具 pip；
• 如果通过浏览器访问服务器，放行后端和前端对应端口；
• 一个空目录用于存放项目代码。

先拉取代码并进入项目目录：

git clone <项目仓库地址> devika
cd devika

创建虚拟环境，避免污染系统 Python：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

如果安装过程中出现编译错误，优先检查系统是否缺少 build-essential、python3-dev 等基础包，而不是反复重装 Python。

修改配置文件接入模型

Devika 的配置通常集中在项目根目录的 config.toml 中。
用编辑器打开：

nano config.toml

找到模型相关段落，填入你的 API Key 和模型名称。
不同版本字段名可能略有差异，以文件中已有字段为准，不要自己新增不存在的键。
常见需要确认的项包括：

• API_KEY：你的模型服务密钥；
• MODEL_NAME：要调用的模型标识；
• BASE_URL：如果使用兼容接口，填写服务商提供的地址；
• LOG_LEVEL：初次配置可设为 INFO，方便看启动日志。

保存后，建议先用一条最小命令检查配置是否被正确读取，例如启动后端时观察日志中是否出现模型初始化成功的提示。
如果日志报“未找到 API Key”或“模型不可用”，回到 config.toml 核对字段名和值是否有多余空格或引号。

启动前后端并验证连通

配置改完后，先启动后端服务。
具体启动命令以项目 README 为准，常见形式是：

python3 devika.py

后端启动后，再按项目说明启动前端。
如果前端是独立目录，通常需要进入对应目录安装依赖并运行开发服务器。
启动完成后，用浏览器访问前端地址，观察页面是否能正常加载。

验证配置是否真正生效，不要只看页面有没有报错。
新建一个简单任务，例如让 Devika 读取当前目录并列出文件，提交后观察：

• 任务是否进入执行状态；
• 后端日志是否有模型请求记录；
• 返回结果是否包含实际文件列表，而不是空响应或鉴权错误。

如果任务一直卡住，先检查 API Key 是否有效、账户余额或调用额度是否充足，再检查服务器到模型服务的网络是否可达。

容易踩坑的几个地方

虚拟环境未激活：安装依赖和启动服务要在同一个虚拟环境中执行，否则会出现“模块找不到”。
每次新开终端都先执行 source venv/bin/activate。

配置文件格式错误：config.toml 对引号和缩进敏感，API Key 建议用双引号包裹，值里不要混入中文标点。

端口冲突：如果后端启动时报端口被占用，用 ss -tlnp | grep 端口号 查看占用进程，再决定换端口还是停掉旧进程。

防火墙未放行：在云服务器上部署时，除了本机服务启动成功，还要在安全组或防火墙中放行实际访问端口，否则浏览器仍然打不开。

配置完成后的检查清单

完成以上步骤后，按下面几项确认再进入正式使用：

• 虚拟环境可正常激活，pip list 能看到关键依赖；
• config.toml 中 API Key 和模型名称填写完整且无多余字符；
• 后端启动日志无鉴权失败或模型初始化错误；
• 前端页面可访问，提交简单任务能返回结果；
• 服务器端口和安全组规则与实际访问地址一致。

Devika 配置教程的关键在于顺序：环境先跑通，配置再对齐，最后用真实任务验证。
只要每一步都有明确的检查结果，后续更换模型或调整参数时也不容易把问题混在一起。